1.\" $NetBSD: access.2,v 1.32 2013/01/13 08:15:02 dholland Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)access.2 8.2 (Berkeley) 4/1/94 31.\" 32.Dd January 12, 2013 33.Dt ACCESS 2 34.Os 35.Sh NAME 36.Nm access , 37.Nm faccessat 38.Nd check access permissions of a file or pathname 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In unistd.h 43.Ft int 44.Fn access "const char *path" "int mode" 45.In fcntl.h 46.Ft int 47.Fn faccessat "int fd" "const char *path" "int mode" "int flags" 48.Sh DESCRIPTION 49The 50.Fn access 51function checks the accessibility of the 52file named by 53.Fa path . 54The 55.Fn faccessat 56function checks the accessibility of the file named by 57.Fa path 58using 59.Fa fd 60as the starting point for relative pathnames. 61If 62.Fa fd 63is 64.Dv AT_FDCWD 65the current directory is used. 66Calling 67.Fn access 68is equivalent to calling 69.Fn faccessat 70with 71.Fa fd 72set to 73.Dv AT_FDCWD 74and 75.Fa flags 76set to 0. 77.Pp 78The form of access to check is specified by the bitwise or of the 79following values for 80.Fa mode : 81.Bl -tag -width W_OK 82.It Dv R_OK 83Check for read permission. 84.It Dv W_OK 85Check for write permission. 86.It Dv X_OK 87Check for execute/search permission. 88.It Dv F_OK 89Check only for existence. 90.El 91.Pp 92All components of the pathname 93.Fa path 94are checked for access permissions as well. 95.Pp 96.\" Maybe this paragraph should be removed... 97The owner of a file has permission checked with respect to the 98.Dq owner 99read, write, and execute mode bits, members of the file's group 100other than the owner have permission checked with respect to the 101.Dq group 102mode bits, and all others have permissions checked with respect to 103the 104.Dq other 105mode bits. 106.Pp 107The file descriptor 108.Fa fd 109must name a directory. 110Search permission is required on this directory. 111.\" (These alternatives await a decision about the semantics of O_SEARCH) 112.\" Search permission is required on this directory, except if 113.\" .Fa fd 114.\" was opened with the 115.\" .Dv O_SEARCH 116.\" flag. 117.\" - or - 118.\" The directory referred to by 119.\" .Fa fd 120.\" must have been opened with the 121.\" .Dv O_SEARCH 122.\" flag. 123.\" - or - 124.\" The directory referred to by 125.\" .Fa fd 126.\" must have been opened with the 127.\" .Dv O_SEARCH 128.\" flag or must be searchable by the current process at the time the 129.\" call is made. 130.Pp 131The 132.Fa flags 133argument to 134.Fn faccessat 135can specify the following optional behavior: 136.Bl -tag -width AT_SYMLINK_NOFOLLOW 137.It AT_EACCESS 138Use the effective user and group IDs instead of the real user and 139group IDs for checking permission. 140See discussion below. 141.It AT_SYMLINK_NOFOLLOW 142Do not follow a symbolic link encountered as the last component in 143.Fa path . 144.El 145.Pp 146For 147.Fn access , 148and 149.Fn faccessat 150when the 151.Dv AT_EACCESS 152flag is not passed, the real user ID and the real group ID are used 153for checking permission in place of the effective user ID and 154effective group ID. 155This affects only set-user-ID and set-group-ID programs, which should 156not use these functions. 157(For other programs, the real and effective IDs are the same.) 158.Pp 159For processes running with super-user privileges, these functions may 160return success for read and write checks regardless of whether read 161and write permission bits are actually set. 162This reflects the fact that the super-user may read and write all 163files regardless of permission settings. 164However, even for the super-user, an execute check using 165.Dv X_OK 166will succeed only if the target object has at least one of its 167execute permission bits set. 168.\" XXX: Is this true of search permission and directories? (I believe so.) 169(This does not guarantee that the target object can necessarily be 170successfully executed. 171See 172.Xr execve 2 . ) 173.Sh RETURN VALUES 174The 175.Fn access 176and 177.Fn faccessat 178functions succeed and return 0 if, at some point in the recent past, 179the target object named by 180.Fa path 181existed and its permission settings allowed the requested access as 182described above. 183If the requested access would not have been granted, the object did 184not exist, or the path lookup failed, the value \-1 is returned 185and the value of 186.Va errno 187is set to reflect what went wrong. 188.Sh ERRORS 189These functions fail if: 190.Bl -tag -width Er 191.It Bq Er EACCES 192Search permission is denied for 193.Fa fd , 194or for the current directory, or for a directory in the prefix of 195.Fa path ; 196or the permission bits on the target file system object do not permit 197the requested access. 198.It Bq Er EBADF 199The file descriptor 200.Fa fd 201is not open and is not 202.Dv AT_FDCWD . 203.\" (possibly -- future) 204.\" or was not opened for searching with 205.\" .Dv O_SEARCH . 206.It Bq Er EFAULT 207.Fa path 208points outside the process's allocated address space. 209.It Bq Er EINVAL 210The 211.Fa mode 212or 213.Fa flags 214argument contained an invalid value. 215.It Bq Er EIO 216An I/O error occurred while reading from or writing to the file system. 217.It Bq Er ELOOP 218Too many symbolic links were encountered in translating the pathname. 219.It Bq Er ENAMETOOLONG 220A component of a pathname exceeded 221.Brq Dv NAME_MAX 222characters, or an entire path name exceeded 223.Brq Dv PATH_MAX 224characters. 225.It Bq Er ENOENT 226The named file does not exist. 227.It Bq Er ENOTDIR 228The file descriptor 229.Fa fd 230does not name a directory, or a component of the path prefix is not a 231directory. 232.It Bq Er EROFS 233Write access is requested for a file on a read-only file system. 234.It Bq Er ETXTBSY 235Write access is requested for a pure procedure (shared text) 236file presently being executed. 237.El 238.Sh SEE ALSO 239.Xr chmod 2 , 240.Xr execve 2 , 241.Xr stat 2 , 242.Xr secure_path 3 243.Sh STANDARDS 244The 245.Fn access 246function conforms to 247.St -p1003.1-90 . 248.Fn faccessat 249function conforms to 250.St -p1003.1-2008 . 251.\" This paragraph could be moved to the end of DESCRIPTION if people 252.\" don't like having it here. 253.Pp 254Note that 255.Fn faccessat 256violates the historic convention that system calls whose names begin 257with `f' operate on file handles rather than paths. 258There is no equivalent to 259.Fn access 260for checking access properties of an already-opened file. 261.Sh SECURITY CONSIDERATIONS 262Because the results of these calls reflect the state of the file 263system at the time they ran, and the file system can potentially be 264modified between that time and the time the caller attempts to act on 265the results, they should 266.Em never 267be used for security enforcement. 268.Pp 269Privileged programs that need to restrict their actions to files or 270directories properly accessible to unprivileged users 271.Em must 272do this by assuming or restoring an unprivileged state (see 273.Xr seteuid 2 ) 274when performing the pertinent actions. 275Checking in advance (with 276.Fn access 277or any other method) and performing such actions while privileged 278introduces a race condition that in most cases is easily exploitable 279by even a naive adversary. 280.Pp 281Even for non-privileged programs, the opportunity for the world to 282change after the call runs makes 283.Fn access 284and 285.Fn faccessat 286not very useful. 287In general only 288.Dv F_OK 289should be used, and that sparingly. 290The other checks may occasionally be useful for user interface or 291diagnostic purposes. 292