Name
freopen - Assigns a new file to a stream.
Syntax
#include <stdio.h>
FILE *freopen(path, type, stream)
const char *path;
const char *type;
FILE *stream;
Description
The freopen function closes the file currently associated
with stream and reassigns stream to the file specified by
path. The freopen function is typically used to redirect the
pre-opened files stdin, stdout, and stderr to files
specified by the user. The new file associated with stream
is opened with type, which is a character string specifying
the type of access requested for the file, as follows:
Type Description
"r" Opens for reading. If r is the first
character in the type string and the file
does not exist or cannot be found, the
freopen call will fail.
"w" Opens an empty file for writing. If the
given file exists, its contents are
destroyed.
"a" Opens for writing at the end of the file
(appending); creates the file first if it
doesn't exist.
"r+" Opens for both reading and writing. (The
file must exist.)
"w+" Opens an empty file for both reading and
writing. If the given file exists, its
contents are destroyed.
"a+" Opens for reading and appending; creates
the file first if it doesn't exist.
Notes
Use the "w" and "w+" types with care, as they can destroy
existing files.
When a file is opened with the "a" or "a+" types, all write
operations take place at the end of the file. Although the
file pointer can be repositioned using fseek or rewind, the
file pointer is always moved back to the end of the file
before any write operation is carried out. Thus, existing
data cannot be overwritten.
When the "r+", "w+", or "a+" type is specified, both reading
and writing are allowed (the file is said to be open for
``update''). However, when switching between reading and
writing, there must be an intervening fsetpos, fseek, or
rewind operation. The current position can be specified for
the fsetpos or fseek operation, if desired.
In addition to the values listed above, one of the following
characters may be appended to the type string or inserted
before the + character to specify the translation mode for
new lines. For example, r+b is the same as rb+.
Mode Meaning
t Open in text (translated) mode;
carriage-return/line-feed (CR-LF)
combinations are translated into a single
line feed on input; line-feed characters
are translated to carriage-return/line-
feed combinations on output. Also, CTRL+Z
is interpreted as an end-of-file
character on input. In files opened for
reading, or writing and reading, the
run-time library checks for a CTRL+Z at
the end of the file and removes it, if
possible. This is done because using the
fseek and ftell functions to move within
a file may cause fseek to behave
improperly near the end of the file.
b Open in binary (untranslated) mode; the
above translations are suppressed.
The t option is not part of the ANSI standard for freopen,
but is a Microsoft extension that should not be used where
ANSI portability is desired.
If t or b is not given in the type string, the translation
mode is defined by the default mode variable _fmode.
Return Value
The freopen function returns a pointer to the newly opened
file. If an error occurs, the original file is closed and
the function returns a null pointer value.
See Also
fclose(DOS), fcloseall(DOS), fdopen(S), fileno(S),
fopen(DOS), open(DOS), setmode(DOS)
Example
#include <stdio.h> #include <process.h>
FILE *stream, *errstream;
main()
{
/* Reassign "stdout" to "data2": */
stream = freopen("data2", "w", stdout);
/* If reassignment failed: */
if (stream == NULL )
fprintf("error on freopen\n");
else
{
fprintf(stream,"This will go to the file
'data2'\n");
fprintf(stream,"'stdout' successfully
reassigned\n");
system("type data2");
}
}
This program reassigns stdout to the file named data2 and
writes a line to that file.
(printed 6/18/89)