Print this page
markup tweaks per mandoc author
fcntl.h only needed for faccessat
copyright
document standards for access, faccess
   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at  http://www.opengroup.org/bookstore/.
   6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
   7 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
   8 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   9 .\"  This notice shall appear on any product containing this material.
  10 .\" 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.
  11 .\"  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
  12 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  13 .TH ACCESS 2 "Jun 16, 2009"
  14 .SH NAME
  15 access, faccessat \- determine accessibility of a file
  16 .SH SYNOPSIS
  17 .LP
  18 .nf
  19 #include <unistd.h>
  20 #include <sys/fcntl.h>
  21 
  22 \fBint\fR \fBaccess\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR \fIamode\fR);
  23 .fi
  24 
  25 .LP
  26 .nf
  27 \fBint\fR \fBfaccessat\fR(\fBint\fR \fIfd\fR, \fBconst char *\fR\fIpath\fR, \fBint\fR \fIamode\fR, \fBint\fR \fIflag\fR);
  28 .fi
  29 
  30 .SH DESCRIPTION
  31 .sp
  32 .LP
  33 The \fBaccess()\fR function checks the file named by the pathname pointed to by
  34 the \fIpath\fR argument for accessibility according to the bit pattern
  35 contained in \fIamode\fR, using the real user \fBID\fR in place of the
  36 effective user \fBID\fR and the real group \fBID\fR in place of the effective











  37 group ID. This allows a setuid process to verify that the user running it would
  38 have had permission to access this file.
  39 .sp
  40 .LP
  41 The value of \fIamode\fR is either the bitwise inclusive \fBOR\fR of the access
  42 permissions to be checked (\fBR_OK\fR, \fBW_OK\fR, \fBX_OK\fR) or the existence
  43 test, \fBF_OK\fR.
  44 .sp
  45 .LP
  46 These constants are defined in <\fBunistd.h\fR> as follows:
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fBR_OK\fR\fR
  51 .ad
  52 .RS 8n







  53 Test for read permission.
  54 .RE
  55 
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fBW_OK\fR\fR
  60 .ad
  61 .RS 8n
  62 Test for write permission.
  63 .RE
  64 
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBX_OK\fR\fR
  69 .ad
  70 .RS 8n
  71 Test for execute or search permission.
  72 .RE
  73 
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fBF_OK\fR\fR
  78 .ad
  79 .RS 8n
  80 Check existence of file
  81 .RE
  82 
  83 .sp
  84 .LP
  85 See \fBIntro\fR(2) for additional information about "File Access Permission".
  86 .sp
  87 .LP
  88 If any access permissions are to be checked, each will be checked individually,
  89 as described in \fBIntro\fR(2). If the process has appropriate privileges, an
  90 implementation may indicate success for \fBX_OK\fR even if none of the execute
  91 file permission bits are set.
  92 .sp
  93 .LP
  94 The \fBfaccessat()\fR function is equivalent to the \fBaccess()\fR function,
  95 except in the case where \fIpath\fR specifies a relative path. In this case the








  96 file whose accessibility is to be determined is located relative to the
  97 directory associated with the file descriptor \fIfd\fR instead of the current
  98 working directory.
  99 .sp
 100 .LP
 101 If \fBfaccessat()\fR is passed in the \fIfd\fR parameter the special value
 102 \fBAT_FDCWD\fR, defined in \fB<fcntl.h>\fR, the current working directory is
 103 used and the behavior is identical to a call to \fBaccess()\fR.
 104 .sp
 105 .LP
 106 Values for \fIflag\fR are constructed by a bitwise-inclusive OR of flags from
 107 the following list, defined in \fB<fcntl.h>\fR:
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBAT_EACCESS\fR\fR
 112 .ad
 113 .RS 14n






 114 The checks for accessibility are performed using the effective user and group
 115 IDs instead of the real user and group ID as required in a call to
 116 \fBaccess()\fR.
 117 .RE
 118 
 119 .SH RETURN VALUES
 120 .sp
 121 .LP
 122 If the requested access is permitted, \fBaccess()\fR and
 123 \fBfaccessat()\fRsucceed and return \fB0\fR. Otherwise, \fB\(mi1\fR is returned
 124 and \fBerrno\fR is set to indicate the error.
 125 .SH ERRORS
 126 .sp
 127 .LP
 128 The \fBaccess()\fR and \fBfaccessat()\fR functions will fail if:
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBEACCES\fR\fR
 133 .ad
 134 .RS 16n
 135 Permission bits of the file mode do not permit the requested access, or search
 136 permission is denied on a component of the path prefix.
 137 .RE
 138 
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBEFAULT\fR\fR
 143 .ad
 144 .RS 16n
 145 The \fIpath\fR argument points to an illegal address.
 146 .RE
 147 
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBEINTR\fR\fR
 152 .ad
 153 .RS 16n
 154 A signal was caught during the \fBaccess()\fR function.
 155 .RE
 156 
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBELOOP\fR\fR
 161 .ad
 162 .RS 16n
 163 Too many symbolic links were encountered in resolving \fIpath\fR, or loop
 164 exists in symbolic links encountered during resolution of the \fIpath\fR
 165 argument.
 166 .RE
 167 
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBENAMETOOLONG\fR\fR
 172 .ad
 173 .RS 16n
 174 The length of the \fIpath\fR argument exceeds {\fBPATH_MAX\fR}, or a pathname
 175 component is longer than {\fBNAME_MAX\fR} while \fB_POSIX_NO_TRUNC\fR is in
 176 effect.
 177 .RE
 178 
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBENOENT\fR\fR
 183 .ad
 184 .RS 16n
 185 A component of \fIpath\fR does not name an existing file or \fIpath\fR is an
 186 empty string.
 187 .RE
 188 
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fBENOLINK\fR\fR
 193 .ad
 194 .RS 16n
 195 The \fIpath\fR argument points to a remote machine and the link to that machine
 196 is no longer active.
 197 .RE
 198 
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fBENOTDIR\fR\fR
 203 .ad
 204 .RS 16n
 205 A component of the path prefix is not a directory.
 206 .RE
 207 
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fBENXIO\fR\fR
 212 .ad
 213 .RS 16n
 214 The \fIpath\fR argument points to a character or block device special file and
 215 the corresponding device has been retired by the fault management framework.
 216 .RE
 217 
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fBEROFS\fR\fR
 222 .ad
 223 .RS 16n
 224 Write access is requested for a file on a read-only file system.
 225 .RE
 226 
 227 .sp
 228 .LP
 229 The \fBfaccessat()\fR function will fail if:
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fBEBADF\fR\fR
 234 .ad
 235 .RS 9n
 236 The \fIpath\fR argument does not specify an absolute path and the \fIfd\fR
 237 argument is neither \fBAT_FDCWD\fR nor a valid file descriptor open for reading
 238 or searching.
 239 .RE
 240 
 241 .sp
 242 .LP
 243 The \fBaccess()\fR and \fBfaccessat()\fR functions may fail if:
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fBEINVAL\fR\fR
 248 .ad
 249 .RS 16n
 250 The value of the \fIamode\fR argument is invalid.
 251 .RE
 252 
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fBENAMETOOLONG\fR\fR
 257 .ad
 258 .RS 16n
 259 Pathname resolution of a symbolic link produced an intermediate result whose
 260 length exceeds {\fBPATH_MAX\fR}.
 261 .RE
 262 
 263 .sp
 264 .ne 2
 265 .na
 266 \fB\fBETXTBSY\fR\fR
 267 .ad
 268 .RS 16n
 269 Write access is requested for a pure procedure (shared text) file that is being
 270 executed.
 271 .RE
 272 
 273 .sp
 274 .LP
 275 The \fBfaccessat()\fR function may fail if:
 276 .sp
 277 .ne 2
 278 .na
 279 \fB\fBEINVAL\fR\fR
 280 .ad
 281 .RS 11n
 282 The value of the \fIflag\fR argument is not valid.
 283 .RE
 284 
 285 .sp
 286 .ne 2
 287 .na
 288 \fB\fBENOTDIR\fR\fR
 289 .ad
 290 .RS 11n
 291 The \fIpath\fR argument is not an absolute path and \fIfd\fR is neither
 292 \fBAT_FDCWD\fR nor a file descriptor associated with a directory.
 293 .RE
 294 
 295 .SH USAGE
 296 .sp
 297 .LP
 298 Additional values of \fIamode\fR other than the set defined in the description
 299 might be valid, for example, if a system has extended access controls.
 300 .sp
 301 .LP
 302 The purpose of the \fBfaccessat()\fR function is to enable the checking of the

 303 accessibility of files in directories other than the current working directory
 304 without exposure to race conditions. Any part of the path of a file could be
 305 changed in parallel to a call to \fBaccess()\fR, resulting in unspecified


 306 behavior. By opening a file descriptor for the target directory and using the
 307 \fBfaccessat()\fR function, it can be guaranteed that the file tested for

 308 accessibility is located relative to the desired directory.
 309 .SH ATTRIBUTES
 310 .sp
 311 .LP
 312 See \fBattributes\fR(5) for descriptions of the following attributes:
 313 .sp
 314 
 315 .sp
 316 .TS
 317 box;
 318 c | c
 319 l | l .
 320 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 321 _
 322 Interface Stability     Committed
 323 _
 324 MT-Level        Async-Signal-Safe
 325 _
 326 Standard        See below.
 327 .TE
 328 
 329 .sp
 330 .LP
 331 For \fBaccess()\fR, see \fBstandards\fR(5).
 332 .SH SEE ALSO
 333 .sp
 334 .LP
 335 \fBIntro\fR(2), \fBchmod\fR(2), \fBstat\fR(2), \fBattributes\fR(5),
 336 \fBstandards\fR(5)
   1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at  http://www.opengroup.org/bookstore/.
   6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
   7 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
   8 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   9 .\"  This notice shall appear on any product containing this material.
  10 .\" 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.
  11 .\"  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
  12 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  13 .Dd "Jul 24, 2014"
  14 .Dt ACCESS 2
  15 .Os
  16 .Sh NAME
  17 .Nm access ,
  18 .Nm faccessat
  19 .Nd determine accessibility of a file
  20 .Sh SYNOPSIS
  21 .In unistd.h
  22 .Ft int
  23 .Fo access
  24 .Fa "const char *path"
  25 .Fa "int amode"
  26 .Fc
  27 .
  28 .In unistd.h
  29 .In fcntl.h
  30 .Ft int
  31 .Fo faccessat
  32 .Fa "int fd"
  33 .Fa "const char *path"
  34 .Fa "int amode"
  35 .Fa "int flag"
  36 .Fc
  37 .Sh DESCRIPTION
  38 The
  39 .Fn access
  40 function checks the file named by the pathname pointed to by
  41 the
  42 .Fa path
  43 argument for accessibility according to the bit pattern
  44 contained in
  45 .Fa amode ,
  46 using the real user ID in place of the
  47 effective user ID and the real group IDR in place of the effective
  48 group ID. This allows a setuid process to verify that the user running it would
  49 have had permission to access this file.
  50 .Lp
  51 The value of
  52 .Fa amode
  53 is either the bitwise inclusive
  54 .Sy OR
  55 of the access
  56 permissions to be checked
  57 .Po
  58 .Dv R_OK ,
  59 .Dv W_OK ,
  60 .Dv X_OK
  61 .Pc
  62 or the existence
  63 test,
  64 .Dv F_OK .
  65 .Lp
  66 These constants are defined in
  67 .In unistd.h
  68 as follows:
  69 .Bl -tag -offset indent -width Dv
  70 .It Dv R_OK
  71 Test for read permission.
  72 .It Dv W_OK







  73 Test for write permission.
  74 .It Dv X_OK







  75 Test for execute or search permission.
  76 .It Dv F_OK







  77 Check existence of file
  78 .El
  79 .Lp
  80 See
  81 .Xr Intro 2
  82 for additional information about "File Access Permission".
  83 .Lp

  84 If any access permissions are to be checked, each will be checked individually,
  85 as described in
  86 .Xr Intro 2 .
  87 If the process has appropriate privileges, an
  88 implementation may indicate success for
  89 .Dv X_OK
  90 even if none of the execute file permission bits are set.
  91 .Lp
  92 The
  93 .Fn faccessat
  94 function is equivalent to the
  95 .Fn access
  96 function,
  97 except in the case where
  98 .Fa path
  99 specifies a relative path. In this case the
 100 file whose accessibility is to be determined is located relative to the
 101 directory associated with the file descriptor
 102 .Fa fd
 103 instead of the current working directory.
 104 .Lp
 105 If
 106 .Fn faccessat
 107 is passed in the
 108 .Fa fd
 109 parameter the special value
 110 .Dv AT_FDCWD ,
 111 defined in
 112 .In fcntl.h ,
 113 the current working directory is
 114 used and the behavior is identical to a call to
 115 .Fn access .
 116 .Lp
 117 Values for
 118 .Fa flag
 119 are constructed by a bitwise-inclusive OR of flags from
 120 the following list, defined in
 121 .In fcntl.h :
 122 .Bl -tag -offset indent -width Dv
 123 .It Dv AT_EACCESS
 124 The checks for accessibility are performed using the effective user and group
 125 IDs instead of the real user and group ID as required in a call to
 126 .Fn access .
 127 .El
 128 .Sh RETURN VALUES
 129 If the requested access is permitted,
 130 .Fn access
 131 and
 132 .Fn faccessat
 133 succeed and return 0. Otherwise, \(mi1 is returned
 134 and
 135 .Va errno
 136 is set to indicate the error.
 137 .Sh ERRORS
 138 The
 139 .Fn access
 140 and
 141 .Fn faccessat
 142 functions will fail if:
 143 .Bl -tag -width Er
 144 .It Er EACCES
 145 Permission bits of the file mode do not permit the requested access, or search
 146 permission is denied on a component of the path prefix.
 147 .
 148 .It Er EFAULT
 149 The
 150 .Fa path
 151 argument points to an illegal address.
 152 .
 153 .It Er EINTR
 154 A signal was caught during the
 155 .Fn access
 156 function.
 157 .
 158 .It Er ELOOP
 159 Too many symbolic links were encountered in resolving
 160 .Fa path ,
 161 or loop exists in symbolic links encountered during resolution of the
 162 .Fa path












 163 argument.
 164 .
 165 .It Er ENAMETOOLONG
 166 The length of the
 167 .Fa path
 168 argument exceeds
 169 .Brq Dv PATH_MAX ,
 170 or a pathname
 171 component is longer than
 172 .Brq Dv NAME_MAX
 173 while
 174 .Dv _POSIX_NO_TRUNC
 175 is in effect.
 176 .
 177 .It Er ENOENT
 178 A component of
 179 .Fa path
 180 does not name an existing file or
 181 .Fa path
 182 is an empty string.
 183 .
 184 .It Er ENOLINK
 185 The
 186 .Fa path
 187 argument points to a remote machine and the link to that machine






 188 is no longer active.
 189 .
 190 .It Er ENOTDIR






 191 A component of the path prefix is not a directory.
 192 .
 193 .It Er ENXIO
 194 The
 195 .Fa path
 196 argument points to a character or block device special file and




 197 the corresponding device has been retired by the fault management framework.
 198 .
 199 .It Er EROFS






 200 Write access is requested for a file on a read-only file system.
 201 .
 202 .El
 203 .Lp
 204 The
 205 .Fn faccessat
 206 function will fail if:
 207 .Bl -tag -width Er
 208 .It Er EBADF
 209 The
 210 .Fa path
 211 argument does not specify an absolute path and the
 212 .Fa fd
 213 argument is neither
 214 .Dv AT_FDCWD
 215 nor a valid file descriptor open for reading or searching.
 216 .El
 217 .Lp
 218 The
 219 .Fn access
 220 and
 221 .Fn faccessat
 222 functions may fail if:
 223 .Bl -tag -width Er
 224 .
 225 .It Er EINVAL
 226 The value of the
 227 .Fa amode
 228 argument is invalid.
 229 .
 230 .It Er ENAMETOOLONG




 231 Pathname resolution of a symbolic link produced an intermediate result whose
 232 length exceeds
 233 .Brq Dv PATH_MAX .
 234 .
 235 .It Er ETXTBSY





 236 Write access is requested for a pure procedure (shared text) file that is being
 237 executed.
 238 .El
 239 .Lp
 240 The
 241 .Fn faccessat
 242 function may fail if:
 243 .Bl -tag -width Er
 244 .
 245 .It Er BEINVAL
 246 The value of the
 247 .Fa flag
 248 argument is not valid.
 249 .
 250 .It Er ENOTDIR
 251 The
 252 .Fa path
 253 argument is not an absolute path and
 254 .Fa fd
 255 is neither
 256 .Dv AT_FDCWD
 257 nor a file descriptor associated with a directory.
 258 .El
 259 .Sh USAGE
 260 Additional values of
 261 .Fa amode
 262 other than the set defined in the description



 263 might be valid, for example, if a system has extended access controls.
 264 .Lp
 265 The purpose of the
 266 .Fn faccessat
 267 function is to enable the checking of the
 268 accessibility of files in directories other than the current working directory
 269 without exposure to race conditions. Any part of the path of a file could be
 270 changed in parallel to a call to
 271 .Fn access ,
 272 resulting in unspecified
 273 behavior. By opening a file descriptor for the target directory and using the
 274 .Fn faccessat
 275 function, it can be guaranteed that the file tested for
 276 accessibility is located relative to the desired directory.
 277 .Sh INTERFACE STABILITY
 278 .Sy Standard .
 279 .Sh MT-LEVEL
 280 .Sy Async-Signal-Safe .
 281 .Sh SEE ALSO
 282 .Xr Intro 2 ,
 283 .Xr chmod 2 ,
 284 .Xr stat 2 ,
 285 .Xr standards 5
 286 .Sh STANDARDS
 287 The
 288 .Fn access
 289 function is defined in
 290 .St -p1003.1 .
 291 The
 292 .Fn faccessat
 293 function was introduced in
 294 .St -p1003.1-2008 .