open(2) System Calls Manual open(2)
Name
open - 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 simultaneously.
Arguments
path is the address of a string of ASCII characters representing a path name, terminated by a null character. The path name identifies
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 reading.
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 controlling 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 exclusive
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 waiting 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 similar 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:
o Use the system call with the request argument set to FIOSINUSE or TIOCSINUSE. For further information, see
o 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 EWOULD-
BLOCK 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:
o When the file descriptor marked as in use is closed
o When the process that set the in use flag exits
o When an system call is issued and FIOCINUSE or TIOCCINUSE is specified 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 environment.
[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 communications 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 deter-
mined by the communications protocol.
[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 Also
chmod(2), close(2), dup(2), fcntl(2), lseek(2), read(2), write(2), umask(2), tty(4)
open(2)