openat()

Updated: May 06, 2022

Open a file at a given location

Synopsis:

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

int openat( int fd,
            const char* path,
            int oflag, 
            ... );

Arguments:

fd
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 fd. 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, fd has no effect.

path
The pathname of the file that you want to open.
oflag
Flags that specify the status and access modes of the file; see below.
If you set O_CREAT in oflag, you must also specify the following argument:
mode_t mode
An object of type mode_t that specifies the access mode that you want to use for a newly created file. For more information, see the entry for struct stat, and the description of O_CREAT in the open() reference.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The openat() function opens the file named by path, creating an open file description that refers to the file, and a file descriptor that refers to the file description. The path argument can contain an absolute or relative path. In the latter case, the fd 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 fd 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.

QNX Neutrino has no concept of a path operation (open(), readlink(), etc.) that references a path relative to an already open file descriptor (for a directory), as far as the filesystem resource manager is concerned. Therefore, it's not possible to eliminate the race inherent in looking up a pathname with multiple intervening directories or symbolic links. However, openat() can still be used for maintaining a per-thread current working directory, using file descriptors maintained by the application.

The open file descriptor created is new, and therefore isn't shared with any other process in the system.

The file status flags and the file access modes of the open file description are set according to the value of oflag. For information about constructing the value of oflag, including which access mode settings are required and which flag combinations are allowed, see the open() reference.

Returns:

A nonnegative integer representing the lowest numbered unused file descriptor. On a file capable of seeking, the file offset is set to the beginning of the file. Otherwise, -1 is returned (errno is set).

Note: In QNX Neutrino, the returned file descriptor is a connection ID (or coid) as used by the QNX Neutrino-specific functions (e.g., MsgSend()).

Errors:

EACCES
One of the following is true:
  • Search permission is denied on a component of the path prefix of path.
  • The file exists and the permissions specified by oflag are denied.
  • The file doesn't exist and write permission is denied for the parent directory of the file to be created.
  • The access mode of the fd file descriptor is not O_SEARCH and the underlying directory doesn't permit directory searches.
  • O_TRUNC is specified in oflag and write permission is denied.
EAGAIN
The path argument names the slave side of a pseudo-terminal device that is locked.
EBADF
The path argument does not specify an absolute path and the fd argument is neither AT_FDCWD nor a valid file descriptor open for reading or searching.
EEXIST
The O_CREAT and O_EXCL flags are set, and the named file exists.
EINTR
The openat() operation was interrupted by a signal.
EINVAL
The requested synchronized modes (O_SYNC, O_DSYNC, O_RSYNC) aren't supported (i.e, IOFUNC_PC_SYNC_IO isn't set in the device's mount configuration). Or, the value of oflag is invalid.
EIO
The path argument names a STREAMS file and a hangup or error occurred during the openat() operation.
EISDIR
The named file is a directory, and the oflag argument includes O_WRONLY or O_RDWR, or O_CREAT without O_DIRECTORY.
ELOOP
During resolution of the path argument, a loop was found in the symbolic links or more than SYMLOOP_MAX symbolic links were encountered, including these cases:
  • The flags include O_NOFOLLOW, and the last component of the path is a symbolic link.
  • The flags include O_NOSYMLINK, and any component of the path is a symbolic link.
EMFILE
All file descriptors available to the process are currently open.
ENAMETOOLONG
The length of the path string exceeds PATH_MAX, the resolution of a symbolic link within path produced a result longer than PATH_MAX, or a pathname component is longer than NAME_MAX.
ENFILE
Too many files are currently open in the system.
ENOENT
The O_CREAT flag isn't set and the named file doesn't exist, O_CREAT is set and the path prefix doesn't exist, or the path argument points to an empty string.
ENOMEM
The path argument names a STREAMS file and the system is unable to allocate resources.
ENOSPC
In the directory or filesystem that would contain the new file, there's not enough space available to create a new file or the maximum limit of files has been reached.
ENOSR
The path argument names a STREAMS file and the system is unable to allocate a STREAM.
ENOTDIR
One of the following is true:
  • A component of the path prefix names an existing file that is neither a directory nor a symbolic link to one.
  • O_CREAT and O_EXCL are not specified, 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.
  • O_DIRECTORY was specified in oflag but the path argument resolves to a non-directory file.
  • The path argument isn't an absolute path and fd is associated with a non-directory file.
  • The file descriptor in fd was created without O_DIRECTORY set.
ENXIO
One of the following is true:
  • The O_NONBLOCK flag is set, the named file is a FIFO, O_WRONLY is set, and no process has the file open for reading.
  • The named file is a character special or block special file, and the device associated with this special file does not exist. This could be because the media associated with the file (e.g., a CD) has been removed.
EOPNOTSUPP
The path argument names a socket.
EOVERFLOW
The named file is a regular file and its size can't be represented correctly in an off_t object.
EROFS
The named file resides on a read-only filesystem and either O_WRONLY, O_RDWR, O_CREAT (if the file doesn't exist), or O_TRUNC is set in oflag.
ETXTBSY
The file is a pure procedure (shared text) file that's currently being executed and oflag is O_WRONLY or O_RDWR.

Classification:

POSIX 2008

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes