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 pro-
       cess' 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
              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 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,
              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  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
              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).

       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
       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 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)

Man(1) output converted with man2html