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