strtoacl(3C)strtoacl(3C)NAMEstrtoacl(), strtoaclpatt(), aclentrystart[] - convert string form to
access control list (ACL) structure (HFS File System only)
SYNOPSISDESCRIPTION
converts an access control list from exact symbolic (string) represen‐
tation to structure form. It parses the input string and verifies its
validity. Optionally it applies the entries in the string as a series
of changes to an existing ACL.
converts an access control list pattern from symbolic (string) repre‐
sentation to structure form. It parses the input string and verifies
its validity.
The external array only valid until the next call of either routine, is
useful for error reporting. See ERRORS below.
The ``operator'' and ``short'' symbolic forms of ACLs and ACL patterns
(described in acl(5)) are acceptable as input strings. If the first
non-whitespace character in string is the ACL or ACL pattern in string
must be in short form. Otherwise operator form is assumed.
takes a pointer to the string to be converted, and a pointer to the
first element of an array of ACL entries initially containing the indi‐
cated number (nentries) of valid entries (zero or more). This array
can grow to the indicated number of entries (maxentries). also takes
file user ID (fuid) and group ID (fgid) values to substitute for char‐
acters in string and returns the resulting number of entries in
Redundant entries (identical user ID and group ID values after process‐
ing characters) are combined, so that contains unique entries in the
order encountered. If a new entry is mentioned, it is added to the end
of the array.
strtoaclpatt()
differs from because it processes an ACL pattern instead of an ACL.
Since modification of an existing initial ACL is not useful, it is not
supported.
Entries with matching user and group ID values are not combined. Each
entry input yields one entry in the returned array.
The character for user and group IDs (see acl(5)) is converted to spe‐
cial values (or respectively, defined in not to specific user or group
names provided by the caller. Thus, need not be called to reparse the
ACL pattern for each file, but the caller must handle the special val‐
ues 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).
returns a different structure than 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
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 non-specific user or group ID of is converted to
or respectively. For only, a wildcard user or group ID of is converted
to or respectively. The values are defined in
Entries can appear in string in any order. string can contain redun‐
dant entries, and in operator form only, redundant and operators for
ACL entry mode modifications (in exact form) or mode bit inclu‐
sions/exclusions (in patterns). Entries or modifications are applied
left to right.
Suggested Use
To build a new ACL (ACL pattern) array using define with as many
entries as desired. Pass it to with nentries set to zero only) and
maxentries set to the number of elements in
To have modify a file's existing ACL, define with the maximum possible
number of entries see Call (see getacl(2)) to read the file's ACL and
(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 with
maxentries set to
If succeeds, the resulting ACL can be passed safely to (see setacl(2))
because all redundancies (if any) have been resolved. However, note
that since neither nor validate user and group ID values, if the values
are not acceptable to the system, fails.
Performance Trick
Normally replaces user and group names of with specific user and group
ID values, and also combines redundant entries. Therefore, calling and
for each of a series of files to which an ACL is being applied is sim‐
plest, although time consuming.
If string contains no character, or if the caller merely wants to com‐
pare one ACL against another (and will handle the special case itself),
it is sufficient to call once, and pointless to call for each file. To
determine this, call the first time with fuid set to and fgid set to
Repeated calls with file-specific fuid and fgid values are needed only
if the special values of fuid and fgid appear in and the caller needs
an exact ACL to set on each file; see EXAMPLES below.
If appears in string and will be used later for a call to it is neces‐
sary to call again to reparse the ACL string for each file. It is pos‐
sible that not all redundant entries were combined the first time
because the names were not resolved to specific IDs. This also compli‐
cates comparisons between two ACLs. Furthermore, the caller cannot do
the combining later because operator information from operator form
input might be lost.
and convert string form to access control list (ACL) structure.
RETURN VALUE
If succeeds, it returns the number of entries in the resulting ACL (ACL
pattern), always equal to or greater than nentries (zero).
also sets values in global array to point to the start of each pattern
entry it parsed in string, in some cases including leading or trailing
whitespace. It only sets a number of pointers equal to its return
value plus one (never more than + 1). The last valid element points to
the null character at the end of string. After calling an entry pat‐
tern's corresponding input string can be used by the caller for error
reporting by (temporarily) putting a null at the start of the next
entry pattern in string.
ERRORS
If an error occurs, and return a negative value and the content of is
undefined (was probably altered). To help with error reporting in this
case, and are set to point to the start of the current and next
entries, respectively, being parsed when the error occurred. If the
current entry does not start with points to the next null character or
comma at or after Otherwise, it points to the next null, or to the
character following the next
The following values are returned in case of error:
−1 Syntax error: entry doesn't start with as expected in short
form.
−2 Syntax error: entry doesn't end with as expected in short
form.
−3 Syntax error: user name is not terminated by a dot.
−4 only) Syntax error: group name is not terminated by an
operator in operator-form input or a comma in short-form
input.
−5 Syntax error: user name is null.
−6 Syntax error: group name is null.
−7 Invalid user name (not found in file and not a valid num‐
ber).
−8 Invalid group name (not found in file and not a valid num‐
ber).
−9 Syntax error: invalid mode character, other than (allowed
in short form only), (allowed in patterns only), (to end an
entry in operator form), or (to end an entry in short
form). Or, or is followed by other mode characters.
−10 The resulting ACL would have more than maxentries entries.
EXAMPLES
The following code fragment converts an ACL from a string to an array
of entries using an fuid of 103 for the file's owner and fgid of 45 for
the file's group.
The following code gets the ACL, fuid, and fgid for file modifies the
ACL using a description string, and changes the ACL on file to be the
new version.
The following code fragment calls with special values of fuid and fgid,
then checks to see if they show up in
The following code fragment converts an ACL pattern from a string to an
array of pattern entries.
The following code fragment inside a loop checks an entry pattern and
variable names) against an entry in a file's ACL variable names) using
the file's user and group IDs variable names).
DEPENDENCIES
and are only supported on HFS file system on standalone HP-UX operating
system.
AUTHOR
and were developed by HP.
FILESSEE ALSOgetacl(2), setacl(2), acltostr(3C), cpacl(3C), chownacl(3C), setaclen‐
try(3C), acl(5), thread_safety(5).
strtoacl(3C)