te
Copyright (c) 20068 Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
acl_totext, acl_fromtext - convert internal representation to or from external representation

cc [ flag.\|.\|. ] file.\|.\|. -lsec [ library.\|.\|. ]
#include <sys/acl.h>

char *acl_totext(acl_t *aclp, int flags);

int acl_fromtext(char *acltextp, acl_t **aclp);

The acl_totext() function converts an internal ACL representation pointed to by aclp into an external ACL representation. The memory for the external text string is obtained using malloc(3C). The caller is responsible for freeing the memory upon completion.

The format of the external ACL is controlled by the flags argument. Values for flags are constructed by a bitwise-inclusive-OR of flags from the following list, defined in <sys/acl.h>. ACL_COMPACT_FMT

ACL_APPEND_ID ACL_SID_FMT

The acl_fromtext() function converts an external ACL representation pointed to by acltextp into an internal ACL representation. The memory for the list of ACL entries is obtained using malloc(3C). The caller is responsible for freeing the memory upon completion. Depending on type of ACLs a file system supports, one of two external external representations are possible. For POSIX draft file systems such as ufs, the external representation is described in acltotext(3SEC). The external ACL representation For NFSv4-style ACLs is detailed as follows.

Each acl_entry contains one ACL entry. The external representation of an ACL entry contains three, four or five colon separated fields. The first field contains the ACL entry type. The entry type keywords are defined as: everyone@

group group@ groupsid owner@ sid user usersid

The second field contains the ACL entry ID, and is used only for user or group ACL entries. This field is not used for owner@, group@, or everyone@ entries. uid

gid

The third field contains the discretionary access permissions. The format of the permissions depends on whether ACL_COMPACT_FMT is specified. When the flags field does not request ACL_COMPACT_FMT, the following format is used with a forward slash (/) separating the permissions. add_file

add_subdirectory append delete delete_child execute list_directory read_acl read_data read_attributes read_xattr synchronize write_acl write_attributes write_data write_owner write_xattr

This format allows permissions to be specified as, for example: read_data/read_xattr/read_attributes.

When ACL_COMPACT_FMT is specified, the permissions consist of 14 unique letters. A hyphen (-) character is used to indicate that the permission at that position is not specified. a

A c C d D o p r R s w W x

This format allows compact permissions to be represented as, for example: rw--d-a-------

The fourth field is optional when ACL_COMPACT_FMT is not specified, in which case the field will be present only when the ACL entry has inheritance flags set. The following is the list of inheritance flags separated by a slash (/) character. dir_inherit

file_inherit inherit_only no_propagate

When ACL_COMPACT_FMT is specified the inheritance will always be present and is represented as positional arguments. A hyphen (-) character is used to indicate that the inheritance flag at that position is not specified. d

f F i n S

The fifth field contains the type of the ACE (allow or deny): allow

deny

Upon successful completion, the acl_totext() function returns a pointer to a text string. Otherwise, it returns NULL.

Upon successful completion, the acl_fromtext() function returns 0. Otherwise, the return value is set to one of the following: EACL_FIELD_NOT_BLANK

EACL_FLAGS_ERROR EACL_INHERIT_ERROR EACL_INVALID_ACCESS_TYPE EACL_INVALID_STR EACL_INVALID_USER_GROUP EACL_MISSING_FIELDS EACL_PERM_MASK_ERROR EACL_UNKNOWN_DATA

Example 1 Examples of permissions when ACL_COMPACT_FMT is not specified.

user:joe:read_data/write_data:file_inherit/dir_inherit:allow

owner@:read_acl:allow,user:tom:read_data:file_inherit/inherit_only:deny

Example 2 Examples of permissions when ACL_COMPACT_FMT is specified.

user:joe:rw------------:fd----:allow

owner@:----------c---:------allow,user:tom:r-------------:f-i---:deny

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Committed

MT-Level Safe

ls(1), tar(1), acl(2), malloc(3C), aclfromtext(3SEC), acl(5), attributes(5)