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]
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 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
For NFSv4 ACLs, the ACL entries will be formatted using the compact ACL format detailed in ls(1) for the -V option.
Append the uid or gid for additional user or group entries. This flag is used to construct ACL entries in a manner that is suitable for archive utilities such as tar(1). When the ACL is translated from the external format to internal representation using acl_fromtext(), the appended ID will be used to populate the uid or gid field of the ACL entry when the user or group name does not exist on the host system. The appended id will be ignored when the user or group name does exist on the system.
Do not translate the numeric identifier (uid, gid, or sid) found in ACL entries into a name.
For NFSv4 ACLs, the ACL entries for user or group entries will use the usersid or groupsid format when the "id" field in the ACL entry is an ephemeral uid or gid. The raw sid format will only be used if ACL_NORESOLVE is also present in flags or if the "id" cannot be resolved to a windows name.
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@
This ACL entry specifies the access granted to any user or group that does not match any previous ACL entry.
This ACL entry with a GID specifies the access granted to a additional group of the object.
This ACL entry with no GID specified in the ACL entry field specifies the access granted to the owning group of the object.
This ACL entry with a SID or Windows name specifies the access granted to a Windows group. This type of entry is for a CIFS server created file.
This ACL entry with no UID specified in the ACL entry field specifies the access granted to the owner of the object.
This ACL entry with a SID or Windows name when the entry could be either a group or a user.
This ACL entry with a UID specifies the access granted to a additional user of the object.
This ACL entry with a SID or Windows name specifies the access granted to a Windows user. This type of entry is for a CIFS server created file.
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
This field contains a user-name or user-ID. If the user-name cannot be resolved to a UID, then the entry is assumed to be a numeric UID.
This field contains a group-name or group-ID. If the group-name can't be resolved to a GID, then the entry is assumed to be a numeric 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 a file to a directory.
Add a subdirectory.
Append data.
Delete.
Delete child.
Execute permission.
List a directory.
Read ACL.
Read permission.
Read attributes.
Read named attributes.
Synchronize.
Write ACL.
Write attributes.
Write permission.
Write owner.
Write named attributes.
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
read attributes
write attributes
read ACL
write ACL
delete
delete child
write owner
append
read_data
read named attributes
synchronize
write_data
write named attributes
execute
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
ACE_DIRECTORY_INHERIT_ACE
ACE_FILE_INHERIT_ACE
ACE_INHERIT_ONLY_ACE
ACE_NO_PROPAGATE_INHERIT_ACE
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
dir_inherit
file_inherit
failed access (not currently supported)
inherit_only
no_propagate
successful access (not currently supported)
The fifth field contains the type of the ACE (allow or deny): allow
The mask specified in field three should be allowed.
The mask specified in field three should be denied.
Upon successful completion, the acl_fromtext() function returns 0. Otherwise, the return value is set to one of the following: EACL_FIELD_NOT_BLANK
A field that should be blank is not blank.
An invalid ACL flag was specified.
An invalid inheritance field was specified.
An invalid access type was specified.
The string is NULL.
The required user or group name not found.
The ACL needs more fields to be specified.
The permission mask is invalid.
Unknown data was found in the ACL.
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
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| Interface Stability Committed |
| MT-Level Safe |