strtoacl(3C)

NAME

strtoacl(), strtoaclpatt(), aclentrystart — convert string form to access control list (ACL) structure, HFS file system only

SYNOPSIS

#include <acllib.h> 

int strtoacl( 
     const char *string, 
     int nentries, 
     int maxentries, 
     struct acl_entry *acl, 
     uid_t fuid, 
     gid_t fgid); 

int strtoaclpatt( 
     const char *string, 
     int maxentries, 
     struct acl_entry_patt *acl); 

int strtoacl_r( 
     const char *string, 
     int nentries, 
     int maxentries, 
     struct acl_entry *acl, 
     uid_t fuid, 
     gid_t fgid, 
     char *entrystart[]); 

int strtoaclpatt_r( 
     const char *string, 
     int maxentries, 
     struct acl_entry_patt *acl 
     char *entrystart[]); 

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 the ERRORS section below.

The "operator" and "short" symbolic forms of ACLs and ACL patterns (described in acl(5)) are acceptable as input strings. If the first nonwhitespace 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 added to the end of the acl array.

strtoaclpatt()

strtoaclpatt() differs from strtoacl() in that 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 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 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 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 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 (...); 
} 

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; 
} 

DEPENDENCIES

strtoacl() and strtoaclpatt() are only supported on HFS file systems on standalone HP-UX operating systems.

AUTHOR

strtoacl() and strtoaclpatt() were developed by HP.

FILES

/etc/passwd
/etc/group