(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.

3 files changed, 35 insertions, 29 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index dc48052ae..f30b6a3e5 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -4,6 +4,10 @@
 	restricted deletion flag is another name for the sticky bit.
 	* 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.
 
 2006-07-16  Paul Eggert  <eggert@cs.ucla.edu>
 
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 18141c603..dacac7df9 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -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
diff --git a/doc/perm.texi b/doc/perm.texi
index 2b3d2d573..5a65420a1 100644
--- a/doc/perm.texi
+++ b/doc/perm.texi
@@ -3,14 +3,14 @@ access that users have to that file.  They can be represented either in
 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
-@section Structure of File Permissions
+@section 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
-@cindex execute permission
+@cindex 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
-@dfn{restricted deletion flag} for the directory.
-For regular files on some systems, save the program's text image on the
+@dfn{restricted 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 example:
 
 @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 read the file;
 @cindex write permission, symbolic
 the permission the @var{users} have to write to the file;
 @item x
-@cindex execute permission, symbolic
-the permission the @var{users} have to execute the file.
+@cindex 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 directories.
 
 @cindex conditional executability
 There is one more special type of symbolic permission: if you use
-@samp{X} instead of @samp{x}, execute permission is affected only if the
+@samp{X} 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