OPEN(2)                          System Calls                          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  cre‐
       ated  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  val‐
       ues:

       O_RDONLY
              Open the file for reading only.

       O_WRONLY
              Open the file for writing only.  An attempt to open a volume di‐
              rectory 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 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.

       O_BINARY
              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,  be‐
              low).   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  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
              files.

       O_NONBLOCK
              If  the O_NONBLOCK flag is specified and the open call would re‐
              sult 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  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  de‐
       scriptor.   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  si‐
       multaneously by one process.  getdtablesize(2) returns the current sys‐
       tem 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, al‐
       though 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  imple‐
       mented 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.



GNO                             22 January 1997                        OPEN(2)