open(2) open(2)
NAME
open - open for reading or writing
C 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 file associated with a communication line:
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.
Page 1
open(2) open(2)
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.
ODSYNCWhen opening a regular file, this flag affects subsequent writes.
If set, each write(2) will wait for the file data to be physically
updated.
ORSYNCWhen opening a regular file, this flag affects subsequent reads.
If set, and either OSYNC or ODSYNC is set then each read(2) will
wait for the file to be in the same state as OSYNC or ODSYNC
would require for writes.
ONOCTTY
If set and the file is a terminal, the terminal will not be
allocated as the calling process's controlling terminal.
OCREATIf 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 IDs of the process, the
group ID of the file is set to the effective group IDs of the
process or to the group ID of the directory in which the file is
being created. This is determined as follows:
If the underlying filesystem was mounted with the BSD file
creation semantics flag [see fstab(4)] or the SISGID bit is
set [see chmod(2)] on the parent directory, then the group ID
of the new file is set to the group ID of the parent
directory, otherwise it is set to the effective group ID of
the calling process.
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)].
OTRUNCIf the file exists and is a regular file, and the file is
successfully opened ORDWR or OWRONLY, its length is truncated to
0 and the mode and owner are unchanged. It will have no effect on
FIFO special files or terminal device files. It's effect on other
files types is implementation-dependent. The result of using
OTRUNC with ORDONLY is undefined.
Page 2
open(2) open(2)
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.
OLCFLUSH
If set, when all copies of a file descriptor are closed, all
modified buffers associated with the file will be written back to
the physical medium. OLCFLUSH is a Silicon Graphics extension.
OLCINVAL
If set, when all copies of a file descriptor are closed, all
modified buffers associated with the file will be written back to
the physical medium, then invalidated, immediately freeing the
buffers for other use. The process doing the last close must be
able to aquire write access at the time of last close for the
cache to be invalidated. OLCINVAL is a Silicon Graphics
extension.
ODIRECT
If set, all reads and writes on the resulting file descriptor will
be performed directly to or from the user program buffer, provided
appropriate size and alignment restrictions are met. Refer to the
FSETFL and FDIOINFO commands in the fcntl(2) manual entry for
information about how to determine the alignment constraints.
ODIRECT is a Silicon Graphics extension and is only supported on
local EFS and XFS file systems, and remote BDS file systems.
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 descriptor available
and is set to remain open across exec system calls [see fcntl(2)].
Page 3
open(2) open(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.
There is a system enforced limit on the number of open file descriptors
per process {OPENMAX}, whose value is returned by the getdtablesize(2)
function.
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 OCREAT or OTRUNC is specified and write permission is denied.
EACCES A component of the path prefix denies search permission.
EACCES The file is a character or block device file and the file system
in which it resides has been mounted with the nodev option [see
fstab(4)].
EACCES oflag permission is denied for an existing file.
EAGAIN The file exists, OCREAT or OTRUNC are specified, 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.
EDQUOT OCREAT is specified, the file does not exist, and the directory
in which the entry for the new file is being placed cannot be
extended either because the user's quota of disk blocks on the
file system containing the directory has been exhausted or the
user's quota of inodes on the file system on which the file is
being created has been exhausted.
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.
Page 4
open(2) open(2)
EINVAL An attempt was made to open a file not in an EFS, XFS or BDS file
system with ODIRECT set.
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)].
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.
ENODEV path points to a device special file and the device is not in the
activated state.
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.
ENOMEM The system is unable to allocate a send descriptor.
ENOSPC OCREAT and OEXCL are set, and the file system is out of inodes
or the directory in which the entry for the new file is being
placed cannot be extended because there is no space left on the
file system containing the directory.
ENOSPC OCREAT is set and the directory that would contain the file
cannot be extended.
ENOSR Unable to allocate a stream.
ENOTDIRA 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.
EOPNOTSUPP
An attempt was made to open a socket (not currently supported).
Page 5
open(2) open(2)
EPERM path points to a device special file, the device is in the setup
state, and the calling process does not have the PDEV privilege.
ETIMEDOUT
The object of the open is located on a remote system which is not
available [see intro(2)].
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).
SEE ALSO
chmod(2), close(2), creat(2), dup(2), exec(2), fcntl(2),
getdtablesize(2), getmsg(2), getrlimit(2), intro(2), lseek(2), putmsg(2),
read(2), stat(2), stat(5), umask(2), write(2)
DIAGNOSTICS
Upon successful completion, the file descriptor is returned. Otherwise,
a value of -1 is returned and errno is set to indicate the error.
Page 6