OPEN(2)

NAME
open - open or create a file for reading or writing

SYNOPSIS
#include <fcntl.h>

int open(const char *path, int flags, ...);

DESCRIPTION
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 created with mode mode as described in chmod(2) and modified by the process' umask value (see umask(2)).

The flags specified are formed by the bitwise OR of the following values:

O_RDONLY
    Open the file for reading only.

O_WRONLY
    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.

O_APPEND
    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.

O_CREAT
    Create file if it does not exist.

O_TRUNC
    If O_TRUNC is specified and the file exists, the file is truncated 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 exclusive 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.

O_BINARY
    Files opened with the Orca/Shell open call by default do newline translation unless the O_BINARY flag is used. This implementation 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.

O_TRANS
    If the O_TRANS flag has been set, then newline translation will occur on all read and write calls on the returned file descriptor: 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 platforms), will not have the character pair collapsed to (expanded from) a single character during reads from (writes to) those files.

O_NONBLOCK
    If the O_NONBLOCK flag is specified and the open call would result in the process being blocked for some reason (e.g., waiting 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).

O_SHLOCK
    Atomically obtain a shared lock. (This feature is not currently implemented under GNO.)

O_EXLOCK
    Atomically obtain an exclusive lock. (This feature is not currently 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 system limit.

COMPATIBILITY
Unlike the GNO implementation, the Orca/C open call takes no optional third parameter.

The mode parameter is normally expected to be in Unix mode format, although this can be changed by the application. See mapMode(3).

BUGS
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 implemented and will be ignored.

SEE ALSO
chmod(2), close(2), dup(2), getdtablesize(2), lseek(2), read(2), write(2), umask(2)

HISTORY
An open function call appeared in Version 6 AT&T UNIX.