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 |