setacl(2)setacl(2)NAMEsetacl(), fsetacl() - set access control list (ACL) information
SYNOPSISDESCRIPTION
sets an existing file's access control list (ACL) or deletes optional
entries from it. path points to a path name of a file.
Similarly, sets an existing file's access control list for an open file
known by the file descriptor fildes.
A successful call to deletes all of a file's previous optional ACL
entries (see explanation below), if any. nentries indicates how many
valid entries are defined in the acl parameter. If nentries is zero or
greater, the new ACL is applied to the file. If any of the file's base
entries (see below) is not mentioned in the new ACL, it is retained but
its access mode is set to zero (no access). Hence, routine calls of
completely define the file's ACL.
As a special case, if nentries is negative (that is, a value of
(defined in the acl parameter is ignored, all of the file's optional
entries, if any, are deleted, and its base entries are left unaltered.
Some of the miscellaneous mode bits in the file's mode might be turned
off as a consequence of calling See chmod(2).
Access Control Lists
An ACL consists of a series of entries. Entries can be categorized in
four levels of specificity:
applies to user
u in group g
applies to user
u in any group
applies to any user in group
g
applies to any user in any group
Entries in the ACL must be unique; no two entries can have the same
user ID (uid) and group ID (gid) (see below). Entries can appear in
any order. The system orders them as needed for access checking.
The header file defines as the non-specific uid value and as the non-
specific gid value represented by above. If uid in an entry is it is a
entry. If gid in an entry is it is a entry. If both uid and gid are
non-specific, the file's entry is
The header file defines meanings of mode bits in ACL entries and Irrel‐
evant bits in mode values must be zero.
Every file's ACL has three base entries which cannot be added or
deleted, but only modified. The base ACL entries are mapped directly
from the file's permission bits.
(<file's owner> . ACL_NSGROUP, <file's owner mode bits>)
(ACL_NSUSER . <file's group>, <file's group mode bits>)
(ACL_NSUSER . ACL_NSGROUP, <file's other mode bits>)
In addition, up to 13 optional ACL entries can be set to restrict or
grant access to a file.
Altering a base ACL entry's modes with changes the file's corresponding
permission bits. The permission bits can be altered also by using (see
chmod(2)) and read using (see stat(2)).
The number of entries allowed per file (see in is small for space and
performance reasons. User groups should be created as needed for
access control purposes. Since ordinary users cannot create groups,
their ability to control file access with ACLs might be somewhat lim‐
ited.
Security Restrictions
The effective user ID of the process must match the owner of the file,
or it must be the superuser or a user with the privilege to set a
file's ACL.
See privileges(5) for more information about privileged access on sys‐
tems that support fine-grained privileges.
RETURN VALUE
and return the following values:
Successful completion.
Failure.
The file's ACL is not modified, and is set to indicate
the error.
ERRORS
fails if any of the following conditions are encountered:
A component of the
path prefix is not a directory.
The named file does not exist (for example,
path is null or a component of path does not exist).
A component of the
path prefix denies search permission.
The effective user ID
does not match the owner of the file and the effective
user ID is not superuser or does not have the privilege.
The named file resides on a read-only file system.
path or acl points outside the allocated address space of the
process, or acl is not as large as indicated by nen‐
tries.
There is a redundant entry in the
ACL, or acl contains an invalid uid, gid, or mode value.
An attempt was made to set an ACL with more than
entries.
The function is not supported on remote files by some
networking services.
The function is not supported by this file system type.
Not enough space on the file system.
System file table is full.
The length of path exceeds bytes, or the length of a component of path
exceeds bytes while is in effect.
Too many symbolic links were encountered in translating the
path name.
User's disk quota block or inode limit
has been reached for this file system.
fails if any of the following conditions are encountered:
fildes is not a valid file descriptor.
The effective user
ID does not match the owner of the file and the effec‐
tive user ID is not superuser or does not have the priv‐
ilege.
The named file resides on a read-only file system.
path or acl points outside the allocated address space of the
process, or acl is not as large as indicated by nen‐
tries.
There is a redundant entry in the ACL, or
acl contains an invalid uid, gid, or mode value.
An attempt was made to set an
ACL with more than entries.
The function is not supported on remote files by some
networking services.
The function is not supported by this file system type.
Not enough space on the file system.
System file table is full.
User's disk quota block or inode limit
has been reached for this file system.
EXAMPLES
The following code fragment defines and sets an ACL on file which
allows the file's owner to read, write, and execute or search the file,
and allows user 103, group 204 to read the file.
The following call deletes all optional ACL entries from
setacl ("file1", ACL_DELOPT, (struct acl_entry *) 0);
DEPENDENCIES
NFS
and are not supported on remote files.
HFS
ACLs are only supported on HFS file systems.
AUTHOR
and were developed by HP.
SEE ALSOaccess(2), chmod(2), getaccess(2), getacl(2), stat(2), acl(5), privi‐
leges(5), unistd(5).
setacl(2)