doc: use bold face for "mkdir" and "touch".

[apply-default-acl.git] / doc / man / apply-default-acl.1

diff --git a/doc/man/apply-default-acl.1 b/doc/man/apply-default-acl.1
index 87e9803c916f514f5e34020d97c8e7caf0486042..42233f1f7bd219b573a682ea41dbfa435408ac28 100644 (file)
--- a/doc/man/apply-default-acl.1
+++ b/doc/man/apply-default-acl.1
@@ -5,7 +5,7 @@ apply-default-acl \- Apply default POSIX ACLs to files and directories.
 
 .SH SYNOPSIS
 
-\fBapply-default-acl\fR [\fB-rx\fR] \fIpath\fR [\fIpath2 ...\fR]
+\fBapply-default-acl\fR [\fB-r\fR] \fIpath\fR [\fIpath2 ...\fR]
 
 .SH DESCRIPTION
 
@@ -15,14 +15,12 @@ If the directory containing \fIpath\fR has a default ACL, the ACL on
 links are followed; symbolic links are ignored in all path components
 to avoid a dangerous race condition.
 .P
-By default, a heuristic is used to determine whether or not the
-execute bit is masked on \fIpath\fR. If \fIpath\fR is not a directory,
-and no user or group has \fBeffective\fR execute permissions on
-\fIpath\fR, then the execute bit will not masked. Otherwise, it is
-left alone. In effect we pretend that the \fBx\fR permission acts like
+A heuristic is used to determine whether or not the execute bits are
+removed from \fIpath\fR. If \fIpath\fR is a directory or if some user
+or group has \fBeffective\fR execute permissions on \fIpath\fR, then
+the execute bits will be left alone. Otherwise, they will be
+removed. In effect we pretend that the \fBx\fR permission acts like
 the \fBX\fR (note the case difference) permission of \fBsetfacl\fR.
-.P
-This behavior can be modified with the \fB--no-exec-mask\fR flag.
 
 .SH OPTIONS
 .IP \fB\-\-recursive\fR,\ \fB\-r\fR
@@ -30,10 +28,63 @@ Apply default ACLs recursively. This works top-down, so if directory
 \fBfoo\fR is in another directory \fBbar\fR which has a default ACL,
 then \fBbar\fR's default ACL will be applied to \fBfoo\fR before the
 contents of \fBfoo\fR are processed.
-.IP \fB\-\-no-exec-mask\fR,\ \fB\-x\fR
-Apply the default ACL literally; that is, don't use a heuristic to
-decide whether or not to mask the execute bit. This usually results in
-looser-than-necessary execute permissions.
+
+.SH ALGORITHM
+.IP "I. Argument validation" 0.4i
+.RS
+.IP "a. If any part of the target path contains a symlink" 0.4i
+Return failure
+.IP "b. If there is no default ACL to apply"
+Return success
+.IP "c. If the target is not a (non-hardlink) regular file or directory"
+Return failure
+.RE
+.IP "II. ACL application"
+.RS
+.IP "a. If the target is a directory" 0.4i
+Set the target's default ACL equal to its parent's default ACL
+.IP "b. Set the target's access ACL equal to its parent's default ACL"
+.IP "c. If the target is a directory"
+Return success
+.IP "d. If the target was executable by anyone"
+Return success
+.IP "e. Unset the user/group/other/mask execute bits"
+.IP "f. Return success"
+.RE
+.P
+The action of apply-default ACL largely mimics what the kernel would
+do if you ran \fBmkdir\fR or \fBtouch\fR to create a new file. The one
+point of disagreement is on how to mask group-execute permissions for
+files. The kernel will let the \(dqmask\(dq bits prevent group-execute,
+whereas apply-default-acl will explicitly remove the group-execute bits.
+For example,
+
+.nf
+.I $ mkdir herp
+.I $ setfacl --default --modify user:mjo:rw herp
+.I $ touch herp/derp
+.I $ getfacl --omit-header herp/derp
+user::rw-
+user:mjo:rw-
+group::r-x                     #effective:r--
+mask::rw-
+other::r--
+.fi
+
+In the same situation, apply-default-acl will mask the group \fBx\fR bit:
+
+.nf
+.I $ apply-default-acl herp/derp
+.I $ getfacl --omit-header herp/derp
+user::rw-
+user:mjo:rw-
+group::r--
+mask::rw-
+other::r--
+.fi
+
+The author is of the opinion that the latter is more sensible, if not
+simply more consistent.
 
 .SH EXIT CODE
 .P