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.Pp 119Even if a process has appropriate privileges and indicates success for 120.Dv X_OK , 121the file may not actually have execute permission bits set. 122Likewise for 123.Dv R_OK 124and 125.Dv W_OK . 126.Sh RETURN VALUES 127.Rv -std 128.Sh ERRORS 129.Fn access 130or 131.Fn faccessat 132will fail if: 133.Bl -tag -width Er 134.It Bq Er EINVAL 135The value of the 136.Fa mode 137argument is invalid. 138.It Bq Er ENOTDIR 139A component of the path prefix is not a directory. 140.It Bq Er ENAMETOOLONG 141A component of a pathname exceeded 142.Dv {NAME_MAX} 143characters, or an entire path name exceeded 144.Dv {PATH_MAX} 145characters. 146.It Bq Er ENOENT 147The named file does not exist. 148.It Bq Er ELOOP 149Too many symbolic links were encountered in translating the pathname. 150.It Bq Er EROFS 151Write access is requested for a file on a read-only file system. 152.It Bq Er ETXTBSY 153Write access is requested for a pure procedure (shared text) 154file presently being executed. 155.It Bq Er EACCES 156Permission bits of the file mode do not permit the requested 157access, or search permission is denied on a component of the 158path prefix. 159.It Bq Er EFAULT 160The 161.Fa path 162argument 163points outside the process's allocated address space. 164.It Bq Er EIO 165An I/O error occurred while reading from or writing to the file system. 166.El 167.Pp 168Also, the 169.Fn faccessat 170system call may fail if: 171.Bl -tag -width Er 172.It Bq Er EBADF 173The 174.Fa path 175argument does not specify an absolute path and the 176.Fa fd 177argument is 178neither 179.Dv AT_FDCWD 180nor a valid file descriptor. 181.It Bq Er EINVAL 182The value of the 183.Fa flag 184argument is not valid. 185.It Bq Er ENOTDIR 186The 187.Fa path 188argument is not an absolute path and 189.Fa fd 190is neither 191.Dv AT_FDCWD 192nor a file descriptor associated with a directory. 193.El 194.Sh SEE ALSO 195.Xr chmod 2 , 196.Xr intro 2 , 197.Xr stat 2 198.Sh STANDARDS 199The 200.Fn access 201system call is expected to conform to 202.St -p1003.1-90 . 203The 204.Fn faccessat 205system call is expected to conform to POSIX.1-2008 . 206.Sh HISTORY 207The 208.Fn access 209function appeared in 210.At v7 . 211.Sh SECURITY CONSIDERATIONS 212The result of 213.Fn access 214should not be used to make an actual access control decision, since its 215response, even if correct at the moment it is formed, may be outdated at the 216time you act on it. 217.Fn access 218results should only be used to pre-flight, such as when configuring user 219interface elements or for optimization purposes. The actual access control 220decision should be made by attempting to execute the relevant system call while 221holding the applicable credentials, and properly handling any resulting errors; 222and this must be done even though 223.Fn access 224may have predicted success. 225.Pp 226Additionally, set-user-ID and set-group-ID applications should restore the 227effective user or group ID, 228and perform actions directly rather than use 229.Fn access 230to simulate access checks for the real user or group ID. 231