NAME

open – open a file

SYNOPSIS

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

int open(const char *path , int oflag , …);

int creat(const char *path , mode_t mode );

DESCRIPTION

The open() function establishes the connection between a file and a file descriptor. It creates an open file description that refers to a file and a file descriptor that refers to that open file description. The file descriptor is used by other I/O functions to refer to that file. The path argument points to the pathname naming a file. The open() function shall return a file descriptor for the named file that is the lowest file descriptor not currently open for that process. The open file description is new, and therefore the file descriptor does not share it with any other process in the system. The file offset shall be set to the beginning of the file. The FD_CLOEXEC file descriptor flag associated with the new file descriptor shall be cleared. The file status flags and file access modes of the open file description shall be set according to the value of oflag. The value of oflag is the bitwise inclusive OR of values from the following list. Applications shall specify exactly one of the first three values (file access modes) below in the value of oflag:

O_RDONLY

Open for reading only.

O_WRONLY

Open for writing only.

O_RDWR

Open for reading and writing. The result is undefined if this flag is applied to a FIFO.

Any combination of the remaining flags may be specified in the value of oflag:

O_APPEND

If set, the file offset shall be set to the end of the file prior to each write.

O_CREAT

This option requires a third argument, mode, which is of type mode_t. If the file exists, this flag has no effect, except as noted under O_EXCL below. Otherwise, the file is created. The file permission bits shall be set to the value of mode. When bits in mode other than the file permission bits are set, the effect is unspecified. The mode argument does not affect whether the file is opened for reading, for writing, or for both.

O_DSYNC

Write I/O operations on the file descriptor complete as defined by synchronized I/O data integrity completion.

O_EXCL

If O_EXCL and O_CREAT are set, open() shall fail if the file exists. The check for the existence of the file and the creation of the file if it does not exist shall be atomic with respect to other processes executing open() naming the same filename in the same directory with O_EXCL and O_CREAT set. If O_EXCL is set abd O_CREAT is not set, the result is undefined.

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.

O_NONBLOCK

(1) When opening a FIFO with O_RDONLY or O_WRONLY set:
(a) If 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.
(b) If O_NONBLOCK is clear: An open() for reading-only shall block until a process opens the file for writing. An open() for writing-only will block until a process opens the file for reading.

(2) When opening a block special or character special file that supports nonblocking opens:
(a) If O_NONBLOCK is set: The open() shall return without waiting for the device to be ready or available. Subsequent behavior of the device is device-specific.
(b) If O_NONBLOCK is clear: The open() shall wait until the device is ready or available before returning.

(3) Otherwise, the behaviour of O_NONBLOCK is unspecified.

O_RSYNC

Read I/O operations on the file descriptor complete at the same level of integrity as specified by the O_DSYNC and O_SYNC flags. If both O_DSYNC and O_RSYNC are set in oflag, all I/O operations on the file descriptor complete as defined by synchronized I/O data integrity completion. If both O_SYNC and O_RSYNC are set in oflag, all I/O operations on the file descriptor complete as defined by synchronized I/O file integrity completion.

O_SYNC

Write I/O operations on the file descriptor complete as defined by synchronized I/O file integrity completion.

O_TRUNC

If the file exists and is a regular file, and the file is successfully opened O_RDWR or O_WRONLY, it shall truncated to zero length and the mode and owner shall be unchanged by this function call. O_TRUNC shall have no effect on FIFO special files or terminal device files. Its effect on other file types is implementation defined. The result of using O_TRUNC with O_RDONLY is undefined.

If O_CREAT is set and the file did not previously exist, upon successful completion the open() function shall mark for update the st_atime, st_ctime, and st_mtime fields of the file and the st_ctime and st_mtime fields of the parent directory.

If both O_SYNC and O_DSYNC flags are set, the effect is as if only the O_SYNC flag was set.

If O_TRUNC is set and the file did not previously exist, upon successful completion the open() function shall mark for update the st_ctime and st_mtime fields of the file.

creat(path, mode) is equivalent to open(path, O_WRONLY | O_CREATE | O_TRUNC, mode);

RETURN VALUES

Upon successful completion, the function shall open the file and return a nonnegative integer representing the lowest numbered unused file descriptor. Otherwise, it shall return -1 and set errno to indicate the error. No files shall be created or modified if the function returns -1.

ERRORS

This function is a member of Unison’s IOLIB family of functions. IOLIB is implemented as a message passing and generalized interface layer. Each Unison I/O server is responsible for its own error reporting.

For an exact list of error codes returned by a particular server, refer to that server’s documentation in the Unison Programmer’s Guide for each specific platform.

Servers may implement these errors codes in response to this function.

If any of the following conditions occur, the open() function shall return -1 and set errno to the corresponding value:

EACCES

Search permission is denied on a component of the path prefix, pr the file exists and the permissions specified b oflag are denied, 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.

EEXIST

O_CREAT and O_EXCL are set and the named file exists.

EINVAL

The implementation does not support synchronized I/O for this file.

EISDIR

The named file is a directory, and the oflag argument specifies write or read/write access.

EMFILE

Too many file descriptors are currently in use.

ENAMETOOLONG

The length of the path string exceeds {PATH_MAX}, or a pathname component is longer than {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect.

ENFILE

Too many files 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 the path prefix does not exist or the path argument points to an empty string.

ENOSPC

The directory or file system that would contain the new file cannot be extended.

ENOTDIR

A component of the path prefix is not a directory.

ENXIO

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 either O_WRONLY, O_RDWR, O_CREAT (if the file does not exist), or O_TRUNC is set in oflag argument.

SEE ALSO

close(), lseek(), read(), stat(), write()