Determines the accessibility of a file.
Standard C Library (libc.a)
#include <unistd.h>int access (PathName,Mode)
char *PathName;
int Mode;
int accessx (PathName, Mode, Who)
char *PathName;
int Mode, Who;
int faccessx (FileDescriptor, Mode, Who)
int FileDescriptor;
int Mode, Who;
int accessxat (DirFileDescriptor, PathName, Mode, Who)
int DirFileDescriptor;
char *PathName;
int Mode, Who;
int faccessat (DirFileDescriptor, PathName, Mode, Flag)
int DirFileDescriptor;
char *PathName;
int Mode, Flag;
The access, accessx, accessxat, faccessat and faccessx subroutines determine the accessibility of a file system object. The accessx, accessxat, and faccessx subroutines allow the specification of a class of users or processes for whom access is to be checked.
The caller must have search permission for all components of the PathName parameter.
The accessxat subroutine is equivalent to the accessx subroutine, and the faccessat subroutine is equivalent to the access subroutine if the PathName parameter specifies an absolute path or if the DirFileDescriptor parameter is set to AT_FDCWD. The file accessibility is determined by the relative path to the directory that is associated with the DirFileDescriptor parameter instead of the current working directory. If the directory is accessed without the O_SEARCH open flag, the subroutine checks to determine whether directory searches are permitted by using the current permissions of the directory. If the directory is accessed with the O_SEARCH open flag, the subroutine does not perform the check.
| Item | Description |
|---|---|
| PathName | Specifies the path name of the file. If the PathName parameter refers to a symbolic link, the access subroutine returns information about the file pointed to by the symbolic link. If the DirFileDescriptor is specified and PathName is relative, then the DirFileDescriptor specifies the effective current working directory for the PathName. |
| FileDescriptor | Specifies the file descriptor of an open file. |
| Mode | Specifies the access modes to be checked. This parameter is
a bit mask containing 0 or more of the following values, which are
defined in the <sys/access.h> file:
If none of these values are specified, the existence of a file is checked. |
| Who | Specifies the class of users for whom access is to be checked.
This parameter must be one of the following values, which are defined
in the <sys/access.h> file:
|
| DirFileDescriptor | Specifies the file descriptor of an open directory, which is used as the effective current working directory for the PathName argument. If the DirFileDescriptor parameter equals AT_FDCWD, the DirFileDescriptor parameter is ignored and the PathName argument specifies the complete file. |
| Flag | Specifies a bit field argument. If the Flag parameter equals AT_EACCESS, the effective user and group IDs are checked (ACC_SELF). If the Flag parameter is zero, the real IDs are checked (ACC_INVOKER). |
If the requested access is permitted, the access, accessx, faccessx, accessxat, and faccessat subroutines return a value of 0. If the requested access is not permitted or the function call fails, a value of -1 is returned and the errno global variable is set to indicate the error.
The access subroutine indicates success for X_OK even if none of the execute file permission bits are set.
The access faccessat, accessx, and accessx subroutines fail if one or more of the following are true:
| Item | Description |
|---|---|
| EACCES | Search permission is denied on a component of the PathName prefix. |
| EFAULT | The PathName parameter points to a location outside the allocated address space of the process. |
| ELOOP | Too many symbolic links were encountered in translating the PathName parameter. |
| ENAMETOOLONG | A component of the PathName parameter exceeded 255 characters or the entire PathName parameter exceeded 1022 characters. |
| ENOENT | A component of the PathName does not exist or the process has the disallow truncation attribute set. |
| ENOENT | The named file does not exist. |
| ENOENT | The PathName parameter was null. |
| ENOENT | A symbolic link was named, but the file to which it refers does not exist. |
| ENOTDIR | A component of the PathName is not a directory. |
| ESTALE | The process root or current directory is located in a virtual file system that has been unmounted. |
The faccessx subroutine fails if the following is true:
| Item | Description |
|---|---|
| EBADF | The value of the FileDescriptor parameter is not valid. |
The access, accessx, and faccessx subroutines fail if one or more of the following is true:
| Item | Description |
|---|---|
| EACCES | The file protection does not allow the requested access. |
| ENOMEM | Unable to allocate memory. |
| EIO | An I/O error occurred during the operation. |
| EROFS | Write access is requested for a file on a read-only file system. |
The accessxat and faccessat subroutines fail if one or more of the following settings are true:
| Item | Description |
|---|---|
| EBADF | The PathName parameter does not specify an absolute path and the DirFileDescriptor argument is neither AT_FDCWD nor a valid file descriptor. |
| EINVAL | The value of the Flag parameter is not valid. |
| ENOTDIR | The PathName parameter is not an absolute path and DirFileDescriptor is a file descriptor but is not associated with a directory. |
If Network File System (NFS) is installed on your system, the accessx, accessxat, and faccessx subroutines can also fail if the following settings are true:
| Item | Description |
|---|---|
| ETIMEDOUT | The connection timed out. |
| ETXTBSY | Write access is requested for a shared text file that is being executed. |
| EINVAL | The value of the Mode argument is invalid. |