open(2) UNIX System V 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 constructed 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 block-special or character-special file:
If ONDELAY or ONONBLOCK 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 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.
10/89 Page 1
open(2) UNIX System V open(2)
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 terminal 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. Otherwise, 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 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.
Page 2 10/89
open(2) UNIX System V open(2)
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 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(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 permission is
denied by the parent directory of the file to be
created.
EACCES OTRUNC 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)].
EAGAIN ONDELAY or ONONBLOCK is set, the named file is a
STREAMS device and there is another process trying to
open it at the same time.
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 system call.
EIO A hangup or error occurred during the open of the
STREAMS-based device.
10/89 Page 3
open(2) UNIX System V open(2)
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 component 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 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 associated 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).
Page 4 10/89
open(2) UNIX System V open(2)
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.
10/89 Page 5