open() -- System Call (libc)

Open a file
#include <fcntl.h>
int open(file, type[, mode])
char *file; int type; [int mode;]

open() opens  a file to  receive data, or  to have its data  read.  When it
opens file,  open() returns a  file descriptor, which is  a small, positive
integer  that identifies  the  open file  for subsequent  calls to  read(),
write(), close(), dup(), dup2(),  or lseek(). After file is opened, reading
or writing begins at byte 0.

The second  argument, type,  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 <fcntl.h>):

     O_RDONLY  Read only
     O_WRONLY  Write only
     O_RDWR    Read and write

One, and only  one, of the above three bit  values must be set in flag. The
following bit  values can be used  to describe further how  the file can be
opened:

     O_NDELAY  Non-blocking I/O
     O_APPEND  Append (writes guaranteed at the file's end)

     O_SYNC    Sync on every write
     O_TRACE   For file system debugging (non-standard)
     O_NONBLOCKNon-blocking I/O

     O_CREAT   Open with file create (third argument)
     O_TRUNC   Open with truncation
     O_EXCL    Exclusive open
     O_NOCTTY  Do not assign a controlling tty

The remaining bit values are used to how you wish to manipulate file:

O_APPEND
     Precede every write with an automatic seek to end of file.

O_CREAT
     If file  does not  exist, create  it.  If this  flag is set  the third
     argument, mode, sets  the mode on the file.  Note  that this mode will
     be masked by umask(). See the Lexicon article on the command chmod for
     details on what the various values of mode mean.

O_EXCL
     Exclusive open: this flag is  meaningful only if O_CREAT is also used.
     In that  case, open()  fails with error  value EEXIST if  file already
     exists.

O_NDELAY
     No delay  in writing to disk.  Please note  the following caveats when
     using this flag:

     If set:
          Opening a  FIFO with O_RDONLY  returns without delay.   Opening a
          FIFO with  O_WRONLY 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.

     If not set:
          Opening a  FIFO with  O_RDONLY blocks  until a process  opens the
          file for  writing.  Opening a  FIFO with O_WRONLY  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_NOCTTY
     If file names  a terminal device, do not set  it to be the controlling
     terminal for the process.

O_SYNC
     All  writes to  file will  be  synchronous to  disk.  This  means that
     write() will not return until the data have been physically written to
     disk.

O_TRUNC
     If  file exists,  truncate it  to  zero length.   You must  have write
     permissions on file to use this flag.

The third  argument, mode, is  significant only if O_CREAT  is specified in
the second argument and if file did not exist before the call to open(). In
that  case, mode  specifies  the access  permissions  of the  new file,  in
exactly the manner  that the system call creat() uses  its mode argument to
set permissions.  The  value of mode is typically given  as either an octal
constant or  bitwise OR of permission-bit values as  defined in header file
<sys/stat.h>.

Example

This example copies  the file named in argv[1] to  the one named in argv[2]
by  using  system calls.   It  demonstrates open()  plus  the system  calls
close(), read(), write(), and creat().

#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);
}

See Also

fopen(),
file descriptor,
close(),
libc
ANSI Standard, §4.9.3
POSIX Standard, §5.3.1

Diagnostics

open()  returns  -1  if the  file  does  not  exist,  if the  caller  lacks
permission, or if a system resource is exhausted.

Notes

open()  is a  low-level call  that  passes data  directly to  COHERENT.  It
should not  be mixed with  high-level calls, such as  fread(), fwrite(), or
fopen().

Code that  uses the third argument  to open() cannot be  ported to COHERENT
286.

COHERENT release  4.2.10 changes some  of the behaviors  triggered by flags
O_EXCL and O_NDELAY. In  previous release of COHERENT, flag O_EXCL COHERENT
would handle blocking subsequent open()s. This is no longer the case -- the
device driver  must handle it.  In previous release  of COHERENT, when flag
O_NDELAY was used to open a  character driver, the I/O flag IONDLY would be
set.  Now, the I/O flag IONONBLOCK is set instead.

© 2012 by Stephen A. Ness