GNU Info

Info Node: (libc.info)Opening Streams

(libc.info)Opening Streams


Next: Closing Streams Prev: Standard Streams Up: I/O on Streams
Enter node , (file) or (file)node

Opening Streams
===============

   Opening a file with the `fopen' function creates a new stream and
establishes a connection between the stream and a file.  This may
involve creating a new file.

   Everything described in this section is declared in the header file
`stdio.h'.

 - Function: FILE * fopen (const char *FILENAME, const char *OPENTYPE)
     The `fopen' function opens a stream for I/O to the file FILENAME,
     and returns a pointer to the stream.

     The OPENTYPE argument is a string that controls how the file is
     opened and specifies attributes of the resulting stream.  It must
     begin with one of the following sequences of characters:

    `r'
          Open an existing file for reading only.

    `w'
          Open the file for writing only.  If the file already exists,
          it is truncated to zero length.  Otherwise a new file is
          created.

    `a'
          Open a file for append access; that is, writing at the end of
          file only.  If the file already exists, its initial contents
          are unchanged and output to the stream is appended to the end
          of the file.  Otherwise, a new, empty file is created.

    `r+'
          Open an existing file for both reading and writing.  The
          initial contents of the file are unchanged and the initial
          file position is at the beginning of the file.

    `w+'
          Open a file for both reading and writing.  If the file
          already exists, it is truncated to zero length.  Otherwise, a
          new file is created.

    `a+'
          Open or create file for both reading and appending.  If the
          file exists, its initial contents are unchanged.  Otherwise,
          a new file is created.  The initial file position for reading
          is at the beginning of the file, but output is always
          appended to the end of the file.

     As you can see, `+' requests a stream that can do both input and
     output.  The ISO standard says that when using such a stream, you
     must call `fflush' (Note: Stream Buffering) or a file positioning
     function such as `fseek' (Note: File Positioning) when switching
     from reading to writing or vice versa.  Otherwise, internal buffers
     might not be emptied properly.  The GNU C library does not have
     this limitation; you can do arbitrary reading and writing
     operations on a stream in whatever order.

     Additional characters may appear after these to specify flags for
     the call.  Always put the mode (`r', `w+', etc.) first; that is
     the only part you are guaranteed will be understood by all systems.

     The GNU C library defines one additional character for use in
     OPENTYPE: the character `x' insists on creating a new file--if a
     file FILENAME already exists, `fopen' fails rather than opening
     it.  If you use `x' you are guaranteed that you will not clobber
     an existing file.  This is equivalent to the `O_EXCL' option to
     the `open' function (Note: Opening and Closing Files).

     The character `b' in OPENTYPE has a standard meaning; it requests
     a binary stream rather than a text stream.  But this makes no
     difference in POSIX systems (including the GNU system).  If both
     `+' and `b' are specified, they can appear in either order.  Note:
     Binary Streams.

     If the OPENTYPE string contains the sequence `,ccs=STRING' then
     STRING is taken as the name of a coded character set and `fopen'
     will mark the stream as wide-oriented which appropriate conversion
     functions in place to convert from and to the character set STRING
     is place.  Any other stream is opened initially unoriented and the
     orientation is decided with the first file operation.  If the
     first operation is a wide character operation, the stream is not
     only marked as wide-oriented, also the conversion functions to
     convert to the coded character set used for the current locale are
     loaded.  This will not change anymore from this point on even if
     the locale selected for the `LC_CTYPE' category is changed.

     Any other characters in OPENTYPE are simply ignored.  They may be
     meaningful in other systems.

     If the open fails, `fopen' returns a null pointer.

     When the sources are compiling with `_FILE_OFFSET_BITS == 64' on a
     32 bit machine this function is in fact `fopen64' since the LFS
     interface replaces transparently the old interface.

   You can have multiple streams (or file descriptors) pointing to the
same file open at the same time.  If you do only input, this works
straightforwardly, but you must be careful if any output streams are
included.  Note: Stream/Descriptor Precautions.  This is equally true
whether the streams are in one program (not usual) or in several
programs (which can easily happen).  It may be advantageous to use the
file locking facilities to avoid simultaneous access.  Note: File
Locks.

 - Function: FILE * fopen64 (const char *FILENAME, const char *OPENTYPE)
     This function is similar to `fopen' but the stream it returns a
     pointer for is opened using `open64'.  Therefore this stream can be
     used even on files larger then 2^31 bytes on 32 bit machines.

     Please note that the return type is still `FILE *'.  There is no
     special `FILE' type for the LFS interface.

     If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32
     bits machine this function is available under the name `fopen' and
     so transparently replaces the old interface.

 - Macro: int FOPEN_MAX
     The value of this macro is an integer constant expression that
     represents the minimum number of streams that the implementation
     guarantees can be open simultaneously.  You might be able to open
     more than this many streams, but that is not guaranteed.  The
     value of this constant is at least eight, which includes the three
     standard streams `stdin', `stdout', and `stderr'.  In POSIX.1
     systems this value is determined by the `OPEN_MAX' parameter;
     Note: General Limits.  In BSD and GNU, it is controlled by the
     `RLIMIT_NOFILE' resource limit; Note: Limits on Resources.

 - Function: FILE * freopen (const char *FILENAME, const char
          *OPENTYPE, FILE *STREAM)
     This function is like a combination of `fclose' and `fopen'.  It
     first closes the stream referred to by STREAM, ignoring any errors
     that are detected in the process.  (Because errors are ignored,
     you should not use `freopen' on an output stream if you have
     actually done any output using the stream.)  Then the file named by
     FILENAME is opened with mode OPENTYPE as for `fopen', and
     associated with the same stream object STREAM.

     If the operation fails, a null pointer is returned; otherwise,
     `freopen' returns STREAM.

     `freopen' has traditionally been used to connect a standard stream
     such as `stdin' with a file of your own choice.  This is useful in
     programs in which use of a standard stream for certain purposes is
     hard-coded.  In the GNU C library, you can simply close the
     standard streams and open new ones with `fopen'.  But other
     systems lack this ability, so using `freopen' is more portable.

     When the sources are compiling with `_FILE_OFFSET_BITS == 64' on a
     32 bit machine this function is in fact `freopen64' since the LFS
     interface replaces transparently the old interface.

 - Function: FILE * freopen64 (const char *FILENAME, const char
          *OPENTYPE, FILE *STREAM)
     This function is similar to `freopen'.  The only difference is that
     on 32 bit machine the stream returned is able to read beyond the
     2^31 bytes limits imposed by the normal interface.  It should be
     noted that the stream pointed to by STREAM need not be opened
     using `fopen64' or `freopen64' since its mode is not important for
     this function.

     If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32
     bits machine this function is available under the name `freopen'
     and so transparently replaces the old interface.

   In some situations it is useful to know whether a given stream is
available for reading or writing.  This information is normally not
available and would have to be remembered separately.  Solaris
introduced a few functions to get this information from the stream
descriptor and these functions are also available in the GNU C library.

 - Function: int __freadable (FILE *STREAM)
     The `__freadable' function determines whether the stream STREAM
     was opened to allow reading.  In this case the return value is
     nonzero.  For write-only streams the function returns zero.

     This function is declared in `stdio_ext.h'.

 - Function: int __fwritable (FILE *STREAM)
     The `__fwritable' function determines whether the stream STREAM
     was opened to allow writing.  In this case the return value is
     nonzero.  For read-only streams the function returns zero.

     This function is declared in `stdio_ext.h'.

   For slightly different kind of problems there are two more functions.
They provide even finer-grained information.

 - Function: int __freading (FILE *STREAM)
     The `__freading' function determines whether the stream STREAM was
     last read from or whether it is opened read-only.  In this case
     the return value is nonzero, otherwise it is zero.  Determining
     whether a stream opened for reading and writing was last used for
     writing allows to draw conclusions about the content about the
     buffer, among other things.

     This function is declared in `stdio_ext.h'.

 - Function: int __fwriting (FILE *STREAM)
     The `__fwriting' function determines whether the stream STREAM was
     last written to or whether it is opened write-only.  In this case
     the return value is nonzero, otherwise it is zero.

     This function is declared in `stdio_ext.h'.


automatically generated by info2www version 1.2.2.9