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 .