fopen

open a file

Synopsis:

#include <stdio.h>
FILE *fopen( const char *filename,
             const char *mode );

Description:

The fopen() function opens the file whose name is the string pointed to by filename, and associates a stream with it. The argument mode points to a string beginning with one of the following sequences:

r: open file for reading
w: create file for writing, or truncate to zero length
a: append: open text file or create for writing at end-of-file
r+: open file for update (reading and/or writing); use default file translation
w+: create file for update, or truncate to zero length; use default file translation
a+: append; open file or create for update, writing at end-of-file; use default file translation

The letter b may be added to any of the above sequences in the second or third position to indicate that the file is (or must be) a binary file (an ANSI requirement for portability to systems that make a distinction between text and binary files). Under QNX, there is no difference between text files and binary files.

Opening a file with read mode (r as the first character in the mode argument) fails if the file does not exist or it cannot be read.
Opening a file with append mode (a as the first character in the mode argument) causes all subsequent writes to the file to be forced to the current end-of-file, regardless of previous calls to the fseek function.
When a file is opened with update mode (+ as the second or third character of the mode argument), both input and output may be performed on the associated stream.

When a stream is opened in update mode, both reading and writing may be performed. However, writing may not be followed by reading without an intervening call to the fflush() function, or to a file-positioning function (fseek(), fsetpos(), rewind()). Similarly, reading may not be followed by writing without an intervening call to a file-positioning function, unless the read resulted in end-of-file.

Returns:

The fopen() function returns a pointer to the object controlling the stream. This pointer must be passed as a parameter to subsequent functions for performing operations on the file.

If the open operation fails, fopen() returns NULL. When an error has occurred, errno contains a value indicating the type of error that has been detected.

Examples:

#include <stdio.h>

void main()
  {
    FILE *fp;

    fp = fopen( "report.dat", "r" );
    if( fp != NULL ) {
      /* rest of code goes here */
      fclose( fp );
    }
  }

Classification:

ANSI

Systems:

All (except DOS/PM)