function
<cstdio>

freopen

FILE * freopen ( const char * filename, const char * mode, FILE * stream );
Reopen stream with different file or mode
Reuses stream to either open the file specified by filename or to change its access mode.

If a new filename is specified, the function first attempts to close any file already associated with stream (third parameter) and disassociates it. Then, independently of whether that stream was successfuly closed or not, freopen opens the file specified by filename and associates it with the stream just as fopen would do using the specified mode.

If filename is a null pointer, the function attempts to change the mode of the stream. Although a particular library implementation is allowed to restrict the changes permitted, and under which circumstances.

The error indicator and eof indicator are automatically cleared (as if clearerr was called).

This function is especially useful for redirecting predefined streams like stdin, stdout and stderr to specific files (see the example below).

Parameters

filename
C string containing the name of the file to be opened.
Its value shall follow the file name specifications of the running environment and can include a path (if supported by the system).
If this parameter is a null pointer, the function attempts to change the mode of the stream, as if the file name currently associated with that stream had been used.
mode
C string containing a file access mode. It can be:
"r"read: Open file for input operations. The file must exist.
"w"write: Create an empty file for output operations. If a file with the same name already exists, its contents are discarded and the file is treated as a new empty file.
"a"append: Open file for output at the end of a file. Output operations always write data at the end of the file, expanding it. Repositioning operations (fseek, fsetpos, rewind) are ignored. The file is created if it does not exist.
"r+"read/update: Open a file for update (both for input and output). The file must exist.
"w+"write/update: Create an empty file and open it for update (both for input and output). If a file with the same name already exists its contents are discarded and the file is treated as a new empty file.
"a+"append/update: Open a file for update (both for input and output) with all output operations writing data at the end of the file. Repositioning operations (fseek, fsetpos, rewind) affects the next input operations, but output operations move the position back to the end of file. The file is created if it does not exist.
With the mode specifiers above the file is open as a text file. In order to open a file as a binary file, a "b" character has to be included in the mode string. This additional "b" character can either be appended at the end of the string (thus making the following compound modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+").

The new C standard (C2011, wich is not part of C++) adds a new standard subspecifier ("x"), that can be appended to any "w" speficier (to form "wx", "wbx", "w+x" or "w+bx"/"wb+x"). This subspecifier forces the function to fail if the file exists, instead of overwriting it.

If additional characters follow the sequence, the behavior depends on the library implementation: some implementations may ignore additional characters so that for example an additional "t" (sometimes used to explicitly state a text file) is accepted.

On some library implementations, opening or creating a text file with update mode may treat the stream instead as a binary file.
stream
pointer to a FILE object that identifies the stream to be reopened.


Return Value

If the file is successfully reopened, the function returns the pointer passed as parameter stream, which can be used to identify the reopened stream.
Otherwise, a null pointer is returned.
On most library implementations, the errno variable is also set to a system-specific error code on failure.

Example

1
2
3
4
5
6
7
8
9
10
 
/* freopen example: redirecting stdout */
#include <stdio.h>

int main ()
{
  freopen ("myfile.txt","w",stdout);
  printf ("This sentence is redirected to a file.");
  fclose (stdout);
  return 0;
}


This sample code redirects the output that would normally go to the standard output to a file called myfile.txt, that after this program is executed contains:
This sentence is redirected to a file.

See also

fopen
Open file (function )
fclose
Close file (function )

C++