The GNU C Library - Open-time Flags

Open-time Flags

The open-time flags specify options affecting how open will behave. These options are not preserved once the file is open. The exception to this is O_NONBLOCK , which is also an I/O operating mode and so it is saved. See Opening and Closing Files, for how to call open .

There are two sorts of options specified by open-time flags.

• File name translation flags affect how open looks up the file name to locate the file, and whether the file can be created.

• Open-time action flags specify extra operations that open will perform on the file once it is open.

Here are the file name translation flags.

Macro int O_CREAT

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

Macro int O_EXCL

If both O_CREAT and O_EXCL are set, then open fails if the specified file already exists. This is guaranteed to never clobber an existing file.

Macro int O_NONBLOCK

This prevents open from blocking for a ``long time'' to open the file. This is only meaningful for some kinds of files, usually devices such as serial ports. Often opening a port to a modem blocks until the modem reports carrier detection; if O_NONBLOCK is specified, open will return immediately without a carrier.

Note that the O_NONBLOCK flag is overloaded as both an I/O operating mode and a file name translation flag. This means that specifying O_NONBLOCK in open also sets nonblocking I/O mode; see Operating Modes. To open the file without blocking but do normal I/O that blocks, you must call open with O_NONBLOCK set and then call fcntl to turn the bit off.

Macro int O_NOCTTY

If the named file is a terminal device, don't make it the controlling terminal for the process. See Job Control, for information about what it means to be the controlling terminal. In the GNU system and 4.4 BSD, opening a file never makes it the controlling terminal and O_NOCTTY is zero.

These three file name translation flags exist only in the GNU system.

Macro int O_IGNORE_CTTY

Do not recognize the named file as the controlling terminal, even if it refers to the process's existing controlling terminal device. Operations on the new file descriptor will never induce job control signals. See Job Control.

Macro int O_NOLINK

If the named file is a symbolic link, open the link itself instead of the file it refers to. (fstat on the new file descriptor will return the information returned by lstat on the link's name.)

Macro int O_NOTRANS

If the named file is specially translated, do not invoke the translator. Open the bare file the translator itself sees.

The open-time action flags tell open to do additional operations which are not really related to opening the file. The reason to do them as part of open instead of in separate calls is that open can do them atomically.

Macro int O_TRUNC

Truncate the file to zero length. This option is only useful for regular files, not special files such as directories or FIFOs. POSIX.1 requires that you open the file for writing to use O_TRUNC . In BSD and GNU you must have permission to write the file to truncate it, but you need not open for write access.

This is the only open-time action flag specified by POSIX.1. There is no good reason for truncation to be done by open , instead of by calling ftruncate afterwards. The O_TRUNC flag existed in Unix before ftruncate was invented, and is retained for backward compatibility.

Macro int O_SHLOCK

Acquire a shared lock on the file, as with flock . See File Locks.

If O_CREAT is specified, the locking is done atomically when creating the file. You are guaranteed that no other process will get the lock on the new file first.

Macro int O_EXLOCK

Acquire an exclusive lock on the file, as with flock . See File Locks. This is atomic like O_SHLOCK .