Go to the previous, next section.

Opening and Closing Files

This section describes the primitives for opening and closing files using file descriptors. The open and creat functions are declared in the header file `fcntl.h', while close is declared in `unistd.h'.

Function: int open (const char *filename, int flags[, mode_t mode])

The open function creates and returns a new file descriptor for the file named by filename. Initially, the file position indicator for the file is at the beginning of the file. The argument mode is used only when a file is created, but it doesn't hurt to supply the argument in any case.

The flags argument controls how the file is to be opened. This is a bit mask; you create the value by the bitwise OR of the appropriate parameters (using the `|' operator in C).

The flags argument must include exactly one of these values to specify the file access mode:

O_RDONLY

Open the file for read access.

O_WRONLY

Open the file for write access.

O_RDWR

Open the file for both reading and writing.

The flags argument can also include any combination of these flags:

O_APPEND

If set, then all write operations write the data at the end of the file, extending it, regardless of the current file position.

O_CREAT

If set, the file will be created if it doesn't already exist.

O_EXCL

If both O_CREAT and O_EXCL are set, then open fails if the specified file already exists.

O_NOCTTY

If filename names a terminal device, don't make it the controlling terminal for the process. See section Job Control, for information about what it means to be the controlling terminal.

O_NONBLOCK

This sets nonblocking mode. This option is usually only useful for special files such as FIFOs (see section Pipes and FIFOs) and devices such as terminals. Normally, for these files, open blocks until the file is "ready". If O_NONBLOCK is set, open returns immediately.

The O_NONBLOCK bit also affects read and write: It permits them to return immediately with a failure status if there is no input immediately available (read), or if the output can't be written immediately (write).

O_TRUNC

If the file exists and is opened for write access, truncate it to zero length. This option is only useful for regular files, not special files such as directories or FIFOs.

For more information about these symbolic constants, see section File Status Flags.

The normal return value from open is a non-negative integer file descriptor. In the case of an error, a value of -1 is returned instead. In addition to the usual file name syntax errors (see section File Name Errors), the following errno error conditions are defined for this function:

EACCES

The file exists but is not readable/writable as requested by the flags argument.

EEXIST

Both O_CREAT and O_EXCL are set, and the named file already exists.

EINTR

The open operation was interrupted by a signal. See section Primitives Interrupted by Signals.

EISDIR

The flags argument specified write access, and the file is a directory.

EMFILE

The process has too many files open.

ENFILE

The entire system, or perhaps the file system which contains the directory, cannot support any additional open files at the moment. (This problem cannot happen on the GNU system.)

ENOENT

The named file does not exist, but O_CREAT is not specified.

ENOSPC

The directory or file system that would contain the new file cannot be extended, because there is no disk space left.

ENXIO

O_NONBLOCK and O_WRONLY are both set in the flags argument, the file named by filename is a FIFO (see section Pipes and FIFOs), and no process has the file open for reading.

EROFS

The file resides on a read-only file system and any of O_WRONLY, O_RDWR, O_CREAT, and O_TRUNC are set in the flags argument.

The open function is the underlying primitive for the fopen and freopen functions, that create streams.

Obsolete function: int creat (const char *filename, mode_t mode)

This function is obsolete. The call:

creat (filename, mode)

is equivalent to:

open (filename, O_WRONLY | O_CREAT | O_TRUNC, mode)

Function: int close (int filedes)

The function close closes the file descriptor filedes. Closing a file has the following consequences:

• The file descriptor is deallocated.

• Any record locks owned by the process on the file are unlocked.

• When all file descriptors associated with a pipe or FIFO have been closed, any unread data is discarded.

The normal return value from close is 0; a value of -1 is returned in case of failure. The following errno error conditions are defined for this function:

EBADF

The filedes argument is not a valid file descriptor.

EINTR

The close call was interrupted by a signal. See section Primitives Interrupted by Signals. Here is an example of how to handle EINTR properly:

TEMP_FAILURE_RETRY (close (desc));

To close a stream, call fclose (see section Closing Streams) instead of trying to close its underlying file descriptor with close. This flushes any buffered output and updates the stream object to indicate that it is closed.

Go to the previous, next section.