acltostr_r(3c) [hpux man page]
acltostr(3C) acltostr(3C) NAME
acltostr() - convert access control list (ACL) structure to string form (HFS File Systems only) SYNOPSIS
Obsolescent Interface Remarks To ensure continued conformance with emerging industry standards, features described in this manual entry are likely to change in a future release. DESCRIPTION
converts an access control list from structure form to string representation. takes a pointer to the first element of an array of ACL entries containing the indicated number (nentries) of valid entries (zero or more), and the output form desired or It returns a pointer to a static string (overwritten by the next call), which is a symbolic representation of the ACL, ending in a null character. The output forms are described in acl(5). In long form, the string returned contains newline characters. A user ID of and a group ID of are both represented by As with the command (see ls(1)), if an entry contains any other user ID or group ID value not listed in or returns a string equivalent of the ID number instead. Just as in routines that manage the file, truncates user and group names to eight characters. Note: is complementary in function to Obsolescent Interface converts access control list (ACL) structure to string form. RETURN VALUE
If succeeds, it returns a pointer to a null-terminated string. If nentries is zero or less, the string is of zero length. If nentries is greater than (defined in or if form is an invalid value, the call returns (char *) NULL . If succeeds, it returns 0. If it fails, it returns -1 and sets If nentries is zero or less, the string is of zero length. ERRORS
strbuf equals to NULL, or nentries is greater than (defined in or form is not one of the valid forms, or length of strbuf is too short. length is less than or equal zero. EXAMPLES
The following code fragment reads the ACL on file and prints its short-form representation. #include <stdio.h> #include <acllib.h> int nentries; struct acl_entry acl [NACLENTRIES]; if ((nentries = getacl ("/users/ggd/test", NACLENTRIES, acl)) < 0) error (...); fputs (acltostr (nentries, acl, FORM_SHORT), stdout); WARNINGS
The value returned by is a pointer into a buffer, the contents of which are overwritten by subsequent calls to by the same thread. is an obsolescent interface supported only for compatibility with existing DCE applications. New multithreaded applications should use DEPENDENCIES
is only supported on HFS file system on standard HP-UX operating system. AUTHOR
was developed by HP. FILES
SEE ALSO
getacl(2), setacl(2), cpacl(3C), chownacl(3C), setaclentry(3C), strtoacl(3C), acl(5), thread_safety(5). acltostr(3C)
Check Out this Related Man Page
strtoacl(3C) strtoacl(3C) NAME
strtoacl(), strtoaclpatt(), aclentrystart[] - convert string form to access control list (ACL) structure (HFS File System only) SYNOPSIS
DESCRIPTION
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. 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 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 characters in string and returns the resulting number of entries in Redundant entries (identical user ID and group ID values after processing 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 special 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 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). returns a different structure than 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 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 con- verted to or respectively. The values are defined in 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 define with as many entries as desired. Pass it to with nentries set to zero only) and maxen- tries 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 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 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 necessary to call 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 com- plicates 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 trail- ing 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 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, 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 number). -8 Invalid group name (not found in file and not a valid number). -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. FILES
SEE ALSO
getacl(2), setacl(2), acltostr(3C), cpacl(3C), chownacl(3C), setaclentry(3C), acl(5), thread_safety(5). strtoacl(3C)