open, openat, openx, openxat, open64, open64at, open64x, open64xat, creat, or creat64 Subroutine

Purpose

Opens a file for reading or writing.

Syntax

#include <fcntl.h>

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

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

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

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

int open64x (Path, OFlag, Mode, Extension)
char *Path;
int64_t OFlag;
mode_t Mode;
ext_t Extension;

int open64xat (DirFileDescriptor, Path, OFlag, Mode, Extension)
int DirFileDescriptor;
char *Path;
int64_t OFlag;
mode_t Mode;
ext_t Extension;

Description

The openat subroutine is equivalent to the open subroutine if the DirFileDescriptor parameter is AT_FDCWD or the Path parameter is an absolute path name. If DirFileDescriptor is a valid file descriptor of an open directory and Path is a relative path name, Path is considered to be relative to the directory that is associated with the DirFileDescriptor parameter instead of the current working directory. Similarly, the openxat, open64at, or open64xat subroutine are equivalent to the openx, open64, or open64x subroutine, respectively, in the same way as openat and open.

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, exect, or fexecve Subroutinea) 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.

The open64x subroutine creates and accesses an encrypted file in an Encrypting File System (EFS). The open64x subroutine is similar to the openx subroutine, with the modification of the OFlag parameter, which is updated to a 64-bit quantity.

If the DirFileDescriptor parameter in the openat, openxat, open64at, or open64xat subroutine was opened without the O_SEARCH open flag, the subroutine checks to determine whether directory searches are permitted for that directory by using the current permissions of the directory. If the directory was opened with the O_SEARCH open flag, the subroutine does not perform the check for that directory.

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 O_SEARCH flag has the same value as the O_EXEC flag. Starting in AIX 7.1, programs that passed the O_EXEC flag to a directory open may fail, as the open code will also check the search permission for the directory.

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,openat openx, openxat, open64, open64at, open64x, open64xat, and creat subroutines are unsuccessful and the named file is not opened if one or more of the following are true:

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

The openat, openxat, open64at, and open64xat subroutines are unsuccessful and the named file is not opened if one or more of the following are true: