OPEN

Section: System Calls (2)
Updated: August 1, 1992
Index Return to Main Contents

NAME

open - open a file for reading or writing, or create a new file

BSD SYNOPSIS

#include <sys/file.h>

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

POSIX SYNOPSIS

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

int open(const char *path, int flags, ...);

DESCRIPTION

The open function opens a file, whose pathname is specified by path, for reading and/or writing as specified by the flags argument, and returns a file descriptor for that file that is the lowest file descriptor not currently open for the process. The flags argument may indicate that the file is to be created if it doesn't already exist by specifying the O_CREAT flag, in which case the file is created with permissions as given in a third argument, mode, as described in chmod(2) and modified by the process' umask value (see umask(2)). For POSIX applications, the mode argument is optional, and isn't given unless the O_CREAT flag is specified.

The path argument is a pointer to an array of ASCII characters representing a pathname, terminated by a null character. The flags argument specifies the file status flags and file access modes for the open file, and it must contain exactly one of the following values (file access modes):

O_RDONLY: Open for reading only.
O_WRONLY: Open for writing only.
O_RDWR: Open for reading and writing.

Any combination of the following values may be bitwise or'ed with the file access mode above:

O_APPEND: Append on each write.
O_CREAT: If the file already exists, then this flag has no effect, except as noted under O_EXCL below. Otherwise the file is created; the file's user ID is set to the effective user ID of the calling process; the file's group ID is set to the group ID of the directory in which the file is created; and the file permission bits is set to the value of the third argument, mode, which is of type mode_t, except for those set in the process' umask value. The value of the mode argument does not affect whether the file is opened for reading, writing or both.
O_EXCL: If both O_EXCL and O_CREAT are set, then the open function will fail if the file exists, setting errno to EEXIST. This can be used to implement a simple locking system.
: If O_EXCL is set and the last component of the pathname is a symbolic link, then open will fail even if the symbolic link points to a nonexistent name.
O_NDELAY: (BSD only) If opening the file would result in the process being blocked for some reason, (for example, waiting for carrier on a dialup line), open returns immediately. The first time the process attempts to perform I/O on the open file it will block (not currently implemented).
O_NOCTTY: (POSIX only) If path identifies a terminal device, then open will not cause the terminal device to become the controlling terminal for the calling process.
O_NONBLOCK: (POSIX only) As the BSD O_NDELAY, with these additions:
: When opening a FIFO and the O_NONBLOCK flag is set, then an open for reading will return without delay. On the other hand, an open for writing will return an error if no process has the FIFO open for reading.
: When an opening a FIFO and the O_NONBLOCK flag is clear, then an open for reading will block until a process opens the FIFO for writing. On the other hand, an open for writing will block until a process opens the FIFO for reading.
: When opening a block special or character special file that supports nonblocking opens, and the O_NONBLOCK flag is set, then the open function will return without delay. If the O_NONBLOCK flag is clear, then the function will wait until the device is ready or available before returning.
O_TRUNC: If the file exists and is a regular file, it is truncated to zero length upon successful open.

If O_CREAT is set and the file did not exist previously, then open will mark of update the st_atime, st_ctime and st_mtime fields of the file, and the st_ctime and st_mtime fields of the directory in which the file is created.

If O_TRUNC is set and the file previously existed, then open will mark for update the st_ctime and st_mtime fields of the file.

Upon successful completion, open sets the file pointer used to mark the current position within the file to the beginning of the file. Furthermore, the new descriptor is set to remain open across execve system calls---the close-on-exec file descriptor flag associated with the new file descriptor is cleared; see close(2) and fcntl(2).

The system imposes a limit on the number of file descriptors that can be opened simultaneously by one process. For BSD applications, the getdtablesize(2) function returns the current system limit. For POSIX applications, this number is given by the constant OPEN_MAX.

RETURN VALUE

Upon successful completion, open opens the file and returns a nonnegative integer representing the lowest numbered unused file descriptor. Otherwise, the function returns -1 and sets errno to indicate the error.

ERRORS

If any of the following conditions occurs, open returns -1 and sets errno to the corresponding value:

[EACCES]: Search permission is denied for a component of the path prefix; or, the required permissions (for reading and/or writing) are denied for the named flag; or, O_CREAT is specified, the file does not exist, and the directory in which it is to be created does not permit writing; or, O_TRUNC is specified and the file 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; or, 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 are specified and the file exists.
[EFAULT]: The path argument points outside the process's allocated address space.
[EINTR]: (POSIX only) The open function was interrupted by a signal.
[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 flags argument specifies O_WRONLY or O_RDWR.
[ELOOP]: Too many symbolic links were encountered in translating the pathname.
[EMFILE]: The system limit for open file descriptors per process has already been reached.
[ENAMETOOLONG]: A component of path exceeds 255 characters, or the entire pathname exceeds 1023 characters. For POSIX applications these values are given by the constants {NAME_MAX} and {PATH_MAX}, respectively.
[ENFILE]: The system file table is full (too many files are 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 a component of the pathname that must exist does not exist or path is empty string.
[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; or, 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; or (POSIX only), O_NONBLOCK is set, the file is a FIFO, O_WRONLY is set and no process has the FIFO opened for reading.
[EOPNOTSUPP]: (BSD only) An attempt was made to open a socket (not currently implemented).
[EROFS]: The named file resides on a read-only file system, and the file is to be modified (O_WRONLY, O_RDWR, O_CREAT or O_TRUNC is set).
[ETXTBSY]: The file is a pure procedure (shared text) file that is being executed and the open call requests write access.

This document was created by man2html, using the manual pages.
Time: 17:22:19 GMT, March 25, 2025