.\" 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 .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.