OPEN(2-POSIX) RISC/os Reference Manual OPEN(2-POSIX)
NAME
open - open for reading or writing
SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open (path, oflag [, mode] )
char *path;
int oflag;
modet mode;
DESCRIPTION
path points to a path name naming a file. open opens a file
descriptor for the named file and sets the file status flags
according to the value of oflag.
open returns a file descriptor for the named file that is
the lowest file descriptor not currently open for that pro-
cess. The open file description is new, and therefore the
file descriptor does not share it with any other process in
the system. The file offset is set to the beginning of the
file. The file status flags and file access modes of the
open file description are set according to the value of
oflag. For non-STREAMS (see intro(2)) files, the value of
oflag is the bitwise inclusive OR of the values from the
following list. Exactly one of the first three values (file
access modes) below must be specified in oflag.
ORDONLY Open for reading only.
OWRONLY Open for writing only.
ORDWR Open for reading and writing.
Any combination of the remaining flags may be specified in
the value of oflag.
ONONBLOCK This flag may affect subsequent reads and
writes [see read(2) and write(2)].
When opening a FIFO with O_RDONLY or O_WRONLY
set:
If O_NONBLOCK is set:
An open for reading-only will return
without delay. An open for writing-only
will return an error if no process
currently has the file open for reading.
Printed 1/15/91 Page 1
OPEN(2-POSIX) RISC/os Reference Manual OPEN(2-POSIX)
If O_NONBLOCK is clear:
An open for reading-only will block
until a process opens the file for writ-
ing. An open for writing-only will
block until a process opens the file for
reading.
When opening a file associated with a block
special or character special file that sup-
ports the nonblocking option:
If O_NONBLOCK is set:
The open will return without waiting for
the device to become ready or available.
Subsequent behavior of the device is
device-specific.
If O_NONBLOCK is clear:
The open will block until the device is
ready or available.
OAPPEND If set, the file offset will be set to the
end of the file prior to each write.
OSYNC When opening a regular file, this flag
affects subsequent writes. If set, each
write(2) will wait for both the file data and
file status to be physically updated.
OCREAT If the file exists, this flag has no effect.
Otherwise, 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 or to the group ID of
the directory in which the file is being
created, depending on the setting of
_riscos_group_parent (see kopt(8)), and the
low-order 12 bits of the file mode are set to
the value of mode modified as follows [see
creat(2)]:
All bits set in the file mode creation
mask of the process are cleared [see
umask(2)].
The ``save text image after execution
bit'' of the mode is cleared [see
chmod(2)].
Page 2 Printed 1/15/91
OPEN(2-POSIX) RISC/os Reference Manual OPEN(2-POSIX)
OTRUNC If the file exists, and is a regular file,
and the file is successfully open O_RDWR or
O_WRONLY, its length is truncated to 0 and
the mode and owner are unchanged. O_TRUNC
has no effect on file types other than regu-
lar files and directories. An error is gen-
erated if the file is a directory.
OEXCL If O_EXCL and O_CREAT are set, open will fail
if the file exists. O_EXCL has no meaning
without O_CREAT. If O_EXCL is specified
without O_CREAT and the file already exists,
it is opened but others can also open the
file; if O_EXCL is specified without O_CREAT
and the file does not already exist, -1 is
returned and errno is set to ENOENT.
ONOCTTY If path indicates a terminal device, the
opened device will not become the controlling
terminal for the process.
When opening a STREAMS file, oflag may be constructed from
O_NONBLOCK or-ed 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_NONBLOCK affects the
operation of STREAMS drivers and certain system calls [see
read(2), getmsg(2), putmsg(2) and write(2)]. For drivers,
the implementation of 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 fcntl(2).
The file pointer used to mark 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
system calls [see fcntl(2)].
If O_CREAT is set and the file did not previously exist,
upon successful completion, open marks for update the
st_atime, st_ctime, and st_mtime, fields of the file and the
st_ctime and st_mtime fields of the parent directory.
If O_TRUNC is set and the file existed previously, upon suc-
cessful completion, open marks for update the st_ctime and
st_mtime fields of the file.
The named file is opened unless one or more of the following
are true. If any of the following conditions occur, open
returns -1 and errno is set to the corresponding value:
Printed 1/15/91 Page 3
OPEN(2-POSIX) RISC/os Reference Manual OPEN(2-POSIX)
[EACCES] A component of the path prefix denies
search permission, or the file exists
and the permissions specified by oflag
are denied for the named file, or the
file does not exist and write permission
is denied for the directory in which the
file is to be created, or O_TRUNC is
specified and write permission is
denied.
[EAGAIN] The file exists, mandatory file/record
locking is set, and there are outstand-
ing record locks on the file [see chmod
(2)].
[EEXIST] O_CREAT and O_EXCL are set, and the
named file exists.
[EFAULT] Path points outside the allocated
address space of the process.
[EINTR] A signal was caught during the open sys-
tem call.
[EIO] A hangup or error occurred during a
STREAMS open.
[EISDIR] The named file is a directory and oflag
specifies write or read/write access.
This includes attempting to truncate a
directory with O_TRUNC.
[EMFILE] Too many file descriptors are currently
open.
[ENFILE] The system file table is full.
[ENOENT] O_CREAT is not set and the named file
does not exist or O_CREAT is set and
either the path prefix does not exist,
or path specifies an empty string.
[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] Unable to allocate a stream.
[ENOTDIR] A component of the path prefix is not a
directory.
Page 4 Printed 1/15/91
OPEN(2-POSIX) RISC/os Reference Manual OPEN(2-POSIX)
[ENXIO] The named file is a character special or
block special file, and the device asso-
ciated with this special file does not
exist, or O_NONBLOCK is set, the named
file is a FIFO, O_WRONLY is set, and no
process has the file open for reading,
or a STREAMS module or driver open rou-
tine failed.
[ENAMETOOLONG] The length of path exceeds {PATH_MAX},
or a pathname component is longer than
{NAME_MAX} while {_POSIX_NO_TRUNC} is in
effect.
[EROFS] The named file resides on a read-only
file system and oflag is write or
read/write.
[ETXTBSY] The file is a pure procedure (shared
text) file that is being executed and
oflag is write or read/write.
SEE ALSO
chmod(2), close(2), creat(2), dup(2), exec(2), fcntl(2),
intro(2), lseek(2), read(2), getmsg(2), putmsg(2), stat(2),
umask(2), write(2).
DIAGNOSTICS
Upon successful completion, the file descriptor is returned.
Otherwise, a value of -1 is returned and errno is set to
indicate the error.
Printed 1/15/91 Page 5