ooppeenn() -- System Call (libc)

Open a file
#iinncclluuddee <ffccnnttll.hh>
iinntt ooppeenn(_f_i_l_e, _t_y_p_e[, _m_o_d_e])
cchhaarr *_f_i_l_e; iinntt _t_y_p_e; [iinntt _m_o_d_e;]

ooppeenn() opens  a _f_i_l_e to  receive data, or  to have its data  read.  When it
opens _f_i_l_e,  ooppeenn() returns a  file descriptor, which is  a small, positive
integer  that identifies  the  open _f_i_l_e  for subsequent  calls to  rreeaadd(),
wwrriittee(), cclloossee(), dduupp(), dduupp22(),  or llsseeeekk(). After _f_i_l_e is opened, reading
or writing begins at byte 0.

The second  argument, _t_y_p_e,  determines how  the file is  opened.  It  is a
bitwise OR  of flag bits taken  from the following list  (as defined in the
header file <ffccnnttll.hh>):

     OO_RRDDOONNLLYY  Read only
     OO_WWRROONNLLYY  Write only
     OO_RRDDWWRR    Read and write

One, and only  one, of the above three bit  values must be set in _f_l_a_g. The
following  bit values  can be  used to  deine further how  the file  can be
opened:

     OO_NNDDEELLAAYY  Non-blocking I/O
     OO_AAPPPPEENNDD  Append (writes guaranteed at the file's end)

     OO_SSYYNNCC    Sync on every write
     OO_TTRRAACCEE   For file system debugging (_n_o_n-_s_t_a_n_d_a_r_d)
     OO_NNOONNBBLLOOCCKKNon-blocking I/O

     OO_CCRREEAATT   Open with file create (third argument)
     OO_TTRRUUNNCC   Open with truncation
     OO_EEXXCCLL    Exclusive open
     OO_NNOOCCTTTTYY  Do not assign a controlling tty

The remaining bit values are used to how you wish to manipulate _f_i_l_e:

OO_AAPPPPEENNDD
     Precede every write with an automatic seek to end of _f_i_l_e.

OO_CCRREEAATT
     If _f_i_l_e  does not  exist, create  it.  If this  flag is set  the third
     argument, _m_o_d_e, sets  the mode on the file.  Note  that this mode will
     be masked by uummaasskk(). See the Lexicon article on the command cchhmmoodd for
     details on what the various values of _m_o_d_e mean.

OO_EEXXCCLL
     Exclusive open: this flag is  meaningful only if OO_CCRREEAATT is also used.
     In that  case, ooppeenn()  fails with error  value EEEEXXIISSTT if  _f_i_l_e already
     exists.

OO_NNDDEELLAAYY
     No delay  in writing to disk.  Please note  the following caveats when
     using this flag:

     _I_f _s_e_t:
          Opening a  FIFO with OO_RRDDOONNLLYY  returns without delay.   Opening a
          FIFO with  OO_WWRROONNLLYY returns an  error if no process  has the file
          open for reading.  Opening a file associated with a communication
          line returns without waiting for a carrier signal.

     _I_f _n_o_t _s_e_t:
          Opening a  FIFO with  OO_RRDDOONNLLYY blocks  until a process  opens the
          file for  writing.  Opening a  FIFO with OO_WWRROONNLLYY  blocks until a
          process opens  the file for  reading.  Opening a  file associated
          with  a  communication  line blocks  until  a  carrier signal  is
          present.

OO_NNOOCCTTTTYY
     If _f_i_l_e names  a terminal device, do not set  it to be the controlling
     terminal for the process.

OO_SSYYNNCC
     All  writes to  _f_i_l_e will  be  synchronous to  disk.  This  means that
     wwrriittee() will not return until the data have been physically written to
     disk.

OO_TTRRUUNNCC
     If  _f_i_l_e exists,  truncate it  to  zero length.   You must  have write
     permissions on _f_i_l_e to use this flag.

The third  argument, _m_o_d_e, is  significant only if OO_CCRREEAATT  is specified in
the second argument and if _f_i_l_e did not exist before the call to ooppeenn(). In
that  case, _m_o_d_e  specifies  the access  permissions  of the  new file,  in
exactly the manner  that the system call ccrreeaatt() uses  its _m_o_d_e argument to
set permissions.  The  value of _m_o_d_e is typically given  as either an octal
constant or  bitwise OR of permission-bit values as  defined in header file
<ssyyss/ssttaatt.hh>.

_E_x_a_m_p_l_e
This example copies  the file named in aarrggvv[11] to  the one named in aarrggvv[22]
by  using  system calls.   It  demonstrates ooppeenn()  plus  the system  calls
cclloossee(), rreeaadd(), wwrriittee(), and ccrreeaatt().

#include <stdio.h>
#include <fcntl.h>
#define BUFSIZE (20*512)
char buf[BUFSIZE];

void fatal(s)
char *s;
{
    fprintf(stderr, "copy: %s\n", s);
    exit(1);
}

main(argc, argv)
int argc; char *argv[];
{
    register int ifd, ofd;
    register unsigned int n;

    if (argc != 3)
        fatal("Usage: copy source destination");
    if ((ifd = open(argv[1], O_RDONLY)) == -1)
        fatal("cannot open input file");
    if ((ofd = open(argv[2], O_CREAT | O_RDWR | O_TRUNC, 0666)) == -1)
        fatal("cannot open output file");
    /* For COHERENT 286, use creat() instead of open():
     * if ((ofd = creat(argv[2], 0666)) == -1)
     */

    while ((n = read(ifd, buf, BUFSIZE)) != 0) {
        if (n == -1)
            fatal("read error");
        if (write(ofd, buf, n) != n)
            fatal("write error");
    }

    if (close(ifd) == -1 || close(ofd) == -1)
        fatal("cannot close");
    exit(0);
}

_S_e_e _A_l_s_o
ffooppeenn(), cclloossee(), lliibbcc
ANSI Standard, section 4.9.3
POSIX Standard, section 5.3.1

_D_i_a_g_n_o_s_t_i_c_s
ooppeenn()  returns  -1  if the  file  does  not  exist,  if the  caller  lacks
permission, or if a system resource is exhausted.

_N_o_t_e_s
ooppeenn()  is a  low-level call  that  passes data  directly to  COHERENT.  It
should not  be mixed with  high-level calls, such as  ffrreeaadd(), ffwwrriittee(), or
ffooppeenn().

Code that  uses the third argument  to ooppeenn() cannot be  ported to COHERENT
286.
