Open a file
Synopsis:
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open( const char * path,
int oflag,
... );
int open64( const char * path,
int oflag,
... );
Arguments:
- path
- The path name 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,
below.
Library:
libc
Use the -l c option to
qcc
to link against this library.
This library is usually included automatically.
Description:
The open() and open64() functions open 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 open64() function is a large-file support version of open().
If the size of the file is more than the maximum value that can be represented correctly in an
off_t, you should use open64().
Note:
- In QNX Neutrino 6.6 or later, the large-file support functions and data types
appear in the name space only if you define _LARGEFILE64_SOURCE when you compile your code.
For more information, see
Classification
in What's in a Function Description?
- The open() and open64() functions
ignore any advisory locks that you set with
fcntl().
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.
Construct the value of oflag by bitwise ORing values
from the following list, defined in the <fcntl.h>
header file.
You must specify exactly one of the following file access modes in the value of oflag:
- O_RDONLY
- Open for reading only.
- O_RDWR
- Open for reading and writing.
Opening a FIFO for read-write is unsupported.
- O_WRONLY
- Open for writing only.
You can also specify any combination of the remaining flags in the value
of oflag:
- O_APPEND
- If set, the file offset is set to the end of the file prior to each write.
- O_ASYNC
- (QNX Neutrino extension) Not currently supported.
- O_CLOEXEC
- Close the file descriptor if the program calls
one of the exec*(), posix_spawn*(), or spawn*() functions.
This flag is a shortcut that's equivalent to calling
fcntl()
with F_SETFD and
FD_CLOEXEC after opening the file.
- O_CREAT
- This option requires a third argument, mode, which is of type mode_t.
If the file exists, this flag has no effect, except in combination with O_EXCL as noted below.
Otherwise, the file is created; the file's user ID is set to the
effective user ID of the process; the group ID is set to the effective
group ID of the process or the group ID of the file's parent
directory (see chmod()).
The permission bits, as defined in <sys/stat.h>,
are set to the value of mode, except those bits set in
the process's file mode creation mask (see
umask() for details).
Bits set in mode other than
the file permission bits (i.e., the file type bits) are ignored.
The mode argument doesn't affect whether the file is opened for reading, for writing, or for both.
CAUTION:
The open() and open64() functions are varargs functions.
If you specify O_CREAT but you don't provide a mode argument, they
use whatever is on the stack as the mode.
- O_DSYNC
- If set, this flag affects subsequent I/O calls; each call to
write()
waits until all data is successfully transferred
to the storage device such that it's readable on any subsequent open of
the file (even one that follows a system failure) in the absence of a
failure of the physical storage medium. If the physical storage medium
implements a non-write-through cache, then a system failure may be
interpreted as a failure of the physical storage medium, and data may
not be readable even if this flag is set and the write()
indicates that it succeeded.
- O_EXCL
- If you set both O_EXCL and O_CREAT,
open() fails if the file exists. The check for the
existence of the file and the creation of the file if it doesn't
exist are atomic; no other process that's attempting the same
operation with the same filename at the same time will succeed.
Specifying O_EXCL
without O_CREAT has no effect.
- O_LARGEFILE
- (QNX Neutrino extension) Allow the file offset to be 64 bits long.
- O_NOCTTY
- If set, and path identifies a terminal device, the
open() function doesn't cause the terminal device to become
the controlling terminal for the process.
- O_NOFOLLOW
- (QNX Neutrino 6.6 or later) If the last component in the path is a symlink, make the open fail
with an error of ELOOP.
- O_NONBLOCK
-
- When you're opening a FIFO with O_RDONLY or O_WRONLY set:
- If O_NONBLOCK is set:
- Calling open() for reading-only returns without delay.
Calling open() for writing-only
returns an error if no process currently has the FIFO open for reading.
- If O_NONBLOCK is clear:
- Calling open() for reading-only blocks until
a process opens the file for writing.
Calling open() for writing-only blocks until a process opens the file for reading.
- When you're opening a block special or character special file that supports nonblocking opens:
- If O_NONBLOCK is set:
- The open() function returns without waiting for the device to be ready or available.
Subsequent behavior of the device is device-specific.
- If O_NONBLOCK is clear:
- The open() function waits until the device is ready or available before returning.
The definition of when a device is ready is device-specific.
- Otherwise, the O_NONBLOCK flag doesn't cause an error, but it is unspecified whether the file status flags
will include O_NONBLOCK.
- O_NOSYMLINK
- (QNX Neutrino extension) If any component in the path is a symlink, make the open fail
with an error of ELOOP.
- O_REALIDS
- (QNX Neutrino extension) Use the real uid/gid
for permissions checking.
- O_RSYNC
- Read I/O operations on the file descriptor complete at the same level of integrity as
specified by the O_DSYNC and O_SYNC flags.
- O_SYNC
- If set, this flag affects subsequent I/O calls; each call to
read()
or
write()
is complete only when both the data has been successfully transferred
(either read or written) and all file system information relevant to
that I/O operation (including that required to retrieve said data) is
successfully transferred, including file update and/or access times,
and so on. See the discussion of a successful data transfer in O_DSYNC, above.
- O_TRUNC
- If the file exists and is a regular file, and the file is successfully
opened O_WRONLY or O_RDWR,
the file length is truncated to zero and the mode and owner are left
unchanged. O_TRUNC has no effect on FIFO or block or
character special files or directories. Using O_TRUNC
with O_RDONLY has no effect.
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
- Search permission is denied on a component of the path prefix, or the
file exists and the permissions specified by oflag
are denied, or the file doesn't exist and write permission is denied
for the parent directory of the file to be created.
- EBADFSYS
- While attempting to open the named file, either the file itself or a
component of the path prefix was found to be corrupted.
A system failure—from which no automatic recovery is possible—occurred while
the file was being written to, or while the directory was
being updated. You'll need to invoke appropriate
systems-administration procedures to correct this situation before proceeding.
- EBUSY
- File access was denied due to a conflicting open (see
sopen()).
- EEXIST
- The O_CREAT and O_EXCL flags are set, and the named file exists.
- EINTR
- The open() 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).
- EISDIR
- The named file is a directory, and the oflag
argument specifies write-only or read/write access.
- ELOOP
- Too many levels of symbolic links or prefixes, 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,
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;
or O_CREAT is set and either the path prefix doesn't
exist, or the path argument points to an empty string.
- 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.
- ENOSYS
- The open() function isn't implemented for the filesystem specified
in path.
- ENOTDIR
- A component of the path prefix isn't a directory.
- ENXIO
- One of the following:
- 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 media associated with the file (e.g., a CD) has been removed.
- EOVERFLOW
- The named file is a regular file and the size of the file can't be
represented correctly in an object of type off_t.
- EPERM
- The process doesn't have the necessary MAC permissions to connect.
- 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 the
oflag argument.
- ETXTBSY
- The file is a pure procedure (shared text) file that's currently being executed
and oflag is O_WRONLY or O_RDWR.
Examples:
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <stdlib.h>
int main( void )
{
int fd;
/* open a file for output */
/* replace existing file if it exists */
/* with read/write perms for owner */
fd = open( "myfile.dat",
O_WRONLY | O_CREAT | O_TRUNC,
S_IRUSR | S_IWUSR );
/* read a file that is assumed to exist */
fd = open( "myfile.dat", O_RDONLY );
/* append to the end of an existing file */
/* write a new file if file doesn't exist */
/* with full read/write permissions */
fd = open( "myfile.dat",
O_WRONLY | O_CREAT | O_APPEND,
S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP
| S_IROTH | S_IWOTH );
return EXIT_SUCCESS;
}
Classification:
open() is
POSIX 1003.1;
open64() is
Large-file support
Safety: |
|
Cancellation point |
Yes |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Yes |
Caveats:
The open() function includes POSIX 1003.1-1996 and QNX Neutrino extensions.