[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

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;

Note: The open64 and creat64 subroutines apply to AIX 4.2 and later releases. 

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


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

Description

Note: The open64 and creat64 subroutines apply to AIX 4.2 and later releases.

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


Path Specifies the file to be opened.
Mode Specifies the read, write, and execute permissions of the file to be created (requested by the O_CREAT flag). If the file already exists, this parameter is ignored. The Mode parameter is constructed by logically ORing one or more of the following values, which are defined in the sys/mode.h file:

S_ISUID
Enables the setuid attribute for an executable file. A process executing this program acquires the access rights of the owner of the file.

S_ISGID
Enables the setgid attribute for an executable file. A process executing this program acquires the access rights of the group of the file. Also, enables the group-inheritance attribute for a directory. Files created in this directory have a group equal to the group of the directory.

The following attributes apply only to files that are directly executable. They have no meaning when applied to executable text files such as shell scripts and awk scripts.

S_ISVTX
Enables the link/unlink attribute for a directory. Files cannot be linked to in this directory. Files can only be unlinked if the requesting process has write permission for the directory and is either the owner of the file or the directory.

S_ISVTX
Enables the save text attribute for an executable file. The program is not unmapped after usage.

S_ENFMT
Enables enforcement-mode record locking for a regular file. File locks requested with the lockf subroutine are enforced.

S_IRUSR
Permits the file's owner to read it.

S_IWUSR
Permits the file's owner to write to it.

S_IXUSR
Permits the file's owner to execute it (or to search the directory).

S_IRGRP
Permits the file's group to read it.

S_IWGRP
Permits the file's group to write to it.

S_IXGRP
Permits the file's group to execute it (or to search the directory).

S_IROTH
Permits others to read the file.

S_IWOTH
Permits others to write to the file.

S_IXOTH
Permits others to execute the file (or to search the directory).

Other mode values exist that can be set with the mknod subroutine but not with the chmod subroutine.

Extension Provides communication with character device drivers that require additional information or return additional status. Each driver interprets the Extension parameter in a device-dependent way, either as a value or as a pointer to a communication area. Drivers must apply reasonable defaults when the Extension parameter value is 0.
OFlag Specifies the type of access, special open processing, the type of update, and the initial state of the open file. The parameter value is constructed by logically ORing special open processing flags. These flags are defined in the fcntl.h file and are described in the following flags.

Flags That Specify Access Type

The following OFlag parameter flag values specify type of access:

O_RDONLY The file is opened for reading only.
O_WRONLY The file is opened for writing only.
O_RDWR The file is opened for both reading and writing.

Note: One of the file access values must be specified. Do not use O_RDONLY, O_WRONLY, or O_RDWR together. If none is set, none is used, and the results are unpredictable.

Flags That Specify Special Open Processing

The following OFlag parameter flag values specify special open processing:

O_CREAT If the file exists, this flag has no effect, except as noted under the O_EXCL flag. If the file does not exist, a regular file is created with the following characteristics:
  • The owner ID of the file is set to the effective user ID of the process.
  • The group ID of the file is set to the group ID of the parent directory if the parent directory has the SetGroupID attribute (S_ISGID bit) set. Otherwise, the group ID of the file is set to the effective group ID of the calling process.
  • The file permission and attribute bits are set to the value of the Mode parameter, modified as follows:
    • All bits set in the process file mode creation mask are cleared. (The file creation mask is described in the umask subroutine.)
    • The S_ISVTX attribute bit is cleared.
O_EXCL If the O_EXCL and O_CREAT flags are set, the open is unsuccessful if the file exists.

Note: The O_EXCL flag is not fully supported for Network File Systems (NFS). The NFS protocol does not guarantee the designed function of the O_EXCL flag.
O_NSHARE Assures that no process has this file open and precludes subsequent opens. If the file is on a physical file system and is already open, this open is unsuccessful and returns immediately unless the OFlag parameter also specifies the O_DELAY flag. This flag is effective only with physical file systems.

Note: This flag is not supported by NFS.
O_RSHARE Assures that no process has this file open for writing and precludes subsequent opens for writing. The calling process can request write access. If the file is on a physical file system and is open for writing or open with the O_NSHARE flag, this open fails and returns immediately unless the OFlag parameter also specifies the O_DELAY flag.

Note: This flag is not supported by NFS.
O_DEFER The file is opened for deferred update. Changes to the file are not reflected on permanent storage until an fsync (fsync Subroutine) subroutine operation is performed. If no fsync subroutine operation is performed, the changes are discarded when the file is closed.

Note: This flag is not supported by NFS.

Note: This flag causes modified pages to be backed by paging space. Before using this flag make sure there is sufficient paging space.
O_NOCTTY This flag specifies that the controlling terminal should not be assigned during this open.
O_TRUNC If the file does not exist, this flag has no effect. If the file exists, is a regular file, and is successfully opened with the O_RDWR flag or the O_WRONLY flag, all of the following apply:
  • The length of the file is truncated to 0.
  • The owner and group of the file are unchanged.
  • The SetUserID attribute of the file mode is cleared.
  • The SetUserID attribute of the file is cleared.
O_DIRECT This flag specifies that direct i/o will be used for this file while it is opened.

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

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:

O_SYNC: If set, updates to regular files and writes to block devices are synchronous updates. File update is performed by the following subroutines:
  • fclear
  • ftruncate
  • open with O_TRUNC
  • write

On return from a subroutine that performs a synchronous update (any of the preceding subroutines, when the O_SYNC flag is set), the program is assured that all data for the file has been written to permanent storage, even if the file is also open for deferred update.

Note: The O_DSYNC flag applies to AIX 4.2.1 and later releases.

O_DSYNC: If set, the file data as well as all file system meta-data required to retrieve the file data are written to their permanent storage locations. File attributes such as access or modification times are not required to retrieve file data, and as such, they are not guaranteed to be written to their permanent storage locations before the preceding subroutines return. (Subroutines listed in the O_SYNC description.)
O_SYNC | O_DSYNC: If both flags are set, the file's data and all of the file's meta-data (including access time) are written to their permanent storage locations.

Note: The O_RSYNC flag applies to AIX 4.3 and later releases.

O_RSYNC: This flag is used in combination with O_SYNC or D_SYNC, and it extends their write operation behaviors to read operations. For example, when O_SYNC and R_SYNC are both set, a read operation will not return until the file's data and all of the file's meta-data (including access time) are written to their permanent storage locations.

Flags That Define the Open File Initial State

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

O_APPEND The file pointer is set to the end of the file prior to each write operation.
O_DELAY Specifies that if the open subroutine could not succeed due to an inability to grant the access on a physical file system required by the O_RSHARE flag or the O_NSHARE flag, the process blocks instead of returning the ETXTBSY error code.
O_NDELAY Opens with no delay.
O_NONBLOCK Specifies that the open subroutine should not block.

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:

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

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:

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

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

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

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:

EACCES One of the following is true:
  • The file exists and the type of access specified by the OFlag parameter is denied.
  • Search permission is denied on a component of the path prefix specified by the Path parameter. Access could be denied due to a secure mount.
  • The file does not exist and write permission is denied for the parent directory of the file to be created.
  • The O_TRUNC flag is specified and write permission is denied.
EAGAIN The O_TRUNC flag is set and the named file contains a record lock owned by another process.
EDQUOT The directory in which the entry for the new link is being placed cannot be extended, or an i-node could not be allocated for the file, because the user or group quota of disk blocks or i-nodes in the file system containing the directory has been exhausted.
EEXIST The O_CREAT and O_EXCL flags are set and the named file exists.
EFBIG An attempt was made to write a file that exceeds the process' file limit or the maximum file size. If the user has set the environment variable XPG_SUS_ENV=ON prior to execution of the process, then the SIGXFSZ signal is posted to the process when exceeding the process' file size limit.
EINTR A signal was caught during the open subroutine.
EIO The path parameter names a STREAMS file and a hangup or error occurred.
EISDIR Named file is a directory and write access is required (the O_WRONLY or O_RDWR flag is set in the OFlag parameter).
EMFILE The system limit for open file descriptors per process has already been reached (OPEN_MAX).
ENAMETOOLONG The length of the Path parameter exceeds the system limit (PATH_MAX); or a path-name component is longer than NAME_MAX and _POSIX_NO_TRUNC is in effect.
ENFILE The system file table is full.
ENOENT The O_CREAT flag is not set and the named file does not exist; or the O_CREAT flag is not set and either the path prefix does not exist or the Path parameter points to an empty string.
ENOMEM The Path parameter names a STREAMS file and the system is unable to allocate resources.
ENOSPC The directory or file system that would contain the new file cannot be extended.
ENOSR The Path argument names a STREAMS-based file and the system is unable to allocate a STREAM.
ENOTDIR A component of the path prefix specified by the Path component is not a directory.
ENXIO One of the following is true:
  • Named file is a character special or block special file, and the device associated with this special file does not exist.
  • Named file is a multiplexed special file and either the channel number is outside of the valid range or no more channels are available.
  • The O_DELAY flag or the O_NONBLOCK flag is set, the named file is a FIFO, the O_WRONLY flag is set, and no process has the file open for reading.
EROFS Named file resides on a read-only file system and write access is required (either the O_WRONLY, O_RDWR, O_CREAT (if the file does not exist), or O_TRUNC flag is set in the OFlag parameter).
ETXTBSY File is on a physical file system and is already open in a manner (with the O_RSHARE or O_NSHARE flag) that precludes this open; or the O_NSHARE or O_RSHARE flag was requested with the O_NDELAY flag set, and there is a conflicting open on a physical file system.

Note: The EOVERFLOW error code applies to AIX 4.2 and later releases.

EOVERFLOW A call was made to open and creat and the file already existed and its size was larger than OFF_MAX and the O_LARGEFILE flag was not set.

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

EFAULT The Path parameter points outside of the allocated address space of the process.
EINVAL The value of the OFlag parameter is not valid.
ELOOP Too many symbolic links were encountered in translating the Path parameter.
ETXTBSY The file specified by the Path parameter is a pure procedure (shared text) file that is currently executing, and the O_WRONLY or O_RDWR flag is set in the OFlag parameter.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

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 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.1 General Programming Concepts: Writing and Debugging Programs.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]