Document the new flags comments

2 files changed, 28 insertions, 16 deletions

diff --git a/man/man1/getfacl.1 b/man/man1/getfacl.1
index 967f72c..5fe60a1 100644
--- a/man/man1/getfacl.1
+++ b/man/man1/getfacl.1
@@ -49,29 +49,38 @@ The output format of getfacl is as follows:
  1:  # file: somedir/
  2:  # owner: lisa
  3:  # group: staff
- 4:  user::rwx
- 5:  user:joe:rwx               #effective:r\-x
- 6:  group::rwx                 #effective:r\-x
- 7:  group:cool:r\-x
- 8:  mask:r\-x
- 9:  other:r\-x
-10:  default:user::rwx
-11:  default:user:joe:rwx       #effective:r\-x
-12:  default:group::r\-x
-13:  default:mask:r\-x
-14:  default:other:\-\-\-
+ 4:  # flags: \-s\-
+ 5:  user::rwx
+ 6:  user:joe:rwx               #effective:r\-x
+ 7:  group::rwx                 #effective:r\-x
+ 8:  group:cool:r\-x
+ 9:  mask::r\-x
+10:  other::r\-x
+11:  default:user::rwx
+12:  default:user:joe:rwx       #effective:r\-x
+13:  default:group::r\-x
+14:  default:mask::r\-x
+15:  default:other::\-\-\-
 
 .fi
 .RE
 .fam T
 
-Lines 4, 6 and 9 correspond to the user, group and other fields of
+Lines 1\-\-3 indicate the file name, owner, and owning group.
+
+Line 4 indicates the setuid (s), setgid (s), and sticky (t) bits: either
+the letter representing the bit, or else a dash (\-). This line is
+included if any of those bits is set and left out otherwise, so it will
+not be shown for most files. (See CONFORMANCE TO POSIX 1003.1e DRAFT STANDARD\~17
+below.)
+
+Lines 5, 7 and 10 correspond to the user, group and other fields of
 the file mode permission bits. These three are called the base ACL
-entries. Lines 5 and 7 are named user and named group entries. Line 8 is
+entries. Lines 6 and 8 are named user and named group entries. Line 9 is
 the effective rights mask. This entry limits the effective rights granted
 to all groups and to named users. (The file owner and others permissions
 are not affected by the effective rights mask; all other entries are.)
-Lines 10\-\-14 display
+Lines 11\-\-15 display
 the default ACL associated with this directory. Directories may
 have a default ACL. Regular files never have a default ACL.
 
@@ -153,6 +162,7 @@ If the environment variable POSIXLY_CORRECT is defined, the default behavior of
 option is given. If no command line parameter is given,
 .I getfacl
 behaves as if it was invoked as ``getfacl \-''.
+No flags comments indicating the setuid, setgit, and sticky bits are generated.
 .SH AUTHOR
 Andreas Gruenbacher,
 .RI < a.gruenbacher@bestbits.at >.
diff --git a/man/man1/setfacl.1 b/man/man1/setfacl.1
index 000407f..25908e2 100644
--- a/man/man1/setfacl.1
+++ b/man/man1/setfacl.1
@@ -110,8 +110,10 @@ the input set are discarded. (A warning is issued if that happens).
 .I \-\-restore=file
 Restore a permission backup created by `getfacl \-R' or similar. All permissions
 of a complete directory subtree are restored using this mechanism. If the input
-contains owner comments or group comments, and setfacl is run by root, the
-owner and owning group of all files are restored as well. This option cannot be mixed with other options except `\-\-test'.
+contains owner comments or group comments, setfacl attempts to restore the
+owner and owning group. If the input contains flags comments (which define the setuid,
+setgid, and sticky bits), setfacl sets those three bits accordingly; otherwise,
+it clears them. This option cannot be mixed with other options except `\-\-test'.
 .TP 4
 .I \-\-test
 Test mode. Instead of changing the ACLs of any files, the resulting ACLs are listed.