freopen() — Redirect an open file

Standards

Standards / Extensions	C or C++	Dependencies
ISO C POSIX.1 XPG4 XPG4.2 C99 Single UNIX Specification, Version 3	both

Format

#include <stdio.h>

FILE *freopen(const char *__restrict__filename, const char *__restrict__mode, 
              FILE *__restrict__stream);

General description

Closes the file currently associated with stream and pointed to by stream, opens the file specified by the filename, and then associates the stream with it.

The freopen() function opens the new file with the type of access requested by the mode argument. The mode argument is used as in the fopen() function. See fopen() — Open a file for a description of the mode parameter.

You can also use the freopen() function to redirect the standard stream files stdin, stdout, and stderr to files that you specify. The file pointer input to the freopen() function must point to a valid open file. If the file pointer has been closed, the behavior is undefined.

You could use the following freopen() call to redirect stdout to a memory file a.b:

    freopen("a.b","wb,type=memory",stdout);

If filename is an empty string, freopen() closes the file and reuses the original file name. For details on how the file name and open mode is interpreted, see z/OS XL C/C++ Programming Guide.

A standard stream can be opened by default to a type of file not available to a general fopen(). This is true for standard streams under CICS®, and also true for the default stderr, when running a non-POSIX Language Environment application.

The following statement uses freopen() to have stdin use binary mode instead of text mode:

   fp = freopen("", "rb", stdin);

You can use the same empty string method to change the mode from binary back to text. This method is not allowed for:

The default CICS data queues used by the standard streams under CICS
The Language Environment® Message File (MSGFILE), which is the default for stderr
z/OS UNIX files.
-CELQPIPI MSGRTN file, which is the default for stderr if MSGRTN service routine is specified.

Note: Using the empty string method is included in the SAA C definition, but not in the ANSI C standard.

Large file support for z/OS UNIX files: Large z/OS UNIX files are supported automatically for AMODE 64 C/C++ applications. AMODE 31 C/C++ applications must be compiled with the option LANGLVL(LONGLONG) and define the _LARGE_FILES feature test macro before any headers are included to enable this function to operate on z/OS UNIX files that are larger than 2 GB in size. File size and offset fields are enlarged to 63 bits in width. Therefore, any other function operating on the file is required to define the _LARGE_FILES feature test macro as well.

Returned value

If successful, freopen() returns the value of stream, the same value that was passed to it, and clears both the error and EOF indicators associated with the stream.

A failed attempt to close the original file is ignored.

If an error occurs in reopening the requested file, freopen() closes the original file, and returns a NULL pointer value.

Special behavior for large z/OS UNIX files: The following is the possible value of errno:

Error Code: Description
EOVERFLOW: The named file is a regular file and the size of the file cannot be represented correctly in an object of type off_t.

Example

This example illustrates the z/OS® XL C extension that allows you to change characteristics of a file by reopening it.

#include <stdio.h>

int main(void)
{
   FILE *stream, *stream2;

   stream = fopen("myfile.dat","r");
   stream2 = freopen("", "w+", stream);
}

This example closes the stream data stream and reassigns its stream pointer:

#include <stdio.h>

int main(void)
{
   FILE *stream, *stream2;

   stream = fopen("myfile.dat","r");
   stream2 = freopen("myfile2.dat", "w+", stream);
}

Note: stream and stream2 will have the same value.