acl(2)

acl -- manipulate a file's Access Control List (ACL)

facl- manipulate a file's Access Control List (ACL)

Synopsis

   #include <sys/types.h>
   #include <acl.h>
   
   int acl(char *pathp, int cmd, int nentries, struct acl *aclbufp);
   

   int facl(int *fd, int cmd, int nentries, struct acl *aclbufp);

Description

The acl and facl system calls are used to manipulate ACLs on file system objects. These calls are valid only on sfs and vxfs file system types.

pathp

a pointer to a pathname naming a file.

fd

an open file descriptor (obtained, for example, from a call to open(2)) referencing a file.

nentries

the number of ACL entries pointed to by aclbufp.

aclbufp

a pointer to the first element of an array of struct acl data structures. This type is defined in sys/acl.h as follows:

   	struct acl {
   	     int     a_type;        /* entry type */
   	     uid_t   a_id;          /* user or group ID */
   	     ushort  a_perm;        /* entry permissions */
   	};

The values for a_type are:

USER_OJB: Permissions for the owner of the object.
USER: Permissions for additional users.
GROUP_OBJ: Permissions for members of the owning group of the object.
GROUP: Permissions for members of additional groups.
CLASS_OBJ: Maximum permissions granted to the file group class.
OTHER_OBJ: Permissions for other users.
DEF_USER_OBJ: Default permissions for the object owner.
DEF_USER: Default permissions for additional users.
DEF_GROUP_OBJ: Default permissions for members of the owning group of the object.
DEF_GROUP: Default permissions for members of additional groups
DEF_CLASS_OBJ: Default maximum permissions granted to the file group class.
DEF_OTHER_OBJ: Default permissions for other users.

cmd

The following values for cmd are available:

ACL_SET: nentries ACL entries, specified in buffer aclbufp, are stored in the file's ACL. Any existing ACL on the file is replaced by the new ACL. This value for cmd can only be executed by a process that has an effective user ID equal to the owner of the file, or by a process with the P_OWNER privilege. All directories in the pathname must be searchable.
ACL_GET: Buffer aclbufp is filled with the file's ACL entries. Discretionary read access to the file is not required, but all directories in the pathname must be searchable.
ACL_CNT: The number of entries in the file's ACL is returned. Discretionary read access to the file is not required, but all directories in the pathname must be searchable.

For command ACL_SET, the acl call will succeed if all of the following are true:

There is exactly one entry each of type USER_OBJ, GROUP_OBJ, CLASS_OBJ, and OTHER_OBJ.
There is at most one entry each of type DEF_USER_OBJ, DEF_GROUP_OBJ, DEF_CLASS_OBJ, and DEF_OTHER_OBJ.
Entries of type USER, GROUP, DEF_USER, or DEF_GROUP may not contain duplicate entries. A duplicate entry is one of the same type containing the same numeric ID.
If an ACL contains no entries of type USER and no entries of type GROUP, then the entries of type GROUP_OBJ and CLASS_OBJ must have the same permissions.
If an ACL contains no entries of type DEF_USER and no entries of type DEF_GROUP, and an entry of type DEF_GROUP_OBJ is specified, then an entry of type DEF_CLASS_OBJ must also be specified and the two entries must have the same permissions.

Return values

On failure, ``-1'' is returned and errno is set to identify the error (see below for errno values). The return value on success depends on the cmd specified. For ACL_CNT and ACL_GET, the number of ACL entries is returned on success. For ACL_SET, ``0'' is returned on success.

Errors

On failure, errno is set to one of the following values:

EACCES: (acl only) The caller does not have access to a component of the pathname specified by pathp.
EACCES: The caller does not have read access to the file for ACL_GET and ACL_CNT, or write access to the file for ACL_SET.
EBADF: (facl only) fd is not an open file descriptor.
EINVAL: cmd is not ACL_GET, ACL_SET, or ACL_CNT.
EINVAL: cmd is ACL_SET and nentries is less than the number of mandatory ACL entries (4).
EINVAL: cmd is ACL_SET and the ACL specified in aclbufp is not valid [see aclsort(3C)].
EIO: A disk I/O error has occurred while storing or retrieving the ACL.
EPERM: cmd is ACL_SET and the effective user ID of the caller does not match the owner of the file, and the caller does not have the P_OWNER privilege to perform the operation.
ENOENT: (acl only) A component of the path does not exist.
ENOSPC: cmd is ACL_GET and nentries is less than the number of entries in the file's ACL.
ENOSPC: cmd is ACL_SET and there is insufficient space to store the ACL.
ENOSPC: cmd is ACL_SET and nentries is greater than the tunable parameter MAXACL.
ENOTDIR: (acl only) A component of the path specified by pathp is not a directory.
ENOTDIR: cmd is ACL_SET and an attempt is made to set a default ACL on a file type other than a directory.
ENOSYS: cmd is ACL_SET, the file specified by pathp resides on a file system that does not support ACLs, and additional entries were specified in the ACL.
EROFS: cmd is ACL_SET and the file specified by pathp resides on a file system that is mounted read-only.
EFAULT: aclbufp points to an illegal address.

References

aclipc(2), aclsort(3C), getacl(1), setacl(1)