### 12.3 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)` ¶

  Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd lock | See POSIX Safety Concepts.

  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. 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.

  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 additional characters for use in opentype:

  ‘`c`’

    The file is opened with cancellation in the I/O functions disabled.

  ‘`e`’

    The underlying file descriptor will be closed if you use any of the `exec…` functions (see Executing a File). (This is equivalent to having set `FD_CLOEXEC` on that descriptor. See File Descriptor Flags.)

  ‘`m`’

    The file is opened and accessed using `mmap`. This is only supported with files opened for reading.

  ‘`x`’

    Insist 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 (see Opening and Closing Files).

    The ‘`x`’ modifier is part of ISO C11, which says the file is created with exclusive access; in the GNU C Library this means the equivalent of `O_EXCL`.

  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 GNU systems). If both ‘`+`’ and ‘`b`’ are specified, they can appear in either order. See Text and 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 with appropriate conversion functions in place to convert from and to the character set STRING. 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 compiled 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. See Dangers of Mixing Streams and Descriptors. 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.

Function: `FILE *` fopen64 `(const char *filename, const char *opentype)` ¶

  Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd lock | See POSIX Safety Concepts.

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

Function: `FILE *` freopen `(const char *filename, const char *opentype, FILE *stream)` ¶

  Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt fd | See POSIX Safety Concepts.

  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. On Linux, `freopen` may also fail and set `errno` to `EBUSY` when the kernel structure for the old file descriptor was not initialized completely before `freopen` was called. This can only happen in multi-threaded programs, when two threads race to allocate the same file descriptor number. To avoid the possibility of this race, do not use `close` to close the underlying file descriptor for a `FILE`; either use `freopen` while the file is still open, or use `open` and then `dup2` to install the new file descriptor.

  `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 compiled 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.

  The GNU C Library only supports use of `freopen` on streams opened with `fopen` or `fopen64` and on the original values of the standard streams `stdin`, `stdout`, and `stderr`; such a stream may be reopened multiple times with `freopen`. If it is called on another kind of stream (opened with functions such as `popen`, `fmemopen`, `open_memstream`, and `fopencookie`), `freopen` fails and returns a null pointer.

Function: `FILE *` freopen64 `(const char *filename, const char *opentype, FILE *stream)` ¶

  Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt fd | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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 kinds of problems there are two more functions. They provide even finer-grained information.

Function: `int` __freading `(FILE *stream)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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`.