acl_from_text() — Create an ACL from text

Standards

Standards / Extensions	C or C++	Dependencies
z/OS® UNIX	both	z/OS V1R3

Format

#define _OPEN_SYS	1
#include <sys/acl.h>

int 	acl_from_text (const char *buf_p, short OpType, acl_all_t ptr, char **ret);

General description

Use access control lists (ACLs) in conjunction with permission bits to control access to files and directories. Currently, ACLs are supported by the HFS, TFS, and zFS file systems. You must know whether your security product supports ACLs and what rules are used when determining file access. See z/OS UNIX System Services Planning for details.

The acl_from_text() function converts the text form of an ACL referred to by buf_p into the acl_t form of an ACL. It parses both the extended and base ACL entries.

If successful, the structure that ptr points to will be updated with ACL entries for the 3 types of ACLs. The structure members that ptr points to must either be NULL or point to a valid acl_t structure. If the structure member is not NULL, ACL entries contained in buf_p will be merged in. New storage for those structure members may be allocated as needed and in that case passed-in storage will be freed, so structure members may point to a different storage than the one originally supplied.

If ptr is NULL, the acl_from_text will fail. If the buf_p has no ACL entries (such as empty string, only empty lines, etc), acl_from_text() will fail with errno set to EINVAL and ret will point to the null terminator in buf_p.

Working storage is allocated for the individual ACLs structures as needed and need to be freed using acl_free().

If the function is unsuccessful due to error encountered in parsing, ret will contain the address of beginning of extended/base ACL entry where the error was found in buf_p and errno will be set to EINVAL. Otherwise ret will be NULL.

The text form of the ACL referred to by buf_p may be incomplete or may be a non-valid ACL as defined by acl_valid(). The buf_p must be null terminated. The first call to acl_get_entry() following the call to acl_from_text() obtains the first entry in the ACL as ordered by the system.

For OpType =ACL_DELETE, the extended ACL entries will be updated with the flag bit to be removed from the ACL when acl_set_fd() or acl_set_file() is called. The base ACL entries are parsed but not put into the structure that ptr points to since you cannot delete base ACL entries.

The buf_p cannot have a mixture of ACL entry delimiters (newline and comma). All ACL entries in the buf must use the same delimiter, either a newline or comma. For a mixture of delimiters, acl_from_text() will fail with errno set to EINVAL and ret parameter will point to the delimiter in error.

acl_all_t :

index 0: access acl
index 1: file default acl
index 2: directory default acl

Valid text input format based on OpType:

tag: fdefault, default (access if nothing is specified)
type: user, group, other
id: uid, gid, username, groupname
perm: rwx ( or '-' for no permission), octal (0-7) , +/^ (where + is turn on and ^ is turn off)

Pound sign (#) is used to designate a comment. When the input is separated by commas, everything past # is treated as a comment. When the input is separated by a newline, everything after # till the newline is considered a comment. Comments are ignored and are not stored in the buffer.

	ACL_ADD		tag:type:id:perm	// extended ACL entry
				type::perm    	// base ACL entry
	ACL_MODIFY	same as ACL_ADD
	ACL_DELETE	tag:type:id		// extended ACL entry

Note: The extended ACL entries must have the type (group or user) and the id (uid/gid). The base ACL entries do not have a value for the id field. The id field or the lack of one is what distinguishes the base ACL entry from the extended ACL entry. The base ACL entries do not have the tag fields since they only apply to access ACL.

The acl_from_text() allows for trailing ACL entry separator (newline or comma). For relative permission settings, only one of '+' or '^' is allowed per ACL entry. When using relative permissions you must have at least one of r, w, or x. For example: +rw or ^rwx.

Returned value

Upon successful completion, the function returns a zero.

If any of the following conditions occur, the acl_from_text() function returns -1 and sets errno to the corresponding value:

Error Code: Description
EINVAL: Argument buf_p cannot be translated into an ACL.
ENOMEM: The ACL working storage requires more memory than is available.
E2BIG: The number of base ACL entries exceeded allowable 3.

The ret will contain the address in buf_p where the error was found.