| 1 | .\" Copyright (c) 1980, 1991, 1993 |
| 2 | .\" The Regents of the University of California. All rights reserved. |
| 3 | .\" |
| 4 | .\" %sccs.include.redist.man% |
| 5 | .\" |
| 6 | .\" @(#)access.2 8.1 (Berkeley) %G% |
| 7 | .\" |
| 8 | .Dd |
| 9 | .Dt ACCESS 2 |
| 10 | .Os BSD 4 |
| 11 | .Sh NAME |
| 12 | .Nm access |
| 13 | .Nd check access permissions of a file or pathname |
| 14 | .Sh SYNOPSIS |
| 15 | .Fd #include <unistd.h> |
| 16 | .Ft int |
| 17 | .Fn access "const char *path" "int mode" |
| 18 | .Sh DESCRIPTION |
| 19 | The |
| 20 | .Fn access |
| 21 | function checks the accessibility of the |
| 22 | file named by |
| 23 | .Fa path |
| 24 | for the access permissions indicated by |
| 25 | .Fa mode . |
| 26 | The value of |
| 27 | .Fa mode |
| 28 | is the bitwise inclusive OR of the access permissions to be |
| 29 | checked |
| 30 | .Pf ( Dv R_OK |
| 31 | for read permission, |
| 32 | .Dv W_OK |
| 33 | for write permission and |
| 34 | .Dv X_OK |
| 35 | for execute/search permission) or the existence test, |
| 36 | .Dv F_OK . |
| 37 | All components of the pathname |
| 38 | .Fa path |
| 39 | are checked for access permissions (including |
| 40 | .Dv F_OK ) . |
| 41 | .Pp |
| 42 | The real user ID is used in place of the effective user ID |
| 43 | and the real group access list |
| 44 | (including the real group ID) are |
| 45 | used in place of the effective ID for verifying permission. |
| 46 | .Pp |
| 47 | Even if a process has appropriate privileges and indicates success for |
| 48 | .Dv X_OK , |
| 49 | the file may not actually have execute permission bits set. |
| 50 | Likewise for |
| 51 | .Dv R_OK |
| 52 | and |
| 53 | .Dv W_OK . |
| 54 | .Sh RETURN VALUES |
| 55 | If |
| 56 | .Fa path |
| 57 | cannot be found or if any of the desired access modes would |
| 58 | not be granted, then a -1 value is returned; otherwise |
| 59 | a 0 value is returned. |
| 60 | .Sh ERRORS |
| 61 | Access to the file is denied if: |
| 62 | .Bl -tag -width Er |
| 63 | .It Bq Er ENOTDIR |
| 64 | A component of the path prefix is not a directory. |
| 65 | .It Bq Er EINVAL |
| 66 | The pathname contains a character with the high-order bit set. |
| 67 | .It Bq Er ENAMETOOLONG |
| 68 | A component of a pathname exceeded 255 characters, |
| 69 | or an entire path name exceeded 1023 characters. |
| 70 | .It Bq Er ENOENT |
| 71 | The named file does not exist. |
| 72 | .It Bq Er EACCES |
| 73 | Search permission is denied for a component of the path prefix. |
| 74 | .It Bq Er ELOOP |
| 75 | Too many symbolic links were encountered in translating the pathname. |
| 76 | .It Bq Er EROFS |
| 77 | Write access is requested for a file on a read-only file system. |
| 78 | .It Bq Er ETXTBSY |
| 79 | Write access is requested for a pure procedure (shared text) |
| 80 | file presently being executed. |
| 81 | .It Bq Er EACCES |
| 82 | Permission bits of the file mode do not permit the requested |
| 83 | access, or search permission is denied on a component of the |
| 84 | path prefix. The owner of a file has permission checked with |
| 85 | respect to the ``owner'' read, write, and execute mode bits, |
| 86 | members of the file's group other than the owner have permission |
| 87 | checked with respect to the ``group'' mode bits, and all |
| 88 | others have permissions checked with respect to the ``other'' |
| 89 | mode bits. |
| 90 | .It Bq Er EFAULT |
| 91 | .Fa Path |
| 92 | points outside the process's allocated address space. |
| 93 | .It Bq Er EIO |
| 94 | An I/O error occurred while reading from or writing to the file system. |
| 95 | .El |
| 96 | .Sh SEE ALSO |
| 97 | .Xr chmod 2 , |
| 98 | .Xr stat 2 |
| 99 | .Sh STANDARDS |
| 100 | .Fn Access |
| 101 | conforms to IEEE Std 1003.1-1988 |
| 102 | .Pq Dq Tn POSIX . |
| 103 | .Sh CAVEAT |
| 104 | .Fn Access |
| 105 | is a potential security hole and |
| 106 | should never be used. |