12288 getfacl and setfacl could stand improvement

@@ -1,19 +1,19 @@
 '\" te
+.\" Copyright (c) 2020 Peter Tribble.
 .\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.
 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH ACL 5 "Nov 24, 2014"
+.TH ACL 5 "Feb 8, 2020"
 .SH NAME
 acl \- Access Control Lists
 .SH DESCRIPTION
-.LP
 Access control lists (ACLs) are discretionary access control mechanisms that
 grant and deny access to files and directories. Two different ACL models are
-supported in the Solaris release: POSIX-draft ACLs and NFSv4 ACLs.
+supported in this release: POSIX-draft ACLs and NFSv4 ACLs.
 .sp
 .LP
 The older, POSIX-draft model is supported by the UFS file system. This model is
 based on a withdrawn ACL POSIX specification that was never standardized. It
 was subsequently withdrawn by the POSIX committee.

@@ -21,14 +21,13 @@
 .LP
 The other model is based on the standards of the NFSv4 working group and is an
 approved standard from the Internet Engineering Task Force (IETF). The ZFS file
 system uses the NFSv4 model, and provides richer semantics and finer grained
 permission capabilities than the POSIX-draft model.
-.SS "\fBPOSIX\fR-draft \fBACL\fRs"
-.LP
+.SS "POSIX-draft ACLs"
 POSIX-draft ACLs provide an alternative security mechanism to basic UNIX file
-permissions in the Solaris release. Their purpose is to further restrict access
+permissions. Their purpose is to further restrict access
 to files and directories or to extend permissions to a particular user. ACLs
 can be used to change the permissions for the standard owner, group and other
 class bits of a file's mode. ACLs can give additional users and groups access
 to the file. A directory can also have a special kind of ACL called a
 \fBdefault\fR ACL, which defines ACL entries to be inherited by descendents of

@@ -102,13 +101,12 @@
 user:joe:rw-
 .fi
 .in -2
 .sp
 
-.SS "\fBNFS\fRv4 \fBACL\fRs"
-.LP
-NFSv4 ACL model is based loosely on the Windows NT ACL model. NFSv4 ACLs
+.SS "NFSv4 ACLs"
+The NFSv4 ACL model is based loosely on the Windows NT ACL model. NFSv4 ACLs
 provide a much richer ACL model than POSIX-draft ACLs.
 .sp
 .LP
 The major differences between NFSv4 and POSIX-draft ACLs are as follows:
 .RS +4

@@ -149,11 +147,11 @@
 .RS +4
 .TP
 .ie t \(bu
 .el o
 NFSv4 ACLs provide a mechanism for hooking into a system's audit trail.
-Currently, Solaris does not support this mechanism.
+Currently, illumos does not support this mechanism.
 .RE
 .RS +4
 .TP
 .ie t \(bu
 .el o

@@ -538,14 +536,13 @@
 user:fred:rwR:f------:allow
 .fi
 .in -2
 .sp
 
-.SS "Shell-level Solaris \fBAPI\fR"
-.LP
-The Solaris command interface supports the manipulation of ACLs. The following
-Solaris utilities accommodate both ACL models:
+.SS "Shell-level API"
+Several utilities support the manipulation of ACLs. The following
+utilities accommodate both ACL models:
 .sp
 .ne 2
 .na
 \fB\fBchmod\fR\fR
 .ad

@@ -654,42 +651,41 @@
 .RS 12n
 When a file with an ACL is unpacked, the unpacked file retains the ACL
 information.
 .RE
 
-.SS "Application-level \fBAPI\fR"
-.LP
+.SS "Application-level API"
 The primary interfaces required to access file system ACLs at the programmatic
 level are the \fBacl_get()\fR and \fBacl_set()\fR functions. These functions
-support both POSIX draft ACLs and NFSv4 ACLs.
-.SS "Retrieving a file's \fBACL\fR"
+support both POSIX-draft ACLs and NFSv4 ACLs.
+.SS "Retrieving a file's ACL"
 .in +2
 .nf
 int acl_get(const char *path, int flag, acl_t **aclp);
 int facl_get(int fd, int flag, acl_t **aclp);
 .fi
 .in -2
 
 .sp
 .LP
-The \fBacl_get\fR(3SEC) and \fBfacl_get\fR(3SEC) functions retrieves an ACL on
+The \fBacl_get\fR(3SEC) and \fBfacl_get\fR(3SEC) functions retrieve an ACL on
 a file whose name is given by path or referenced by the open file descriptor
 fd. The flag argument specifies whether a trivial ACL should be retrieved. When
-the flag argument equals \fBACL_NO_TRIVIAL\fR then only ACLs that are not
+the flag argument equals \fBACL_NO_TRIVIAL\fR only ACLs that are not
 trivial are retrieved. The ACL is returned in the \fBaclp\fR argument.
-.SS "Freeing \fBACL\fR structure"
+.SS "Freeing ACL structure"
 .in +2
 .nf
-void acl_free(acl_t *aclp)s;
+void acl_free(acl_t *aclp);
 .fi
 .in -2
 
 .sp
 .LP
 The \fBacl_free()\fR function frees up memory allocated for the argument
-\fBaclp;\fR.
-.SS "Setting an \fBACL\fR on a file"
+\fBaclp\fR.
+.SS "Setting an ACL on a file"
 .in +2
 .nf
 int acl_set(const char *path, acl_t *aclp);
 int facl_set(int fd, acl_t *aclp);
 .fi

@@ -698,14 +694,14 @@
 .sp
 .LP
 The \fBacl_set\fR(3SEC) and \fBfacl_get\fR(3SEC) functions are used for setting
 an ACL on a file whose name is given by path or referenced by the open file
 descriptor \fBfd\fR. The \fBaclp\fR argument specifies the ACL to set. The
-\fBacl_set\fR(3SEC) translates an POSIX-draft ACL into a NFSv4 ACL when the
-target file systems supports NFSv4 ACLs. No translation is performed when
+\fBacl_set\fR(3SEC) function translates a POSIX-draft ACL into a NFSv4 ACL when
+the target file system supports NFSv4 ACLs. No translation is performed when
 trying to set an NFSv4 ACL on a POSIX-draft ACL supported file system.
-.SS "Determining an \fBACL\fR's trivialness"
+.SS "Determining an ACL's trivialness"
 .in +2
 .nf
 int acl_trivial(const char *path);
 .fi
 .in -2

@@ -712,11 +708,11 @@
 
 .sp
 .LP
 The \fBacl_trivial()\fR function is used to determine whether a file has a
 trivial ACL.
-.SS "Removing all \fBACL\fRs from a file"
+.SS "Removing all ACLs from a file"
 .in +2
 .nf
 int acl_strip(const char *path, uid_t uid, gid_t gid, mode_t mode);
 .fi
 .in -2

@@ -725,11 +721,11 @@
 .LP
 The \fBacl_strip()\fR function removes all ACLs from a file and replaces them
 with a trivial ACL based off of the passed in argument mode. After replacing
 the ACL the owner and group of the file are set to the values specified in the
 uid and gid parameters.
-.SS "Converting \fBACL\fRs to/from external representation"
+.SS "Converting ACLs to/from external representation"
 .in +2
 .nf
 int acl_fromtext(const char *path, acl_t **aclp);
 char *acl_totext(acl_t *aclp, int flags);
 .fi

@@ -740,15 +736,14 @@
 The \fBacl_totext()\fR function converts an internal ACL representation pointed
 to by aclp into an external representation. See \fBDESCRIPTION\fR for details
 about external representation.
 .sp
 .LP
-The \fBacl_fromtext()\fR functions converts and external representation into an
+The \fBacl_fromtext()\fR function converts an external representation into an
 internal representation. See \fBDESCRIPTION\fR for details about external
 representation.
 .SH EXAMPLES
-.LP
 The following examples demonstrate how the API can be used to perform basic
 operations on ACLs.
 .LP
 \fBExample 1 \fRRetrieving and Setting an ACL
 .sp

@@ -829,11 +824,10 @@
 \&...
 .fi
 .in -2
 
 .SH SEE ALSO
-.LP
 \fBchgrp\fR(1), \fBchmod\fR(1), \fBchown\fR(1), \fBcp\fR(1), \fBcpio\fR(1),
 \fBfind\fR(1), \fBls\fR(1), \fBmv\fR(1), \fBtar\fR(1), \fBsetfacl\fR(1),
 \fBchmod\fR(2), \fBacl\fR(2), \fBstat\fR(2), \fBacl_get\fR(3SEC),
 \fBaclsort\fR(3SEC), \fBacl_fromtext\fR(3SEC), \fBacl_free\fR(3SEC),
 \fBacl_strip\fR(3SEC), \fBacl_trivial\fR(3SEC)