usr/src/man/man2/acl.2

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH ACL 2 "Jan 10, 2007"
   7 .SH NAME
   8 acl, facl \- get or set a file's Access Control List (ACL)
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/acl.h>
  13
  14 \fBint\fR \fBacl\fR(\fBchar *\fR\fIpathp\fR, \fBint\fR \fIcmd\fR, \fBint\fR \fInentries\fR, \fBvoid *\fR\fIaclbufp\fR);
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fBint\fR \fBfacl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIcmd\fR, \fBint\fR \fInentries\fR, \fBvoid *\fR\fIaclbufp\fR);
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 The \fBacl()\fR and \fBfacl()\fR functions get or set the  \fBACL\fR of a file
  26 whose name is given by \fIpathp\fR or referenced by the open file descriptor
  27 \fIfildes\fR. The \fInentries\fR argument specifies how many \fBACL\fR entries
  28 fit into buffer \fIaclbufp\fR. The \fBacl()\fR function is used to manipulate
  29 \fBACL\fR on file system objects.
  30 .sp
  31 .LP
  32 The following types are supported for \fIaclbufp\fR:
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fBaclent_t\fR\fR
  37 .ad
  38 .RS 12n
  39 Used by the UFS file system.
  40 .RE
  41
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fBace_t\fR\fR
  46 .ad
  47 .RS 12n
  48 Used by the ZFS and NFSv4 file systems.
  49 .RE
  50
  51 .sp
  52 .LP
  53 The following values for \fIcmd\fR are supported:
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fBSETACL\fR\fR
  58 .ad
  59 .RS 17n
  60 \fInentries\fR \fBaclent_t\fR \fBACL\fR entries, specified in buffer
  61 \fIaclbufp\fR, are stored in the file's  \fBACL\fR. All directories in the path
  62 name must be searchable.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBGETACL\fR\fR
  69 .ad
  70 .RS 17n
  71 Buffer \fIaclbufp\fR is filled with the file's  \fBaclent_t\fR \fBACL\fR
  72 entries. Read access to the file is not required, but all directories in the
  73 path name must be searchable.
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fBGETACLCNT\fR\fR
  80 .ad
  81 .RS 17n
  82 The number of entries in the file's \fBaclent_t\fR \fBACL\fR is returned. Read
  83 access to the file is not required, but all directories in the path name must
  84 be searchable.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBACE_SETACL\fR\fR
  91 .ad
  92 .RS 17n
  93 \fInentries\fR \fBace_t\fR ACL entries, specified in buffer \fIaclbufp\fR, are
  94 stored in the file's ACL. All directories in the path name must be searchable.
  95 Write ACL access is required to change the file's ACL.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBACE_GETACL\fR\fR
 102 .ad
 103 .RS 17n
 104 Buffer \fIaclbufp\fR is filled with the file's \fBace_t\fR ACL entries. Read
 105 access to the file is required and all directories in the path name must be
 106 searchable.
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fBACE_GETACLCNT\fR\fR
 113 .ad
 114 .RS 17n
 115 The number of entries in the file's \fBace_t\fR ACL is  returned. Read access
 116 to the file is required and all directories in the path name must be
 117 searchable.
 118 .RE
 119
 120 .SH RETURN VALUES
 121 .sp
 122 .LP
 123 Upon successful completion, \fBacl()\fR and \fBfacl()\fR return \fB0\fR if
 124 \fIcmd\fR is  \fBSETACL\fR or \fBACE_SETACL\fR. If \fIcmd\fR is  \fBGETACL\fR,
 125 \fBGETACLCNT\fR, \fBACE_GETACL\fR or \fBACE_GETACLCNT\fR, the number of
 126 \fBACL\fR entries is returned. Otherwise, \fB\(mi1\fR is returned and
 127 \fBerrno\fR is set to indicate the error.
 128 .SH ERRORS
 129 .sp
 130 .LP
 131 The \fBacl()\fR function will fail if:
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fBEACCES\fR\fR
 136 .ad
 137 .RS 11n
 138 The caller does not have access to a component of the pathname.
 139 .RE
 140
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fBEFAULT\fR\fR
 145 .ad
 146 .RS 11n
 147 The \fIpathp\fR or \fIaclbufp\fR argument points to an illegal address.
 148 .RE
 149
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fBEINVAL\fR\fR
 154 .ad
 155 .RS 11n
 156 The \fIcmd\fR argument is not  \fBGETACL\fR, \fBSETACL\fR, \fBACE_GETACL\fR,
 157 \fBGETACLCNT\fR, or \fBACE_GETACLCNT\fR; the \fIcmd\fR argument is
 158 \fBSETACL\fR and  \fInentries\fR is less than 3; or the \fIcmd\fR argument is
 159 \fBSETACL\fR or \fBACE_SETACL\fR and the \fBACL\fR specified in \fIaclbufp\fR
 160 is not valid.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBEIO\fR\fR
 167 .ad
 168 .RS 11n
 169 A disk  I/O  error has occurred while storing or retrieving the  \fBACL.\fR
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBENOENT\fR\fR
 176 .ad
 177 .RS 11n
 178 A component of the path does not exist.
 179 .RE
 180
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBENOSPC\fR\fR
 185 .ad
 186 .RS 11n
 187 The \fIcmd\fR argument is  \fBGETACL\fR and \fInentries\fR is less than the
 188 number of entries in the file's  \fBACL\fR, or the \fIcmd\fR argument is
 189 \fBSETACL\fR and there is insufficient space in the file system to store the
 190 \fBACL\fR.
 191 .RE
 192
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fBENOSYS\fR\fR
 197 .ad
 198 .RS 11n
 199 The \fIcmd\fR argument is  \fBSETACL\fR or \fBACE_SETACL\fR and the file
 200 specified by \fIpathp\fR resides on a file system that does not support
 201 \fBACLs\fR, or the \fBacl()\fR function is not supported by this
 202 implementation.
 203 .RE
 204
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBENOTDIR\fR\fR
 209 .ad
 210 .RS 11n
 211 A component of the path specified by \fIpathp\fR is not a directory, or the
 212 \fIcmd\fR argument is  \fBSETACL\fR or \fBACE_SETACL\fR and an attempt is made
 213 to set a default \fBACL\fR on a file type other than a directory.
 214 .RE
 215
 216 .sp
 217 .ne 2
 218 .na
 219 \fB\fBENOTSUP\fR\fR
 220 .ad
 221 .RS 11n
 222 The \fIcmd\fR argument is \fBGETACL\fR, but the ACL is composed of \fBace_t\fR
 223 entries, and the ACL cannot be translated into \fBaclent_t\fR form.
 224 .sp
 225 The \fIcmd\fR argument is \fBACE_SETACL\fR, but the underlying filesystem only
 226 supports ACLs composed of \fBaclent_t\fR entries and the ACL could not be
 227 translated into \fBaclent_t\fR form.
 228 .RE
 229
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fBEPERM\fR\fR
 234 .ad
 235 .RS 11n
 236 The effective user \fBID\fR does not match the owner of the file and the
 237 process does not have appropriate privilege.
 238 .RE
 239
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fBEROFS\fR\fR
 244 .ad
 245 .RS 11n
 246 The \fIcmd\fR argument is  \fBSETACL\fR or \fBACE_SETACL\fR and the file
 247 specified by \fIpathp\fR resides on a file system that is mounted read-only.
 248 .RE
 249
 250 .SH ATTRIBUTES
 251 .sp
 252 .LP
 253 See \fBattributes\fR(5) for descriptions of the following attributes:
 254 .sp
 255
 256 .sp
 257 .TS
 258 box;
 259 c | c
 260 l | l .
 261 ATTRIBUTE  TYPE ATTRIBUTE  VALUE
 262 _
 263 Interface  Stability    Evolving
 264 .TE
 265
 266 .SH SEE ALSO
 267 .sp
 268 .LP
 269 \fBgetfacl\fR(1), \fBsetfacl\fR(1), \fBaclcheck\fR(3SEC), \fBaclsort\fR(3SEC)