'\" te
.\" Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
.TH acl_get 3SEC "4 Jun 2010" "SunOS 5.11" "File Access Control Library Functions"
.SH NAME
acl_get, facl_get, acl_set, facl_set \- get or set a file's Access Control List (ACL)
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lsec\fR [ \fIlibrary\fR\&.\|.\|. ] 
#include <sys/acl.h>

\fBint\fR \fBacl_get\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR \fIflag\fR, \fBacl_t **\fR\fIaclp\fR);
.fi

.LP
.nf
\fBint\fR \fBfacl_get\fR(\fBint\fR \fIfd\fR, \fBint\fR \fIflag\fR, \fBacl_t **\fR\fIaclp\fR);
.fi

.LP
.nf
\fBint\fR \fBacl_set\fR(\fBconst char *\fR\fIpath\fR, \fBacl_t *\fR\fIaclp\fR);
.fi

.LP
.nf
\fBint\fR \fBfacl_set\fR(\fBint\fR \fIfd\fR, \fBacl_t *\fR\fIaclp\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBacl_get()\fR and \fBfacl_get()\fR functions retrieve an Access Control List (ACL) of a file whose name is given by \fIpath\fR or referenced by the open file descriptor \fIfd\fR. The \fIflag\fR argument specifies whether a trivial ACL should be retrieved. When the \fIflag\fR argument is \fBACL_NO_TRIVIAL\fR, only ACLs that are not trivial will be retrieved. The ACL is returned in the \fIaclp\fR argument.
.sp
.LP
The \fBacl_set()\fR and \fBfacl_set()\fR functions are used for setting an ACL of a file whose name is given by \fIpath\fR or referenced by the open file descriptor \fIfd\fR. The \fIaclp\fR argument specifies the ACL to set.
.sp
.LP
The \fBacl_get()\fR and \fBacl_set()\fR functions support multiple types of ACLs.  When possible, the \fBacl_set()\fR function translates an ACL to the target file's style of ACL. Currently this is only possible when translating from a POSIX-draft ACL such as on UFS to a file system that supports NFSv4 ACL semantics such as ZFS or NFSv4.
.sp
.LP
The caller is responsible for freeing the returned \fBacl_t\fR structure using \fBacl_free\fR(3SEC).
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBacl_get()\fR and \fBfacl_get()\fR return 0 and \fIaclp\fR is non-\fINULL\fR. The \fIaclp\fR argument can be \fINULL\fR after successful completion if the file had a trivial ACL and the \fIflag\fR argument was \fBACL_NO_TRIVIAL\fR. Otherwise, -1 is returned and \fBerrno\fR is set to indicate the error.
.sp
.LP
Upon successful completion, \fBacl_set()\fR and \fBfacl_set()\fR return 0. Otherwise, -1 is returned and \fBerrno\fR is set to indicate the error.
.SH ERRORS
.sp
.LP
These functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEACCES\fR\fR
.ad
.RS 11n
.rt  
The caller does not have access to a component of \fIpath\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEIO\fR\fR
.ad
.RS 11n
.rt  
A disk I/O error has occured while retrieving the ACL.
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOENT\fR\fR
.ad
.RS 11n
.rt  
A component of the \fIpath\fR does not exist.
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOSYS\fR\fR
.ad
.RS 11n
.rt  
The file system does not support ACLs.
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOTSUP\fR\fR
.ad
.RS 11n
.rt  
The ACL supplied could not be translated to an NFSv4 ACL.
.RE

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

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBchmod\fR(1), \fBacl\fR(2), \fBacl_free\fR(3SEC), \fBacl\fR(5), \fBattributes\fR(5)