open(2) SYSTEM CALLS open(2)
NAME
open - open for reading or writing
SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open (const char *path, int oflag, ... /* modet mode
*/);
DESCRIPTION
path points to a path name naming a file. open opens a file
descriptor for the named file and sets the file status flags
according to the value of oflag. oflag values are con-
structed by OR-ing Flags from the following list (only one
of the first three flags below may be used):
ORDONLY Open for reading only.
OWRONLY Open for writing only.
ORDWR Open for reading and writing.
ONDELAY or ONONBLOCK
These flags may affect subsequent reads and
writes [see read(2) and write(2)]. If both
ONDELAY and ONONBLOCK are set, ONONBLOCK
will take precedence.
When opening a FIFO with ORDONLY or OWRONLY
set:
If ONDELAY or ONONBLOCK 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 ONDELAY and ONONBLOCK 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 ONDELAY or ONONBLOCK is set: The
open will return without waiting for the
device to be ready or available; subse-
quent behavior of the device is device
1
open(2) SYSTEM CALLS open(2)
specific.
If ONDELAY and ONONBLOCK are clear: The
open will block until the device is ready
or available.
OAPPEND If set, the file pointer will be set to the
end of the file prior to each write.
OSYNC When opening a regular file, this flag affects
subsequent writes. If set, each write(2) will
wait for both the file data and file status to
be physically updated.
ONOCTTY If set and the file is a terminal, the termi-
nal will not be allocated as the calling
process's controlling terminal.
OCREAT If the file exists, this flag has no effect,
except as noted under OEXCL below. Other-
wise, the file is created and the owner ID of
the file is set to the effective user ID of
the process, the group ID of the file is set
to the effective group ID of the process, or
if the SISGID 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 SISGID
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)].
OTRUNC If the file exists, its length is truncated to
0 and the mode and owner are unchanged.
OTRUNC has no effect on FIFO special files or
directories.
OEXCL If OEXCL and OCREAT 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
2
open(2) SYSTEM CALLS open(2)
naming the same filename in the same directory
with OEXCL and OCREAT set.
When opening a STREAMS file, oflag may be constructed from
ONDELAY or ONONBLOCK OR-ed with either ORDONLY, OWRONLY
, or ORDWR. Other flag values are not applicable to
STREAMS devices and have no effect on them. The values of
ONDELAY and ONONBLOCK 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 ONDELAY and ONONBLOCK 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 IRECVFD ioctl
[see streamio(7)] to receive the file descriptor.
If path is a symbolic link and OCREAT and OEXCL 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 descrip-
tor 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(2).
If OCREAT is set and the file did not previously exist,
upon successful completion open marks for update the
statime, stctime and stmtime fields of the file and the
stctime and stmtime fields of the parent directory.
If OTRUNC is set and the file did previously exist, upon
successful completion open marks for update the stctime and
stmtime fields of the file.
The named file is opened unless one or more of the following
are true:
EACCES The file does not exist and write per-
mission is denied by the parent direc-
tory of the file to be created.
EACCES OTRUNC is specified and write permis-
sion is denied
EACCES A component of the path prefix denies
search permission.
3
open(2) SYSTEM CALLS open(2)
EACCES oflag permission is denied for an exist-
ing file.
EAGAIN The file exists, mandatory file/record
locking is set, and there are outstand-
ing record locks on the file [see
chmod(2)].
EEXIST OCREAT and OEXCL 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 sys-
tem call.
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
{PATHMAX}, or the length of a path com-
ponent exceeds {NAMEMAX} while
{POSIXNOTRUNC} is in effect.
ENFILE The system file table is full.
ENOENT OCREAT is not set and the named file
does not exist.
ENOENT OCREAT 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.
ENOMEM The system is unable to allocate a send
4
open(2) SYSTEM CALLS open(2)
descriptor.
ENOSPC OCREAT and OEXCL are set, and the file
system is out of inodes.
ENOSPC OCREAT 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 asso-
ciated with this special file does not
exist.
ENXIO ONDELAY or ONONBLOCK is set, the named
file is a FIFO, OWRONLY is set, and no
process has the file open for reading.
ENXIO A STREAMS module or driver open routine
failed.
EROFS The named file resides on a read-only
file system and either OWRONLY, ORDWR,
OCREAT, or OTRUNC is set in oflag (if
the file does not exist).
ETXTBSY The file is a pure procedure (shared
text) file that is being executed and
oflag is write or read/write.
SEE ALSO
intro(2), chmod(2), close(2), creat(2), dup(2), exec(2),
fcntl(2), getrlimit(2), lseek(2), read(2), getmsg(2),
putmsg(2), stat(2), umask(2), write(2), stat(5).
DIAGNOSTICS
Upon successful completion, the file descriptor is returned.
Otherwise, a value of -1 is returned and errno is set to
indicate the error.
5