open(2) DG/UX 5.4R3.00 open(2)
NAME
open - open file for reading or writing
SYNOPSIS
#include <fcntl.h>
int open (path, openflag, protectionmode)
char * path;
int openflag;
int protectionmode;
where:
path Address of a pathname
openflag Open intent and open behavior flags
protectionmode 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. openflag 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 openflag:
⊕ 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
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 openflag:
Licensed material--property of copyright holder(s) 1
open(2) DG/UX 5.4R3.00 open(2)
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(2) and
write(2).
O_CREAT If set, the O_CREAT flag guarantees that the file 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:
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 virtual disk unit that contains the new
file.
⊕ The represented device (st_rdev) is undefined.
⊕ The file size (st_size) is set to 0.
⊕ The number of links (st_nlink) is set to one.
Licensed material--property of copyright holder(s) 2
open(2) DG/UX 5.4R3.00 open(2)
⊕ 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
protectionmode 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) may be updated.
⊕ 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-accessible 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.
Licensed material--property of copyright holder(s) 3
open(2) DG/UX 5.4R3.00 open(2)
⊕ 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 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.
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.
O_DG_UNBUFFERED
Normally, the default behavior for acquiring data from an
ordinary file is to use the system buffer cache to cache
Licensed material--property of copyright holder(s) 4
open(2) DG/UX 5.4R3.00 open(2)
requests for the data from the file and then to copy data
from the system buffer into the user's buffer. The
presence of this flag will change the default behavior and
access method for acquiring data from the file.
Specifically, read(2) and write(2) will not operate, but
the system calls, dgunbufferedread(2) and
dgunbufferedwrite(2) will work. dgunbufferedread(2)
and dgunbufferedwrite(2) transfers blocks of file data
from the disk directly to or from the user's buffer in a
synchronous manner. Upon successful opening of the file
with this flag, the buffer cache for the file will have
been flushed to disk and invalidated. Any attempts to use
read(2) or write(2) on the descriptor will return an
error. Descriptors returned with this flag differ in no
other way from other descriptors returned without this
flag being set. This call will fail if there are other
descriptors for the file that were opened without this
flag set. Also, open calls without this flag will fail if
there are descriptors to the file that have the flag set.
This flag cannot be set or unset via the fcntl(2)
interface.
O_DG_SHARED_DESCRIPTOR
By default, descriptors are part of the per-process data
of the process that creates them. The use of this flag in
the open call will change this behavior. If set, the
descriptor created by the open will exist in the shared
descriptor table for the process and be accessible to all
processes that have attached the shared descriptor array
via dgattachtoshareddescriptors(2). Descriptors in
this shared table have different reference count semantics
from normal descriptors. See the manual page for
dgattachtoshareddescriptors(2) for details.
Bits in openflag 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,OWRONLY|OCREAT|OTRUNC,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. The limit on per-process descriptors is bounded above by the
soft limit on per-process descriptors for the process. A process may
raise this soft limit by calling setrlimit(2). The current soft
limit may be found by calling getrlimit(2). The soft limit may only
be raised until the system wide hard limit is reached.
Licensed material--property of copyright holder(s) 5
open(2) DG/UX 5.4R3.00 open(2)
Upon successful completion, the descriptor is returned. The
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
Any non-negative integer
The file descriptor for the successfully opened file.
-1 An error occurred. errno is set to indicate the
error.
DIAGNOSTICS
Errno may be set to one of the following error codes:
EACCES The open intents specified in openflag 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.
EMFILE NOFILE file descriptors are currently open. You have
reached the soft limit on file descriptors. If you
wish to open another file, then you must increase the
number of available descriptors with the getrlimit(2)
and setrlimit(2) system calls.
ENOENT O_CREAT is clear and the named file does not exist; or
the file the pathname resolved to does not exist and
O_CREAT was not specified; or a non-terminal component
of the pathname 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; or O_NDELAY or O_NONBLOCK is set, the
named file is a FIFO file, O_WRONLY is set, and no
Licensed material--property of copyright holder(s) 6
open(2) DG/UX 5.4R3.00 open(2)
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.
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.
ENOTDIR A non-terminal component of the pathname was not a
directory or symbolic link.
ENAMETOOLONG The pathname exceeds the length limit for pathnames;
or 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.
ENOSR The path is STREAMS-based and the system is unable to
allocate a stream.
EIO if during the open() of a STREAMS-based device, a
hangup or error occurs.
SEE ALSO
chmod(2), close(2), creat(2), dgallowshareddescriptorattach(2),
dgattachtoshareddescriptors(2). dup(2), fcntl(2), getrlimit(2),
lseek(2), read(2), setrlimit(2), umask(2), write(2), fcntl(5),
stat(5),
Licensed material--property of copyright holder(s) 7