fshash.in: Support POSIX ACLs and extended attributes.

[rsync-backup] / fshash.1

diff --git a/fshash.1 b/fshash.1
index 8577d65b57001a0495ce59bccab61cdc6049cb41..0c4ee9ddbd0a29c815dfd35f6b5c9e45ab0c19ea 100644 (file)
--- a/fshash.1
+++ b/fshash.1
@@ -109,7 +109,7 @@ were made with the bugs.  By default,
 produces manifests in the most recent format, but this option will force
 it to be compatible with old versions.  The original version was 1; all
 later versions print a comment reporting the version number at the start
-of the manifest.  The current version is 2.
+of the manifest.  The current version is 3.
 .TP
 .B \-H, \-\-hash=\fIhash
 Use the
@@ -134,8 +134,11 @@ is treated specially:
 .B fshash
 writes filenames relative to the given directory.
 .SS Output format
-Information about each filesystem object is written on a separate line.
-These lines can be quite long, and consist of a number of fields:
+For each filesystem object,
+.B fshash
+writes a summary line, followed by zero or more additional lines.
+A summary line can be quite long, and consists of a number of
+fields:
 .hP 1.
 For regular files, a cryptographic hash of the file's content, in
 hexadecimal.  For other kinds of filesystem object, a description of the
@@ -229,6 +232,82 @@ or
 as appropriate, followed by the major and minor device numbers in
 decimal, and separated by a colon.
 .PP
+Additional lines begin with a tab character.  The possible lines are as
+follows.
+.TP
+.I POSIX ACLs
+.RS
+If an object has nontrivial POSIX ACLs, then they are printed as additional
+lines of the form
+.IP
+.BI "acl posix-access " acl
+.PP
+or
+.IP
+.BI "acl posix-default " acl
+.PP
+for access and default ACLs respectively.  The
+.I acl
+is the ACL in short text format, with numeric IDs, and with the entries
+sorted into a canonical order (owner, other users, mask, file group, other
+groups, others), or
+.BI <E nn \~ message >
+if there was an error retrieving the ACL.
+.PP
+An access ACL is nontrivial if it contains entries for
+other users, other groups, or a mask, i.e., it is not completely described by
+the file's traditional permissions.  A default ACL is nontrivial if it is not
+empty.
+.PP
+POSIX ACLs are recognized at compatibility level 3 and above.  ACL
+support requires the
+.B pylibacl
+library.
+.RE
+.TP
+.I Extended attributes
+.RS
+If a file has extended attributes then they are printed as additional lines
+of the form
+.IP
+.BI "xattr " name " " hash
+.PP
+where
+.I name
+is the attribute name, escaped in the same manner as filenames, and
+.I hash
+is the hash of the attribute's contents.  Extended attribute hashes are not
+currently cached, because they're usually too small for it to be worthwhile.
+If errors occur, then
+.BI <E nn \~ message >
+is printed in place of the
+.I hash
+if the error occurred when trying to retrieve the attribute value,
+or in place of both
+.I name
+and
+.I hash
+if the error occurred when trying to list the attributes.
+.PP
+The
+.B fshash
+program does not print lines for extended attributes which are used to
+implement features which
+.B fshash
+handles explicitly: for example, on Linux, POSIX ACLs are stored in extended
+attributes named
+.B system.posix_acl_access
+and
+.BR system.posix_acl_default ,
+so these attributes are ignored if ACL support is available.
+.PP
+Extended attributes are recognized at compatibility level 3 and above.
+Extended attribute support requires the
+.B pyxattr
+or
+.B xattr
+library, or Python 3.3.
+.RE
 .SH BUGS
 No attempt is made to sort filenames read in
 .B find0