OPEN(2,L) AIX Technical Reference OPEN(2,L)
-------------------------------------------------------------------------------
open, openx, creat
PURPOSE
Opens a file for reading or writing.
SYNTAX
#include <fcntl.h>
int open (path, oflag, mode) int creat (path, mode)
char *path; char *path;
int oflag, mode; int mode;
int openx (path, oflag, mode, ext)
char *path;
int oflag, mode, ext;
DESCRIPTION
The open and openx system calls open a file descriptor for the file named by
the path parameter.
The file status flags are set according to the value of the oflag parameter.
The oflag parameter values are constructed by logically ORing flags from the
following list:
Note: Do not use O_RDONLY, O_WRONLY, or O_RDWR together.
O_RDONLY Open for reading only.
O_WRONLY Open for writing only.
O_RDWR Open for reading and writing.
O_DEFERC Open with defer commit update semantics. This is used with other
modes indicating the file is open for modification. With this
mode, changes to the file are not made permanent until either an
fcommit, fsync, close, or exit are done (or the program aborts).
Changes made since the last commit can be undone using fabort.
These semantics may not apply if the file is open for
modification multiple times and all opens are not with the
O_DEFERC flag set. See also "fsync, fcommit," "fabort," and
"close, closex."
Processed November 7, 1990 OPEN(2,L) 1
OPEN(2,L) AIX Technical Reference OPEN(2,L)
O_NDELAY Open with no delay. This flag may affect subsequent reads and
writes.
When a FIFO is opened with O_RDONLY or O_WRONLY set, the
following facts apply:
o If O_NDELAY is set, an open for reading-only returns without
delay. An open for writing-only returns an error if no
process currently has the file open for reading.
o If O_NDELAY is clear, an open for reading-only blocks until a
process opens the file for writing. An open for writing-only
blocks until a process opens the file for reading.
When opening a file associated with a communication line:
o If O_NDELAY is set, the open returns without waiting for
carrier.
o If O_NDELAY is clear, the open blocks until carrier is
present.
When opening a regular file that supports enforced record locks:
o If O_NDELAY is set, then reads and writes to portions of the
file that are locked by other processes return an error.
o If O_NDELAY is clear, then reads and writes to portions of
the file that are locked by other processes blocks until the
locks are released.
O_NONBLOCK Open with no delay. This flag is identical in function to
O_NDELAY when opening a file. However, subsequent reads and
writes return different values based on whether the file is
opened with O_NDELAY or O_NONBLOCK. See "read, readv, readx" and
"write, writex."
O_APPEND If set, the file pointer is set to the end of the file prior to
each write.
O_CREAT If the file exists, this flag has no effect. If the file does
not exist, the file is created. The file's owner ID is set to
the process's effective user ID. If the S_ISGID mode bit is set
in the parent directory, the file's group ID is set to the group
ID of the parent directory. Otherwise, the file's group ID is
set to the process's effective group ID. The low-order 12 bits
of the file mode are set to the value of the mode parameter
modified as follows:
o All bits set in the process's file mode creation mask are
cleared. (For information about the creation mask, see
"umask.")
Processed November 7, 1990 OPEN(2,L) 2
OPEN(2,L) AIX Technical Reference OPEN(2,L)
o The S_ISVTX bit of the mode, which saves the text image after
execution, is cleared.
For information about file modes and a list of the mode values,
see "chmod, fchmod" and "stat.h."
O_TRUNC If the file exists, then its length is truncated to 0, and the
mode and owner are unchanged. This requires write permission on
the file. If the file has any outstanding record locks, then
open fails and the file remains unchanged. The S_ISGID and
S_ISUID mode bits are cleared.
O_EXCL If O_EXCL and O_CREAT are set, open fails if the file exists.
O_SYNC Open with immediate commit update semantics. This is used with
other modes indicating the file is open for modification. With
this mode, changes to the file are guaranteed to be made
permanent (with an implicit fsync) before the write system call
to be considered atomic, performing both write and commit
functions before returning. This flag is only effective with
regular and block special files.
O_REPLSYNC Open with immediate replicated commit update semantics. This is
only meaningful when used with the O_SYNC flag and if you have
the TCF (Transparent Computing Facility) installed. In the case
where a file is replicated on more than one site, this flag
guarantees that the modified file will be sorted on at least two
file systems before the write system call completes. These two
file systems necessarily will be the primary and either a
backbone or secondary sites.
This flag will be ignored when either the O_SYNC bit is not set,
the file is not replicated, or no backbone site is available in
the cluster to replicate the file. When writing data to this
file with the write system call, errors reported through the
return code reflect only the success or failure of the primary
copy of the file.
Propagation errors which include not having a backbone site for
the file in the current cluster or having a backbone file system
run out of free space are noted in the system log (see syslog in
the AIX Operating Systems Commands Reference). Thus, no change
in write return status is noted; the system log must be queried
to ascertain possible errors. Finally, this flag is only
effective with regular files.
The file pointer used to mark the current position within the file is set to
the beginning of the file. The mode parameter is used only if open or openx
creates the file named path (as requested by O_CREAT, described above). The
ext parameter provides communication with character device drivers that require
additional information or provide additional status. Each driver interprets
Processed November 7, 1990 OPEN(2,L) 3
OPEN(2,L) AIX Technical Reference OPEN(2,L)
the ext in a device-dependent way, either as a value or as a pointer to a
communication area. Drivers must apply reasonable defaults when the ext
parameter is 0.
The new file descriptor is set to remain open across exec system calls (see
"fcntl, flock, lockf").
No process can have more than 200 file descriptors open simultaneously.
If the named file is a hidden directory, (see "chhidden") open or openx selects
one of the existing components inside the hidden directory according to the
process's xvers string (see "getxvers, setxvers") and site path list (see
"getspath, setspath"). A component within the hidden directory is created by
open only if O_CREAT is specified and the component is named explicitly, using
the @ syntax.
If the Transparent Computing Facility is installed, the following information
applies to replicated files and special files.
When creating a file in a replicated file system, or opening an existing file
in that file system with O_WRONLY or O_RDWR, the primary copy is used as the
storage site; the site which provides the data for reading and writing. This
is because the primary copy of the file system is the only one on which change
can be made. The other copies of the file system are brought up-to-date when
changes to the file are committed. While a file is open for O_WRONLY or
W_RDWR, all read and writes on the file by any process will be using the same
copy of the file.
When all processes which have a replicated file open have it open for O_RDONLY,
the system may provide data to each process from any up-to-date copy of the
file, (that is, several different copies/sites can provide data when only read
access is being used by all processes using the files) often a non-primary copy
stored on the site where the process is running. If this storage site goes
down, files open with O_RDONLY will continue to read uninterrupted if another
storage site for the file can be found.
If the named file is in a replicated file system, the site that stores the
primary copy of the file system must be up. If the file does not previously
exist, upon creation it is replicated on only the primary and backbone copies
of the file system. Once created, the chfstore system call can be used to
increase the number of sites on which the file is stored.
TTY devices and block devices can be opened from any site within the TCF
cluster. To be able to open a remote TTY device, that device must already be
held open by at least one process in the cluster; that is, the first open of a
TTY device must be local. The site to which the physical device is attached is
identified by the device site specified in mknod or mknodx when the device
special file was created.
Character devices other than TTY devices and null can only be opened at the
site which has the device.
Processed November 7, 1990 OPEN(2,L) 4
OPEN(2,L) AIX Technical Reference OPEN(2,L)
Note that the following two system calls are equivalent:
creat (path, mode)
open (path, O_WRONLY | O_CREAT | O_TRUNC, mode)
Upon successful completion, the file descriptor, a nonnegative integer, is
returned. If open fails, a value of -1 is returned, and errno is set to
indicate the error.
ERROR CONDITIONS
The open system call fails, and the named file is not opened if one or more of
the following are true:
ENOTDIR A component of the path prefix is not a directory.
ENOENT O_CREAT is not set and the named file does not exist.
EACCES A component of the path prefix denies search permission.
EACCES The type of access specified by the oflag parameter is denied for the
named file.
EISDIR The named file is a directory and the oflag parameter is write or
read/write.
EROFS The named file resides on a read-only file system and the oflag
parameter is write or read/write.
EMFILE Two hundred (200) file descriptors are currently open.
ENXIO The named file is a character special or block special file, and the
device associated with this special file does not exist.
ENXIO The named file is a multiplexed special file and either the channel
number is outside of the valid range, or no more channels are
available.
ETXTBSY The file is a pure procedure (shared text) file that is being
executed and the oflag parameter is write or read/write.
EFAULT The path parameter points to a location outside of the process's
allocated address space.
EEXIST O_CREAT and O_EXCL are set, and the named file exists.
ENXIO O_NDELAY is set, the named file is a FIFO, O_WRONLY is set, and no
process has the file open for reading.
Processed November 7, 1990 OPEN(2,L) 5
OPEN(2,L) AIX Technical Reference OPEN(2,L)
EAGAIN O_TRUNC is set, and the named file contains a record lock owned by
another process. See "fcntl, flock, lockf" for information about
record locks.
EINTR A signal was caught during the open system call.
ENFILE The system file table or inode table is full.
ENOSPC The directory that would contain the new file cannot be extended.
ESTALE The process's root or current directory is located in a virtual file
system that has been unmounted.
ENAMETOOLONG
A component of the path parameter exceeded NAME_MAX characters or the
entire path parameter exceeded PATH_MAX characters.
EIO An I/O error occurred during the operation.
ENOENT O_CREAT is set but a directory in the path prefix does not exist.
A hidden directory was named, but no component inside it matched the
process's current site path list.
ENOENT A symbolic link was named, but the file to which it refers does not
exist.
ELOOP A loop of symbolic links was detected.
ENOSPC The file system is out of inodes.
EDQUOT The directory in which the entry for the new link is being placed
cannot be extended because the user's quota of disk blocks or inodes
on the file system containing the directory has been exhausted.
EINVAL An invalid combination of open modes (O_RDONLY, O_WRONLY and O_RDWR)
is specified, or the named file is a FIFO and O_RDWR is set.
ELOCK A named pipe already open for read is opened again for read, or
already open for write and is opened again for write.
EOPNOTSUPP
A socket was named, and opens on sockets are not permitted.
If the Transparent Computing Facility is installed on your system, open can
also fail if one or more of the following are true:
ESITEDN1 path cannot be accessed because a site went down.
ESITEDN2 The operation was terminated because a site failed.
Processed November 7, 1990 OPEN(2,L) 6
OPEN(2,L) AIX Technical Reference OPEN(2,L)
ENOSTORE path is a name relative to the working directory, but no site which
stores this directory is currently up.
ENOSTORE A component of path is replicated but not stored on any site which is
currently up.
EROFS Write access is requested for a file on a replicated file system in
which the primary copy is unavailable.
ENLDEV The named file is a non-tty character special file which corresponds
to a device physically attached to another site in the cluster.
EINTR A signal was caught during the system call.
RELATED INFORMATION
In this book: "chmod, fchmod," "close, closex," "dup," "fabort," "fcntl,
flock, lockf," "fsync, fcommit," "lseek," "mknod, mknodx, mkfifo," "open,
openx, creat," "read, readv, readx," "umask," "write, writex," and "stat.h."
Processed November 7, 1990 OPEN(2,L) 7