Re: Error in chmod man page

[Paul Eggert]

Thanks for reporting that.  The bug was fixed in CVS on July 5, but
your message prompted me to review the documentation and I found a few
other related glitches.  I installed this:

2006-07-22  Paul Eggert  <address@hidden>

        * doc/coreutils.texi (What information is listed): Clarify that the
        restricted deletion flag is another name for the sticky bit.
        * doc/perm.texi (Mode Structure): The restricted deletion flag
        restricts only unprivileged users.
        (Mode Structure, Symbolic Modes, Numeric Modes): Be more careful
        about distinguishing file mode bits from permissions bits,
        and about execute versus search permission.  The FreeBSD command
        is chflags, not chrflags.
        * man/chmod.x: Update to reflect recent changes to coreutils.texi.

Index: doc/coreutils.texi
===================================================================
RCS file: /fetish/cu/doc/coreutils.texi,v
retrieving revision 1.340
diff -p -u -r1.340 coreutils.texi
--- doc/coreutils.texi  22 Jul 2006 23:41:43 -0000      1.340
+++ doc/coreutils.texi  23 Jul 2006 01:25:41 -0000
@@ -431,9 +431,9 @@ Numeric operations
 
 File permissions
 
-* Mode Structure::               Structure of File Permissions
-* Symbolic Modes::               Mnemonic permissions representation
-* Numeric Modes::                Permissions as octal numbers
+* Mode Structure::               Structure of file mode bits.
+* Symbolic Modes::               Mnemonic representation of file mode bits.
+* Numeric Modes::                File mode bits as octal numbers.
 * Directory Setuid and Setgid::  Set-user-ID and set-group-ID on directories.
 
 Date input formats
Index: doc/perm.texi
===================================================================
RCS file: /fetish/cu/doc/perm.texi,v
retrieving revision 1.17
diff -p -u -r1.17 perm.texi
--- doc/perm.texi       22 Jul 2006 23:42:19 -0000      1.17
+++ doc/perm.texi       23 Jul 2006 01:25:41 -0000
@@ -3,14 +3,14 @@ access that users have to that file.  Th
 symbolic form or as an octal number.
 
 @menu
-* Mode Structure::              Structure of file permissions.
-* Symbolic Modes::              Mnemonic permissions representation.
-* Numeric Modes::               Permissions as octal numbers.
+* Mode Structure::              Structure of file mode bits.
+* Symbolic Modes::              Mnemonic representation of file mode bits.
+* Numeric Modes::               File mode bits as octal numbers.
 * Directory Setuid and Setgid:: Set-user-ID and set-group-ID on directories.
 @end menu
 
 @node Mode Structure
address@hidden Structure of File Permissions
address@hidden Structure of File Mode Bits
 
 The file mode bits have two parts: the @dfn{file permission bits},
 which control ordinary access to the file, and @dfn{special mode
@@ -28,7 +28,7 @@ list the contents of the directory.
 permission to write to (change) the file.  For directories, this means
 permission to create and remove files in the directory.
 @item
address@hidden execute permission
address@hidden execute/search permission
 permission to execute the file (run it as a program).  For directories,
 this means permission to access files in the directory.
 @end enumerate
@@ -83,8 +83,10 @@ subdirectories.
 @cindex restricted deletion flag
 Prevent unprivileged users from removing or renaming a file in a directory
 unless they own the file or the directory; this is called the
address@hidden deletion flag} for the directory.
-For regular files on some systems, save the program's text image on the
address@hidden deletion flag} for the directory, and is commonly
+found on world-writable directories like @file{/tmp}.
+
+For regular files on some older systems, save the program's text image on the
 swap device so it will load more quickly when run; this is called the
 @dfn{sticky bit}.
 @end enumerate
@@ -98,21 +100,20 @@ specific to the file system.  For exampl
 
 @table @asis
 @item ext2
-On @acronym{GNU} and @acronym{GNU}/Linux the file permissions
-(``attributes'') specific to
+On @acronym{GNU} and @acronym{GNU}/Linux the file attributes specific to
 the ext2 file system are set using @command{chattr}.
 
 @item FFS
-On FreeBSD the file permissions (``flags'') specific to the FFS
-file system are set using @command{chrflags}.
+On FreeBSD the file flags specific to the FFS
+file system are set using @command{chflags}.
 @end table
 
-Even if a file's permission bits allow an operation on that file,
+Even if a file's mode bits allow an operation on that file,
 that operation may still fail, because:
 
 @itemize
 @item
-the file-system-specific permissions do not permit it;
+the file-system-specific attributes or flags do not permit it; or
 
 @item
 the file system is mounted as read-only.
@@ -159,7 +160,7 @@ symbolic modes.
 
 The basic symbolic operations on a file's permissions are adding,
 removing, and setting the permission that certain users have to read,
-write, and execute the file.  These operations have the following
+write, and execute or search the file.  These operations have the following
 format:
 
 @example
@@ -224,11 +225,12 @@ the permission the @var{users} have to r
 @cindex write permission, symbolic
 the permission the @var{users} have to write to the file;
 @item x
address@hidden execute permission, symbolic
-the permission the @var{users} have to execute the file.
address@hidden execute/search permission, symbolic
+the permission the @var{users} have to execute the file,
+or search it if it is a directory.
 @end table
 
-For example, to give everyone permission to read and write a file,
+For example, to give everyone permission to read and write a regular file,
 but not to execute it, use:
 
 @example
@@ -290,7 +292,7 @@ analogously.
 @subsection Changing Special Mode Bits
 
 @cindex changing special mode bits
-In addition to changing a file's read, write, and execute permissions,
+In addition to changing a file's read, write, and execute/search permissions,
 you can change its special mode bits.  @xref{Mode Structure}, for a
 summary of these special mode bits.
 
@@ -340,7 +342,7 @@ o=t
 
 @noindent
 does set the restricted deletion flag or sticky bit, but it also
-removes all read, write, and execute permissions that users not in the
+removes all read, write, and execute/search permissions that users not in the
 file's group might have had for it.
 
 @xref{Directory Setuid and Setgid}, for additional rules concerning
@@ -351,7 +353,7 @@ set-user-ID and set-group-ID bits and di
 
 @cindex conditional executability
 There is one more special type of symbolic permission: if you use
address@hidden instead of @samp{x}, execute permission is affected only if the
address@hidden instead of @samp{x}, execute/search permission is affected only 
if the
 file is a directory or already had execute permission.
 
 For example, this mode:
@@ -384,7 +386,7 @@ og+rX-w
 @noindent
 gives users other than the owner of the file read permission and, if
 it is a directory or if someone already had execute permission
-to it, gives them execute permission; and it also denies them write
+to it, gives them execute/search permission; and it also denies them write
 permission to the file.  It does not affect the permission that the
 owner of the file has for it.  The above mode is equivalent to
 the two modes:
@@ -422,7 +424,7 @@ a+r,g+x-w
 
 @noindent
 gives all users permission to read the file, and gives users who are in
-the file's group permission to execute it, as well, but not permission
+the file's group permission to execute/search it as well, but not permission
 to write to it.  The above mode could be written in several different
 ways; another is:
 
@@ -475,7 +477,7 @@ the file to all users.
 @cindex octal numbers for file modes
 As an
 alternative to giving a symbolic mode, you can give an octal (base 8)
-number that represents the new mode.
+number that represents the mode.
 This number is always interpreted in octal; you do not have to add a
 leading @samp{0}, as you do in C.
 
@@ -498,17 +500,17 @@ Value in  Corresponding
 Mode      Mode Bit
 
           Other users not in the file's group:
-   1      Execute
+   1      Execute/search
    2      Write
    4      Read
 
           Other users in the file's group:
-  10      Execute
+  10      Execute/search
   20      Write
   40      Read
 
           The file's owner:
- 100      Execute
+ 100      Execute/search
  200      Write
  400      Read
 
Index: man/chmod.x
===================================================================
RCS file: /fetish/cu/man/chmod.x,v
retrieving revision 1.6
diff -p -u -r1.6 chmod.x
--- man/chmod.x 5 Jul 2006 10:03:55 -0000       1.6
+++ man/chmod.x 23 Jul 2006 01:25:41 -0000
@@ -1,42 +1,55 @@
 [NAME]
-chmod \- change file access permissions
+chmod \- change file mode bits
 [DESCRIPTION]
 This manual page
 documents the GNU version of
 .BR chmod .
 .B chmod
-changes the permissions of each given file according to
+changes the file mode bits of each given file according to
 .IR mode ,
 which can be either a symbolic representation of changes to make, or
-an octal number representing the bit pattern for the new permissions.
+an octal number representing the bit pattern for the new mode bits.
 .PP
-The format of a symbolic mode is
-`[ugoa...][[+-=][rwxXstugo...]...][,...]'.  Multiple symbolic
-operations can be given, separated by commas.
-.PP
-A combination of the letters `ugoa' controls which users' access to
-the file will be changed: the user who owns it (u), other users in the
-file's group (g), other users not in the file's group (o), or all
-users (a).  If none of these are given, the effect is as if `a' were
+The format of a symbolic mode is [\c
+\fBugoa\fP.\|.\|.][[\fB+-=\fP][\fIperms\fP.\|.\|.].\|.\|.],
+where
+.I "perms"
+is either zero or more letters from the set
+\fBrwxXst\fP, or a single letter from the set \fBugo\fP.
+Multiple symbolic
+modes can be given, separated by commas.
+.PP
+A combination of the letters \fBugoa\fP controls which users' access
+to the file will be changed: the user who owns it (\fBu\fP), other
+users in the file's group (\fBg\fP), other users not in the file's
+group (\fBo\fP), or all users (\fBa\fP).  If none of these are given,
+the effect is as if \fBa\fP were
 given, but bits that are set in the umask are not affected.
 .PP
-The operator `+' causes the permissions selected to be added to the
-existing permissions of each file; `-' causes them to be removed; and
-`=' causes them to be the only permissions that the file has.
-.PP
-The letters `rwxXstugo' select the new permissions for the affected
-users: read (r), write (w), execute (or access for directories) (x),
-execute only if the file is a directory or already has execute
-permission for some user (X), set user or group ID on execution (s),
-sticky (t), the permissions granted to the user who owns the file (u),
-the permissions granted to other users who are members of the file's group (g),
+The operator \fB+\fP causes the selected file mode bits to be added to
+the existing file mode bits of each file; \fB-\fP causes them to be
+removed; and \fB=\fP causes them to be added and causes unmentioned
+bits to be removed except that a directory's unmentioned set user and
+group ID bits are not affected.
+.PP
+The letters \fBrwxXst\fP select file mode bits for the affected users:
+read (\fBr\fP), write (\fBw\fP), execute (or search for directories)
+(\fBx\fP), execute/search only if the file is a directory or already
+has execute permission for some user (\fBX\fP), set user or group ID
+on execution (\fBs\fP), restricted deletion flag or sticky bit
+(\fBt\fP).  Instead of one or more of these letters, you can specify
+exactly one of the letters \fBugo\fP: the permissions granted to the
+user who owns the file (\fBu\fP), the permissions granted to other
+users who are members of the file's group (\fBg\fP),
 and the permissions granted to users that are in neither of the two preceding
-categories (o).
+categories (\fBo\fP).
 .PP
-A numeric mode is from one to four octal digits (0-7), derived by
-adding up the bits with values 4, 2, and 1.  Any omitted digits are
-assumed to be leading zeros.  The first digit selects the set user ID
-(4) and set group ID (2) and sticky (1) attributes.  The second digit
+A numeric mode is from one to four octal digits (0\-7), derived by
+adding up the bits with values 4, 2, and 1.  Omitted digits are
+assumed to be leading zeros, except that if the first digit is
+omitted, a directory's set user and group ID bits are not affected.
+The first digit selects the set user ID (4) and set group ID (2) and
+restricted deletion or sticky (1) attributes.  The second digit
 selects permissions for the user who owns the file: read (4), write (2),
 and execute (1); the third selects permissions for other users in the
 file's group, with the same values; and the fourth for other users not
@@ -54,18 +67,17 @@ In contrast,
 .B chmod
 ignores symbolic links encountered during recursive directory
 traversals.
-.SH STICKY FILES
-On older Unix systems, the sticky bit caused executable files to be
-hoarded in swap space.  This feature is not useful on modern VM
-systems, and the Linux kernel ignores the sticky bit on files.  Other
-kernels may use the sticky bit on files for system-defined purposes.
-On some systems, only the superuser can set the sticky bit on files.
-.SH STICKY DIRECTORIES
-When the sticky bit is set on a directory, a file in that directory may
-be unlinked or renamed only by the directory owner, the file owner, or root.
-Without the sticky bit, anyone able to write to the
-directory can delete or rename files.  The sticky bit is commonly found
-on directories, such as /tmp, that are world-writable.
+.SH "RESTRICTED DELETION FLAG OR STICKY BIT"
+The restricted deletion flag or sticky bit is a single bit, whose
+interpretation depends on the file type.  For directories, it prevents
+unprivileged users from removing or renaming a file in the directory
+unless they own the file or the directory; this is called the
+.I "restricted deletion flag"
+for the directory, and is commonly found on world-writable directories
+like \fB/tmp\fP.  For regular files on some older systems, the bit
+saves the program's text image on the swap device so it will load more
+quickly when run; this is called the
+.IR "sticky bit" .
 .SH OPTIONS
 [SEE ALSO]
 chmod(2)