Add additional documentation to setfacl(1) regarding the behavior of

tools such as chmod(1) and ls(1) when it comes to acting on objects
that have POSIX.1e extended ACLs.  Specifically, discuss the
substitution of the mask entry for the group entry in the mode
representation of the ACL.  Differently worded from the submission,
and could probably use further refinement.

PR:		55319
Submitted by:	Grzegorz Czaplinski <G.Czaplinski@prioris.mini.pw.edu.pl>

1 files changed, 18 insertions, 0 deletions

diff --git a/bin/setfacl/setfacl.1 b/bin/setfacl/setfacl.1
index 43eba960d1e0..452a0411b287 100644
--- a/bin/setfacl/setfacl.1
+++ b/bin/setfacl/setfacl.1
@@ -185,6 +185,24 @@ with all
 .Dq Li group
 ACL entries in the resulting ACL.
 .Pp
+Traditional POSIX interfaces acting on file system object modes have
+modified semantics in the presence of POSIX.1e extended ACLs.
+When a mask entry is present on the access ACL of an object, the mask
+entry is substituted for the group bits; this occurs in programs such
+as
+.Xr stat 1
+or
+.Xr ls 1 .
+When the mode is modified on an object that has a mask entry, the
+changes applied to the group bits will actually be applied to the
+mask entry.
+These semantics provide for greater application compatibility:
+applications modifying the mode instead of the ACL will see
+conservative behavior, limiting the effective rights granted by all
+of the additional user and group entries; this occurs in programs
+such as
+.Xr chmod 1 .
+.Pp
 ACL entries applied from a file using the
 .Fl M
 or