Technical Reference: Base Operating System and Extensions, Volume 1

open, openx, open64, creat, or creat64 Subroutine

Purpose

Opens a file for reading or writing.

Syntax

#include <fcntl.h>

int open ( Path, OFlag [, Mode])
const char *Path;
int OFlag;
mode_t Mode;

int openx (Path, OFlag, Mode, Extension)
const char *Path;
int OFlag;
mode_t Mode;
int Extension;

int creat (Path, Mode)
const char *Path;
mode_t Mode;

int open64 (Path, OFlag [, Mode])
const char *Path;
int OFlag;
mode_t Mode;

int creat64 (Path, Mode)
const char *Path;
mode_t Mode;

Description

The open, openx, and creat subroutines establish a connection between the file named by the Path parameter and a file descriptor. The opened file descriptor is used by subsequent I/O subroutines, such as read and write, to access that file.

The openx subroutine is the same as the open subroutine, with the addition of an Extension parameter, which is provided for device driver use. The creat subroutine is equivalent to the open subroutine with the O_WRONLY, O_CREAT, and O_TRUNC flags set.

The returned file descriptor is the lowest file descriptor not previously open for that process. No process can have more than OPEN_MAX file descriptors open simultaneously.

The file offset, marking the current position within the file, is set to the beginning of the file. The new file descriptor is set to remain open across exec (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutines.

The open64 and creat64 subroutines are equivalent to the open and creat subroutines except that the O_LARGEFILE flag is set in the open file description associated with the returned file descriptor. This flag allows files larger than OFF_MAX to be accessed. If the caller attempts to open a file larger than OFF_MAX and O_LARGEFILE is not set, the open will fail and errno will be set to EOVERFLOW.

In the large file enabled programming environment, open is redefined to be open64 and creat is redefined to be creat64.

Parameters

Flags That Specify Access Type

The following OFlag parameter flag values specify type of access:

Flags That Specify Special Open Processing

The following OFlag parameter flag values specify special open processing:

The open subroutine is unsuccessful if any of the following conditions are true:

• The file supports enforced record locks and another process has locked a portion of the file.
• The file is on a physical file system and is already open with the O_RSHARE flag or the O_NSHARE flag.
• The file does not allow write access.
• The file is already opened for deferred update.

Flag That Specifies Type of Update

A program can request some control on when updates should be made permanent for a regular file opened for write access. The following OFlag parameter values specify the type of update performed:

Flags That Define the Open File Initial State

The following OFlag parameter flag values define the initial state of the open file:

The O_NDELAY flag and the O_NONBLOCK flag are identical except for the value returned by the read and write subroutines. These flags mean the process does not block on the state of an object, but does block on input or output to a regular file or block device.

The O_DELAY flag is relevant only when used with the O_NSHARE or O_RSHARE flags. It is unrelated to the O_NDELAY and O_NONBLOCK flags.

General Notes on OFlag Parameter Flags

The effect of the O_CREAT flag is immediate, even if the file is opened with the O_DEFER flag.

When opening a file on a physical file system with the O_NSHARE flag or the O_RSHARE flag, if the file is already open with conflicting access the following can occur:

• If the O_DELAY flag is clear (the default), the open subroutine is unsuccessful.
• If the O_DELAY flag is set, the open subroutine blocks until there is no conflicting open. There is no deadlock detection for processes using the O_DELAY flag.

When opening a file on a physical file system that has already been opened with the O_NSHARE flag, the following can occur:

• If the O_DELAY flag is clear (the default), the open is unsuccessful immediately.
• If the O_DELAY flag is set, the open blocks until there is no conflicting open.

When opening a file with the O_RDWR, O_WRONLY, or O_TRUNC flag, and the file is already open with the O_RSHARE flag:

• If the O_DELAY flag is clear (the default), the open is unsuccessful immediately.
• If the O_DELAY flag is set, the open blocks until there is no conflicting open.

When opening a first-in-first-out (FIFO) with the O_RDONLY flag, the following can occur:

• If the O_NDELAY and O_NONBLOCK flags are clear, the open blocks until a process opens the file for writing. If the file is already open for writing (even by the calling process), the open subroutine returns without delay.
• If the O_NDELAY flag or the O_NONBLOCK flag is set, the open succeeds immediately even if no process has the FIFO open for writing.

When opening a FIFO with the O_WRONLY flag, the following can occur:

• If the O_NDELAY and O_NONBLOCK flags are clear (the default), the open blocks until a process opens the file for reading. If the file is already open for writing (even by the calling process), the open subroutine returns without delay.
• If the O_NDELAY flag or the O_NONBLOCK flag is set, the open subroutine returns an error if no process currently has the file open for reading.

When opening a block special or character special file that supports nonblocking opens, such as a terminal device, the following can occur:

• If the O_NDELAY and O_NONBLOCK flags are clear (the default), the open blocks until the device is ready or available.
• If the O_NDELAY flag or the O_NONBLOCK flag is set, the open subroutine returns without waiting for the device to be ready or available. Subsequent behavior of the device is device-specific.

Any additional information on the effect, if any, of the O_NDELAY, O_RSHARE, O_NSHARE, and O_DELAY flags on a specific device is documented in the description of the special file related to the device type.

If path refers to a STREAMS file, oflag may be constructed from O_NONBLOCK OR-ed with either O_RDONLY, O_WRONLY or O_RDWR. Other flag values are not applicable to STREAMS devices and have no effect on them. The value O_NONBLOCK affects the operation of STREAMS drivers and certain functions applied to file descriptors associated with STREAMS files. For STREAMS drivers, the implementation of O_NONBLOCK is device-specific.

If path names the master side of a pseudo-terminal device, then it is unspecified whether open locks the slave side so that it cannot be opened. Portable applications must call unlockpt before opening the slave side.

The largest value that can be represented correctly in an object of type off_t will be established as the offset maximum in the open file description.

Return Values

Upon successful completion, the file descriptor, a nonnegative integer, is returned. Otherwise, a value of -1 is returned, no files are created or modified, and the errno global variable is set to indicate the error.

Error Codes

The open, openx, and creat subroutines are unsuccessful and the named file is not opened if one or more of the following are true:

The open, openx, and creat subroutines are unsuccessful if one of the following are true:

Related Information

The chmod (chmod or fchmod Subroutine) subroutine, close (close Subroutine) subroutine, exec (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutine, fcntl, dup, or dup2 (fcntl, dup, or dup2 Subroutine) subroutine, fsync (fsync or fsync_range Subroutine) subroutine, ioctl (ioctl, ioctlx, ioctl32, or ioctl32x Subroutine) subroutine, lockfx (lockfx, lockf, flock, or lockf64 Subroutine) subroutine, lseek (lseek, llseek or lseek64 Subroutine) subroutine, read subroutine, stat subroutine, umask subroutine, write subroutine.

The Input and Output Handling in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.