Check if a file or directory at a given location can be accessed
Synopsis:
#include <fcntl.h>
int faccessat( int dirfd,
const char* const path,
int const amode,
int const flags );
Arguments:
- dirfd
- A file descriptor that indicates the base directory for relative file paths.
The pathname given in path is resolved by appending it to the directory associated with dirfd.
You can set this argument to AT_FDCWD to use the current working directory as the base directory.
Note: You must use a file descriptor obtained from an
open() call with the
O_DIRECTORY flag set. Otherwise, the function fails and sets
errno to
ENOTDIR.
If path specifies an absolute path, dirfd has no effect.
- path
- The pathname of the file or directory whose accessibility you want to check.
This can be absolute or relative; for details of how relative pathname resolution is done, see above.
- amode
- Either the bitwise-inclusive OR of the access permissions to be checked
(R_OK, W_OK, X_OK) or the existence test (F_OK).
- flags
- A bitfield of the following flags:
- AT_EACCESS —
perform the accessibility check of the file or directory (and the directory permissions check during pathname resolution)
using the effective user ID and group ID instead of the real user ID and group ID
Library:
libc
Use the -l c option to
qcc
to link against this library.
This library is usually included automatically.
Description:
The faccessat() function checks if the file or directory named by path is accessible based on the
permissions in amode. The path argument can contain an absolute or relative path. In the latter case,
the dirfd argument is used to resolve the pathname, as explained in this argument's description (above).
If the access mode of the open file description associated with the dirfd file descriptor is not
O_SEARCH,
the function checks if directory searches are permitted using the current permissions of the directory underlying the file descriptor.
If the access mode is O_SEARCH, the function doesn't perform the check.
When the flags field is 0, this function is equivalent to access() when path is
an absolute and not a relative path.
For details about other possible flags settings, see this argument's description (above).
This function can be used to test for the existence of a file or directory or to check if a certain user has read, write, or execute access
to it. However, the permissions can change between the time the client calls this function and the time they access the file or directory.
Returns:
- 0
- The file or directory exists and can be accessed with the specified mode.
- -1
- The file or directory can't be accessed with the specified mode,
or an error occurred (errno is set).
Errors:
- EACCES
- The file or directory doesn't permit the requested access, search permission is denied on a component of the path prefix,
or the access mode of the directory associated with dirfd is not O_SEARCH and the underlying
directory doesn't permit searching.
- EBADF
- The path argument does not specify an absolute path and the dirfd argument is
neither AT_FDCWD nor a valid file descriptor open for reading or searching.
- EINVAL
- An invalid value was specified for amode or flag.
- ELOOP
- During resolution of the path argument,
a loop was found in the symbolic links or more than SYMLOOP_MAX symbolic links were encountered.
- ENAMETOOLONG
- The length of a pathname component in path exceeds NAME_MAX, the length of the entire pathname exceeds
PATH_MAX, or the path component generated from a symbolic link resolution has a length exceeding PATH_MAX.
- ENOENT
- A component of the specified path doesn't name an existing file, or path is an empty string.
- ENOTDIR
- One of the following conditions is true:
- A component of the path prefix names an existing file that is neither a directory nor a symbolic link to one.
- The path argument contains at least one non-slash character, ends with at least one slash character
(/), and the last component names an existing file that is neither a directory nor a symbolic link to one.
- The path argument is not an absolute path and dirfd is associated with a non-directory
file.
- The file descriptor in dirfd was created without O_DIRECTORY set.
- EROFS
- Write access is requested for a file on a read-only filesystem.
- ETXTBSY
- Write access is requested for a pure procedure (shared text) file that is being executed.
Classification:
POSIX 2008
| Safety: |
|
|---|
| Cancellation point |
No |
| Interrupt handler |
No |
| Signal handler |
Yes |
| Thread |
Yes |