lib/libc/sys/access.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)access.2    8.2 (Berkeley) 4/1/94
  33 .\" $FreeBSD: src/lib/libc/sys/access.2,v 1.7.2.5 2002/10/12 22:02:53 rwatson Exp $
  34 .\" $DragonFly: src/lib/libc/sys/access.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
  35 .\"
  36 .Dd August 23, 2009
  37 .Dt ACCESS 2
  38 .Os
  39 .Sh NAME
  40 .Nm access ,
  41 .Nm faccessat
  42 .Nd check access permissions of a file or pathname
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In unistd.h
  47 .Ft int
  48 .Fn access "const char *path" "int mode"
  49 .Ft int
  50 .Fn faccessat "int fd" "const char *path" "int mode" "int flags"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn access
  54 function checks the accessibility of the
  55 file named by
  56 .Fa path
  57 for the access permissions indicated by
  58 .Fa mode .
  59 The value of
  60 .Fa mode
  61 is the bitwise inclusive OR of the access permissions to be
  62 checked
  63 .Pf ( Dv R_OK
  64 for read permission,
  65 .Dv W_OK
  66 for write permission and
  67 .Dv X_OK
  68 for execute/search permission) or the existence test,
  69 .Dv F_OK .
  70 All components of the pathname
  71 .Fa path
  72 are checked for access permissions (including
  73 .Dv F_OK ) .
  74 .Pp
  75 The real user ID is used in place of the effective user ID
  76 and the real group access list
  77 (including the real group ID) are
  78 used in place of the effective ID for verifying permission.
  79 .Pp
  80 Even if a process has appropriate privileges and indicates success for
  81 .Dv X_OK ,
  82 the file may not actually have execute permission bits set.
  83 Likewise for
  84 .Dv R_OK
  85 and
  86 .Dv W_OK .
  87 .Pp
  88 The
  89 .Fn faccessat
  90 function
  91 operates as the
  92 .Fn access
  93 function but uses either the effective and group IDs or real ones depending on
  94 the value of
  95 .Fa flags .
  96 .Pp
  97 The values for the
  98 .Fa flags
  99 are constructed by a bitwise-inclusive OR of flags from the following list,
 100 defined in
 101 .In fcntl.h :
 102 .Bl -tag -width indent
 103 .It Dv AT_EACCESS
 104 Use effective user and group IDs.
 105 .El
 106 .Pp
 107 If
 108 .Fa path
 109 specifies a relative path the file to access is determined relative to the
 110 directory associated with the file descriptor
 111 .Fa fd
 112 instead of the current working directory.
 113 If
 114 .Fa fd
 115 is the special value
 116 .Dv AT_FDCWD
 117 the current working directory is used and the behavior is identical to a call to
 118 .Fn access .
 119 .Sh RETURN VALUES
 120 If
 121 .Fa path
 122 cannot be found or if any of the desired access modes would
 123 not be granted, then a -1 value is returned; otherwise
 124 a 0 value is returned.
 125 .Sh ERRORS
 126 The
 127 .Fn access
 128 and
 129 .Fn faccessat
 130 functions can fail with:
 131 .Bl -tag -width Er
 132 .It Bq Er ENOTDIR
 133 A component of the path prefix is not a directory.
 134 .It Bq Er ENAMETOOLONG
 135 A component of a pathname exceeded 255 characters,
 136 or an entire path name exceeded 1023 characters.
 137 .It Bq Er ENOENT
 138 The named file does not exist.
 139 .It Bq Er ELOOP
 140 Too many symbolic links were encountered in translating the pathname.
 141 .It Bq Er EROFS
 142 Write access is requested for a file on a read-only file system.
 143 .It Bq Er ETXTBSY
 144 Write access is requested for a pure procedure (shared text)
 145 file presently being executed.
 146 .It Bq Er EACCES
 147 Permission bits of the file mode do not permit the requested
 148 access, or search permission is denied on a component of the
 149 path prefix.  The owner of a file has permission checked with
 150 respect to the ``owner'' read, write, and execute mode bits,
 151 members of the file's group other than the owner have permission
 152 checked with respect to the ``group'' mode bits, and all
 153 others have permissions checked with respect to the ``other''
 154 mode bits.
 155 .It Bq Er EFAULT
 156 .Fa Path
 157 points outside the process's allocated address space.
 158 .It Bq Er EIO
 159 An I/O error occurred while reading from or writing to the file system.
 160 .El
 161 .Pp
 162 In addition the
 163 .Fn faccessat
 164 function can fail with:
 165 .Bl -tag -width Er
 166 .It Bq Er EBADF
 167 .Fa fd
 168 is not a valid file descriptor.
 169 .It Bq Er ENOTDIR
 170 .Fa path
 171 is relative and
 172 .Fa fd
 173 does not point to a directory.
 174 .It Bq Er EINVAL
 175 .Fa flags
 176 contains unsupported flags.
 177 .El
 178 .Sh SEE ALSO
 179 .Xr chmod 2 ,
 180 .Xr stat 2
 181 .Sh STANDARDS
 182 The
 183 .Fn access
 184 function call is expected to conform to
 185 .St -p1003.1-90 .
 186 .Pp
 187 The
 188 .Fn faccessat
 189 function call is expected to conform to
 190 .St -p1003.1-2008 .
 191 .Sh CAVEAT
 192 .Fn Access
 193 is a potential security hole due to race conditions and
 194 should never be used.
 195 Setuid and setgid applications should either use the
 196 .Fn faccessat
 197 function or restore the effective uid or gid
 198 and perform actions directly rather than use
 199 .Fn access
 200 to simulate access checks for the real user of group id.
 201 .Sh HISTORY
 202 An
 203 .Fn access
 204 function call appeared in
 205 .At v7 .
 206 .Pp
 207 The
 208 .Fn faccessat
 209 system call appeared in
 210 .Dx 2.3 .