OPEN(2) System Calls OPEN(2)
open - open or create a file for reading or writing
int open(const char *path, int flags, ...);
The file name specified by path is opened for reading and/or writing as
specified by the argument flags. A third parameter, mode, (of type
mode_t) must be specified if and only if the O_CREAT flag is set. The
O_CREAT flag indicates that if the file doesn't exist it is to be cre-
ated with mode mode as described in chmod(2) and modified by the pro-
cess' umask value (see umask(2)).
The flags specified are formed by the bitwise OR of the following val-
Open the file for reading only.
Open the file for writing only. An attempt to open a volume
directory or subdirectory will fail.
O_RDWR Open the file for reading and writing. An attempt to open a
volume directory or subdirectory will fail.
Opening a file with O_APPEND set causes the file pointer to be
moved to the current end of file; each write on the file will be
appended to the end.
Create file if it does not exist.
If O_TRUNC is specified and the file exists, the file is trun-
cated to zero length.
O_EXCL If O_EXCL is set with O_CREAT and the file already exists, open
returns an error. This may be used to implement a simple exclu-
sive access locking mechanism. If O_EXCL is set and the last
component of the pathname is a symbolic link, open will fail
even if the symbolic link points to a non-existent name.
Files opened with the ORCA/Shell open call by default do newline
translation unless the O_BINARY flag is used. This implementa-
tion does no newline translation by default (see O_TRANS,
below). The O_BINARY flag is ignored except that if it is set,
the GS/OS file type of any newly created file will be set to BIN
rather than TXT.
The O_BINARY flag is non-standard.
If the O_TRANS flag has been set, then newline translation will
occur on all read and write calls on the returned file descrip-
tor: During write calls, any LF (linefeed) character will be
translated to a CR (carridge return). During read calls, the
opposite translation occurs. This is similar to, but opposite
of, the O_BINARY flag interpretation under the ORCA/Shell.
The O_TRANS flag is non-standard and has been included only to
assist in the porting of problem Unix programs. Note that files
which use the CR-LF pair (as is commonly found on MS-DOS plat-
forms), will not have the character pair collapsed to (expanded
from) a single character during reads from (writes to) those
If the O_NONBLOCK flag is specified and the open call would
result in the process being blocked for some reason (e.g., wait-
ing for carrier on a dialup line), open returns immediately.
The first time the process attempts to perform I/O on the open
file it will block. (This feature is not currently implemented).
Atomically obtain a shared lock. (This feature is not currently
implemented under GNO.)
Atomically obtain an exclusive lock. (This feature is not cur-
rently implemented under GNO.)
When opening a file, a lock with flock(2) semantics can be obtained by
setting O_SHLOCK for a shared lock, or O_EXLOCK for an exclusive lock.
If creating a file with O_CREAT, the request for the lock will never
fail (provided that the underlying filesystem supports locking).
If successful, open returns a non-negative integer, termed a file
descriptor. It returns -1 and sets errno on failure. Unless O_APPEND
was specified, the file pointer used to mark the current position
within the file is set to the beginning of the file.
The new descriptor is set to remain open across execve system calls;
see close(2) and fcntl(2).
The system imposes a limit on the number of file descriptors open
simultaneously by one process. getdtablesize(2) returns the current
Unlike the GNO implementation, the ORCA/C open call takes no optional
The mode parameter is normally expected to be in Unix mode format,
although this can be changed by the application. See mapMode(3).
Because umask(2) is not yet implemented in the GNO kernel, it has no
effect on the fopen(3) or GS/OS OpenGS calls. Consequently, the umask
is not used in open(2), either.
Due to the way the stack is maintained under ORCA/C, it is an error to
provide the mode parameter if the O_CREAT flag is not set. Similarily,
it is an error to omit mode if O_CREATE is set. Depending on how the
calling routine was compiled, this error will either manifest itself as
a failed ORCA/C runtime stack check, or as a crash of the machine.
The flags O_NONBLOCK, O_SHLOCK, and O_EXLOCK are not currently imple-
mented and will be ignored.
chmod(2), close(2), dup(2), getdtablesize(2), lseek(2), read(2),
An open function call appeared in Version 6 AT&T UNIX.
GNO 22 January 1997 OPEN(2)
Man(1) output converted with