Re: perm.texi from coreutils

[Aaron S. Hawley]

On Thu, 8 Dec 2005, James Youngman wrote:

> > I am willing to volunteer to look into precisely what merges would be
> > necessary to take their changes.
>
> I suspect we can just take the update as-is.  But I would be grateful if
> you could check.

The changes were minimal enough to make a readable patch (as far as
patches go).  It is attached.

The more significant differences were:

- update of the definition of "sticky bit" support, removing the mention
of "a" (append-only support) and its respective example.
- addition of a note about ACLs and other controls provided at the file
system by file systems (ext, FFS, mounting read-only),
- removal of the ispell.el LocalWords.

Below are the relevant hunks for the significant changes, and after those
are the word-level changes (using `wdiff')--for those of us who are
extremely detail-oriented.

/a

@@ -69,13 +69,48 @@
 @cindex sticky
 @cindex swap space, saving text image in
 @cindex text image, saving in swap space
address@hidden append-only directories
-save the program's text image on the swap device so it will load more
-quickly when run (called the @dfn{sticky bit}).  For directories on some
-systems, prevent users from removing files that they do not own in the
-directory; this is called making the directory @dfn{append-only}.
address@hidden restricted deletion flag
+prevent 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
+swap device so it will load more quickly when run; this is called the
address@hidden bit}.
 @end enumerate

+In addition to the permissions listed above, there may be file attributes
+specific to the file system, e.g: access control lists (ACLs), whether a
+file is compressed, whether a file can be modified (immutability), whether
+a file can be dumped.  These are usually set using programs
+specific to the file system.  For example:
address@hidden should probably say a lot more about ACLs... someday
+
address@hidden @asis
address@hidden ext2
+On @acronym{GNU} and @acronym{GNU}/Linux the file permissions
+(``attributes'') specific to
+the ext2 file system are set using @command{chattr}.
+
address@hidden FFS
+On FreeBSD the file permissions (``flags'') specific to the FFS
+file system are set using @command{chrflags}.
address@hidden table
+
+Although a file's permission ``bits'' allow an operation on that file,
+that operation may still fail, because:
+
address@hidden
address@hidden
+the file-system-specific permissions do not permit it;
+
address@hidden
+the file system is mounted as read-only.
address@hidden itemize
+
+For example, if the immutable attribute is set on a file,
+it cannot be modified, regardless of the fact that you
+may have just run @code{chmod a+w FILE}.
+
 @node Symbolic Modes
 @section Symbolic Modes

@@ -252,7 +291,7 @@
 @samp{g} in the @var{users} part of the symbolic mode and
 @samp{s} in the @var{permissions} part.

-To change a file's permission to stay permanently on the swap device,
-use @samp{o} in the @var{users} part of the symbolic mode and
+To change a file's permission to set the restricted deletion flag or sticky 
bit,
+omit the @var{users} part of the symbolic mode (or use @samp{a}) and put
 @samp{t} in the @var{permissions} part.

@@ -263,27 +302,16 @@
 ug-s
 @end example

-To cause a program to be saved on the swap device, you can use
+To set the restricted deletion flag or sticky bit, you can use
 the mode:

 @example
-o+t
++t
 @end example
-
-Remember that the special permissions only affect files that are
-executable, plus, on some systems, directories (on which they have
-different meanings; @pxref{Mode Structure}).  Using @samp{a}
-in the @var{users} part of a symbolic mode does not cause the special
-permissions to be affected; thus,
-
address@hidden
-a+s
address@hidden example

address@hidden
-has @emph{no effect}.  You must use @samp{u}, @samp{g}, and @samp{o}
-explicitly to affect the special permissions.  Also, the
-combinations @samp{u+t}, @samp{g+t}, and @samp{o+s} have no effect.
+The combination @samp{o+s} has no effect.  On @acronym{GNU} systems
+the combinations @samp{u+t} and @samp{g+t} have no effect, and
address@hidden acts like plain @samp{+t}.

 The @samp{=} operator is not very useful with special permissions; for
 example, the mode:
@@ -470,7 +497,7 @@
  400      Read

           Special permissions:
-1000      Save text image on swap device
+1000      Restricted deletion flag or sticky bit
 2000      Set group ID on execution
 4000      Set user ID on execution
 @end example
@@ -478,16 +505,4 @@
 For example, numeric mode 4755 corresponds to symbolic mode
 @samp{u=rwxs,go=rx}, and numeric mode 664 corresponds to symbolic mode
 @samp{ug=rw,o=r}.  Numeric mode 0 corresponds to symbolic mode
address@hidden
-
address@hidden texi related words used by Emacs' spell checker ispell.el
-
address@hidden LocalWords: texinfo setfilename settitle setchapternewpage
address@hidden LocalWords: iftex finalout ifinfo DIR titlepage vskip pt
address@hidden LocalWords: filll dir samp dfn noindent xref pxref
address@hidden LocalWords: var deffn texi deffnx itemx emph asis
address@hidden LocalWords: findex smallexample subsubsection cindex
-
address@hidden LocalWords: chgrp chown executability filesystem FIXME ls og rw
address@hidden LocalWords: rwx rwxr rwxs rwxXstugo rx rX rxw setgid setuid ug
address@hidden LocalWords: ugo ugoa umask
address@hidden

Here are the word-level changes in their context (line numbers are
approximate) that are unmentioned by the hunks above:

@@ -46,9 +46,11 @@
 Files are given an owner and group when they are created.  Usually the
 owner is the current user and the group is the group of the directory
 the file is in, but this varies with the operating system, the
 [-filesystem-]
 {+file system+} the file is created on, and the way the file is created.  You
 can change the owner and group of a file by using the address@hidden 
address@hidden and
 address@hidden
 address@hidden commands.

 In addition to the three sets of three permissions listed above, a
 file's permissions have three special components, which affect only
@@ -57,11 +59,13 @@
 @enumerate
 @item
 @cindex setuid
 [-set-]
 {+Set+} the process's effective user ID to that of the file upon execution
 (called the @dfn{setuid bit}).  No effect on directories.
 @item
 @cindex setgid
 [-set-]
 {+Set+} the process's effective group ID to that of the file upon execution
 (called the @dfn{setgid bit}).  For directories on some systems, put
 files created in the directory into the same group as the directory, no
 matter what group the user who creates them is in.
@@ -89,9 +130,14 @@
 The format of symbolic modes is:

 @example
 
address@hidden@address@hidden@address@hidden@address@hidden@r{][},@address@hidden
 address@hidden@address@hidden@address@hidden@address@hidden,@address@hidden
 @end example

 address@hidden
 where @var{perms} is either zero or more letters from the set
 @samp{rwxXst}, or a single letter from the set @samp{ugo}.+}

 The following sections describe the operators and other details of
 symbolic modes.

@@ -118,7 +164,7 @@

 @noindent
 The spaces between the three parts above are shown for readability only;
 symbolic modes [-can not-] {+cannot+} contain spaces.

 The @var{users} part tells which users' access to the file is changed.
 It consists of one or more of the following letters (or it can be empty;
@@ -160,7 +206,7 @@
 @end table

 The @var{permissions} part tells what kind of access to the file should
 be changed; it is {+normally+} zero or more of the following letters.  As with 
the
 @var{users} part, the order does not matter when more than one letter is
 given.  Omitting the @var{permissions} part is useful only with the
 @samp{=} operation, where it gives the specified @var{users} no access
@@ -185,7 +231,7 @@
 a=rw
 @end example

 To remove write permission for [-from-] all users other than the file's
 owner, use:

 @example
@@ -209,7 +255,8 @@
 Another way to specify the same thing is:

 @example
 [-og-rxw-]
 {+og-rwx+}
 @end example

 @node Copying Permissions
@@ -217,17 +264,18 @@

 @cindex copying existing permissions
 @cindex permissions, copying existing
 You can base [-part of-] a file's permissions on [-part of-] its existing 
permissions.  To do
 this, instead of using {+a series of+} @samp{r}, @samp{w}, or @samp{x}
 {+letters+} after the
 operator, you use the letter @samp{u}, @samp{g}, or @samp{o}.  For
 example, the mode

 @example
 o+g
 @end example

 @noindent
 address@hidden FIXME describe the ls -l notation for showing permissions.-]
 adds the permissions for users who are in a file's group to the
 permissions that other users have for the file.  Thus, if the file
 started out as mode 664 (@samp{rw-rw-r--}), the above mode would change
@@ -252,11 +300,13 @@
 @samp{t} in the @var{permissions} part.

 For example, to add [-set user ID-] {+set-user-ID+} permission to a program,
 you can use the mode:

 @example
 u+s
 @end example

 To remove both [-set user ID-] {+set-user-ID+} and [-set group ID-] 
{+set-group-ID+} permission from
 it, you can use the mode:

 @example
@@ -263,5 +313,7 @@
 the mode:

 @example
 [-o+t-]
 {++t+}
 @end example

@@ -300,6 +352,7 @@
 @end example

 @noindent
 does [-cause the file to be saved on-] {+set+} the [-swap device,-] 
{+restricted deletion flag or sticky bit,+} but it also
 removes all read, write, and execute permissions that users not in the
 file's group might have had for it.

@@ -310,9 +362,8 @@
 @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
 file [-already had execute permission or-] is a [-directory.  It affects
 directories' execute permission even if they did not initially have any-] 
{+directory or already had+} execute [-permissions set.-] {+permission.+}

 For example, this mode:

@@ -321,8 +372,8 @@
 @end example

 @noindent
 gives all users permission to {+search directories, or to+} execute files 
[-(or search directories)-] if
 anyone could {+execute them+} before.

 @node Multiple Changes
 @subsection Making Multiple Changes
@@ -345,7 +396,7 @@
 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
 permission to [-it-] {+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:

@@ -433,22 +484,25 @@
 @cindex numeric modes
 @cindex file permissions, numeric
 @cindex octal numbers for file modes
 [-File permissions are stored internally as 16 bit integers.-]
 As an
 alternative to giving a symbolic mode, you can give an octal (base 8)
 number that [-corresponds to the internal representation of-] {+represents+} 
the new mode.
 This number is always interpreted in octal; you do not have to add a
 leading 0, as you do in C.  Mode 0055 is the same as mode 55.

 A numeric mode is usually shorter than the corresponding symbolic
 mode, but it is limited in that it [-can not-] {+cannot+} take into account a 
file's
 previous permissions; it can only set them absolutely.

 The permissions granted to the user,
 to other users in the file's group,
 and to other users not in the file's group [-are-] each [-stored as-] 
{+require+} three
 bits, which are represented as one octal digit.  The three special
 permissions [-are-] also [-each stored as-] {+require+} one [-bit,-] {+bit 
each,+} and they are as a group
 represented as another octal digit.  Here is how the bits are [-arranged
 in the 16 bit integer,-] {+arranged,+}
 starting with the lowest valued bit:

 @example
 Value in  Corresponding
@@ -478,3 +532,5 @@
 For example, numeric mode 4755 corresponds to symbolic mode
 @samp{u=rwxs,go=rx}, and numeric mode 664 corresponds to symbolic mode
 @samp{ug=rw,o=r}.  Numeric mode 0 corresponds to symbolic mode
 address@hidden
 address@hidden

perm.texi_coreutils-update.diff
Description: Patch from coreutils perm.texi