'\" 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]
.TH ACL_TOTEXT 3SEC "Jun 16, 2008"
.SH NAME
acl_totext, acl_fromtext \- convert internal representation  to or from
external representation
.SH SYNOPSIS
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lsec\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <sys/acl.h>

\fBchar *\fR\fBacl_totext\fR(\fBacl_t *\fR\fIaclp\fR, \fBint\fR \fIflags\fR);
.fi

.LP
.nf
\fBint\fR \fBacl_fromtext\fR(\fBchar *\fR\fIacltextp\fR, \fBacl_t **\fR\fIaclp\fR);
.fi

.SH DESCRIPTION
The \fBacl_totext()\fR function converts an internal ACL representation pointed
to by \fIaclp\fR into an external ACL representation. The memory for the
external text string is obtained using \fBmalloc\fR(3C). The caller is
responsible for freeing the memory upon completion.
.sp
.LP
The format of the external ACL is controlled by the \fIflags\fR argument.
Values for \fIflags\fR are constructed by a bitwise-inclusive-OR of \fIflags\fR
from the following list, defined in <\fBsys/acl.h\fR>.
.sp
.ne 2
.na
\fB\fBACL_COMPACT_FMT\fR\fR
.ad
.RS 19n
For NFSv4 ACLs, the ACL entries will be formatted using the compact ACL format
detailed in \fBls\fR(1) for the \fB-V\fR option.
.RE

.sp
.ne 2
.na
\fB\fBACL_APPEND_ID\fR\fR
.ad
.RS 19n
Append the \fBuid\fR or \fBgid\fR 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 \fBtar\fR(1). When the ACL is translated from the external
format to internal representation using \fBacl_fromtext()\fR, the appended ID
will be used to populate the \fBuid\fR or \fBgid\fR 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.
.RE

.sp
.ne 2
.na
\fB\fBACL_SID_FMT\fR\fR
.ad
.RS 19n
For NFSv4 ACLs, the ACL entries for user or group entries will use the
\fBusersid\fR or \fBgroupsid\fR format when the "id" field in the ACL entry is
an ephemeral \fBuid\fR or \fBgid\fR.  The raw \fBsid\fR format will only be
used when the "id" cannot be resolved to a windows name.
.RE

.sp
.LP
The \fBacl_fromtext()\fR function converts an external ACL representation
pointed to by \fIacltextp\fR into an internal ACL representation. The memory
for the list of ACL entries is obtained using \fBmalloc\fR(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 \fBacltotext\fR(3SEC). The external ACL representation For
NFSv4-style ACLs is detailed as follows.
.sp
.LP
Each \fBacl_entry\fR 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:
.sp
.ne 2
.na
\fB\fBeveryone@\fR\fR
.ad
.RS 13n
This ACL entry specifies the access granted to any user or group that does not
match any previous ACL entry.
.RE

.sp
.ne 2
.na
\fB\fBgroup\fR\fR
.ad
.RS 13n
This ACL entry with a GID specifies the access granted to a additional group of
the object.
.RE

.sp
.ne 2
.na
\fB\fBgroup@\fR\fR
.ad
.RS 13n
This ACL entry with no GID specified in the ACL entry field specifies the
access granted to the owning group of the object.
.RE

.sp
.ne 2
.na
\fB\fBgroupsid\fR\fR
.ad
.RS 13n
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.
.RE

.sp
.ne 2
.na
\fB\fBowner@\fR\fR
.ad
.RS 13n
This ACL entry with no UID specified in the ACL entry field specifies the
access granted to the owner of the object.
.RE

.sp
.ne 2
.na
\fB\fBsid\fR\fR
.ad
.RS 13n
This ACL entry with a SID or Windows name when the entry could be either a
group or a user.
.RE

.sp
.ne 2
.na
\fB\fBuser\fR\fR
.ad
.RS 13n
This ACL entry with a UID specifies the access granted to a additional user of
the object.
.RE

.sp
.ne 2
.na
\fB\fBusersid\fR\fR
.ad
.RS 13n
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.
.RE

.sp
.LP
The second field contains the ACL entry ID, and is used only for user or group
ACL entries. This field is not used for \fBowner@\fR, \fBgroup@\fR, or
\fBeveryone@\fR entries.
.sp
.ne 2
.na
\fB\fBuid\fR\fR
.ad
.RS 7n
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.
.RE

.sp
.ne 2
.na
\fB\fBgid\fR\fR
.ad
.RS 7n
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.
.RE

.sp
.LP
The third field contains the discretionary access permissions. The format of
the permissions depends on whether \fBACL_COMPACT_FMT\fR is specified. When the
\fIflags\fR field does not request \fBACL_COMPACT_FMT\fR, the following format
is used with a forward slash (/) separating the permissions.
.sp
.ne 2
.na
\fB\fBadd_file\fR\fR
.ad
.RS 20n
Add a file to a directory.
.RE

.sp
.ne 2
.na
\fB\fBadd_subdirectory\fR\fR
.ad
.RS 20n
Add a subdirectory.
.RE

.sp
.ne 2
.na
\fB\fBappend\fR\fR
.ad
.RS 20n
Append data.
.RE

.sp
.ne 2
.na
\fB\fBdelete\fR\fR
.ad
.RS 20n
Delete.
.RE

.sp
.ne 2
.na
\fB\fBdelete_child\fR\fR
.ad
.RS 20n
Delete child.
.RE

.sp
.ne 2
.na
\fB\fBexecute\fR\fR
.ad
.RS 20n
Execute permission.
.RE

.sp
.ne 2
.na
\fB\fBlist_directory\fR\fR
.ad
.RS 20n
List a directory.
.RE

.sp
.ne 2
.na
\fB\fBread_acl\fR\fR
.ad
.RS 20n
Read ACL.
.RE

.sp
.ne 2
.na
\fB\fBread_data\fR\fR
.ad
.RS 20n
Read permission.
.RE

.sp
.ne 2
.na
\fB\fBread_attributes\fR\fR
.ad
.RS 20n
Read attributes.
.RE

.sp
.ne 2
.na
\fB\fBread_xattr\fR\fR
.ad
.RS 20n
Read named attributes.
.RE

.sp
.ne 2
.na
\fB\fBsynchronize\fR\fR
.ad
.RS 20n
Synchronize.
.RE

.sp
.ne 2
.na
\fB\fBwrite_acl\fR\fR
.ad
.RS 20n
Write ACL.
.RE

.sp
.ne 2
.na
\fB\fBwrite_attributes\fR\fR
.ad
.RS 20n
Write attributes.
.RE

.sp
.ne 2
.na
\fB\fBwrite_data\fR\fR
.ad
.RS 20n
Write permission.
.RE

.sp
.ne 2
.na
\fB\fBwrite_owner\fR\fR
.ad
.RS 20n
Write owner.
.RE

.sp
.ne 2
.na
\fB\fBwrite_xattr\fR\fR
.ad
.RS 20n
Write named attributes.
.RE

.sp
.LP
This format allows permissions to be specified as, for example:
\fBread_data\fR/\fBread_xattr\fR/\fBread_attributes\fR.
.sp
.LP
When \fBACL_COMPACT_FMT\fR 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.
.sp
.ne 2
.na
\fB\fBa\fR\fR
.ad
.RS 5n
read attributes
.RE

.sp
.ne 2
.na
\fB\fBA\fR\fR
.ad
.RS 5n
write attributes
.RE

.sp
.ne 2
.na
\fB\fBc\fR\fR
.ad
.RS 5n
read ACL
.RE

.sp
.ne 2
.na
\fB\fBC\fR\fR
.ad
.RS 5n
write ACL
.RE

.sp
.ne 2
.na
\fB\fBd\fR\fR
.ad
.RS 5n
delete
.RE

.sp
.ne 2
.na
\fB\fBD\fR\fR
.ad
.RS 5n
delete child
.RE

.sp
.ne 2
.na
\fB\fBo\fR\fR
.ad
.RS 5n
write owner
.RE

.sp
.ne 2
.na
\fB\fBp\fR\fR
.ad
.RS 5n
append
.RE

.sp
.ne 2
.na
\fB\fBr\fR\fR
.ad
.RS 5n
read_data
.RE

.sp
.ne 2
.na
\fB\fBR\fR\fR
.ad
.RS 5n
read named attributes
.RE

.sp
.ne 2
.na
\fB\fBs\fR\fR
.ad
.RS 5n
synchronize
.RE

.sp
.ne 2
.na
\fB\fBw\fR\fR
.ad
.RS 5n
write_data
.RE

.sp
.ne 2
.na
\fB\fBW\fR\fR
.ad
.RS 5n
write named attributes
.RE

.sp
.ne 2
.na
\fB\fBx\fR\fR
.ad
.RS 5n
execute
.RE

.sp
.LP
This format allows compact permissions to be represented as, for example:
\fBrw--d-a-------\fR
.sp
.LP
The fourth field is optional when \fBACL_COMPACT_FMT\fR 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.
.sp
.ne 2
.na
\fB\fBdir_inherit\fR\fR
.ad
.RS 16n
\fBACE_DIRECTORY_INHERIT_ACE\fR
.RE

.sp
.ne 2
.na
\fB\fBfile_inherit\fR\fR
.ad
.RS 16n
\fBACE_FILE_INHERIT_ACE\fR
.RE

.sp
.ne 2
.na
\fB\fBinherit_only\fR\fR
.ad
.RS 16n
\fBACE_INHERIT_ONLY_ACE\fR
.RE

.sp
.ne 2
.na
\fB\fBno_propagate\fR\fR
.ad
.RS 16n
\fBACE_NO_PROPAGATE_INHERIT_ACE\fR
.RE

.sp
.LP
When \fBACL_COMPACT_FMT\fR 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.
.sp
.ne 2
.na
\fB\fBd\fR\fR
.ad
.RS 5n
\fBdir_inherit\fR
.RE

.sp
.ne 2
.na
\fB\fBf\fR\fR
.ad
.RS 5n
\fBfile_inherit\fR
.RE

.sp
.ne 2
.na
\fB\fBF\fR\fR
.ad
.RS 5n
failed access (not currently supported)
.RE

.sp
.ne 2
.na
\fB\fBi\fR\fR
.ad
.RS 5n
\fBinherit_only\fR
.RE

.sp
.ne 2
.na
\fB\fBn\fR\fR
.ad
.RS 5n
\fBno_propagate\fR
.RE

.sp
.ne 2
.na
\fB\fBS\fR\fR
.ad
.RS 5n
successful access (not currently supported)
.RE

.sp
.LP
The fifth field contains the type of the ACE (\fBallow\fR or \fBdeny\fR):
.sp
.ne 2
.na
\fB\fBallow\fR\fR
.ad
.RS 9n
The mask specified in field three should be allowed.
.RE

.sp
.ne 2
.na
\fB\fBdeny\fR\fR
.ad
.RS 9n
The mask specified in field three should be denied.
.RE

.SH RETURN VALUES
Upon successful completion, the \fBacl_totext()\fR function returns a pointer
to a text string. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, the \fBacl_fromtext()\fR function returns 0.
Otherwise, the return value is set to one of the following:
.sp
.ne 2
.na
\fB\fBEACL_FIELD_NOT_BLANK\fR\fR
.ad
.RS 28n
A field that should be blank is not blank.
.RE

.sp
.ne 2
.na
\fB\fBEACL_FLAGS_ERROR\fR\fR
.ad
.RS 28n
An invalid ACL flag was specified.
.RE

.sp
.ne 2
.na
\fB\fBEACL_INHERIT_ERROR\fR\fR
.ad
.RS 28n
An invalid inheritance field was specified.
.RE

.sp
.ne 2
.na
\fB\fBEACL_INVALID_ACCESS_TYPE\fR\fR
.ad
.RS 28n
An invalid access type was specified.
.RE

.sp
.ne 2
.na
\fB\fBEACL_INVALID_STR\fR\fR
.ad
.RS 28n
The string is \fINULL\fR.
.RE

.sp
.ne 2
.na
\fB\fBEACL_INVALID_USER_GROUP\fR\fR
.ad
.RS 28n
The required user or group name not found.
.RE

.sp
.ne 2
.na
\fB\fBEACL_MISSING_FIELDS\fR\fR
.ad
.RS 28n
The ACL needs more fields to be specified.
.RE

.sp
.ne 2
.na
\fB\fBEACL_PERM_MASK_ERROR\fR\fR
.ad
.RS 28n
The permission mask is invalid.
.RE

.sp
.ne 2
.na
\fB\fBEACL_UNKNOWN_DATA\fR\fR
.ad
.RS 28n
Unknown data was found in the ACL.
.RE

.SH EXAMPLES
\fBExample 1 \fRExamples of permissions when \fBACL_COMPACT_FMT\fR is not
specified.
.sp
.in +2
.nf
user:joe:read_data/write_data:file_inherit/dir_inherit:allow
.fi
.in -2
.sp

.sp
.in +2
.nf
owner@:read_acl:allow,user:tom:read_data:file_inherit/inherit_only:deny
.fi
.in -2
.sp

.LP
\fBExample 2 \fRExamples of permissions when \fBACL_COMPACT_FMT\fR is
specified.
.sp
.in +2
.nf
user:joe:rw------------:fd----:allow
.fi
.in -2
.sp

.sp
.in +2
.nf
owner@:----------c---:------allow,user:tom:r-------------:f-i---:deny
.fi
.in -2
.sp

.SH ATTRIBUTES
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
\fBls\fR(1), \fBtar\fR(1), \fBacl\fR(2), \fBmalloc\fR(3C),
\fBaclfromtext\fR(3SEC), \fBacl\fR(5), \fBattributes\fR(5)