open - open or create a file for reading or writing
#include <fcntl.h>
int
open(const char *path, int flags, mode_t mode);
The file name specified by path is opened for reading and/or
writing as
specified by the argument flags and the file descriptor returned to the
calling process. The flags argument may indicate the file
is to be created
if it does not exist (by specifying the O_CREAT flag),
in which case
the file is created with mode mode as described in chmod(2)
and modified
by the process' umask value (see umask(2)).
The flags specified are formed by OR'ing the following values
O_RDONLY Open for reading only.
O_WRONLY Open for writing only.
O_RDWR Open for reading and writing.
O_NONBLOCK Do not block on open or for data to become
available.
O_APPEND Append on each write.
O_CREAT Create file if it does not exist.
O_TRUNC Truncate size to 0.
O_EXCL Error if create and file exists.
O_SYNC Perform synchronous I/O operations.
O_SHLOCK Atomically obtain a shared lock.
O_EXLOCK Atomically obtain an exclusive lock.
O_NOFOLLOW If last path element is a symlink, don't
follow it.
Opening a file with O_APPEND set causes each write on the
file to be appended
to the end. If O_TRUNC and a writing mode are specified and the
file exists, the file is truncated to zero length. If O_EXCL is set with
O_CREAT and the file already exists, open() returns an error. This may
be used to implement a simple exclusive access locking mechanism. If either
of O_EXCL or O_NOFOLLOW are set and the last component
of the pathname
is a symbolic link, open() will fail even if the symbolic link
points to a non-existent name. If the O_NONBLOCK flag is
specified, do
not wait for the device or file to be ready or available.
If the open()
call would result in the process being blocked for some reason (e.g.,
waiting for carrier on a dialup line), open() returns immediately. This
flag also has the effect of making all subsequent I/O on the
open file
non-blocking. If the O_SYNC flag is set, all I/O operations
on the file
will be done synchronously.
A FIFO should either be opened with O_RDONLY or with O_WRONLY. The behavior
for opening a FIFO with O_RDWR is undefined.
When opening a file, a lock with flock(2) semantics can be
obtained by
setting O_SHLOCK for a shared lock, or O_EXLOCK for an exclusive lock.
If creating a file with O_CREAT, the request for the lock
will never fail
(provided that the underlying filesystem supports locking).
If open() is successful, the file pointer used to mark the
current position
within the file is set to the beginning of the file.
When a new file is created it is given the group of the directory which
contains it.
The new descriptor is set to remain open across execve(2)
system calls;
see close(2) and fcntl(2).
The system imposes a limit on the number of file descriptors
open simultaneously
by one process. getdtablesize(3) returns the current system
limit.
If successful, open() returns a non-negative integer, termed
a file descriptor.
Otherwise, a value of -1 is returned and errno is
set to indicate
the error.
The named file is opened unless:
[ENOTDIR] A component of the path prefix is not a directory.
[ENAMETOOLONG]
A component of a pathname exceeded {NAME_MAX}
characters,
or an entire path name exceeded {PATH_MAX}
characters.
[ENOENT] O_CREAT is not set and the named file does not
exist.
[ENOENT] A component of the path name that must exist
does not exist.
[EACCES] Search permission is denied for a component of
the path
prefix.
[EACCES] The required permissions (for reading and/or
writing) are
denied for the given flags.
[EACCES] O_CREAT is specified, the file does not exist,
and the directory
in which it is to be created does not
permit writing.
[ELOOP] Too many symbolic links were encountered in
translating the
pathname, or the O_NOFOLLOW flag was specified
and the target
is a symbolic link.
[EISDIR] The named file is a directory, and the arguments specify it
is to be opened for writing.
[EINVAL] The flags specified for opening the file are
not valid.
[EROFS] The named file resides on a read-only file
system, and the
file is to be modified.
[EMFILE] The process has already reached its limit for
open file descriptors.
[ENFILE] The system file table is full.
[ENXIO] The named file is a character special or block
special
file, and the device associated with this special file does
not exist.
[ENXIO] The named file is a FIFO, the O_NONBLOCK and
O_WRONLY flags
are set, and no process has the file open for
reading.
[EINTR] The open() operation was interrupted by a signal.
[EOPNOTSUPP] O_SHLOCK or O_EXLOCK is specified but the underlying
filesystem does not support locking.
[EWOULDBLOCK]
O_NONBLOCK and one of O_SHLOCK or O_EXLOCK is
specified and
the file is already locked.
[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.
[ENOSPC] 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.
[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.
[EDQUOT] 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.
[EIO] An I/O error occurred while making the directory entry or
allocating the inode for O_CREAT.
[ETXTBSY] The file is a pure procedure (shared text)
file that is being
executed and the open() call requests
write access.
[EFAULT] path points outside the process's allocated
address space.
[EEXIST] O_CREAT and O_EXCL were specified and the file
exists.
[EOPNOTSUPP] An attempt was made to open a socket (not currently implemented).
chmod(2), close(2), dup(2), flock(2), lseek(2), read(2),
umask(2),
write(2), getdtablesize(3)
The open() function conforms to IEEE Std 1003.1-1990
(``POSIX'') and
X/Open Portability Guide Issue 4.2 (``XPG4.2'').
POSIX specifies three different flavors for synchronous I/O:
O_SYNC,
O_DSYNC, and O_RSYNC. In OpenBSD, these are all equivalent.
The O_SHLOCK, O_EXLOCK, and O_NOFOLLOW flags are non-standard extensions
and should not be used if portability is of concern.
An open() function call appeared in Version 2 AT&T UNIX.
The O_TRUNC flag requires that one of O_RDWR or O_WRONLY also be specified,
else EINVAL is returned.
OpenBSD 3.6 November 16, 1993
[ Back ] |
