1@c File mode bits 2 3@c Copyright (C) 1994--2023 Free Software Foundation, Inc. 4 5@c Permission is granted to copy, distribute and/or modify this document 6@c under the terms of the GNU Free Documentation License, Version 1.3 or 7@c any later version published by the Free Software Foundation; with no 8@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 9@c Texts. A copy of the license is included in the ``GNU Free 10@c Documentation License'' file as part of this distribution. 11 12Each file has a set of @dfn{file mode bits} that control the kinds of 13access that users have to that file. They can be represented either in 14symbolic form or as an octal number. 15 16@menu 17* Mode Structure:: Structure of file mode bits. 18* Symbolic Modes:: Mnemonic representation of file mode bits. 19* Numeric Modes:: File mode bits as octal numbers. 20* Operator Numeric Modes:: ANDing, ORing, and setting modes octally. 21* Directory Setuid and Setgid:: Set-user-ID and set-group-ID on directories. 22@end menu 23 24@node Mode Structure 25@section Structure of File Mode Bits 26 27The file mode bits have two parts: the @dfn{file permission bits}, 28which control ordinary access to the file, and @dfn{special mode 29bits}, which affect only some files. 30 31There are three kinds of permissions that a user can have for a file: 32 33@enumerate 34@item 35@cindex read permission 36permission to read the file. For directories, this means permission to 37list the contents of the directory. 38@item 39@cindex write permission 40permission to write to (change) the file. For directories, this means 41permission to create and remove files in the directory. 42@item 43@cindex execute/search permission 44permission to execute the file (run it as a program). For directories, 45this means permission to access files in the directory. 46@end enumerate 47 48There are three categories of users who may have different permissions 49to perform any of the above operations on a file: 50 51@enumerate 52@item 53the file's owner; 54@item 55other users who are in the file's group; 56@item 57everyone else. 58@end enumerate 59 60@cindex owner, default 61@cindex group owner, default 62Files are given an owner and group when they are created. Usually the 63owner is the current user and the group is the group of the directory 64the file is in, but this varies with the operating system, the 65file system the file is created on, and the way the file is created. You 66can change the owner and group of a file by using the @command{chown} and 67@command{chgrp} commands. 68 69In addition to the three sets of three permissions listed above, the 70file mode bits have three special components, which affect only 71executable files (programs) and, on most systems, directories: 72 73@table @asis 74@item The @dfn{set-user-ID bit} (@dfn{setuid bit}). 75@cindex set-user-ID 76@cindex setuid 77On execution, set the process's effective user ID to that of the file. 78For directories on a few systems, give files created in the directory 79the same owner as the directory, no matter who creates them, and set 80the set-user-ID bit of newly-created subdirectories. 81 82@item The @dfn{set-group-ID bit} (@dfn{setgid bit}). 83@cindex set-group-ID 84@cindex setgid 85On execution, set the process's effective group ID to that of the file. 86For directories on most systems, give files created in the directory 87the same group as the directory, no matter what group the user who 88creates them is in, and set the set-group-ID bit of newly-created 89subdirectories. 90 91@item The @dfn{restricted deletion flag} or @dfn{sticky bit}. 92@cindex sticky 93@cindex swap space, saving text image in 94@cindex text image, saving in swap space 95@cindex restricted deletion flag 96Prevent unprivileged users from removing or renaming a file in a directory 97unless they own the file or the directory; this is commonly 98found on world-writable directories like @file{/tmp}. 99For regular files on some older systems, save the program's text image on the 100swap device so it will load more quickly when run, so that the image 101is ``sticky''. 102@end table 103 104In addition to the file mode bits listed above, there may be file attributes 105specific to the file system, e.g., access control lists (ACLs), whether a 106file is compressed, whether a file can be modified (immutability), and whether 107a file can be dumped. These are usually set using programs 108specific to the file system. For example: 109@c should probably say a lot more about ACLs... someday 110 111@table @asis 112@item ext2 113On GNU and GNU/Linux the file attributes specific to 114the ext2 file system are set using @command{chattr}. 115 116@item FFS 117On FreeBSD the file flags specific to the FFS 118file system are set using @command{chflags}. 119@end table 120 121Even if a file's mode bits allow an operation on that file, 122that operation may still fail, because: 123 124@itemize 125@item 126the file-system-specific attributes or flags do not permit it; or 127 128@item 129the file system is mounted as read-only. 130@end itemize 131 132For example, if the immutable attribute is set on a file, 133it cannot be modified, regardless of the fact that you 134may have just run @code{chmod a+w FILE}. 135 136@node Symbolic Modes 137@section Symbolic Modes 138 139@cindex symbolic modes 140@dfn{Symbolic modes} represent changes to files' mode bits as 141operations on single-character symbols. They allow you to modify either 142all or selected parts of files' mode bits, optionally based on 143their previous values, and perhaps on the current @code{umask} as well 144(@pxref{Umask and Protection}). 145 146The format of symbolic modes is: 147 148@example 149@r{[}ugoa@dots{}@r{][}-+=@r{]}@var{perms}@dots{}@r{[},@dots{}@r{]} 150@end example 151 152@noindent 153where @var{perms} is either zero or more letters from the set 154@samp{rwxXst}, or a single letter from the set @samp{ugo}. 155 156The following sections describe the operators and other details of 157symbolic modes. 158 159@menu 160* Setting Permissions:: Basic operations on permissions. 161* Copying Permissions:: Copying existing permissions. 162* Changing Special Mode Bits:: Special mode bits. 163* Conditional Executability:: Conditionally affecting executability. 164* Multiple Changes:: Making multiple changes. 165* Umask and Protection:: The effect of the umask. 166@end menu 167 168@node Setting Permissions 169@subsection Setting Permissions 170 171The basic symbolic operations on a file's permissions are adding, 172removing, and setting the permission that certain users have to read, 173write, and execute or search the file. These operations have the following 174format: 175 176@example 177@var{users} @var{operation} @var{permissions} 178@end example 179 180@noindent 181The spaces between the three parts above are shown for readability only; 182symbolic modes cannot contain spaces. 183 184The @var{users} part tells which users' access to the file is changed. 185It consists of one or more of the following letters (or it can be empty; 186@pxref{Umask and Protection}, for a description of what happens then). When 187more than one of these letters is given, the order that they are in does 188not matter. 189 190@table @code 191@item u 192@cindex owner of file, permissions for 193the user who owns the file; 194@item g 195@cindex group, permissions for 196other users who are in the file's group; 197@item o 198@cindex other permissions 199all other users; 200@item a 201all users; the same as @samp{ugo}. 202@end table 203 204The @var{operation} part tells how to change the affected users' access 205to the file, and is one of the following symbols: 206 207@table @code 208@item + 209@cindex adding permissions 210to add the @var{permissions} to whatever permissions the @var{users} 211already have for the file; 212@item - 213@cindex removing permissions 214@cindex subtracting permissions 215to remove the @var{permissions} from whatever permissions the 216@var{users} already have for the file; 217@item = 218@cindex setting permissions 219to make the @var{permissions} the only permissions that the @var{users} 220have for the file. 221@end table 222 223The @var{permissions} part tells what kind of access to the file should 224be changed; it is normally zero or more of the following letters. As with the 225@var{users} part, the order does not matter when more than one letter is 226given. Omitting the @var{permissions} part is useful only with the 227@samp{=} operation, where it gives the specified @var{users} no access 228at all to the file. 229 230@table @code 231@item r 232@cindex read permission, symbolic 233the permission the @var{users} have to read the file; 234@item w 235@cindex write permission, symbolic 236the permission the @var{users} have to write to the file; 237@item x 238@cindex execute/search permission, symbolic 239the permission the @var{users} have to execute the file, 240or search it if it is a directory. 241@end table 242 243For example, to give everyone permission to read and write a regular file, 244but not to execute it, use: 245 246@example 247a=rw 248@end example 249 250To remove write permission for all users other than the file's 251owner, use: 252 253@example 254go-w 255@end example 256 257@noindent 258The above command does not affect the access that the owner of 259the file has to it, nor does it affect whether other users can 260read or execute the file. 261 262To give everyone except a file's owner no permission to do anything with 263that file, use the mode below. Other users could still remove the file, 264if they have write permission on the directory it is in. 265 266@example 267go= 268@end example 269 270@noindent 271Another way to specify the same thing is: 272 273@example 274og-rwx 275@end example 276 277@node Copying Permissions 278@subsection Copying Existing Permissions 279 280@cindex copying existing permissions 281@cindex permissions, copying existing 282You can base a file's permissions on its existing permissions. To do 283this, instead of using a series of @samp{r}, @samp{w}, or @samp{x} 284letters after the 285operator, you use the letter @samp{u}, @samp{g}, or @samp{o}. For 286example, the mode 287 288@example 289o+g 290@end example 291 292@noindent 293adds the permissions for users who are in a file's group to the 294permissions that other users have for the file. Thus, if the file 295started out as mode 664 (@samp{rw-rw-r--}), the above mode would change 296it to mode 666 (@samp{rw-rw-rw-}). If the file had started out as mode 297741 (@samp{rwxr----x}), the above mode would change it to mode 745 298(@samp{rwxr--r-x}). The @samp{-} and @samp{=} operations work 299analogously. 300 301@node Changing Special Mode Bits 302@subsection Changing Special Mode Bits 303 304@cindex changing special mode bits 305In addition to changing a file's read, write, and execute/search permissions, 306you can change its special mode bits. @xref{Mode Structure}, for a 307summary of these special mode bits. 308 309To change the file mode bits to set the user ID on execution, use 310@samp{u} in the @var{users} part of the symbolic mode and 311@samp{s} in the @var{permissions} part. 312 313To change the file mode bits to set the group ID on execution, use 314@samp{g} in the @var{users} part of the symbolic mode and 315@samp{s} in the @var{permissions} part. 316 317To set both user and group ID on execution, omit the @var{users} part 318of the symbolic mode (or use @samp{a}) and use @samp{s} in the 319@var{permissions} part. 320 321To change the file mode bits to set the restricted deletion flag or sticky bit, 322omit the @var{users} part of the symbolic mode (or use @samp{a}) and use 323@samp{t} in the @var{permissions} part. 324 325For example, to set the set-user-ID mode bit of a program, 326you can use the mode: 327 328@example 329u+s 330@end example 331 332To remove both set-user-ID and set-group-ID mode bits from 333it, you can use the mode: 334 335@example 336a-s 337@end example 338 339To set the restricted deletion flag or sticky bit, you can use 340the mode: 341 342@example 343+t 344@end example 345 346The combination @samp{o+s} has no effect. On GNU systems 347the combinations @samp{u+t} and @samp{g+t} have no effect, and 348@samp{o+t} acts like plain @samp{+t}. 349 350The @samp{=} operator is not very useful with special mode bits. 351For example, the mode: 352 353@example 354o=t 355@end example 356 357@noindent 358does set the restricted deletion flag or sticky bit, but it also 359removes all read, write, and execute/search permissions that users not in the 360file's group might have had for it. 361 362@xref{Directory Setuid and Setgid}, for additional rules concerning 363set-user-ID and set-group-ID bits and directories. 364 365@node Conditional Executability 366@subsection Conditional Executability 367 368@cindex conditional executability 369There is one more special type of symbolic permission: if you use 370@samp{X} instead of @samp{x}, execute/search permission is affected only if the 371file is a directory or already had execute permission. 372 373For example, this mode: 374 375@example 376a+X 377@end example 378 379@noindent 380gives all users permission to search directories, or to execute files if 381anyone could execute them before. 382 383@node Multiple Changes 384@subsection Making Multiple Changes 385 386@cindex multiple changes to permissions 387The format of symbolic modes is actually more complex than described 388above (@pxref{Setting Permissions}). It provides two ways to make 389multiple changes to files' mode bits. 390 391The first way is to specify multiple @var{operation} and 392@var{permissions} parts after a @var{users} part in the symbolic mode. 393 394For example, the mode: 395 396@example 397og+rX-w 398@end example 399 400@noindent 401gives users other than the owner of the file read permission and, if 402it is a directory or if someone already had execute permission 403to it, gives them execute/search permission; and it also denies them write 404permission to the file. It does not affect the permission that the 405owner of the file has for it. The above mode is equivalent to 406the two modes: 407 408@example 409og+rX 410og-w 411@end example 412 413The second way to make multiple changes is to specify more than one 414simple symbolic mode, separated by commas. For example, the mode: 415 416@example 417a+r,go-w 418@end example 419 420@noindent 421gives everyone permission to read the file and removes write 422permission on it for all users except its owner. Another example: 423 424@example 425u=rwx,g=rx,o= 426@end example 427 428@noindent 429sets all of the permission bits for the file explicitly. (It 430gives users who are not in the file's group no permission at all for 431it.) 432 433The two methods can be combined. The mode: 434 435@example 436a+r,g+x-w 437@end example 438 439@noindent 440gives all users permission to read the file, and gives users who are in 441the file's group permission to execute/search it as well, but not permission 442to write to it. The above mode could be written in several different 443ways; another is: 444 445@example 446u+r,g+rx,o+r,g-w 447@end example 448 449@node Umask and Protection 450@subsection The Umask and Protection 451 452@cindex umask and modes 453@cindex modes and umask 454If the @var{users} part of a symbolic mode is omitted, it defaults to 455@samp{a} (affect all users), except that any permissions that are 456@emph{set} in the system variable @code{umask} are @emph{not affected}. 457The value of @code{umask} can be set using the 458@code{umask} command. Its default value varies from system to system. 459 460@cindex giving away permissions 461Omitting the @var{users} part of a symbolic mode is generally not useful 462with operations other than @samp{+}. It is useful with @samp{+} because 463it allows you to use @code{umask} as an easily customizable protection 464against giving away more permission to files than you intended to. 465 466As an example, if @code{umask} has the value 2, which removes write 467permission for users who are not in the file's group, then the mode: 468 469@example 470+w 471@end example 472 473@noindent 474adds permission to write to the file to its owner and to other users who 475are in the file's group, but @emph{not} to other users. In contrast, 476the mode: 477 478@example 479a+w 480@end example 481 482@noindent 483ignores @code{umask}, and @emph{does} give write permission for 484the file to all users. 485 486@node Numeric Modes 487@section Numeric Modes 488 489@cindex numeric modes 490@cindex file mode bits, numeric 491@cindex octal numbers for file modes 492As an 493alternative to giving a symbolic mode, you can give an octal (base 8) 494number that represents the mode. 495 496The permissions granted to the user, 497to other users in the file's group, 498and to other users not in the file's group each require three 499bits: one bit for read, one for write, and one for execute/search permission. 500These three bits are represented as one octal digit; 501for example, if all three are present, the resulting 111 (in binary) 502is represented as the digit 7 (in octal). The three special 503mode bits also require one bit each, and they are as a group 504represented as another octal digit. Here is how the bits are arranged, 505starting with the highest valued bit: 506 507@example 508Value in Corresponding 509Mode Mode Bit 510 511 Special mode bits: 5124000 Set user ID 5132000 Set group ID 5141000 Restricted deletion flag or sticky bit 515 516 The file's owner: 517 400 Read 518 200 Write 519 100 Execute/search 520 521 Other users in the file's group: 522 40 Read 523 20 Write 524 10 Execute/search 525 526 Other users not in the file's group: 527 4 Read 528 2 Write 529 1 Execute/search 530@end example 531 532For example, numeric mode @samp{4751} corresponds to symbolic mode 533@samp{u=srwx,g=rx,o=x}, and numeric mode @samp{664} corresponds to symbolic mode 534@samp{ug=rw,o=r}. Numeric mode @samp{0} corresponds to symbolic mode 535@samp{a=}. 536 537A numeric mode is usually shorter than the corresponding symbolic 538mode, but it is limited in that normally it cannot take into account the 539previous file mode bits; it can only set them absolutely. 540The set-user-ID and set-group-ID bits of directories are an exception 541to this general limitation. @xref{Directory Setuid and Setgid}. 542Also, operator numeric modes can take previous file mode bits into 543account. @xref{Operator Numeric Modes}. 544 545Numeric modes are always interpreted in octal; you do not have to add a 546leading @samp{0}, as you do in C@. Mode @samp{0055} is the same as 547mode @samp{55}. However, modes of five digits or more, such as 548@samp{00055}, are sometimes special (@pxref{Directory Setuid and Setgid}). 549 550@node Operator Numeric Modes 551@section Operator Numeric Modes 552 553An operator numeric mode is a numeric mode that is prefixed by a 554@samp{-}, @samp{+}, or @samp{=} operator, which has the same 555interpretation as in symbolic modes. For example, @samp{+440} enables 556read permission for the file's owner and group, @samp{-1} disables 557execute permission for other users, and @samp{=600} clears all 558permissions except for enabling read-write permissions for the file's 559owner. Operator numeric modes can be combined with symbolic modes by 560separating them with a comma; for example, @samp{=0,u+r} clears all 561permissions except for enabling read permission for the file's owner. 562 563The commands @samp{chmod =755 @var{dir}} and @samp{chmod 755 564@var{dir}} differ in that the former clears the directory @var{dir}'s 565setuid and setgid bits, whereas the latter preserves them. 566@xref{Directory Setuid and Setgid}. 567 568Operator numeric modes are a GNU extension. 569 570@node Directory Setuid and Setgid 571@section Directories and the Set-User-ID and Set-Group-ID Bits 572 573On most systems, if a directory's set-group-ID bit is set, newly 574created subfiles inherit the same group as the directory, and newly 575created subdirectories inherit the set-group-ID bit of the parent 576directory. On a few systems, a directory's set-user-ID bit has a 577similar effect on the ownership of new subfiles and the set-user-ID 578bits of new subdirectories. These mechanisms let users share files 579more easily, by lessening the need to use @command{chmod} or 580@command{chown} to share new files. 581 582These convenience mechanisms rely on the set-user-ID and set-group-ID 583bits of directories. If commands like @command{chmod} and 584@command{mkdir} routinely cleared these bits on directories, the 585mechanisms would be less convenient and it would be harder to share 586files. Therefore, a command like @command{chmod} does not affect the 587set-user-ID or set-group-ID bits of a directory unless the user 588specifically mentions them in a symbolic mode, or uses an operator 589numeric mode such as @samp{=755}, or sets them in a numeric mode, or 590clears them in a numeric mode that has five or more octal digits. 591For example, on systems that support 592set-group-ID inheritance: 593 594@example 595# These commands leave the set-user-ID and 596# set-group-ID bits of the subdirectories alone, 597# so that they retain their default values. 598mkdir A B C 599chmod 755 A 600chmod 0755 B 601chmod u=rwx,go=rx C 602mkdir -m 755 D 603mkdir -m 0755 E 604mkdir -m u=rwx,go=rx F 605@end example 606 607If you want to try to set these bits, you must mention them 608explicitly in the symbolic or numeric modes, e.g.: 609 610@example 611# These commands try to set the set-user-ID 612# and set-group-ID bits of the subdirectories. 613mkdir G 614chmod 6755 G 615chmod +6000 G 616chmod u=rwx,go=rx,a+s G 617mkdir -m 6755 H 618mkdir -m +6000 I 619mkdir -m u=rwx,go=rx,a+s J 620@end example 621 622If you want to try to clear these bits, you must mention them 623explicitly in a symbolic mode, or use an operator numeric mode, or 624specify a numeric mode with five or more octal digits, e.g.: 625 626@example 627# These commands try to clear the set-user-ID 628# and set-group-ID bits of the directory D. 629chmod a-s D 630chmod -6000 D 631chmod =755 D 632chmod 00755 D 633@end example 634 635This behavior is a GNU extension. Portable scripts should 636not rely on requests to set or clear these bits on directories, as 637POSIX allows implementations to ignore these requests. 638The GNU behavior with numeric modes of four or fewer digits 639is intended for scripts portable to systems that preserve these bits; 640the behavior with numeric modes of five or more digits is for scripts 641portable to systems that do not preserve the bits. 642