open(2)open(2)Nameopen - open for reading or writing
Syntax
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <limits.h> /* definition of OPEN_MAX */
open(path, flags, mode)
char *path;
int flags, mode;
Description
The system call opens a specified file and returns a descriptor for
that file. The file pointer used to mark the current position within
the file is set to the beginning of the file.
The file descriptor remains open across system calls. The system call
closes the file descriptor.
A process cannot have more than OPEN_MAX file descriptors open simulta‐
neously.
Arguments
path is the address of a string of ASCII characters representing a
path name, terminated by a null character. The path name iden‐
tifies the file to be opened.
mode is only used with the O_CREAT flag. The file is created with
the specified mode, as described in and modified by the
process's umask value. For further information, see
flags defines how the file is to be opened. This argument is formed
by ORing the following values:
O_RDONLY Open for reading only.
O_WRONLY Open for writing only.
O_RDWR Open for reading and writing.
O_NDELAY Do not block on open when opening a port (named
pipe) with O_RDONLY or O_WRONLY:
If O_NDELAY is set, an for read only returns without
delay. An for write only returns an error if no
process currently has the file open for reading.
If O_NDELAY is clear, an for read only blocks until
a process opens the file for writing. An for write
only blocks until a process opens the file for read‐
ing.
O_NONBLOCK POSIX definition of O_NDELAY. See O_NDELAY for
explanation of functionality.
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_BLKINUSE Block if file is in use.
O_BLKANDSET Block if file is in use; then, set in use.
O_FSYNC Do file writes synchronously.
O_NOCTTY In the POSIX environment, if this flag is set and
path identifies a terminal device, the function will
not cause the terminal device to become the control‐
ling terminal for the process.
Opening a file with O_APPEND set causes each write on the file to
be appended to the end.
If O_TRUNC is 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, the
returns an error. This can be used to implement a simple exclu‐
sive access locking mechanism.
If the O_NDELAY or O_NONBLOCK flag is specified and the open call
would result in the process being blocked for some reason, the
open returns immediately. For example, if the process were wait‐
ing for carrier on a dialup line, an open with the O_NDELAY or
O_NONBLOCK flag would return immediately. The first time the
process attempts to perform I/O on the open file, it blocks.
If the O_FSYNC flag is specified, each subsequent write (see for
the file is synchronous, instead of the default asynchronous
writes. Use this flag to ensure that the write is complete when
the system call returns. With asynchronous writes, the call
returns when data is written to the buffer cache. There is no
guarantee that the data was actually written out to the device.
With synchronous writes, the call returns when the data is written
from the buffer cache to the device.
O_BLKINUSE and O_BLKANDSET provide a test and set operation simi‐
lar to a semaphore. O_BLKINUSE causes the open to block if
another process has marked the file as in use. The blocks in the
system at a point where no references to the file are established.
There are two ways to mark a file as in use:
· Use the system call with the request argument set to FIOSI‐
NUSE or TIOCSINUSE. For further information, see
· Use the O_BLKANDSET flag to
O_BLKANDSET caused the to block if another process has marked the
file in use. When the resumes, the file is marked in use by the
current process.
If O_NDELAY is used with either O_BLKINUSE or O_BLKANDSET, the
failed if the file is in use. The external variable is set to
EWOULDBLOCK in this case. The in use flag cannot be inherited by
a child process, nor can it be replicated by the system call.
When the in use flag is cleared, all processes that are blocked
for that reason resume. The continues to block if another process
marks the file as in use again.
The in use flag can be cleared in three ways:
· When the file descriptor marked as in use is closed
· When the process that set the in use flag exits
· When an system call is issued and FIOCINUSE or TIOCCINUSE is speci‐
fied in the request argument.
Environment
System Five
When your program is compiled using the System V environment, and
O_NDELAY is specified, subsequent reads and writes are also affected.
Return Values
Upon successful completion, an integer value greater than -1 is
returned.
Diagnostics
The call fails under the following conditions:
[EACCES] The required permissions for reading, writing, or both
are denied for the named flag.
[EACCES] Search permission is denied for a component of the path
prefix.
[EACCES] O_CREAT is specified, the file does not exist, and the
directory in which it is to be created 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.
[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.
[EEXIST] O_CREAT and O_EXCL were specified and the file exists.
[EFAULT] The path points outside the process's allocated address
space.
[ENFILE] The system file table is full.
[EINVAL] An attempt was made to open a file with the O_RDONLY and
O_FSYNC flags set.
[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 arguments specify
it is to be opened for writing.
[ELOOP] Too many symbolic links were encountered in translating
the pathname.
[EMFILE] {OPEN_MAX} file descriptors are currently open.
[ENAMETOOLONG] A component of a pathname exceeds 255 characters or an
entire pathname exceeds 1023 characters.
[ENOENT] O_CREAT is not set and the named file does not exist.
[ENOENT] A necessary component of the path name does not exist.
[ENOENT] The path argument points to an empty string and the
process is running in the POSIX or SYSTEM_FIVE environ‐
ment.
[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.
[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] The O_NDELAY flag is given, and the file is a communica‐
tions device on which there is no carrier present.
[ENXIO] O_NONBLOCK is set, the named file is a FIFO, O_WRONLY is
set and no process has the file open for reading.
[EOPNOTSUPP] An attempt was made to open a socket that is not set
active.
[EROFS] The named file resides on a read-only file system, and
the file is to be modified.
[ESTALE] The file handle given in the argument is invalid. The
file referred to by that file handle no longer exists or
has been revoked.
[ETIMEDOUT] A connect request or remote file operation failed
because the connected party did not respond after a
period of time determined by the communications proto‐
col.
[ETXTBSY] The file is a pure procedure (shared text) file that is
being executed and the call requests write access.
[EWOULDBLOCK] The open would have blocked if the O_NDELAY was not
used. The probable cause for the block is that the file
was marked in use.
[EINTR] A signal was caught during the function.
See Alsochmod(2), close(2), dup(2), fcntl(2), lseek(2), read(2), write(2),
umask(2), tty(4)open(2)