From: Paul Eggert <eggert@cs.ucla.edu>
Date: Tue, 31 Jan 2023 21:52:39 +0000 (-0800)
Subject: doc: document --preserve=mode better
X-Git-Tag: v9.2~73
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7a8db7dbafc932cb08403b863a1c1edec5d283ca;p=thirdparty%2Fcoreutils.git

doc: document --preserve=mode better

* doc/coreutils.texi: Spruce up cp --preserve=mode doc.
---

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 143b93de9b..97c5280d3f 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -8972,7 +8972,13 @@ of one or more of the following strings:
 
 @table @samp
 @item mode
-Preserve the file mode bits and access control lists.
+@cindex access control lists (ACLs)
+Preserve attributes relevant to access permissions,
+including file mode bits and (if possible) access control lists (ACLs).
+ACL preservation is system-dependent, and ACLs are not necessarily
+translated when the source and destination are on file systems with
+different ACL formats (e.g., NFSv4 versus POSIX formats).
+
 @item ownership
 Preserve the owner and group.  On most modern systems,
 only users with appropriate privileges may change the owner of a file,
@@ -9014,6 +9020,7 @@ $ mkdir b c; (cd b; : > a; ln -s a b); cp -aL b c; ls -i1 c/b
 @item context
 Preserve SELinux security context of the file, or fail with full diagnostics.
 @item xattr
+@cindex access control lists (ACLs)
 Preserve extended attributes of the file, or fail with full diagnostics.
 If @command{cp} is built without xattr support, ignore this option.
 If SELinux context, ACLs or Capabilities are implemented using xattrs,