NAME    [Toc]    [Back]

     fopen, fdopen, freopen - stream open functions

SYNOPSIS    [Toc]    [Back]

     #include <stdio.h>

     FILE *
     fopen(const char *path, const char *mode);

     FILE *
     fdopen(int fildes, const char *mode);

     FILE *
     freopen(const char *path, const char *mode, FILE *stream);

DESCRIPTION    [Toc]    [Back]

     The fopen() function opens the file whose name is the string
pointed to
     by path and associates a stream with it.

     The  argument  mode points to a string beginning with one of
the following
     sequences  (additional  characters  may  follow  these   sequences):

     ``r''    Open  text  file  for reading.  The stream is positioned at the beginning
 of the file.

     ``r+''  Open for reading and writing.  The stream  is  positioned at the
             beginning of the file.

     ``w''   Truncate file to zero length or create text file for
writing.
             The stream is positioned at  the  beginning  of  the
file.

     ``w+''   Open  for reading and writing.  The file is created
if it does not
             exist, otherwise it is truncated.  The stream is positioned at
             the beginning of the file.

     ``a''    Open  for  writing.  The file is created if it does
not exist.  The
             stream is positioned at the end of the file.

     ``a+''  Open for reading and writing.  The file  is  created
if it does not
             exist.   The  stream is positioned at the end of the
file.

     The mode string can also include the letter ``b'' either  as
a third character
 or as a character between the characters in any of the
two-character
 strings described above.  This is strictly for  compatibility with ANSI
  X3.159-1989 (``ANSI C'') and has no effect; the ``b'' is
ignored.

     Any created files will have mode "S_IRUSR | S_IWUSR |  S_IRGRP | S_IWGRP |
     S_IROTH | S_IWOTH" (0666), as modified by the process' umask
value (see
     umask(2)).

     Reads  and  writes  cannot  be  arbitrarily  intermixed   on
read/write streams.
     ANSI  C  requires that a file positioning function intervene
between output
     and input, unless an input operation encounters end-of-file.

     The  fdopen() function associates a stream with the existing
file descriptor
 fildes.  The mode of the stream must be compatible  with
the mode of
     the file descriptor.  If fdopen() fails, the file descriptor
fildes is
     not affected in any way.

     The freopen() function opens the  file  whose  name  is  the
string pointed to
     by  path and associates the stream pointed to by stream with
it.  The
     original stream (if it exists) is  always  closed,  even  if
freopen() fails.
     The  mode  argument is used just as in the fopen() function.
The primary
     use of the freopen() function is to change the file  associated with a
     standard text stream (stderr, stdin, or stdout).

RETURN VALUES    [Toc]    [Back]

     Upon  successful completion, fopen(), fdopen() and freopen()
return a FILE
     pointer.  Otherwise, NULL is returned and the  global  variable errno is
     set to indicate the error.

ERRORS    [Toc]    [Back]

     [EINVAL]       The  mode  provided  to fopen(), fdopen(), or
freopen() was
                   invalid.

     The fopen(), fdopen() and freopen() functions may also  fail
and set errno
     for any of the errors specified for the routine malloc(3).

     The  fopen() function may also fail and set errno for any of
the errors
     specified for the routine open(2).

     The fdopen() function may also fail and set errno for any of
the errors
     specified for the routine fcntl(2).

     The  freopen()  function may also fail and set errno for any
of the errors
     specified for the routines open(2), fclose(3) and fflush(3).

SEE ALSO    [Toc]    [Back]

     open(2), fclose(3), fseek(3), funopen(3)

STANDARDS    [Toc]    [Back]

     The   fopen()   and  freopen()  functions  conform  to  ANSI
X3.159-1989 (``ANSI
     C'').   The  fdopen()  function   conforms   to   IEEE   Std
1003.1-1988
     (``POSIX'').

CAVEATS    [Toc]    [Back]

     Proper  code  using  fdopen()  with  error  checking  should
close(2) fildes in
     case of failure, and fclose(3) the resulting FILE * in  case
of success.

             FILE *file;
             int fd;

             if ((file = fdopen(fd, "r")) != NULL) {
                     /* perform operations on the FILE * */
                     fclose(file);
             } else {
                     /* failure, report the error */
                     close(fd);
             }

OpenBSD      3.6                           June      4,      1993