Opens a file for reading or writing.
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 Version 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;
Note: The open64 and creat64 subroutines apply to Version 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 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.
|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:
|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.|
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.
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:
|O_EXCL||If the O_EXCL and O_CREAT flags are set, the open is unsuccessful if the file exists.|
|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.|
|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.|
|O_DEFER|| The file is opened for deferred update. Changes to the file are not reflected on permanent storage until an fsync subroutine operation is performed. If no fsync subroutine operation is performed, the changes are discarded when the file is closed.
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:|
|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:
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:
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 Version 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 Version 4.3.0 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.|
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.
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.
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.
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:
|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 envirnoment 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 occured.|
|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:
|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 Version 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.|
These subroutines are part of Base Operating System (BOS) Runtime.
The chmod subroutine, close subroutine, exec subroutine, fcntl, dup, or dup2 subroutine, fsync subroutine, ioctl subroutine, lockfx subroutine, lseek subroutine, read subroutine, stat subroutine, umask subroutine, write subroutine.
The Input and Output Handling Programmer's Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.