OPEN(2) SysV OPEN(2)
NAME
open - open a file
SYNOPSIS
#include <fcntl.h>
#include <sys/stat.h>
#include <sys/types.h>
int open (path, oflag[, mode])
const char *path;
int oflag;
mode_t mode;
DESCRIPTION
The open function establishes a connection between the file named by the
path argument 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 opened file descriptor is used by subsequent I/O
functions, such as read(2) and write(2), to access that file. The
returned file descriptor is the lowest file descriptor not previously
open for that process.
The open file description is new, and therefore the file descriptor does
not share it with any other process in the system. The new file
descriptor is set to remain open across exec functions. (See fcntl(5).)
The file offset, marking the current position within the file, is set to
the beginning of the file. The FD_CLOEXEC file descriptor flag
associated with the new file descriptor is cleared.
path points to a pathname naming a file. If the path argument refers to a
symbolic link, the open function opens the file pointed to by the
symbolic link.
oflag specifies the type of access, special open processing, the type of
update, and the initial state of the open file. The argument value is
constructed by logically ORing special open processing flags. These
flags are defined in the fcntl.h header file and are described below.
mode specifies the read, write, and execute permissions of the file to be
created (for use with the O_CREAT flag). If the file already exists,
this argument is ignored.
Open Processing Flags
Applications must specify exactly one of the first three values below in
the value of oflag:
O_RDONLY Open for reading only.
O_WRONLY Open for writing only.
O_RDWR Open for reading and writing. The result is undefined if this
flag is applied to a FIFO.
O_NDELAY/O_NONBLOCK
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 or O_NONBLOCK 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 opening a block special or character special file that
supports nonblocking opens:
If O_NDELAY or O_NONBLOCK is set:
open will return without blocking for the device to be
ready or available. Subsequent behavior of the device is
device specific.
If O_NDELAY and O_NONBLOCK are both clear:
open will block until device is ready or available before
returning
Otherwise, the behavior of O_NONBLOCK is unspecified.
O_APPEND If set, the file pointer will be set to the end of the file
prior to each write.
O_CREAT This option requires the mode argument. If the file exists,
this flag has no effect, except as noted under O_EXCL below.
Otherwise, the file is created; the user ID of the file is set
to the effective user ID of the process.
For nodes that are configured in a FIPS compliant mode, the
group ID of the file is set to the group ID of the file's
parent directory.
In addition the access permission bits of the file mode are set
to the value of mode modified as follows: the corresponding
bits are bitwise ANDed with the complement of the process' file
mode creation mask. (See umask(2).) Thus, all bits in the file
mode whose corresponding bit in the file mode creation mask is
set are cleared.
The mode argument does not affect whether the file is open for
reading, writing, or for both.
If O_CREAT is set and the file did not previously exist, upon
successful completion, the open function 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.
O_SYNC If O_SYNC is set on a regular file, writes to that file causes
the process to block until the data is delivered to the
underlying hardware.
O_TRUNC If the file exists, and is a regular file, and the file is
successfully opened O_RDWR or O_WRONLY, its length is truncated
to 0 and the mode and owner are unchanged.
Specifying O_TRUNC in an open to a FIFO is ignored. Specifying
O_TRUNC in an open to a directory will fail with [EISDIR]. The
result of using O_TRUNC with O_RDONLY is undefined.
If O_TRUNC is set and the file did previously exist, upon
successful completion, the open function marks for update the
st_ctime and st_mtime fields of the file.
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 on the same path with
O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not
set, O_EXCEL is ignored.
O_NOCTTY If the path argument identifies a terminal device, this flag
assures that the terminal device does not become the
controlling terminal for the process.
NOTES
In prior releases, opening a sparse file (a file containing "holes" in it
that are not backed up by disk blocks) and reading through it from
beginning to end would cause disk blocks to be allocated for the sparse
regions of the file (that is, the file would cease to be sparse).
At SR10.4, if the file is accessed through ordinary open and read(2)
calls, is open for read, resides on an SR10.4 node and is NOT currently
being written by anyone, the sparseness of the file will be "mostly"
preserved. (For example, although file data blocks will not be
allocated, indirect filemap blocks will be.)
ERRORS
The named file is opened unless one or more of the following are true:
[EACCES] Search permission is denied on a component of the path
prefix, or the type of access specified by the oflag
argument is denied for the named file, or the file does not
exist and write permission is denied for the parent
directory, or O_TRUNC is specified and write permission is
denied.
[EAGAIN] The file exists, mandatory file/record locking is set, and
there are outstanding record locks on the file (see
chmod(2)).
[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.
[EIO] A hangup or error occurred during a STREAMS open.
[EISDIR] The named file is a directory and oflag is write or
read/write.
[EMFILE] {OPEN_MAX} file descriptors are currently open.
[ENFILE] The system file table is full.
[ENOENT] The O_CREAT flag is not set and the named file does not
exist, or O_CREAT is set and the path prefix does not
exist, or the path argument points to the empty string.
[ENOMEM] The system is unable to allocate a send descriptor.
[ENOSPC] O_CREAT is set and the file system is out of space and the
file does not exist.
[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.
[EROFS] The named file resides on a read-only file system, and
oflag is write or read/write.
[ETXTBSY] The file is a pure procedure (shared text) file that is
being executed, and oflag is write or read/write.
[ENAMETOOLONG]
The length of the path string exceeds PATH_MAX, or a
pathname component is longer than NAME_MAX.
[EDQUOT] O_CREAT is specified, the file does not exist, and the
directory in which the entry for the new file is being
placed cannot be extended because the user's quota of disk
blocks on the file system containing the directory has been
exhausted.
SEE ALSO
chmod(2), close(2), creat(2), dup(2), fcntl(2), intro(2), lseek(2),
read(2), getmsg(2), putmsg(2), umask(2), write(2).
DIAGNOSTICS
Upon successful completion, a nonnegative integer representing the file
descriptor is returned. Otherwise, a value of -1 is returned and errno
is set as indicated under "Errors."
NOTES
Not including any of O_RDONLY, O_WRONLY, or O_RDWR among the values ORed
to obtain oflag implies opening the file pointed to by path for reading
only.
Under other implementations, open fails if any of the following are true:
[EMULTIHOP] Components of path require hopping to multiple remote
machines.
[ENOLINK] path points to a remote machine and the link to that
machine is no longer active.