HP-UX Reference (11i v3 07/02) - 2 System Calls (vol 5)

s
setacl(2) setacl(2)
NAME
setacl(), fsetacl() - set access control list (ACL) information
SYNOPSIS
#include <sys/acl.h>
int setacl(
const char *path,
int nentries,
const struct acl_entry *acl
);
int fsetacl(
int fildes,
int nentries,
const struct acl_entry *acl
);
DESCRIPTION
setacl() 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,
fsetacl() sets an existing file’s access control list for an open file known by the file descriptor
fildes.
A successful call to setacl() 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
setacl() completely define the file’s ACL.
As a special case, if nentries is negative (that is, a value of ACL_DELOPT (defined in
<sys/acl.h> ), 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
setacl(). See chmod(2).
Access Control Lists
An ACL consists of a series of entries. Entries can be categorized in four levels of specificity:
(u.g, mode) applies to user u in group g
(
u.%, mode) applies to user u in any group
(
%.g, mode) applies to any user in group g
(
%.%, mode) 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
<sys/acl.h> header file defines ACL_NSUSER as the non-specific uid value and
ACL_NSGROUP
as the non-specific gid value represented by % above. If uid in an entry is ACL_NSUSER,itisa%.g entry.
If gid in an entry is ACL_NSGROUP ,itisau.% entry. If both uid and gid are non-specific, the file’s entry
is %.%.
The <unistd.h> header file defines meanings of mode bits in ACL entries (R_OK, W_OK, and X_OK).
Irrelevant 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 setacl() changes the file’s corresponding permission bits. The
permission bits can be altered also by using chmod() (see chmod(2)) and read using stat() (see stat(2)).
HP-UX 11i Version 3: February 2007 − 1 − Hewlett-Packard Company 387