.

1 files changed, 460 insertions, 0 deletions

diff --git a/doc/perm.texi b/doc/perm.texi
new file mode 100644
index 000000000..b231b24ec
--- /dev/null
+++ b/doc/perm.texi
@@ -0,0 +1,460 @@
+Each file on a GNU or Unix system has a set of @dfn{permission modes}
+that control which users are allowed to access that file, and what kind
+of access they are given to it.
+
+@menu
+* Mode Structure::              Structure of File Permissions
+* Symbolic Modes::              Symbolic Modes
+* Numeric Modes::               Numeric Modes
+@end menu
+
+@node     Mode Structure
+@section Structure of File Permissions
+
+There are three kinds of permissions that a user on a GNU or Unix system
+can have for a file:
+
+@enumerate
+@item
+permission to read the file; for directories, this means permission to
+list the contents of the directory.
+@item
+permission to write to (change) the file; for directories, this means
+permission to create files in the directory.
+@item
+permission to execute the file (run it as a program); for directories,
+this means permission to access files in the directory.
+@end enumerate
+
+Which users are allowed to perform each of the above three operations on
+a given file is determined by that file's permission mode.  The
+permission mode is actually three sets of permissions, which control
+access to the file by three sets of users:
+
+@enumerate
+@item
+the file's owner
+@item
+other users who are in the group that the file is in
+@item
+other users who are not in the group that the file is in
+@end enumerate
+
+Files are by default owned by and in the same group as the user who
+created them, but the owner and group of a file can be changed, for
+example by using the @code{chown} and @code{chgrp} commands.
+
+In addition to the three sets of three permissions listed above,
+permission modes have three special components, which affect only
+executable files (i.e., programs) and, on some systems, directories:
+
+@enumerate
+@item
+set the process's effective user i.d. to that of the file upon execution
+(called the @dfn{setuid bit}); no effect on directories.
+@item
+set the process's effective group i.d. to that of the file upon
+execution (called the @dfn{setgid bit}); for directories on
+4.3BSD-derived 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.
+@item
+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
+4.3BSD-derived systems, prevent users from removing files that they do
+not own from the directory.
+@end enumerate
+
+@node     Symbolic Modes
+@section Symbolic Modes
+
+@dfn{Symbolic modes} represent changes to files' permission modes as
+operations on single-character symbols.  They allow you to modify either
+all or selected parts of files' permission modes, optionally based on
+their previous values, and perhaps on the current umask as well
+(@pxref{Umask and Modes}).
+
+The format of symbolic modes recognized is listed
+below, with the optional portions in square brackets, @samp{[@dots{}]}:
+
+@example
+@r{[}ugoa@dots{}@r{][[}+-=@r{][}rwxXstugo@dots{}@r{]}@dots{}@r{][},@dots{}@r{]}
+@end example
+
+The following sections describe the operators and other details of
+symbolic modes.
+
+@menu
+* Elementary::                  Elementary Operations on Permissions
+* Copying::                     Copying Existing Permissions
+* Special::                     Special Permissions
+* Conditional Executability::   Conditionally Affecting Executability
+* Multiple Changes::            Making Multiple Changes
+* Umask and Modes::             The Effect of the Umask
+@end menu
+
+@node     Elementary
+@subsection Elementary Operations on Permissions
+
+The simplest symbolic operations on a file's permission modes are
+adding, removing, and setting the permission that certain users have to
+read, write, and execute the file.  These simple operations have the
+following format:
+
+@example
+@var{users} @var{operation} @var{permissions}
+@end example
+
+@noindent
+The spaces between the three parts above are shown for clarity only.
+
+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;
+@pxref{Umask and Modes}, for a description of what happens then).  When
+more than one of these letters is given, the order that they are in does
+not matter.
+
+@table @code
+@item u
+to affect the permission granted to the user who owns the file;
+@item g
+to affect the permission granted to other users who are in the group
+that the file is in;
+@item o
+to affect the permission granted to all other users.
+@item a
+to affect all users; the same as @samp{ugo}.
+@end table
+
+The @var{operation} part tells how to change the affected users' access
+to the file, and is one of the following symbols.
+
+@table @code
+@item +
+to add the @var{permissions} to whatever permissions the @var{users}
+already have for the file;
+@item -
+to remove the @var{permissions} from whatever permissions the
+@var{users} already have for the file;
+@item =
+to make the @var{permissions} the only permissions that the @var{users}
+have for the file.
+@end table
+
+The @var{permissions} part tells what kind of access to the file should
+be changed; it is 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
+at all to the file.
+
+@table @code
+@item r
+to affect the permission the @var{users} have to read the file;
+@item w
+to affect the permission the @var{users} have to write to the file;
+@item x
+to affect the permission the @var{users} have to execute the file.
+@end table
+
+For example, to give everyone permission to read and write a file,
+but not to execute it, use:
+
+@example
+a=rw
+@end example
+
+To remove write permission for from all users other than the file's
+owner, use:
+
+@example
+go-w
+@end example
+
+@noindent
+Note that the above command does not affect the access that the owner of
+@file{textfile} has to it, nor does it affect whether other users can
+read or execute the file.
+
+To give other users who are not in the group that a file is in no
+permission to do anything with that file, use the argument below.  Note
+that other users would still be able to remove the file, if they have
+permission to write to the directory that it is in.
+
+@example
+go=
+@end example
+
+@noindent
+Another way to do the same thing is:
+
+@example
+og-rxw
+@end example
+
+@node     Copying
+@subsection Copying Existing Permissions
+
+You can base part of a file's new permission mode
+on part of its existing permission mode.  To do this, instead of using
+@samp{r}, @samp{w}, or @samp{x} permissions (described above,
+(@pxref{Elementary}) after the operator, you use the letter @samp{u},
+@samp{g}, or @samp{o}.  For example,
+
+@example
+o+g
+@end example
+
+@noindent
+adds the permissions that users who are in the group that a file
+is in have for it to the permissions that other users who
+are not in group the file is in have for it.  Thus, if the file
+started out as mode 664 (@samp{rw-rw-r--}), the above command would
+change it to mode 666 (@samp{rw-rw-rw-}).  If the file had started
+out as mode 741 (@samp{rwxr----x}), the above command would change it to
+mode 745 (@samp{rwxr--r-x}).  The @samp{-} and @samp{=} operations work
+analogously.
+
+@node     Special
+@subsection Special Permissions
+
+In addition to changing a file's read, write, and execute permissions,
+you can change the special permissions; @pxref{Mode Structure},
+for a summary of these permissions.
+
+To change a file's permission to set the user i.d. on execution, use
+@samp{u} in the @var{users} part of the symbolic mode and the letter
+@samp{s} in the @var{permissions} part.
+
+To change a file's permission to set the group i.d. on execution, use
+@samp{g} in the @var{users} part of the symbolic mode and the letter
+@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 the letter
+@samp{t} in the @var{permissions} part.
+
+For example, to add set user i.d. permission to the a program,
+you can use:
+
+@example
+u+s
+@end example
+
+To remove both set user i.d. and set group i.d. permission from
+it, you can use:
+
+@example
+ug-s
+@end example
+
+To cause a program to be saved on the swap device, you can use
+the command:
+
+@example
+o+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} for a description of their
+effect on directories).  Note that using the @samp{a} letter in the
+@var{users} part of a symbolic mode does not cause the special
+permissions to be affected; thus,
+
+@example
+a+s
+@end example
+
+@noindent
+has @emph{no effect}.  You must type @samp{u}, @samp{g}, and @samp{o}
+explicitly to affect the special permissions.  Also note that the
+combinations @samp{u+t}, @samp{g+t}, and @samp{o+s} have no effect.
+
+The @samp{=} operator is not very useful with special permissions; for
+example, the command:
+
+@example
+o=t
+@end example
+
+@noindent
+does cause the file to be saved on the swap device, but it also
+removes all read, write, and execute permissions that users not in the
+group that the file is in might have had for it.
+
+@node     Conditional Executability
+@subsection Conditionally Affecting Executability
+
+There is one more special type of permission:
+if you use an @samp{X} instead of @samp{x}, execute permission is
+affected only if the file already had execute permission, or else if the
+file is a directory.  It affects execute permission for directories
+@emph{even if they did not initially have any execute permissions
+set}.
+
+For example, this:
+
+@example
+go+X
+@end example
+
+@noindent
+gives all users permission to use files if anyone could before.
+
+@node     Multiple Changes
+@subsection Making Multiple Changes
+
+The format of symbolic modes is
+actually more complex than the one described above (@pxref{Elementary});
+it provides two ways to make multiple
+changes to files' permission modes.
+
+The first way is to specify multiple @var{operation} and
+@var{permissions} parts after a @var{users} part in the symbolic mode.
+
+For example, the command:
+
+@example
+og+rX-w
+@end example
+
+@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
+permission to it file.  It does not affect the permission that the
+owner of the file has for it.  The above command is equivalent to
+the two commands:
+
+@example
+og+rX
+og-w
+@end example
+
+The second way to make multiple changes is to specify more than one
+simple symbolic mode, separated by commas.  For example, the command:
+
+@example
+a+r,go-w
+@end example
+
+@noindent
+gives everyone permission to read the file and removes write
+permission on it for all users except its owner.  Another example:
+
+@example
+u=rwx,g=rx,o=
+@end example
+
+@noindent
+sets all of the permissions for the file explicitly; note that it
+gives users who are not in the group that the file is in no
+permission at all for it.
+
+The two methods can be combined.  The command:
+
+@example
+a+r,g+x-w
+@end example
+
+@noindent
+gives all users permission to read the file, and gives users who are
+in the group that it is in permission to execute it, as well, but not
+permission to write to it.  The above command could be written in
+several different ways; another is:
+
+@example
+u+r,g+rx,o+r,g-w
+@end example
+
+@node     Umask and Modes
+@subsection The Effect of the Umask
+
+If the @var{users} part of a symbolic mode is omitted, it defaults to
+@samp{a} (affect all users), except that any permissions that are
+@emph{set} in the system variable @code{umask} are @emph{not affected}.
+The value of @code{umask} can be set using the
+@code{umask} command.  Its default value varies from system to system.
+
+As an example, if @code{umask} has the write permission set for users
+who are not in the group that it is in, the command:
+
+@example
++w
+@end example
+
+@noindent
+adds permission to write to the file to its owner and to other users
+who are in the group that the file is in, but @emph{not} to other
+users who are not in that group.  In contrast, the command:
+
+@example
+a+w
+@end example
+
+@noindent
+ignores @code{umask}, and @emph{does} give write permission for
+the file to all users.
+
+Omitting the @var{users} part of a symbolic mode is generally not useful
+with operations other than @samp{+}.  It is useful with @samp{+} because
+it allows you to use @code{umask} as an easily customizable protection
+against giving away more permission to files than you intended to.
+
+@node     Numeric Modes
+@section Numeric Modes
+
+File permission modes 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 the new
+mode.  This number is always interpreted in octal; you do not have to
+add a leading @samp{0}, as you do in C.  Leading zeros may be omitted;
+mode 0055 is the same as mode 55.
+
+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 three
+bits, which are represented as one octal digit.  The three special
+permissions are also each stored as one bit, and they are as a group
+represented as another octal digit.  Here is how the bits are arranged
+in the 16 bit integer, starting with the lowest valued bit:
+
+@display
+Value in  Corresponding
+Digit     Permission
+
+          Permissions for other users who are not in the file's group:
+1         Execute
+2         Write
+4         Read
+
+          Permissions for other users who are in the file's group:
+1         Execute
+2         Write
+4         Read
+
+          Permissions for the file's owner:
+1         Execute
+2         Write
+4         Read
+
+          Special permissions:
+1         Save text image on swap device
+2         Set group i.d. on execution
+4         Set user i.d. on execution
+@end display
+
+Therefore, 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
+@samp{ugo=}.  The numeric mode is usually shorter than the corresponding
+symbolic mode, but it is limited in that it can not take into account a
+file's previous permissions; it can only set them absolutely.
+
+As an example, to give the owner of a file and users who are in
+its group permission to read, write, and execute it, and give other
+users no permission to do anything to it, you can use the command:
+
+@example
+770
+@end example