open(2) DG/UX 4.30 open(2)
NAME
open - open for reading or writing
SYNOPSIS
#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 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.
Licensed material--property of copyright holder(s) Page 1
open(2) DG/UX 4.30 open(2)
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 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:
Licensed material--property of copyright holder(s) Page 2
open(2) DG/UX 4.30 open(2)
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 set to 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) may be updated.
* The time last modified (st_mtime) and time of
last attribute change (st_ctime) are set to
the current time.
Licensed material--property of copyright holder(s) Page 3
open(2) DG/UX 4.30 open(2)
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 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
Licensed material--property of copyright holder(s) Page 4
open(2) DG/UX 4.30 open(2)
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 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, dg_unbuffered_read(2) and
dg_unbuffered_write(2) will work.
Dg_unbuffered_read(2) and
Licensed material--property of copyright holder(s) Page 5
open(2) DG/UX 4.30 open(2)
dg_unbuffered_write(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.
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. 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.
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
Licensed material--property of copyright holder(s) Page 6
open(2) DG/UX 4.30 open(2)
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.
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.
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 getrusage(2)
and setrusage(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
process has the file open for reading.
Licensed material--property of copyright holder(s) Page 7
open(2) DG/UX 4.30 open(2)
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.
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.
SEE ALSO
chmod(2), close(2), creat(2), dup(2), fcntl(2), lseek(2),
read(2), umask(2), write(2), fcntl(5), stat(5).
Licensed material--property of copyright holder(s) Page 8