open(2) open(2)
NAME
open, open64 - open file 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 */);
int open64(const char *path, int oflag, ...);
DESCRIPTION
The open() function establishes the connection between a file and a
file descriptor. It creates an open file description that refers to a
file and a file descriptor that refers to that open file description.
The file descriptor is used by other I/O functions to refer to that
file. The path argument points to a pathname naming the file.
The open() function will return a file descriptor for the named file
that is the lowest file descriptor not currently open for that pro-
cess. The open file description is new, and therefore the file
descriptor does not share it with any other process in the system. The
FDCLOEXEC file descriptor flag associated with the new file descrip-
tor will be cleared.
The file offset used to mark the current position within the file is
set to the beginning of the file.
The file status flags and file access modes of the open file descrip-
tion will be set according to the value of oflag.
Values for oflag are constructed by a bitwise-inclusive-OR of flags
from the following list, defined in fcntl.h. Applications must specify
exactly one of the first three values (file access modes) below in the
value of oflag:
ORDONLY Open for reading only
OWRONLY Open for writing only
ORDWR Open for reading and writing.
Any combination of the following may be used:
ONONBLOCK Affect subsequent reads and writes [see read(2) and
write(2)].
When a FIFO file is opened with ORDONLY or OWRONLY, this
has the following effect:
Page 1 Reliant UNIX 5.44 Printed 11/98
open(2) open(2)
If 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 ONONBLOCK is 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 a file associated with a terminal line is opened, this
has the following effect:
If ONONBLOCK is set:
open() will return without waiting for the device to
be ready or available; subsequent behavior of the de-
vice is device specific.
If ONONBLOCK is clear:
open() will block until the device is ready or avail-
able.
OAPPEND The file pointer will be set to the end of the file prior
to each write.
OSYNC When opening a regular file, subsequent writes are
affected. Each write(2) will wait for both the file data
and file status to be physically updated.
ONOCTTY If the file is assigned to a terminal, the terminal will
not be allocated as the calling process' controlling termi-
nal.
OCREAT If the file exists, this flag has no effect except as noted
under OEXCL below. Otherwise, the file is created; the
user ID of the file is set to the effective user ID of the
process; the group ID of the file is set to the group ID of
the file's parent directory or to the effective group ID of
the process; and the access permission bits [see stat(5)]
of the file mode are set to the value of the third argument
taken as type modet modified as follows: a bitwise-AND is
performed on the file-mode bits and the corresponding bits
in the complement of the process' file mode creation mask.
Thus, all bits in the file mode whose corresponding bit in
the file mode creation mask is set are cleared. When bits
other than the file permission bits are set, the effect is
unspecified. The third argument does not affect whether the
file is open for reading, writing or for both.
Page 2 Reliant UNIX 5.44 Printed 11/98
open(2) open(2)
OTRUNC If the file exists and is a regular file, and the file is
successfully opened ORDWR or OWRONLY, its length is trun-
cated to 0 and the mode and owner are unchanged. It will
have no effect on FIFO special files or terminal device
files. Its effect on other file types is implementation-
dependent. The result of using OTRUNC with ORDONLY is
undefined.
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.
The following additional value may be used in constructing oflag:
OLARGEFILE
If set, the offset maximum in the open file description will be
the largest value that can be represented correctly in an object
of type off64t.
When opening a STREAMS file, oflag may be constructed from ONONBLOCK,
OR-ed with ORDONLY, OWRONLY, or ORDWR. Other flag values are not
applicable to STREAMS devices and have no effect on them. The value of
ONONBLOCK affects the operation of STREAMS drivers and certain system
calls [see read(2), getmsg(2), putmsg(2), and write(2)]. For drivers,
the implementation of ONONBLOCK is device-specific. Each STREAMS de-
vice driver may treat these options differently.
If path names the master side of a pseudo-terminal device, then it is
unspecified whether open() locks the slave side so that it cannot be
opened. Portable applications must call unlockpt() before opening the
slave side.
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 descriptor avail-
able 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).
Page 3 Reliant UNIX 5.44 Printed 11/98
open(2) open(2)
If OCREAT is set and the file did not previously exist, upon success-
ful 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.
Note that using open64() is equivalent to using open() with
OLARGEFILE set in oflag.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
The named file is opened unless one or more of the following condi-
tions is 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)].
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.
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 type does not allow it.
Page 4 Reliant UNIX 5.44 Printed 11/98
open(2) open(2)
ENAMETOOLONG The length of the path argument exceeds PATHMAX or the
length of a path component exceeds NAMEMAX.
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.
ENOSPC OCREAT and OEXCL are set, and the file system is out
of inodes.
ENOSPC OCREAT is set and the directory for 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 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).
The open() function may fail if:
EAGAIN The path argument names the slave side of a pseudo-ter-
minal device that is locked.
EINVAL The value of the oflag argument is not valid.
ENAMETOOLONG Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds PATHMAX.
ENOMEM The path argument names a STREAMS file and the system is
unable to allocate resources.
ETXTBSY The file is a pure procedure (shared text) file that is
being executed and oflag is write or read/write.
Page 5 Reliant UNIX 5.44 Printed 11/98
open(2) open(2)
EOVERFLOW The named file is a regular file, OLARGEFILE is not set
and the size of the file cannot be represented correctly
in an object of type offt.
RESULT
Upon successful completion, the file descriptor is returned. Other-
wise, a value of -1 is returned and errno is set to indicate the
error.
NOTES
An open() will fail if the size of the (regular) file cannot be repre-
sented correctly in an object of type offt.
The size of file on which a program is able to operate is determined
by the offt in use for the open(). The open protection rule ensures
that old binaries do not operate on files that are too large to handle
correctly, and prevents the binaries from generating incorrect results
or corrupting the data in the file.
An argument against open protection is that requiring opens to fail
will break some binaries that would have worked perfectly well other-
wise.
Another argument against open protection is that it is unnecessary
because an error will be returned as soon as a function cannot return
the correct result of an operation ("No Lies" rule). However, most
programs check for the success of the open() call, but many do not
check for overflow or error after lseek() and other calls. An audit of
the standard utilities uncovered numerous examples.
An argument for open protection is that it increases the likelihood of
an immediate and informative error message. The error message is
likely to include the name of the file that could not be opened. It is
much less likely that an lseek() error message will be as immediate or
as informative. The delay in, or complete lack of, reporting such
errors may result in "silent failure".
Another argument for open protection is that there are numerous plau-
sible scenarios in which this rule avoids serious harm. It prevents
typical implementations of the touch utility from truncating large
files to 0 length. It can prevent silent failure, which has been
demonstrated to occur in at least one commercial data management sys-
tem. With open protection a commercial backup/restore system will
report errors on files that might otherwise result in a corrupted
backup tape. It prevents typical implementations of dbm/ndbm from
returning incorrect results from a database whose size exceeds the
offt in use for the dbm routines.
SEE ALSO
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),
fcntl(5), lfs(5), stat(5), types(5).
Page 6 Reliant UNIX 5.44 Printed 11/98