United States-English |
|
|
HP-UX Reference > Ssetacl(2)HP-UX 11i Version 3: February 2007 |
|
NAMEsetacl(), 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 ); DESCRIPTIONsetacl() 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 ListsAn ACL consists of a series of entries. Entries can be categorized in four levels of specificity:
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, it is a %.g entry. If gid in an entry is ACL_NSGROUP, it is a u.% 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)). The number of entries allowed per file (see NACLENTRIES in <sys/acl.h>) 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 limited. Security RestrictionsThe effective user ID of the process must match the owner of the file, or it must be the superuser or a user with the OWNER privilege to set a file's ACL. See privileges(5) for more information about privileged access on systems that support fine-grained privileges. RETURN VALUEsetacl() and fsetacl() return the following values:
ERRORSsetacl() fails if any of the following conditions are encountered:
fsetacl() fails if any of the following conditions are encountered:
EXAMPLESThe following code fragment defines and sets an ACL on file ../shared 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. #include <unistd.h> #include <sys/stat.h> #include <sys/acl.h> char *filename = "../shared"; struct acl_entry acl [2]; struct stat statbuf; if (stat (filename, & statbuf) < 0) error (...); acl [0] . uid = statbuf . st_uid; /* file owner */ acl [0] . gid = ACL_NSGROUP; acl [0] . mode = R_OK | W_OK | X_OK; acl [1] . uid = 103; acl [1] . gid = 204; acl [1] . mode = R_OK; if (setacl (filename, 2, acl)) error (...); The following call deletes all optional ACL entries from file1: setacl ("file1", ACL_DELOPT, (struct acl_entry *) 0); |
Printable version | ||
|