open(2)
open, open64 --
open for reading or writing
Synopsis
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open(const char path, int oflag, . . . /* mode_t mode */);
int open64(const char path, int oflag, . . . /* mode_t mode */);
Description
open opens a file descriptor for the file named
path and sets the file status flags
according to the value of oflag.
oflag values are constructed by OR-ing flags
from the following list (only one of the first three flags below
may be used):
O_RDONLY-
Open for reading only.
O_WRONLY-
Open for writing only.
O_RDWR-
Open for reading and writing.
O_LARGEFILE-
If set, the offset maximum in the open file descriptor will
be the largest value that can be represented correctly in
an object of type off64_t.
Using open with O_LARGEFILE set in oflag
is equivalent to using open64.
O_NDELAY or O_NONBLOCK-
These flags may affect subsequent reads and writes
(see
read(2)
and
write(2)).
If both O_NDELAY and O_NONBLOCK are set,
O_NONBLOCK will take precedence.
When opening a FIFO with O_RDONLY or O_WRONLY
set:
-
If O_NDELAY or O_NONBLOCK
is set:
An open for reading-only will return without delay;
an open for writing-only will return an error if no process
currently has the file open for reading.
-
If O_NDELAY and O_NONBLOCK are clear:
An open for reading-only will block until a process
opens the file for writing; an open
for writing-only will block until a process
opens the file for reading.
When opening a file associated with a terminal line:
-
If O_NDELAY or O_NONBLOCK is set:
The open will return without waiting for the device to be ready or
available; subsequent behavior of the device is device specific.
-
If O_NDELAY and O_NONBLOCK are clear:
The open will block until the device is ready or available.
O_APPEND-
If set, the file pointer will be set to the end of the file
prior to each write.
O_SYNC-
When opening a regular file, this flag affects subsequent writes.
If set, each write will wait for both the file data and file
status to be physically updated.
O_NOCTTY-
If set and the file is a terminal, the terminal will not be allocated as
the calling process's controlling terminal.
O_CREAT-
If the file exists, this flag has no effect, except as noted under
O_EXCL below.
Otherwise, the file is created and the owner ID of the file is set
to the effective user IDs of the process, the group ID of the file
is set to the effective group IDs of the process, or if the
S_ISGID bit is set in the directory in which the file is being
created, the file's group ID is set to the group ID of its parent directory.
If the group ID of the new file does not match the effective group
ID or one of the supplementary groups IDs, the S_ISGID bit is cleared.
The access permission bits of the file mode are set to the value of
mode, modified as follows (see
creat(2)):
-
All bits set in the file mode creation mask of the process are cleared
(see
umask(2)).
-
The ``save text image after execution bit'' of the mode is cleared
(see
chmod(2)).
-
This value, together with entries derived from the default entries of
the parent directory's access control list (ACL) are used to create an
ACL for the new file (see
acl(2)).
O_TRUNC -
If the file exists, its length is truncated to 0 and the mode and owner
are unchanged.
O_TRUNC
has no effect on special files or directories.
O_EXCL-
If O_EXCL and O_CREAT are set, open
will fail if the file exists.
The check for the existence of the file and the creation of the file if it
does not exist is atomic with respect to other processes executing open
naming the same filename in the same directory with O_EXCL and
O_CREAT set.
When opening a STREAMS file, oflag may be constructed from
O_NDELAY or O_NONBLOCK OR-ed with either O_RDONLY,
O_WRONLY, or O_RDWR.
Other flag values are not applicable to STREAMS devices and have no
effect on them.
The values of O_NDELAY and O_NONBLOCK affect
the operation of STREAMS drivers and certain system calls
(see
read(2),
getmsg(2),
putmsg(2),
and
write(2)).
For drivers, the implementation of O_NDELAY and
O_NONBLOCK is device specific.
Each STREAMS device driver may treat these options differently.
When open is invoked to open a named stream, and the connld module
(see
connld(7))
has been pushed on the pipe, open blocks until
the server process has issued an I_RECVFD ioctl (see
streamio(7))
to receive the file descriptor.
If path is a symbolic link and O_CREAT and O_EXCL are set,
the link is not followed.
The file pointer used to mark the current position within the file
is set to the beginning of the file.
The new file descriptor is the lowest numbered file descriptor available
and is set to remain open across exec system calls (see
fcntl(2)).
Certain flag values can be set following open as described in fcntl.
Using open on a file adds a reference to the file.
This guarantees that the file will continue to be visible to the process
until it closes it, even if the file is removed from the directory
by unlink.
Return values
On success, open returns the file descriptor of the open file and:
-
If O_CREAT is set and the file did not previously exist,
open marks for update the st_atime,
st_ctime and st_mtime fields of the file and the st_ctime
and st_mtime fields of the parent directory.
-
If O_TRUNC is set and the file did previously exist,
open marks for update the st_ctime and
st_mtime
fields of the file.
On failure, open returns -1 and sets errno to identify the error.
In the following conditions, open fails and sets errno to:
EOVERFLOW-
The named file is a regular file and either the size of the file cannot
be represented correctly in an object of type off_t, or
O_LARGEFILE is set and the size of the file cannot be
represented correctly in an object of type off64_t.
In the following conditions, open64 fails and sets errno to:
EOVERFLOW-
The named file is a regular file and
O_LARGEFILE is set and the size of the file cannot be
represented correctly in an object of type off64_t.
In the following conditions, open and open64 fail and set errno to:
EACCES-
The file does not exist and write permission is denied by the parent
directory of the file to be created.
EACCES-
O_CREAT or O_TRUNC
is specified and write permission is denied.
EACCES-
A component of the path prefix denies search permission.
EACCES-
oflag permission is denied for an existing file.
EAGAIN-
The file exists, mandatory file/record locking is set,
and there are outstanding record locks on the file
(see
chmod(2)).
EBUSY-
path points to a device special file and the device is in the
closing state.
EEXIST-
O_CREAT and O_EXCL are set, and the named file exists.
EFAULT-
path points outside the allocated address space of the process.
EINTR-
A signal was caught during the open system call.
EINVAL-
Returned when there are illegal flag values.
EIO-
A hangup or error occurred during the open of the STREAMS-based device.
EISDIR-
The named file is a directory and oflag is write or read/write.
ELOOP-
Too many symbolic links were encountered in translating path.
EMFILE-
The process has too many open files (see
getrlimit(2)).
EMULTIHOP-
Components of path require hopping to
multiple remote machines and the file system does not allow it.
ENAMETOOLONG-
The length of the path argument exceeds {PATH_MAX}, or the
length of a path component exceeds {NAME_MAX} while
{_POSIX_NO_TRUNC} is in effect.
ENFILE-
The system file table is full.
ENODEV-
path points to a device special file and the device is not in the
activated state.
ENOENT-
O_CREAT is not set and the named file does not exist.
ENOENT-
O_CREAT is set and a component of the path prefix
does not exist or is the null pathname.
ENOLINK-
path points to a remote machine, and the link
to that machine is no longer active.
ENOLOAD-
Failure in loading a loadable exec module.
ENOMEM-
The system is unable to allocate a send descriptor.
ENOSPC-
O_CREAT and O_EXCL are set, and the file system is out of inodes.
ENOSPC-
O_CREAT is set and the directory that would contain the file
cannot be extended.
ENOSR-
Unable to allocate a stream.
ENOTDIR-
A component of the path prefix is not a directory.
ENXIO-
The named file is a character special or block special file,
and the device associated with this special file does not exist.
ENXIO-
O_NDELAY or O_NONBLOCK is set, the named file is a FIFO,
O_WRONLY is set, and no process has the file open for reading.
ENXIO-
A STREAMS module or driver open routine failed.
EPERM-
path points to a device special file, the device is in the setup
state, and the calling process does not have the P_DEV privilege.
EROFS-
The named file resides on a read-only file system and either
O_WRONLY, O_RDWR, O_CREAT, or O_TRUNC is set in
oflag (if the file does not exist).
Usage
The O_EXCL flag is only a modifier to the O_CREAT flag
and has no other meaning.
The concept of ``exclusive open'' is not supported by the operating
system.
Cooperating processes can coordinate their access to a file by
file and record locking or by other mechanisms.
References
chmod(2),
close(2),
creat(2),
dup(2),
exec(2),
fcntl(2),
getmsg(2),
getrlimit(2),
intro(2),
lseek(2),
open(2),
putmsg(2),
read(2),
stat(2),
stat(5),
umask(2),
write(2)
Notices
Considerations for threads programming
Open file descriptors are a process resource and available to any sibling
thread; if used concurrently, actions by one thread can interfere with
those of a sibling.
While one thread is blocked, siblings might still be executing.
Access rights are an attribute of the containing process and
are shared by sibling threads.
Considerations for large file support
open64 supports large files, but is otherwise identical
to open.
Large file support is filesystem-dependent.
For details on programming for large file capable applications, see
``Large File Support''
on intro(2) and
``Large files'' in Understanding filesystem types
in the discussion of the vxfs filesystem type
in Understanding filesystem types.
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004