gno/usr.man/man2/open.2

.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)open.2	8.2 (Berkeley) 11/16/93
.\"
.TH OPEN 2 "22 January 1997" GNO "System Calls"
.SH NAME
.BR open
\- open or create a file for reading or writing
.SH SYNOPSIS
#include <fcntl.h>
.sp 1
int
\fBopen\fR(const char *\fIpath\fR, int \fIflags\fR, ...);
.SH DESCRIPTION
The file name specified by
.I path
is opened
for reading and/or writing as specified by the
argument
.IR flags .
A third parameter,
.IR mode ,
(of type mode_t) must be specified if and only if the
.BR O_CREAT
flag is set.  The 
.BR O_CREAT
flag indicates that if the file doesn't exist it is to be created with mode
.I mode
as described in
.BR chmod (2)
and modified by the process' umask value (see
.BR umask (2)).
.LP
The flags specified are formed by the bitwise 
.IR OR
of the following values:
.IP \fBO_RDONLY\fR
Open the file for reading only.
.IP \fBO_WRONLY\fR
Open the file for writing only.
An attempt to open a volume directory or subdirectory will fail.
.IP \fBO_RDWR\fR
Open the file for reading and writing.
An attempt to open a volume directory or subdirectory will fail.
.IP \fBO_APPEND\fR
Opening a file with
.BR 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.
.IP \fBO_CREAT\fR
Create file if it does not exist.
.IP \fBO_TRUNC\fR
If
.BR O_TRUNC
is specified and the
file exists, the file is truncated to zero length.
.IP \fBO_EXCL\fR
If
.BR O_EXCL
is set with
.BR O_CREAT
and the file already
exists,
.BR open 
returns an error.  This may be used to
implement a simple exclusive access locking mechanism.
If
.BR O_EXCL
is set and the last component of the pathname is
a symbolic link,
.BR open 
will fail even if the symbolic
link points to a non-existent name.
.IP \fBO_BINARY\fR
Files opened with the Orca/Shell
.BR open
call by default do newline translation unless the
.BR O_BINARY
flag is used.  This implementation does no newline translation by
default (see
.BR O_TRANS ,
below).  The
.BR 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.
.sp 1
The
.BR O_BINARY
flag is non-standard.
.IP \fBO_TRANS\fR
If the 
.BR O_TRANS
flag has been set, then newline translation will occur on all 
.BR read
and
.BR write
calls on the returned file descriptor:  During 
.BR write
calls, any LF (linefeed) character will be translated to 
a CR (carridge return).  During
.BR read
calls, the opposite translation occurs.
This is similar to, but opposite of, the 
.BR O_BINARY
flag interpretation under the Orca/Shell.
.sp 1
The
.BR 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), 
.I "will not"
have the character pair collapsed to (expanded from) a single character
during reads from (writes to) those files.
.IP \fBO_NONBLOCK\fR
If the
.BR O_NONBLOCK
flag is specified and the
.BR open 
call would result
in the process being blocked for some reason (e.g., waiting for
carrier on a dialup line),
.BR 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).
.IP \fBO_SHLOCK\fR
Atomically obtain a shared lock.
(This feature is not currently implemented under GNO.)
.IP \fBO_EXLOCK\fR
Atomically obtain an exclusive lock.
(This feature is not currently implemented under GNO.)
.LP
When opening a file, a lock with
.BR flock (2)
semantics can be obtained by setting
.BR O_SHLOCK
for a shared lock, or
.BR O_EXLOCK
for an exclusive lock.
If creating a file with
.BR O_CREAT ,
the request for the lock will never fail
(provided that the underlying filesystem supports locking).
.LP
If successful,
.BR open 
returns a non-negative integer, termed a file descriptor.
It returns -1 and sets 
.BR errno
on failure.
Unless
.BR O_APPEND 
was specified, the file pointer used to mark the current position within the
file is set to the beginning of the file.
.LP
The new descriptor is set to remain open across
.BR execve 
system calls; see
.BR close (2)
and
.BR fcntl (2).
.LP
The system imposes a limit on the number of file descriptors
open simultaneously by one process.
.BR getdtablesize (2)
returns the current system limit.
.SH COMPATIBILITY
Unlike the GNO implementation, the Orca/C
.BR open
call takes no optional third parameter.
.LP
The 
.IR mode
parameter is normally expected to be in Unix mode format, although
this can be changed by the application.  See 
.BR mapMode (3).
.SH BUGS
Because 
.BR umask (2)
is not yet implemented in the GNO kernel, it has no effect on the
.BR fopen (3)
or GS/OS
.BR OpenGS
calls.  Consequently, the umask is not used in
.BR open (2),
either.
.LP
Due to the way the stack is maintained under Orca/C, it is an error to
provide the
.IR mode
parameter if the
.BR O_CREAT
flag is not set.  Similarily, it is an error to omit
.IR mode
if 
.BR 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.
.LP
The flags
.BR O_NONBLOCK ,
.BR O_SHLOCK ,
and
.BR O_EXLOCK 
are not currently implemented and will be ignored.
.SH SEE ALSO
.BR chmod (2),
.BR close (2),
.BR dup (2),
.BR getdtablesize (2),
.BR lseek (2),
.BR read (2),
.BR write (2),
.BR umask (2)
.SH HISTORY
An
.BR open
function call appeared in Version 6 AT&T UNIX.