The GNU C Library - Opening Streams

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 ANSI standard says that when using such a stream, you must call fflush (see Stream Buffering) or a file positioning function such as fseek (see 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.

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 can are guaranteed that you will not clobber an existing file. This is equivalent to the O_EXCL option to the open function (see 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. See Binary Streams.

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

If the open fails, fopen returns a null pointer.

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. See 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. See File Locks.

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; see General Limits. In BSD and GNU, it is controlled by the RLIMIT_NOFILE resource limit; see 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.