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_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 when 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
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+
SEE ALSO
ls(1),
tar(1),
acl(2),
malloc(3C),
aclfromtext(3SEC),
acl(7),
attributes(7) June 16, 2008
ACL_TOTEXT(3SEC)