acl(2)
acl --
set 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);
Description
The
acl
system call is used to manipulate ACLs on file system objects.
- pathp
-
points to a pathname naming a file.
- nentries
-
specifies how many ACL entries are pointed to by aclbufp.
- aclbufp
-
is a pointer to the first element of an array of struct acl.
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.
Mandatory Access Control (MAC) write access to the file is required.
- 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.
Mandatory Access Control (MAC) read access to the file is required.
- 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.
Mandatory read access to the file is required.
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 success, acl returns the number of ACL entries for
cmd ACL_CNT and ACL_GET, and 0 for
cmd ACL_SET.
On failure, acl returns -1 and sets errno to identify the error.
Errors
In the following conditions, acl fails and sets errno to:
- EACCES
-
The caller does not have access to a component of the pathname
- EACCES
-
The caller does not have mandatory read access to the file for
ACL_GET and ACL_CNT, or mandatory write access to
the file for ACL_SET.
- 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). aclmax.
- 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
-
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 aclmax.
- ENOTDIR
-
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)
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.