open(2)

NAME

open − open for reading or writing

SYNOPSIS (SYSV.2)

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open (path, oflag [ , mode ] )
char ∗path;
int oflag;
mode_t mode;

SYNOPSIS (4.2BSD)

#include <sys/file.h>
int open (path, oflag [ , mode ] )
char ∗path;
int oflag
mode_t mode;

DESCRIPTION

Path points to a path name naming a file. open opens a file descriptor for the named file and sets the file status flags according to the value of oflag. Oflag values are constructed by or-ing flags from the following list (only one of the first three flags below may be used):

O_RDONLY Open for reading only.

O_WRONLY Open for writing only.

O_RDWR Open for reading and writing.

O_AFLUSH This flag will affect subsequent awrites to regular disk files. See awrite(2).

When opening a regular disk file with O_AFLUSH set, the system will not report completion of an asynchronous write operation until the data has flushed to disk.

O_APPEND If set, the file pointer will be set to the end of the file prior to each write.

O_CREAT If the file exists, this flag has no effect. Otherwise, the owner ID of the file is set to the effective user ID of the process, the group ID of the file is set to the effective group ID of the process, and the low-order 12 bits of the file mode are set to the value of mode modified as follows (see creat(2)):

All bits set in the file mode creation mask of the process are cleared. See umask(2).

The ”save text image after execution bit” of the mode is cleared. See chmod(2).

O_DIRECT When a regular disk file is opened with O_DIRECT set, all subsequent reads and writes of this file pointer will bypass the buffer cache entirely and transfer data directly to and from the users address space. Use of this flag in opening files other than regular disk files will have no effect.

O_EXCL If O_EXCL and O_CREAT are set, open will fail if the file exists.

O_NDELAY or O_NONBLOCK These flags may not be used together. They may affect subsequent reads and writes. See read(2) and write(2).

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 and O_NONBLOCK are 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 file associated with a communication line:

If O_NDELAY or O_NONBLOCK is set:

The open will return without waiting for carrier.

If O_NDELAY and O_NONBLOCK are clear:

The open will block until carrier is present.

O_NOCTTY If set, and path identifies a terminal device, the open() function shall not cause the terminal device to become the controlling terminal for the process (see intro(2)).

O_SYNC or O_DSYNC These flags may not be used together. When opening a regular disk file, these flags affect subsequent reads and writes. Use of this flag in opening files other than regular disk files will have no effect.

The O_DSYNC flag specifies synchronized I/O data integrity completion. A synchronized I/O data integrity completion occurs when:

1. For reads, the operation has been completed or diagnosed if unsuccessful. The read is complete only when an image of the data has been successfully transferred to the requesting process. If there were any pending write requests affecting the data to be read at the time that the synchronized read operation was requested, these write requests shall be successfully transferred prior to returning to the calling process with the data.

2. For writes, the operation has been completed or diagnosed if unsuccessful. The write is complete only when the data specified in the write request is successfully transferred, and all file system information required to retrieve the data is successfully transferred.

File attributes that are not necessary for data retrieval (access time, modification time, status change time, etc.) need not be successfully transferred prior to returning to the calling process.

The O_SYNC flag specifies synchronized I/O file integrity completion. A synchronized I/O file integrity completion is identical to synchronized I/O data integrity completion with the addition that all file attributes relative to the I/O operation (including access time, modification time, status change time, etc.) shall be successfully transferred prior to returning to the calling process.

O_TRUNC If the file exists, its length is truncated to 0 and the mode and owner are unchanged.

When opening a STREAMS file, oflag may be constructed from O_NDELAY or-ed with either O_RDONLY, O_WRONLY or O_RDWR. Other flag values are not applicable to STREAMS devices and have no effect on them. The value of O_NDELAY affects the operation of STREAMS drivers and certain system calls [see read(2), getmsg(2), putmsg(2) and write(2)]. For drivers, the implementation of O_NDELAY is device-specific. Each STREAMS device driver may treat this option differently.

The file pointer used to mark the current position within the file is set to the beginning of the file.

The new file descriptor is set to remain open across exec system calls. See fcntl(2).

The named file is opened unless one or more of the following are true:.

[EACCES] Oflag permission is denied for the named file, or a component of the path prefix denies search permission, or the file does not exist and write permission is denied for the parent directory of the file to be created, or O_TRUNC is specified and write permission is denied.

[EAGAIN] If the file exists with enforced record locking enabled (see chmod(2)), there are record locks on the file, and O_TRUNC is specified.

[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.

[EISDIR] The named file is a directory and oflag is write or read/write.

[EMFILE] The process has too many open files (see sysconf(2) or getrlimit(2)).

[ENAMETOOLONG] The length of the path string exceeds {PATH_MAX} characters, or a pathname component is longer than {NAME_MAX} characters (see pathconf(2)).

[ENFILE] The system file table or system inode table is full.

[ENOENT] O_CREAT is not set and the named file does not exist; or O_CREAT is set and either the path prefix does not exist or the path argument points to an empty string.

[ENOSPC] The directory or file system which would contain the new file cannot be extended.

[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, or 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.

[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.

RETURN VALUE

Upon successful completion, the file descriptor is returned. Otherwise, a value of −1 is returned and errno is set to indicate the error.

Museum