OPEN(2)OPEN(2)NAMEopen - open a file for reading or writing, or create a new file
BSD SYNOPSIS
#include <libc.h>
open(char *path, int flags, int mode);
POSIX SYNOPSIS
#include <sys/file.h>
#include <sys/stat.h>
#include <fcntl.h>
int open(const char *path, int flags, ...);
DESCRIPTION
The open function opens a file, whose pathname is specified by path,
for reading and/or writing as specified by the flags argument, and
returns a file descriptor for that file that is the lowest file
descriptor not currently open for the process. The flags argument may
indicate that the file is to be created if it doesn't already exist by
specifying the O_CREAT flag, in which case the file is created with
permissions as given in a third argument, mode, as described in
chmod(2) and modified by the process' umask value (see umask(2)). For
POSIX applications, the mode argument is optional, and isn't given
unless the O_CREAT flag is specified.
The path argument is a pointer to an array of ASCII characters
representing a pathname, terminated by a null character. The flags
argument specifies the file status flags and file access modes for the
open file, and it must contain exactly one of the following values
(file access modes):
O_RDONLY Open for reading only.
O_WRONLY Open for writing only.
O_RDWR Open for reading and writing.
Any combination of the following values may be bitwise or'ed with the
file access mode above:
O_APPEND Append on each write.
O_CREAT If the file already exists, then this flag has no
effect, except as noted under O_EXCL below.
Otherwise the file is created; the file's user ID
is set to the effective user ID of the calling
process; the file's group ID is set to the group
ID of the directory in which the file is created;
and the file permission bits is set to the value
of the third argument, mode, which is of type
mode_t, except for those set in the process'
umask value. The value of the mode argument does
not affect whether the file is opened for
reading, writing or both.
O_EXCL If both O_EXCL and O_CREAT are set, then the open
function will fail if the file exists, setting
errno to EEXIST. This can be used to implement a
simple locking system.
If O_EXCL is set and the last component of the
pathname is a symbolic link, then open will fail
even if the symbolic link points to a nonexistent
name.
O_NDELAY (BSD only) If opening the file would result in
the process being blocked for some reason, (for
example, waiting for carrier on a dialup line),
open returns immediately. The first time the
process attempts to perform I/O on the open file
it will block (not currently implemented).
O_NOCTTY (POSIX only) If path identifies a terminal
device, then open will not cause the terminal
device to become the controlling terminal for the
calling process.
O_NONBLOCK (POSIX only) As the BSD O_NDELAY, with these
additions:
When opening a FIFO and the O_NONBLOCK flag is
set, then an open for reading will return without
delay. On the other hand, an open for writing
will return an error if no process has the FIFO
open for reading.
When an opening a FIFO and the O_NONBLOCK flag is
clear, then an open for reading will block until
a process opens the FIFO for writing. On the
other hand, an open for writing will block until
a process opens the FIFO for reading.
When opening a block special or character special
file that supports nonblocking opens, and the
O_NONBLOCK flag is set, then the open function
will return without delay. If the O_NONBLOCK
flag is clear, then the function will wait until
the device is ready or available before
returning.
O_TRUNC If the file exists and is a regular file, it is
truncated to zero length upon successful open.
If O_CREAT is set and the file did not exist previously, then open will
mark of update the st_atime, st_ctime and st_mtime fields of the file,
and the st_ctime and st_mtime fields of the directory in which the file
is created.
If O_TRUNC is set and the file previously existed, then open will mark
for update the st_ctime and st_mtime fields of the file.
Upon successful completion, open sets the file pointer used to mark the
current position within the file to the beginning of the file.
Furthermore, the new descriptor is set to remain open across execve
system calls—the close-on-exec file descriptor flag associated with the
new file descriptor is cleared; see close(2) and fcntl(2).
The system imposes a limit on the number of file descriptors that can
be opened simultaneously by one process. For BSD applications, the
getdtablesize(2) function returns the current system limit. For POSIX
applications, this number is given by the constant OPEN_MAX.
RETURN VALUE
Upon successful completion, open opens the file and returns a
nonnegative integer representing the lowest numbered unused file
descriptor. Otherwise, the function returns -1 and sets errno to
indicate the error.
ERRORS
If any of the following conditions occurs, open returns -1 and sets
errno to the corresponding value:
[EACCES] Search permission is denied for a component of the path
prefix; or, the required permissions (for reading and/or
writing) are denied for the named flag; or, O_CREAT is
specified, the file does not exist, and the directory in
which it is to be created does not permit writing; or,
O_TRUNC is specified and the file does not permit
writing.
[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; or, O_CREAT is specified, the file
does not exist, and the user's quota of inodes on the
file system on which the file is being created has been
exhausted.
[EEXIST] O_CREAT and O_EXCL are specified and the file exists.
[EFAULT] The path argument points outside the process's allocated
address space.
[EINTR] (POSIX only) The open function was interrupted by a
signal.
[EIO] An I/O error occurred while making the directory entry
or allocating the inode for O_CREAT.
[EISDIR] The named file is a directory, and the flags argument
specifies O_WRONLY or O_RDWR.
[ELOOP] Too many symbolic links were encountered in translating
the pathname.
[EMFILE] The system limit for open file descriptors per process
has already been reached.
[ENAMETOOLONG] A component of path exceeds 255 characters, or the
entire pathname exceeds 1023 characters. For POSIX
applications these values are given by the constants
{NAME_MAX} and {PATH_MAX}, respectively.
[ENFILE] The system file table is full (too many files are
currently open in the system).
[ENOENT] O_CREAT is not set and the named file does not exist;
or, O_CREAT is set and either a component of the
pathname that must exist does not exist or path is empty
string.
[ENOSPC] 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 there is no space left
on the file system containing the directory; or, O_CREAT
is specified, the file does not exist, and there are no
free inodes on the file system on which the file is
being created.
[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; or (POSIX only), O_NONBLOCK is set, the
file is a FIFO, O_WRONLY is set and no process has the
FIFO opened for reading.
[EOPNOTSUPP] (BSD only) An attempt was made to open a socket (not
currently implemented).
[EROFS] The named file resides on a read-only file system, and
the file is to be modified (O_WRONLY, O_RDWR, O_CREAT or
O_TRUNC is set).
[ETXTBSY] The file is a pure procedure (shared text) file that is
being executed and the open call requests write access.
SEE ALSOchmod(2), close(2), dup(2), fcntl(2), lseek(2), read(2), umask(2),
write(2)4th Berkeley Distribution August 1, 1992 OPEN(2)
