./_Man_NeXT_html/html2/open.2.html

Manual page for OPEN(2)

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

BSD SYNOPSIS

#include <libc.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: