OPEN(2V)

NAME
open - open or create a file for reading or writing

SYNOPSIS
#include <fcntl.h>

int open(path, flags[ , mode ] )
char *path;
int flags;
int mode;

SYSTEM V SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

int open(path, flags[ , mode ] )
char *path;
int flags;
mode_t mode;

DESCRIPTION

path points to the pathname of a file. open() opens the named file for reading and/or writing, as specified by the flags argument, and returns a descriptor for that file. The flags argument may indicate the file is to be created if it does not already exist (by specifying the O_CREAT flag), in which case the file is created with mode mode as described in chmod(2V) and modified by the process' umask value (see umask(2V)). If the path is an empty string, the kernel maps this empty pathname to `.', the current directory. flags values are constructed by ORing flags from the following list (one and only one of the first three flags below must be used):

O_RDONLY
    Open for reading only.

O_WRONLY
    Open for writing only.

O_RDWR
    Open for reading and writing.

O_NDELAY
    When opening a FIFO (named pipe - see mknod(2V)) with O_RDONLY or O_WRONLY set:

    If O_NDELAY is set:

        An open() for reading-only returns without delay. An open() for writing-only returns an error if no process currently has the file open for reading.

    If O_NDELAY is clear:

        A call to open() for reading-only blocks until a process opens the file for writing. A call to open() for writing-only blocks until a process opens the file for reading.

    When opening a file associated with a communication line:

    If O_NDELAY is set:

        A call to open() returns without waiting for carrier.

    If O_NDELAY is clear:

        A call to open() blocks until carrier is present.

O_NOCTTY
    When this flag is set, and path refers to a terminal device, open() prevents the terminal device from becoming the controlling terminal for the process.

O_NONBLOCK
    Same as O_NDELAY above.

O_SYNC
    When opening a regular file, this flag affects subsequent writes. If set, each write(2V) will wait for both the file data and file status to be physically updated.

O_APPEND
    If set, the seek 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 file is created, and 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 either:

    •   the effective group ID of the process, if the filesystem was not mounted with the BSD file-creation semantics flag (see mount(2V)) and the set-gid bit of the parent directory is clear, or

    •   the group ID of the directory in which the file is created.

    The low-order 12 bits of the file mode are set to the value of mode, modified as follows (see creat(2V)):

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

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

    •   The “set group ID on execution” bit of the mode is cleared if the effective user ID of the process is not super-user and the process is not a member of the group of the created file.

O_TRUNC
    If the file exists and is a regular file, and the file is successfully opened O_RDWR or O_WRONLY, its length is truncated to zero and the mode and owner are unchanged. O_TRUNC has no effect on FIFO special files or directories.

O_EXCL
    If O_EXCL and O_CREAT are set, open() will fail if the file exists. This can be used to implement a simple exclusive access locking mechanism.

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

The new descriptor is set to remain open across execve(2V) system calls; see close(2V) and fcntl(2V).

There is a system enforced limit on the number of open file descriptors per process, whose value is returned by the getdtablesize(2) call.

If O_CREAT is set and the file did not previously exist, upon successful completion, open() marks 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 O_TRUNC is set and the file previously existed, upon successful completion, open() marks for update the st_ctime and st_mtime fields of the file.

SYSTEM V DESCRIPTION

If path points to an empty string an error results.

The flags above behave as described, with the following exception:

If the O_NDELAY or O_NONBLOCK flag is set on a call to open(), the corresponding flag is set for that file descriptor (see fcntl(2V)) and subsequent reads and writes to that descriptor will not block (see read(2V) and write(2V)).

RETURN VALUES

open() returns a non-negative file descriptor on success. On failure, it returns -1 and sets errno to indicate the error.

ERRORS

EACCES
    Search permission is denied for a component of the path prefix of path.

    The file referred to by path does not exist, O_CREAT is specified, and the directory in which it is to be created does not permit writing.

    O_TRUNC is specified and write permission is denied for the file named by path.

    The required permissions (for reading and/or writing) are denied for the file named by path.

EDQUOT
    The file does not exist, O_CREAT is specified, 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.

    The file does not exist, O_CREAT is specified, and the user's quota of inodes on the file system on which the file is being created has been exhausted.

EEXIST
    O_EXCL and O_CREAT were both specified and the file exists.

EFAULT
    path points outside the process's allocated address space.

EINTR
    A signal was caught during the open() system call.

EIO A hangup or error occurred during a STREAMS open().

    An I/O error occurred while reading from or writing to the file system.

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

EMFILE
    The system limit for open file descriptors per process has already been reached.

ENAMETOOLONG
    The length of the path argument exceeds {PATH_MAX}.

    A pathname component is longer than {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect (see pathconf(2V)).

ENFILE
    The system file table is full.

ENOENT
    O_CREAT is not set and the named file does not exist.

    A component of the path prefix of path does not exist.

ENOSPC
    The file does not exist, O_CREAT is specified, 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.

    The file does not exist, O_CREAT is specified, and there are no free inodes on the file system on which the file is being created.

ENOSR
    A stream could not be allocated.

ENOTDIR
    A component of the path prefix of path is not a directory.

ENXIO
    O_NDELAY is set, the named file is a FIFO, O_WRONLY is set, and no process has the file open for reading.

    The file is a character special or block special file, and the associated device does not exist.

    O_NONBLOCK is set, the named file is a FIFO, O_WRONLY is set, and no process has the file open for reading.

    A STREAMS module or driver open routine failed.

EOPNOTSUPP
    An attempt was made to open a socket (not currently implemented).

EROFS
    The named file does not exist, O_CREAT is specified, and the file system on which it is to be created is a read-only file system.

    The named file resides on a read-only file system, and the file is to be opened for writing.

SYSTEM V ERRORS

In addition to the above, the following may also occur:

ENOENT
    path points to an empty string.

SEE ALSO
chmod(2V), close(2V), creat(2V), dup(2V), fcntl(2V), getdtablesize(2), getmsg(2), lseek(2V), mknod(2V), mount(2V), putmsg(2), read(2V), umask(2V) write(2V)