freopen, freopen

Closes the file currently associated with a stream and reassigns a new file to the stream.

#include <stdio.h>

FILE *freopen (const char *filename, const char *mode, FILE *stream);
errno_t _Pascal freopen_s(FILE **pNewStream, const char *filename, const char *mode, FILE *stream);

#include <wchar.h>

FILE *_wfreopen(const wchar_t *filename, const wchar_t *mode, FILE *stream);
errno_t _Pascal _wfreopen_s(FILE **pNewStream, const wchar_t *filename, const wchar_t *mode, FILE *stream);

Parameters

filename: Pathname of new file.
mode: Open mode for the new file.
stream: Pointer to FILE structure for existing stream.
pNewStream: A pointer to the stream pointer that will receive the pointer to the re-opened file.

Remarks

freopen is typically used to redirect stdin, stdout, and stderr to user-specified files, or to chnage the mode of an already-open file.

This list gives the mode string, including required quotes, as used in fdopen. It also relates the mode string and the corresponding oflag arguments used in sopen.

Value	Description
"r"	Opens for reading. If the file does not exist or cannot be found, the call will fail. Relates to O_RDONLY.
"w"	Opens an empty file for writing. If the given file exists, its contents are destroyed. Relates to O_WRONLY (usually O_WRONLY \| O_CREAT \| O_TRUNC).
"a"	Opens for writing at the end of the file (appending); creates the file first if it doesn't exist. Relates to O_WRONLY \| O_APPEND (usually O_WRONLY \| O_CREAT \| O_APPEND).
"r+"	Opens for both reading and writing. The file must exist. Relates to O_RDWR.
"w+"	Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed. Relates to O_RDWR (usually O_RDWR \| O_CREAT \| O_TRUNC).
"a+"	Opens for reading and appending; creates the file first if it doesn't exist. Relates to O_RDWR \| O_APPEND (usually O_RDWR \| O_APPEND \| O_CREAT).

Use the "w" and "w+" types with care, as they can destroy existing files.

When a file is opened with the "a" or "a+" open mode, all write operations occur at the end of the file, even if you've repositioned the file pointer using fseek or rewind. Thus, existing data cannot be overwritten.

When the "r+", "w+", or "a+" open mode is specified, both reading and writing are allowed (the file is open for update). However, when you switch between reading and writing, there must be an intervening rewind operation or fsetpos or fseek, which can reposition the file pointer, if desired.

In addition to these values, one of these characters can be included after mode but between the quotation marks to specify the translation mode for <LF> characters. The t and b characters correspond to the constants used in open and sopen, as listed below.

Value	Description
t	Open in text (translated) mode. <CR><LF> combinations are translated into single <LF> characters on input and <LF> characters are translated to <CR><LF> combinations on output. <Ctrl-Z> is interpreted as an end-of-file character on input. In files opened for reading or for reading/writing, checks for and removes <Ctrl-Z> if possible, because <Ctrl-Z> may cause fseek to behave improperly near the end of the file. Relates to O_TEXT.
b	Open in binary (untranslated) mode; the above translations are suppressed. Relates to O_BINARY.
c	Set commit mode so that the contents of a file buffer are flushed to disk if fflush or fclose is called, or if fflush is called implicitly as the result of writing a file stream.

freopen_s and _wfreopen_s are the secure versions of the calls. All parameters are checked.

Return Values

freopen and _wfreopen return a stream pointer for the newly-opened file on success, or NULL on failure. errno will be set in the case of failure.

freopen_s and _wfreopen_s return 0 on success, or a non-zero errno value on failure.

Generic Text Routines

`tchar.h` routine	`_UNICODE` not defined	`_UNICODE` defined
_tfreopen	freopen	_wfreopen
_tfreopen_s	freopen_s	_wfreopen_s

Requirements

Versions	Defined in	Include	Link to
INtime 3.0 INtime 6.0 (wide-character and generic text routines)	intime/rt/include/stdio.h intime/rt/include/wchar.h intime/rt/include/tchar.h	stdio.h wchar.t tchar.h	clib.lib