FOPEN(3S)                                                            FOPEN(3S)


NAME
     fopen, freopen, fdopen - open a stream

SYNOPSIS
     #include <stdio.h>

     FILE *fopen (const char *filename, const char *type);

     FILE *freopen (const char *filename, const char *type, FILE *stream);

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

DESCRIPTION
     fopen opens the file named by filename and associates a stream with it.
     fopen returns a pointer to the FILE structure associated with the stream.

     filename points to a character string that contains the name of the file
     to be opened.

     type is a character string.  The initial portion of type must consist of
     one of the following character sequences:

          r or rb        open for reading

          w or wb        truncate or create for writing

          a or ab        append: open for writing at end of file or create for
                         writing

          r+,r+b or rb+  open for update (reading and writing)

          w+,w+b or wb+  truncate or create for update

          a+,a+b or ab+  append: open for update at end-of-file or create for
                         update
     As this implementation does not distinguish between binary and text
     files, the character b in the string type, (which is used to indicate
     that the file being opened is a binary file) is inconsequential.

     Opening a file for reading (when r is the first character of type) will
     fail if the file does not exist or is unreadable.

     When a file is opened for update (when + appears as the second (or third,
     in the case of fopen or freopen) character of type) both input and output
     may be done on the resulting stream.  However, output may not be directly
     followed by input without an intervening fseek, fsetpos, or rewind.
     Similarly, input may not be directly followed by output without an
     intervening call to one of these functions, unless the input operation
     left the file positioned at end-of-file.  (See note under BUGS below.)


     When a file is opened for append (i.e., when type is a, ab, a+b, ab+ or
     a+), it is impossible to overwrite information already in the file.
     fseek may be used to reposition the file pointer to any position in the
     file, but when output is written to the file, the current file pointer is
     disregarded.  All output is written at the end of the file and causes the
     file pointer to be repositioned at the end of the output.  If two
     separate processes open the same file for append, each process may write
     freely to the file without fear of destroying output being written by the
     other.  The output from the two processes will be intermixed in the file
     in the order in which it is written.

     freopen substitutes the named file in place of the open stream.  An
     attempt is made to close the original stream, using fclose(3s).  If this
     close attempt is unsuccessful, the failure is ignored. freopen then
     attempts to open the file indicated by filename, returning the result.
     The character string type must have the same form as for fopen.  If the
     open is successful, the end-of-file and error indicators for stream are
     cleared.

     freopen is typically used to attach the preopened streams associated with
     stdin, stdout and stderr to other files.

     fdopen associates a stream with a file descriptor.  File descriptors are
     obtained from open, dup, creat, or pipe(2), which open files but do not
     initialize a stream, which is the object manipulated by many of the
     Section 3S library routines.  fdopen initializes a stream for the open
     file descriptor fildes, and returns a pointer to the corresponding FILE
     structure.  The character string type has the same form as that for
     fopen, with the exception that the (superfluous) binary file
     specification character b, is not allowed.  (This restricts the initial
     portion of type to one of r, w, a, r+, w+, or a+.)  The type specified
     for the stream must agree with the mode of the open file indicated by
     fildes (see open(2)).

SEE ALSO
     creat(2), close(2), dup(2), open(2), pipe(2), write(2), fclose(3S),
     fseek(3S), setbuf(3s), stdio(3S).

DIAGNOSTICS
     fopen, fdopen, and freopen return a NULL pointer on failure.

     Depending on which ABI a program is compiled in, there may be a limit on
     the number of open stdio streams, or a limit on which file descriptors
     may be associated with stdio streams.  When compiling in n32 or n64
     modes, there are no limits, however in o32 mode the functions fopen or
     fdopen may fail and not set errno if there are no free stdio streams. No
     more than 255 files may be opened via fopen, and only file descriptors 0
     through 255 are valid with stdio streams.

     In o32 mode file descriptors used by fdopen must be less than 255.


BUGS
     When operating on a file opened for update on which the last operation
     was output, an input operation may be performed if there is an
     intervening call to a file positioning function.  An input operation
     should also be possible under these circumstances if an intervening call
     is made to fflush.  If this sequence of operations (i.e., output, fflush,
     input) is performed, however, the input operation fails with the
     misleading error EBADF.


                                                                        Page 3