open(2) CLIX open(2)
NAME
open - Opens a file for reading or writing
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
int open(
char *path ,
int oflag ,
int mode );
PARAMETERS
path Points to a pathname naming the file to be opened.
oflag Specifies the type of access, the type of update, and the initial
state of the open file. The oflag value is constructed by a
logical OR of special open flags. These flags are defined in the
<fcntl.h> header file and are described below. (Note that exactly
one of the file access values must be specified. 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_CREAT If the file exists, this flag has no effect, except as
noted under O_EXCL. 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 effective
group ID of the process.
⊕ The low-order 12 bits of the file mode are set to
the value of mode defined as follows: (See the
2/94 - Intergraph Corporation 1
open(2) CLIX open(2)
creat() function.)
-- All bits set in the file mode creation mask of
the process are cleared. (See the umask()
function.)
-- The ``save text image after execution bit'' of
the mode is cleared. (See the chmod()
function.)
O_EXCL If O_EXCL and O_CREAT are set, open() fails if the
file exists.
O_TRUNC If the file exists, its length is truncated to 0 and
the mode and owner are unchanged.
O_SYNC When opening a regular file, this flag affects
subsequent writes. If set, each write() call waits
for both the file data and file status to be
physically updated.
O_APPEND If set, the file pointer is set to the end of the file
prior to each write.
O_NONBLOCK See the description of O_NDELAY below.
O_NDELAY This flag may affect subsequent reads and writes.
(See the read() and write() functions.)
When opening a FIFO with O_RDONLY or O_WRONLY set:
⊕ If O_NDELAY is set:
-- An open() call for reading only will return without delay.
-- An open() call for writing only will return an error if no
process currently has the file open for reading.
⊕ If O_NDELAY is clear:
-- An open() call for reading-only will block until a process
opens the file for writing.
-- An open() call for writing-only will block until a process
opens the file for reading.
When opening a file associated with a communication line:
⊕ If O_NDELAY is set, open() will return without waiting for
carrier.
2 Intergraph Corporation - 2/94
open(2) CLIX open(2)
⊕ If O_NDELAY is clear, open() will block until carrier is
present.
mode Specifies the file permission bits (see the <sys/stat.h> file) of
the file to be created except those set in the process file mode
creation mask. (See the umask() function.) The mode parameter
does not affect whether the file is opened for reading, for
writing, or for both. If the file already exists, this parameter
is ignored.
DESCRIPTION
The open() function establishes a connection between the file named by the
path parameter and a file descriptor. The opened file descriptor is used
by subsequent I/O functions, such as read() and write(), to access that
file.
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() functions.
When opening a STREAMS file, oflag may be constructed from a logical OR of
O_NDELAY (O_NONBLOCK) 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 of O_NDELAY (O_NONBLOCK) affects the operation of STREAMS
drivers and certain functions. (See the read(), getmsg(), putmsg(), and
write() functions.) For drivers, the implementation of O_NDELAY
(O_NONBLOCK) is device-specific. Each STREAMS device driver may treat
this option differently.
Certain flag values can be set following open() as described in the
fcntl() function.
EXAMPLES
1. To open an existing file for reading only:
if (open(filename, O_RDONLY) == -1)
perror("open failed");
2. To open a file for reading and writing, creating the file if it does
not exist:
if (open(filename, O_RDWR | O_CREAT, 0666) == -1)
perror("open failed");
RETURN VALUES
2/94 - Intergraph Corporation 3
open(2) CLIX open(2)
Upon successful completion the file descriptor, a non-negative integer, is
returned. Otherwise, a value of -1 is returned and the global variable
errno is set to indicate the error.
ERRORS
The open() function fails and the named file is not opened if one or more
of the following are true:
[EACCES]
A component of the path prefix denies search permission.
[EACCES]
The named file is denied oflag permission.
[EAGAIN]
The file exists, mandatory file/record locking is set, and there
are outstanding record locks on the file. (See the chmod()
function.)
[EEXIST]
O_CREAT and O_EXCL are set, and the named file exists.
[EFAULT]
The path parameter points outside the allocated address space of
the process.
[EINTR]
A signal was caught during open().
[EIO] A hangup or error occurred during a STREAMS open() call.
[EISDIR]
The named file is a directory and oflag is write or read/write.
[EMFILE]
NOFILES file descriptors are currently open.
[ENAMETOOLONG]
The length of the path string exceeds PATH_MAX, or a pathname
component is longer that NAME_MAX while _POSIX_NO_TRUNC is in
effect.
[EMULTIHOP]
Components of path require hopping to multiple remote machines.
[ENFILE]
The system file table is full.
[ENOENT]
O_CREAT is not set and the named file does not exist.
4 Intergraph Corporation - 2/94
open(2) CLIX open(2)
[ENOLINK]
The path parameter points to a remote machine, and the link to that
machine is no longer active.
[ENOMEM]
The system is unable to allocate a send descriptor.
[ENOSPC]
O_CREAT and O_EXCL are set, and the file system is out of inodes.
[ENOSR]
The system is unable to allocate a stream.
[ENOTDIR]
A component of the path prefix is not a directory.
[ENXIO]
The named file is a character special or block special file, and
the device associated with this special file does not exist.
[ENXIO]
O_NDELAY is set, the named file is a FIFO, O_WRONLY is set, and no
process has the file open for reading.
[ENXIO]
A STREAMS module or driver open routine failed.
[EROFS]
The named file resides on a read-only file system and the oflag
parameter is write or read/write.
[ETXTBSY]
The file is a pure procedure (shared text) file that is being
executed and oflag parameter is write or read/write.
RELATED INFORMATION
Functions: chmod(2), close(2), creat(2), dup(2), fcntl(2), intro(2),
lseek(2), read(2), getmsg(2), putmsg(2), umask(2), write(2)
2/94 - Intergraph Corporation 5