HP-UX Reference (11i v3 07/02) - 3 Library Functions N-Z (vol 7)

s
strtoacl(3C) strtoacl(3C)
The @ character for user and group IDs (see acl(5)) is converted to special values (
ACL_FILEOWNER
or
ACL_FILEGROUP
, respectively, defined in
<acllib.h> ), not to specific user or group names provided
by the caller. Thus,
strtoaclpatt()
need not be called to reparse the ACL pattern for each file, but
the caller must handle the special values when comparing an ACL pattern to an ACL.
Wildcard user names, group names, and mode values are supported, as are absent mode parts; see acl(5).
strtoaclpatt()
returns a different structure than strtoacl() . The acl_entry_patt structure con-
tains onmode and offmode masks rather than a single mode value.
In operator form input, operators have a different effect on
strtoaclpatt()
:
= Sets bits in both the onmode and offmode fields appropriately, replacing existing bits in the
entry, including any set by earlier operators.
+ Sets bits in onmode and clears the same bits in offmode.
- Sets bits in offmode and clears the same bits in onmode.
In short form input, the mode is treated like the
= operator in operator form.
For both routines, a nonspecific user or group ID of
% is converted to
ACL_NSUSER or ACL_NSGROUP ,
respectively. For
strtoaclpatt() only, a wildcard user or group ID of * is converted to
ACL_ANYUSER or ACL_ANYGROUP , respectively. The values are defined in
<acllib.h> .
Entries can appear in string in any order. string can contain redundant entries, and in operator form only,
redundant
+ and - operators for ACL entry mode modifications (in exact form) or mode bit
inclusions/exclusions (in patterns). Entries or modifications are applied left to right.
Suggested Use
To build a new ACL (ACL pattern) array using strtoacl() (strtoaclpatt()
), define acl[] with
as many entries as desired. Pass it to
strtoacl() (strtoaclpatt()
) with nentries set to zero
(
strtoacl() only) and maxentries set to the number of elements in acl[].
To have strtoacl() modify a file’s existing ACL, define
acl[] with the maximum possible number of
entries (
NACLENTRIES ; see <sys/acl.h>).
Call getacl() (see getacl(2)) to read the file’s ACL and
stat() (see stat(2)) to get the file’s owner and group IDs. Then pass the current number of entries, the
current ACL, and the ID values to strtoacl() with maxentries set to NACLENTRIES .
If strtoacl() succeeds, the resulting ACL can be passed safely to setacl() (see setacl(2)) because all
redundancies (if any) have been resolved. However, note that since neither
strtoacl() nor
strtoaclpatt() validate user and group ID values, if the values are not acceptable to the system,
setacl() fails.
Performance Trick
Normally strtoacl() replaces user and group names of @ with specific user and group ID values, and
also combines redundant entries. Therefore, calling stat() and strtoacl() for each of a series of files
to which an ACL is being applied is simplest, although time consuming.
If string contains no @ character, or if the caller merely wants to compare one ACL against another (and
will handle the special case itself), it is sufficient to call strtoacl() once, and pointless to call
stat()
for each file. To determine this, call strtoacl() the first time with fuid set to ACL_FILEOWNER and
fgid set to
ACL_FILEGROUP. Repeated calls with file-specific fuid and fgid values are needed only if the
special values of fuid and fgid appear in acl[] and the caller needs an exact ACL to set on each file; see
the EXAMPLES section below.
If @ appears in string and acl[] will be used later for a call to setacl(), it is necessary to call
strtoacl() again to reparse the ACL string for each file. It is possible that not all redundant entries
were combined the first time because the @ names were not resolved to specific IDs. This also complicates
comparisons between two ACLs. Furthermore, the caller cannot do the combining later because operator
information from operator form input might be lost.
strtoacl_r() and strtoaclpatt_r() convert string form to access control list (ACL) structure.
RETURN VALUE
If strtoacl() (strtoaclpatt()) succeeds, it returns the number of entries in the resulting ACL
(ACL pattern), always equal to or greater than nentries (zero).
strtoaclpatt() also sets values in global array aclentrystart[] to point to the start of each pat-
tern entry it parsed in string, in some cases including leading or trailing whitespace. It only sets a number
HP-UX 11i Version 3: February 2007 − 2 − Hewlett-Packard Company 487