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.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)access.2 8.2 (Berkeley) 4/1/94 29.\" $FreeBSD$ 30.\" 31.Dd September 15, 2014 32.Dt ACCESS 2 33.Os 34.Sh NAME 35.Nm access , 36.Nm faccessat 37.Nd check accessibility of a file 38.Sh SYNOPSIS 39.In unistd.h 40.Ft int 41.Fn access "const char *path" "int mode" 42.Ft int 43.Fn faccessat "int fd" "const char *path" "int mode" "int flag" 44.Sh DESCRIPTION 45The 46.Fn access 47system call checks the accessibility of the 48file named by 49the 50.Fa path 51argument 52for the access permissions indicated by 53the 54.Fa mode 55argument. 56The value of 57.Fa mode 58is either the bitwise-inclusive OR of the access permissions to be 59checked 60.Dv ( R_OK 61for read permission, 62.Dv W_OK 63for write permission, and 64.Dv X_OK 65for execute/search permission), 66or the existence test 67.Pq Dv F_OK . 68.Pp 69For additional information, see the 70.Sx "File Access Permission" 71section of 72.Xr intro 2 . 73.Pp 74The 75.Fn access 76system call uses 77the real user ID in place of the effective user ID, 78the real group ID in place of the effective group ID, 79and the rest of the group access list. 80.Pp 81The 82.Fn faccessat 83system call is equivalent to 84.Fn access 85except in the case where 86.Fa path 87specifies a relative path. 88In this case the file whose accessibility is to be determined is 89located relative to the directory associated with the file descriptor 90.Fa fd 91instead of the current working directory. 92If 93.Fn faccessat 94is passed the special value 95.Dv AT_FDCWD 96in the 97.Fa fd 98parameter, the current working directory is used and the behavior is 99identical to a call to 100.Fn access . 101Values for 102.Fa flag 103are constructed by a bitwise-inclusive OR of flags from the following 104list, defined in 105.In fcntl.h : 106.Bl -tag -width indent 107.It Dv AT_EACCESS 108The checks for accessibility are performed using the effective user and group 109IDs instead of the real user and group ID as required in a call to 110.Fn access . 111.El 112.Bl -tag -width indent 113.It Dv AT_SYMLINK_NOFOLLOW 114If 115.Fa path 116names a symbolic link, the status of the symbolic link is returned. 117.El 118.Bl -tag -width indent 119.It Dv AT_SYMLINK_NOFOLLOW_ANY 120If 121.Fa path 122names a symbolic link, the status of the symbolic link is returned and if the 123path has any other symbolic links, an error is returned. 124.El 125.Pp 126Even if a process has appropriate privileges and indicates success for 127.Dv X_OK , 128the file may not actually have execute permission bits set. 129Likewise for 130.Dv R_OK 131and 132.Dv W_OK . 133.Sh RETURN VALUES 134.Rv -std 135.Sh ERRORS 136.Fn access 137or 138.Fn faccessat 139will fail if: 140.Bl -tag -width Er 141.It Bq Er EINVAL 142The value of the 143.Fa mode 144argument is invalid. 145.It Bq Er ENOTDIR 146A component of the path prefix is not a directory. 147.It Bq Er ENAMETOOLONG 148A component of a pathname exceeded 149.Dv {NAME_MAX} 150characters, or an entire path name exceeded 151.Dv {PATH_MAX} 152characters. 153.It Bq Er ENOENT 154The named file does not exist. 155.It Bq Er ELOOP 156Too many symbolic links were encountered in translating the pathname. 157.It Bq Er ELOOP 158AT_SYMLINK_NOFOLLOW_ANY was passed and a symbolic link was encountered 159in translating the pathname. 160.It Bq Er EROFS 161Write access is requested for a file on a read-only file system. 162.It Bq Er ETXTBSY 163Write access is requested for a pure procedure (shared text) 164file presently being executed. 165.It Bq Er EACCES 166Permission bits of the file mode do not permit the requested 167access, or search permission is denied on a component of the 168path prefix. 169.It Bq Er EFAULT 170The 171.Fa path 172argument 173points outside the process's allocated address space. 174.It Bq Er EIO 175An I/O error occurred while reading from or writing to the file system. 176.El 177.Pp 178Also, the 179.Fn faccessat 180system call may fail if: 181.Bl -tag -width Er 182.It Bq Er EBADF 183The 184.Fa path 185argument does not specify an absolute path and the 186.Fa fd 187argument is 188neither 189.Dv AT_FDCWD 190nor a valid file descriptor. 191.It Bq Er EINVAL 192The value of the 193.Fa flag 194argument is not valid. 195.It Bq Er ENOTDIR 196The 197.Fa path 198argument is not an absolute path and 199.Fa fd 200is neither 201.Dv AT_FDCWD 202nor a file descriptor associated with a directory. 203.El 204.Sh SEE ALSO 205.Xr chmod 2 , 206.Xr intro 2 , 207.Xr stat 2 208.Sh STANDARDS 209The 210.Fn access 211system call is expected to conform to 212.St -p1003.1-90 . 213The 214.Fn faccessat 215system call is expected to conform to POSIX.1-2008 . 216.Sh HISTORY 217The 218.Fn access 219function appeared in 220.At v7 . 221.Sh SECURITY CONSIDERATIONS 222The result of 223.Fn access 224should not be used to make an actual access control decision, since its 225response, even if correct at the moment it is formed, may be outdated at the 226time you act on it. 227.Fn access 228results should only be used to pre-flight, such as when configuring user 229interface elements or for optimization purposes. The actual access control 230decision should be made by attempting to execute the relevant system call while 231holding the applicable credentials, and properly handling any resulting errors; 232and this must be done even though 233.Fn access 234may have predicted success. 235.Pp 236Additionally, set-user-ID and set-group-ID applications should restore the 237effective user or group ID, 238and perform actions directly rather than use 239.Fn access 240to simulate access checks for the real user or group ID. 241