HPUX strtoacl[3c]
strtoacl(3C) strtoacl(3C)
NAME
strtoacl(), strtoaclpatt(), aclentrystart() - convert exact or pattern
string form to access control list (ACL) structure
SYNOPSIS
#include <acllib.h>
int strtoacl(
const char *string,
int nentries,
int maxentries,
struct acl_entry *acl,
int fuid,
int fgid
);
int strtoaclpatt(
const char *string,
int maxentries,
struct acl_entry_patt *acl
);
DESCRIPTION
strtoacl() converts an access control list from exact symbolic
(string) representation 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.
strtoaclpatt() converts an access control list pattern from symbolic
(string) representation to structure form. It parses the input string
and verifies its validity.
The external array aclentrystart[], 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.
strtoacl() takes a pointer to the string to be converted, and a
pointer to the first element of an array of ACL entries (acl[])
initially containing the indicated number (nentries) of valid entries
(zero or more). This array can grow to the indicated number of
entries (maxentries). strtoacl() also takes file user ID (fuid) and
group ID (fgid) values to substitute for @ characters in string and
returns the resulting number of entries in acl[].
Redundant entries (identical user ID and group ID values after
processing @ characters) are combined, so that acl[] contains unique
entries in the order encountered. If a new entry is mentioned, it is
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
strtoacl(3C) strtoacl(3C)
added to the end of the acl array.
strtoaclpatt()
strtoaclpatt() differs from strtoacl() 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
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 contains 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 non-specific 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()
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
strtoacl(3C) strtoacl(3C)
(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 EXAMPLES
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.
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 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
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
strtoacl(3C) strtoacl(3C)
NACLENTRIES + 1). The last valid element points to the null character
at the end of string. After calling strtoaclpatt(), an entry
pattern'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, strtoacl() and strtoaclpatt() return a negative
value and the content of acl is undefined (was probably altered). To
help with error reporting in this case, aclentrystart[0] and
aclentrystart[1] 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 (, aclentrystart[1] points to the
next null character or comma at or after aclentrystart[0]. 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 (strtoacl() 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 /etc/passwd file and not a
valid number).
-8 Invalid group name (not found in /etc/group file and not a
valid number).
-9 Syntax error: invalid mode character, other than 0..7, r, w,
x, - (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, 0..7 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
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
strtoacl(3C) strtoacl(3C)
for the file's group.
#include <acllib.h>
int nentries;
struct acl_entry acl [NACLENTRIES];
if ((nentries = strtoacl (string, 0, NACLENTRIES, acl, 103, 45)) < 0)
error (...);
The following code gets the ACL, fuid, and fgid for file ../myfile,
modifies the ACL using a description string, and changes the ACL on
file ../myfile2 to be the new version.
#include <sys/types.h>
#include <sys/stat.h>
#include <acllib.h>
struct stat statbuf;
int nentries;
struct acl_entry acl [NACLENTRIES];
if (stat ("../myfile", & statbuf) < 0)
error (...);
if ((nentries = getacl ("../myfile", NACLENTRIES, acl)) < 0)
error (...);
if ((nentries = strtoacl (string, nentries, NACLENTRIES, acl,
statbuf.st_uid, statbuf.st_gid)) < 0)
{
error (...);
}
if (setacl ("../myfile2", nentries, acl) < 0)
error (...);
The following code fragment calls strtoacl() with special values of
fuid and fgid, then checks to see if they show up in acl[].
#include <acllib.h>
int perfile = 0; /* need to stat() and reparse per file? */
int entry;
if ((nentries = strtoacl (string, 0, NACLENTRIES, acl,
ACL_FILEOWNER, ACL_FILEGROUP)) < 0)
{
error (...);
}
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992
strtoacl(3C) strtoacl(3C)
for (entry = 0; entry < nentries; entry++)
{
if ((acl [entry] . uid == ACL_FILEOWNER)
|| (acl [entry] . gid == ACL_FILEGROUP))
{
perfile = 1;
break;
}
}
The following code fragment converts an ACL pattern from a string to
an array of pattern entries.
#include <acllib.h>
int nentries;
struct acl_entry_patt acl [NACLENTRIES];
if ((nentries = strtoaclpatt (string, NACLENTRIES, acl)) < 0)
error (...);
The following code fragment inside a for loop checks an entry pattern
(p*, onmask, and offmask variable names) against an entry in a file's
ACL (a* variable names) using the file's user and group IDs (f*
variable names).
include <unistd.h>
if (((puid == ACL_FILEOWNER) && (fuid != auid))
|| ((puid != ACL_ANYUSER) && (puid != auid)))
{
continue;
}
if (((pgid == ACL_FILEGROUP) && (fgid != agid))
|| ((pgid != ACL_ANYGROUP) && (pgid != agid)))
{
continue;
}
if (((( amode) & MODEMASK & onmask ) != onmask)
|| (((~ amode) & MODEMASK & offmask) != offmask))
{
continue;
}
AUTHOR
strtoacl() and strtoaclpatt() were developed by HP.
FILES
/etc/passwd
/etc/group
Hewlett-Packard Company - 6 - HP-UX Release 9.0: August 1992
strtoacl(3C) strtoacl(3C)
SEE ALSO
getacl(2), setacl(2), acltostr(3C), cpacl(3C), chownacl(3C),
setaclentry(3C), acl(5).
Hewlett-Packard Company - 7 - HP-UX Release 9.0: August 1992