open(2)
_________________________________________________________________
open System Call
Open for reading or writing.
_________________________________________________________________
SYNTAX
#include <fcntl.h>
int open (path, open_flag, protection_mode)
char * path;
int open_flag;
int protection_mode;
PARAMETERS
path Address of a pathname.
open_flag Open intent and open behavior flags.
protection_mode
Protection mode, if file is created.
DESCRIPTION
<Path> points to a pathname naming a file to be opened. Terminal
symbolic links are followed in <path>. <Open_flag> is a group of
flags specifying the open intent (read, write, or both) and
requests for optional behavior of the call. It is constructed by
or-ing the desired flags. One and only one of the following
three open intents must be specified in <open_flag>:
* O_RDONLY 0
* O_WRONLY 1
* O_RDWR 2
Ignoring for the moment all flags except the open intents, if the
file exists, the semantics of an open are:
* Ordinary, FIFO, block special, and character special files
may be opened for any of the intents. Directories can only
be opened for O_RDONLY intent.
* If the specified intent is O_RDWR or O_WRONLY and the file's
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
open(2)
type is ordinary or FIFO, the file must reside on a file
system device mounted read-write.
* The lowest numbered available file descriptor is allocated,
and the file pointer is set to the beginning of the file.
* If the file's type is block or character special, a device
driver is called to perform device dependent initialization.
If the file does not exist, and the O_CREAT flag has not been
specified, then the call fails.
The basic semantics of the open call described above may be
modified by setting one or more of the following flags in
<open_flag>:
O_NDELAY This flag has differing semantics depending on the
type of file or or device it is referencing. If
the file is a FIFO and O_NDELAY is set, a reader
of a FIFO file does not pend during the open,
waiting for the presence of a writer. A writer of
such a FIFO file does not pend, either, but the
error ENXIO is asserted if no reader is present.
If the file is a FIFO and O_NDELAY is not set,
then a reader of the file will pend waiting for a
writer of the file to open the FIFO, and likewise,
a writer will pend waiting for a reader to open
the FIFO.
A process opening the FIFO for both read and write
is not affected by this flag.
If the file is associated with a communications
device, and O_NDELAY is set, then an opener for
any intent will not wait for a carrier to be
present on the line before returning from the open
call.
If the file is associated with a communications
device, and O_NDELAY is not set, then an open will
pend waiting for a carrier to be present on the
line.
This flag is "remembered" in the object pointer's
flags and affects subsequent reads and writes.
(See read and write.)
O_CREAT If set, the O_CREAT flag guarantees that the file
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
open(2)
exists after the open call is completed. If it is
set and the file already exists, the open occurs
as described above. If the file does not exist,
an ordinary file with the name <path> is created
and then the file is opened for the intent
requested. The file must be on a file system
device mounted read-write. It is created in the
manner of the creat system call:
in()
* The file is entered into the flat file store by allocating
and initializing a per-file database. The file's attributes
are set as follows:
* The inode number (st_ino) refers to the per-file database
allocated.
* The file's device (st_dev) is set to the device code of the
logical disk unit that contains the new file.
* The represented device (st_rdev) is undefined.
* The file size (st_size) is 0.
* The number of links (st_nlink) is set to one.
* The user id (st_uid) is set to the effective user id of the
calling process. The group id (st_gid) is set to the
process's effective group id.
* The file mode (st_mode) is set as follows: The file type is
ordinary. The sticky bit is cleared. The protection
rights, set-user-id, and set-group-id bits of the file mode
are set to the value of <protection_mode> modified by the
process's file mode creation mask; all bits set in the mask
are cleared in the file mode (see umask). The set-group-id
bit is set only if the file's group id is the same as the
process's effective group id or is in the process's group
set.
* The time last accessed (st_atime), time last modified
(st_mtime), and time of last attribute change (st_ctime) are
set to the current time.
* <Path> is added to the filename store (i.e., a link is
created in the containing directory) and is made to identify
the newly created file. An allocation to the directory
causes its attributes to change as follows:
* The file size (st_size) is updated.
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)
open(2)
* The time last modified (st_mtime) and time of last attribute
change (st_ctime) are set to the current time.
O_EXCL The O_EXCL flag modifies the O_CREAT flag and has
no effect if O_CREAT is clear or the file does not
exist. If O_CREAT and O_EXCL are set, the open
will fail if the file already exists. The O_EXCL
flag also interacts with symbolic links in the
following way. If O_EXCL is on (with O_CREAT),
and the last component of the path is a symlink,
then the open will fail even if the symlink points
to a non-existent file.
O_TRUNC This flag implies that you are opening the file
for write intent, even though the user may have
specified a read-only channel to be opened. Thus,
a channel created with this flag on is always open
for write intent.
O_TRUNC has no effect if the file does not exist. File
specific ramifications of this flag are:
* Directories cannot be truncated. You can never
gain a write-accessable channel to a directory, so
you can never truncate them through this
interface.
* Ordinary and FIFO files being truncated must
reside on a file system device mounted read-write.
* If the file's type is ordinary, the file's disk
blocks are freed and its size (st_size) is set to
zero.
* The file's time last modified (st_mtime) and time
of last change to the attributes (st_ctime) are
set to the current time. (This happens whether
the file's contents were not changed or not.)
* All other file attributes remain unchanged.
O_APPEND The O_APPEND flag has no visible effect on the
operation of the open call. If set, it is
"remembered" as part of the file's open intents
and will affect subsequent writes by positioning
the file pointer to the end of the file prior to
each write.
DG/UX 4.00 Page 4
Licensed material--property of copyright holder(s)
open(2)
O_SYNC The O_SYNC flag has no visible effect on the
operation of the open call. If set, it is
"remembered" as part of the file's open intents
and will affect subsequent writes by forcing all
changes to the file to disk before returning from
the write call. File changes include changes to
any data buffers and inode information.
O_NONBLOCK This flag has differing semantics depending on the
type of file or device it is referencing.
If the file is a FIFO and O_NONBLOCK is set, a reader of a FIFO
file does not pend during the open, waiting for the presence of a
writer. A writer of such a FIFO file does not pend, either, but
the error ENXIO is asserted if no reader is present.
If the file is a FIFO and O_NONBLOCK is not set, then a reader of
the file will pend waiting for a writer of the file to open the
FIFO, and likewise, a writer will pend waiting for a reader to
open the FIFO.
A process opening the FIFO for both read and write is not
affected by this flag.
If the file is a block or character special file and O_NONBLOCK
is set, then an opener for any intent will not wait for a device
to be ready or available before returning from the open call.
Subsequent behavior of the device is device specific.
If the file is a block or character special file and O_NONBLOCK
is not set, then an open will pend waiting for the device to be
ready or available.
Bits in <open_flag> other than those flags mentioned above are
undefined and should not be used.
The <mode> parameter is used only when the file is created, i.e.,
when O_CREAT is set and the file does not already exist. In
other cases, it is ignored.
Note that creat(path, mode) has the same semantics as
open(path,O_WRONLY|O_CREAT|O_TRUNC,mode) -- If the file exists,
it is truncated; if it does not exist, it is created; in both
cases it is opened for writing.
If the process exceeds its limit on open files, the open call
will fail, and the file will be left in the state it was in
before the call.
Upon successful completion, the descriptor is returned. The
DG/UX 4.00 Page 5
Licensed material--property of copyright holder(s)
open(2)
descriptor is set to remain open across exec calls. See fcntl(2).
ACCESS CONTROL
To open an existing file, the calling process must have read
and/or write access (as requested) to the file.
To create a file, the process must have write access to the
containing directory.
To truncate an existing file, the process must have write access
to the file.
The process must have permission to resolve <path>.
RETURN VALUE
0..<NOFILE-1> The file descriptor for the successfully opened
file. (See the file param.h.)
-1 An error occurred. Errno is set to indicate the
error.
EXCEPTIONS
Errno may be set to one of the following error codes:
EACCES The open intents specified in <open_flag> are
denied for the named file or if in creating the
file, the target containing directory disallows
access.
EINVAL Invalid argument passed to this function.
EEXIST O_CREAT and O_EXCL are set, and the named file
exists, or is pointed at by a symbolic link.
EINTR A signal was caught during the open system call.
EISDIR The named file is a directory and the open intent
is write or read/write.
DG/UX 4.00 Page 6
Licensed material--property of copyright holder(s)
open(2)
EMFILE NOFILE file descriptors are currently open.
ENOENT O_CREAT is clear and the named file does not
exist.
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 or O_NONBLOCK is set, the named file is a
FIFO file, O_WRONLY is set, and no process has the
file open for reading.
EOPNOTSUPP An attempt was made to open a socket.
EROFS The named file resides on a file system device
mounted read-only and the open intent is write or
read/write.
ETXTBSY The file is a pure procedure (shared text) file
that is being executed and the open intent is
write or read/write.
ENOSPC No more contiguous space to create a file entry or
inode.
EAGAIN File exists with record locks in mandatory
enforcement mode and O_CREAT and/or O_TRUNC is
specified.
ENOENT The file the pathname resolved to does not exist
and O_CREAT was not specified.
ENOENT A non-terminal component of the pathname does not
exist.
ENOTDIR A non-terminal component of the pathname was not a
directory or symbolic link.
DG/UX 4.00 Page 7
Licensed material--property of copyright holder(s)
open(2)
ENAMETOOLONG The pathname exceeds the length limit for
pathnames.
ENAMETOOLONG A component of the pathname exceeds the length
limit for filenames.
ENOMEM There are not enough system resources to resolve
the pathname or to expand a symbolic link.
ELOOP The number of symbolic links encountered during
pathname resolution exceeded MAXSYMLINKS. A
symbolic link cycle is suspected.
EPERM The pathname contains a character not in the
allowed character set.
EFAULT The pathname does not completely reside in the
process's address space or the pathname does not
terminate in the process's address space.
SEE ALSO
The related manual sections: chmod(2), close(2), creat(2),
dup(2), fcntl(2), lseek(2), read(2), umask(2), write(2),
fcntl(5), stat(5).
DG/UX 4.00 Page 8
Licensed material--property of copyright holder(s)