Improve this man page significantly; more helpful, easier to read, and easier

to learn how chmod(1) works. Oh, and trash those useless BNF grammars.

1 files changed, 145 insertions, 110 deletions

diff --git a/bin/chmod/chmod.1 b/bin/chmod/chmod.1
index 99226fd3b61..699c0c5ad99 100644
--- a/bin/chmod/chmod.1
+++ b/bin/chmod/chmod.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: chmod.1,v 1.13 1999/07/04 18:59:38 aaron Exp $
+.\"	$OpenBSD: chmod.1,v 1.14 1999/09/23 02:37:00 aaron Exp $
 .\"	$NetBSD: chmod.1,v 1.8 1995/03/21 09:02:07 cgd Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993, 1994
@@ -61,10 +61,14 @@ operand. The mode of a file dictates its permissions, among other attributes.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
+.It Fl R
+Recursively descend through any specified directory arguments.
+Change the modes of the file hierarchies rooted in the files
+instead of just the files themselves.
 .It Fl H
 If the
 .Fl R
-option is also specified, symbolic links on the command-line are followed.
+option is also specified, symbolic links on the command line are followed.
 (Symbolic links encountered in the tree traversal are not followed.)
 .It Fl L
 If the
@@ -74,9 +78,6 @@ option is also specified, all symbolic links are followed.
 If the
 .Fl R
 option is also specified, no symbolic links are followed.
-.It Fl R
-Change the modes of the file hierarchies rooted in the files
-instead of just the files themselves.
 .El
 .Pp
 Symbolic links do not have modes, so unless the
@@ -88,7 +89,7 @@ option is set,
 on a symbolic link always succeeds and has no effect.
 The
 .Fl H ,
-.Fl L
+.Fl L ,
 and
 .Fl P
 options are ignored unless the
@@ -103,36 +104,65 @@ the mode of a file.
 The
 .Nm
 utility exits 0 on success or >0 if an error occurred.
-.Sh MODES
-Modes may be absolute or symbolic.
-An absolute mode is an octal number constructed by ORing
-the following values:
+.Ss Absolute mode
+Absolute modes are specified according to the following format:
+.Bd -filled -offset indent
+.Nm chmod
+.Ar nnnn
+.Ar file
+.Op Ar ...
+.Ed
+.Pp
+An absolute mode is an octal number (specified as
+.Ar nnnn ,
+where
+.Ar n
+is a number from 0 to 7) constructed by ORing
+any of the following values:
 .Pp
 .Bl -tag -width 6n -compact -offset indent
-.It Li 4000
-set-user-ID on execution
-.It Li 2000
-set-group-ID on execution
-.It Li 1000
-sticky bit, see
-.Xr sticky 8
-and
-.Xr chmod 2
 .It Li 0400
-read by owner
+Allow read by owner.
 .It Li 0200
-write by owner
+Allow write by owner.
 .It Li 0100
-execute (or search in directories) by owner
+Allow execution (or search in directories) by owner.
+.It Li 0700
+Allow read, write, and execute/search by owner.
+.It Li 0040
+Allow read by group.
+.It Li 0020
+Allow write by group.
+.It Li 0010
+Allow execution (or search in directories) by group.
 .It Li 0070
-read, write, execute/search by group
+Allow read, write, and execute/search by group.
+.It Li 0004
+Allow read by others.
+.It Li 0002
+Allow write by others.
+.It Li 0001
+Allow execution (or search in directories) by others.
 .It Li 0007
-read, write, execute/search by others
+Allow read, write, and execute/search by others.
 .El
 .Pp
-The read, write, and execute/search values for group and others
-are encoded as described for owner. The execute bit for a directory is often
-referred to as the
+In addition to the file permission modes, the following mode bits are
+available:
+.Pp
+.Bl -tag -width 6n -compact -offset indent
+.It Li 4000
+Set-user-ID on execution.
+.It Li 2000
+Set-group-ID on execution.
+.It Li 1000
+Enable sticky bit; see
+.Xr sticky 8
+and
+.Xr chmod 2 .
+.El
+.Pp
+The execute bit for a directory is often referred to as the
 .Dq search
 bit. In order to access a file, a user must have execute permission in each
 directory leading up to it in the filesystem hierarchy. For example, to access
@@ -144,32 +174,40 @@ execute permission is needed on
 and, of course, the
 .Pa ls
 binary itself.
+.Ss Symbolic mode
+Symbolic modes are specified according to the following format:
 .Pp
-The symbolic mode is described by the following grammar:
-.Bd -literal -offset indent
-mode         ::= clause [, clause ...]
-clause       ::= [who ...] [action ...] last_action
-action       ::= op [perm ...]
-last_action  ::= op [perm ...]
-who          ::= a | u | g | o
-op           ::= + | \- | =
-perm         ::= r | s | t | w | x | X | u | g | o
+.Bd -filled -offset indent
+.Nm chmod
+.Sm off
+.Ao
+.Op Ar who
+.Ar op
+.Op Ar perm
+.Ac Ns Li , Oo
+.Op Ar who
+.Ar op
+.Op Ar perm
+.Oc Ns Li , Op Ar ...
+.Sm on
+.Op Ar
 .Ed
 .Pp
 The
 .Ar who
-symbols
-.Sq u ,
-.Sq g ,
-and
-.Sq o
-specify the user, group, and other parts
-of the mode bits, respectively. The
-.Ar who
-symbol
-.Sq a
-is equivalent to
-.Sq ugo .
+symbols indicate whose permissions are to be changed or assigned:
+.Pp
+.Bl -tag -width 4n -compact -offset indent
+.It u
+User (owner) permissions.
+.It g
+Group permissions.
+.It o
+Others permissions.
+.It a
+All of the above.
+.El
+.Pp
 Do not confuse the
 .Sq o
 symbol with
@@ -179,41 +217,6 @@ It is the user bit,
 that refers to the owner of the file.
 .Pp
 The
-.Ar perm
-symbols represent the portions of the mode bits as follows:
-.Pp
-.Bl -tag -width Ds -compact -offset indent
-.It r
-The read bits.
-.It s
-The set-user-ID- and set-group-ID-on-execution bits.
-.It t
-The sticky bit.
-.It w
-The write bits.
-.It x
-The execute/search bits.
-.It X
-The execute/search bits if the file is a directory or any of the
-execute/search bits are set in the original (unmodified) mode.
-Operations with the
-.Ar perm
-symbol
-.Sq X
-are only meaningful in conjunction with the
-.Ar op
-symbol
-.Sq + ,
-and are ignored in all other cases.
-.It u
-The user permission bits in the mode of the original file.
-.It g
-The group permission bits in the mode of the original file.
-.It o
-The other permission bits in the mode of the original file.
-.El
-.Pp
-The
 .Ar op
 symbols represent the operation performed, as follows:
 .Bl -tag -width 4n -offset indent
@@ -271,13 +274,48 @@ and
 values are set.
 .El
 .Pp
-Each
-.Ar clause
-specifies one or more operations to be performed on the mode
-bits, and each operation is applied to the mode bits in the
-order specified.
+The
+.Ar perm
+(permission symbols) represent the portions of the mode bits as follows:
 .Pp
-Operations upon the other permissions only (specified by the symbol
+.Bl -tag -width Ds -compact -offset indent
+.It r
+Read bits.
+.It s
+Set-user-ID and set-group-ID on execution bits.
+.It t
+Sticky bit.
+.It w
+Write bits.
+.It x
+Execute/search bits.
+.It X
+The execute/search bits if the file is a directory or any of the
+execute/search bits are set in the original (unmodified) mode.
+Operations with the
+.Ar perm
+symbol
+.Sq X
+are only meaningful in conjunction with the
+.Ar op
+symbol
+.Sq + ,
+and are ignored in all other cases.
+.It u
+User permission bits in the mode of the original file.
+.It g
+Group permission bits in the mode of the original file.
+.It o
+Other permission bits in the mode of the original file.
+.El
+.Pp
+Each clause (given in a comma-delimited list on the command line) specifies
+one or more operations to be performed on the mode bits, and each operation is
+applied in the order specified.
+.Pp
+Operations upon the
+.Dq other
+permissions (specified by the symbol
 .Sq o
 by itself), in combination with the
 .Ar perm
@@ -286,42 +324,39 @@ symbols
 or
 .Sq t ,
 are ignored.
-.Pp
-Care must be taken when granting elevated privileges to a program through the
-set-user-ID (suid) and set-group-ID (sgid) bits. Do not apply
-.Sq s
-bits to executables you do not trust. Indeed, the source code which makes up
-the suid/sgid binaries shipped with
-.Bx Open
-has been heavily audited by talented developers. Beware of suid/sgid binaries
-from third-party sources and practice safe programming.
 .Sh EXAMPLES
-.Bl -tag -width "u=rwx,go=u-w" -compact
-.It Li 644
 Make a file readable by anyone and writable by the owner only.
 .Pp
-.It Li go-w
+.Dl Ic  chmod 644 file
+.Pp
 Deny write permission to group and others.
 .Pp
-.It Li =rw,+X
+.Dl Ic  chmod go-w file
+.Pp
 Set the read and write permissions to the usual defaults, but
 retain any execute permissions that are currently set.
 .Pp
-.It Li +X
+.Dl Ic  chmod =rw,+X file
+.Pp
 Make a directory or file searchable/executable by everyone if it is
 already searchable/executable by anyone.
 .Pp
-.It Li 755
-.It Li u=rwx,go=rx
-.It Li u=rwx,go=u-w
-Make a file readable/executable by everyone and writable by the owner only.
+.Dl Ic  chmod +X file
+.Pp
+Any of the following will make a file readable/executable by everyone and
+writable by the owner only.
+.Pp
+.Dl Ic  chmod 755 file
+.Dl Ic  chmod u=rwx,go=rx file
+.Dl Ic  chmod u=rwx,go=u-w file
 .Pp
-.It Li go=
 Clear all mode bits for group and others.
 .Pp
-.It Li g=u-w
+.Dl Ic  chmod go= file
+.Pp
 Set the group bits equal to the user bits, but clear the group write bit.
-.El
+.Pp
+.Dl Ic  chmod g=u-w file
 .Sh SEE ALSO
 .Xr chgrp 1 ,
 .Xr install 1 ,