| 1 | .\" Copyright (c) 1980 Regents of the University of California. |
| 2 | .\" All rights reserved. The Berkeley software License Agreement |
| 3 | .\" specifies the terms and conditions for redistribution. |
| 4 | .\" |
| 5 | .\" @(#)access.2 6.2 (Berkeley) %G% |
| 6 | .\" |
| 7 | .TH ACCESS 2 "" |
| 8 | .UC 4 |
| 9 | .SH NAME |
| 10 | access \- determine accessibility of file |
| 11 | .SH SYNOPSIS |
| 12 | .nf |
| 13 | .ft B |
| 14 | #include <sys/file.h> |
| 15 | .PP |
| 16 | .ft B |
| 17 | .ta 1.25i 1.6i |
| 18 | #define R_OK 4 /* test for read permission */ |
| 19 | #define W_OK 2 /* test for write permission */ |
| 20 | #define X_OK 1 /* test for execute (search) permission */ |
| 21 | #define F_OK 0 /* test for presence of file */ |
| 22 | .PP |
| 23 | .ft B |
| 24 | accessible = access(path, mode) |
| 25 | int accessible; |
| 26 | char *path; |
| 27 | int mode; |
| 28 | .ft R |
| 29 | .fi |
| 30 | .SH DESCRIPTION |
| 31 | .I Access |
| 32 | checks the given |
| 33 | file |
| 34 | .I path |
| 35 | for accessibility according to |
| 36 | .IR mode , |
| 37 | which is an inclusive or of the bits |
| 38 | R_OK, |
| 39 | W_OK |
| 40 | and |
| 41 | X_OK. |
| 42 | Specifying |
| 43 | .I mode |
| 44 | as F_OK (i.e. 0) |
| 45 | tests whether the directories leading to the file can be |
| 46 | searched and the file exists. |
| 47 | .PP |
| 48 | The real user ID and the group access list |
| 49 | (including the real group ID) are |
| 50 | used in verifying permission, so this call |
| 51 | is useful to set-UID programs. |
| 52 | .PP |
| 53 | Notice that only access bits are checked. |
| 54 | A directory may be indicated as writable by |
| 55 | .IR access , |
| 56 | but an attempt to open it for writing will fail |
| 57 | (although files may be created there); |
| 58 | a file may look executable, but |
| 59 | .I execve |
| 60 | will fail unless it is in proper format. |
| 61 | .SH "RETURN VALUE |
| 62 | If |
| 63 | .I path |
| 64 | cannot be found or if any of the desired access modes would |
| 65 | not be granted, then a \-1 value is returned; otherwise |
| 66 | a 0 value is returned. |
| 67 | .SH "ERRORS |
| 68 | Access to the file is denied if one or more of the following are true: |
| 69 | .TP 15 |
| 70 | [ENOTDIR] |
| 71 | A component of the path prefix is not a directory. |
| 72 | .TP 15 |
| 73 | [ENOENT] |
| 74 | The argument path name was too long. |
| 75 | .TP 15 |
| 76 | [ENOENT] |
| 77 | Read, write, or execute (search) permission is requested for a null |
| 78 | path name or the named file does not exist. |
| 79 | .TP 15 |
| 80 | [EPERM] |
| 81 | The argument contains a byte with the high-order bit set. |
| 82 | .TP 15 |
| 83 | [ELOOP] |
| 84 | Too many symbolic links were encountered in translating the pathname. |
| 85 | .TP 15 |
| 86 | [EROFS] |
| 87 | Write access is requested for a file on a read-only file system. |
| 88 | .TP 15 |
| 89 | [ETXTBSY] |
| 90 | Write access is requested for a pure procedure (shared text) |
| 91 | file that is being executed. |
| 92 | .TP 15 |
| 93 | [EACCES] |
| 94 | Permission bits of the file mode do not permit the requested |
| 95 | access; or search permission is denied on a component of the |
| 96 | path prefix. The owner of a file has permission checked with |
| 97 | respect to the ``owner'' read, write, and execute mode bits, |
| 98 | members of the file's group other than the owner have permission |
| 99 | checked with respect to the ``group'' mode bits, and all |
| 100 | others have permissions checked with respect to the ``other'' |
| 101 | mode bits. |
| 102 | .TP 15 |
| 103 | [EFAULT] |
| 104 | .I Path |
| 105 | points outside the process's allocated address space. |
| 106 | .SH "SEE ALSO |
| 107 | chmod(2), stat(2) |