Tribblix: manual page: acl

ACL_TOTEXT(3SEC) File Access Control Library Functions ACL_TOTEXT(3SEC)

NAME

acl_totext, acl_fromtext - convert internal representation to or
from external representation

SYNOPSIS

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);

DESCRIPTION

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
For NFSv4 ACLs, the ACL entries will be formatted
using the compact ACL format detailed in ls(1) for
the -V option.

ACL_APPEND_ID
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.

ACL_NORESOLVE
Do not translate the numeric identifier (uid, gid,
or sid) found in ACL entries into a name.

ACL_SID_FMT
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.

group
This ACL entry with a GID specifies the access granted
to a additional group of the object.

group@
This ACL entry with no GID specified in the ACL entry
field specifies the access granted to the owning group
of the object.

groupsid
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.

owner@
This ACL entry with no UID specified in the ACL entry
field specifies the access granted to the owner of the
object.

sid
This ACL entry with a SID or Windows name when the entry
could be either a group or a user.

user
This ACL entry with a UID specifies the access granted
to a additional user of the object.

usersid
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.

gid
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_subdirectory
Add a subdirectory.

append
Append data.

delete
Delete.

delete_child
Delete child.

execute
Execute permission.

list_directory
List a directory.

read_acl
Read ACL.

read_data
Read permission.

read_attributes
Read attributes.

read_xattr
Read named attributes.

synchronize
Synchronize.

write_acl
Write ACL.

write_attributes
Write attributes.

write_data
Write permission.

write_owner
Write owner.

write_xattr
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

A
write attributes

c
read ACL

C
write ACL

d
delete

D
delete child

o
write owner

p
append

r
read_data

R
read named attributes

s
synchronize

w
write_data

W
write named attributes

x
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

file_inherit
ACE_FILE_INHERIT_ACE

inherit_only
ACE_INHERIT_ONLY_ACE

no_propagate
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

f
file_inherit

F
failed access (not currently supported)

i
inherit_only

n
no_propagate

S
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.

deny
The mask specified in field three should be denied.

RETURN VALUES

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
A field that should be blank is not
blank.

EACL_FLAGS_ERROR
An invalid ACL flag was specified.

EACL_INHERIT_ERROR
An invalid inheritance field was
specified.

EACL_INVALID_ACCESS_TYPE
An invalid access type was specified.

EACL_INVALID_STR
The string is NULL.

EACL_INVALID_USER_GROUP
The required user or group name not
found.

EACL_MISSING_FIELDS
The ACL needs more fields to be
specified.

EACL_PERM_MASK_ERROR
The permission mask is invalid.

EACL_UNKNOWN_DATA
Unknown data was found in the ACL.

EXAMPLES

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

ATTRIBUTES