man/apply-default-acl.1: add a note about the --recursive exit codes.

[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 bfbb724a8a7bea5121daa92e4051defa6442375a..b13d5fd910990ff22520668d8e48df74bd1ef3ab 100644 (file)
--- a/doc/man/apply-default-acl.1
+++ b/doc/man/apply-default-acl.1
@@ -12,8 +12,8 @@ apply-default-acl \- Apply default POSIX ACLs to files and directories.
 .P
 If the directory containing \fIpath\fR has a default ACL, the ACL on
 \fIpath\fR is replaced with that default. Neither symbolic nor hard
-links are followed.
-
+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,
@@ -21,19 +21,40 @@ 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
 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
 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 EXIT CODE
+.P
+When given a single path, the following codes correspond directly to
+the action of the program on that path:
+.IP \fB0\ (EXIT_SUCCESS)\fR
+Success
+.IP \fB1\ (EXIT_FAILURE)\fR
+Failure due to a symlink, hardlink, or invalid/inaccessible path
+.IP \fB2\fP
+Other unexpected library error
+.P
+When called on multiple paths, the results from all paths are
+collected and the \(dqworst\(dq result is returned. For example, if
+one path succeeds and another fails, the overall result will be
+failure. If one succeeds, one fails, and one causes an error, then the
+overall result will be an error; and so on.
+.P
+The \fB\-\-recursive\fR flag modifies this behavior. Due to an
+implementation detail, the recursive operation will return
+EXIT_SUCCESS even if it encounters links or inaccessible paths during
+the traversal. Beware; this means that manually supplying all children
+of a directory on the command-line does not act the same as operating
+on that directory recursively.