acltostr(3C)

NAME

acltostr(), acltostr_r() − convert access control list (ACL) structure to string form

SYNOPSIS

#include <acllib.h>

char *acltostr(int nentries, const struct acl_entry acl[], int form);

int acltostr_r(

int nentries,
const struct acl_entry acl[],
int form,
char *strbuf,
int length);

Remarks:

To ensure continued conformance with emerging industry standards, features described in this manual entry are likely to change in a future release.

DESCRIPTION

acltostr() converts an access control list from structure form to string representation. acltostr() takes a pointer to the first element of an array of ACL entries (acl), containing the indicated number (nentries) of valid entries (zero or more), and the output form desired (FORM_SHORT or FORM_LONG). 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 ACL_NSUSER and a group ID of ACL_NSGROUP are both represented by %. As with the ls command (see ls(1)), if an entry contains any other user ID or group ID value not listed in /etc/passwd or /etc/group, acltostr() returns a string equivalent of the ID number instead.

Just as in routines that manage the /etc/passwd file, acltostr() truncates user and group names to eight characters.

Note: acltostr() is complementary in function to strtoacl().

Reentrant Interfaces

acltostr_r() expects to be passed two extra parameters:

strbuf a pointer to a string buffer to store the converted string

length the length of strbuf

A length of 512 is recommended.

RETURN VALUE

If acltostr() 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 NACLENTRIES (defined in <sys/acl.h>), or if form is an invalid value, the call returns (char ∗) NULL.

If acltostr_r() succeeds, it returns 0. If it fails, it returns -1 and sets errno. If nentries is zero or less, the string is of zero length.

ERRORS

[EINVAL] strbuf equals to NULL, or nentries is greater than NACLENTRIES (defined in <sys/acl.h>), or form is not one of the valid forms, or length of strbuf is too short.

[ERANGE] length is less than or equal zero.

EXAMPLES

The following code fragment reads the ACL on file /users/ggd/test 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 acltostr() is a pointer into a static buffer, the contents of which are overwritten by each call. Thus, acltostr() is not safe in multi-thread applications. acltostr_r() is MT-Safe and should be used instead.

AUTHOR

acltostr() was developed by HP.

FILES

/etc/passwd
/etc/group

Museum

Related Articles