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