NAME

       freopen - open a stream

SYNOPSIS

       #include <stdio.h>

       FILE *freopen(const char *restrict filename, const char *restrict mode,
              FILE *restrict stream);

DESCRIPTION

       The  freopen()  function  shall  first  attempt  to  flush  the  stream and close any file
       descriptor associated  with  stream.  Failure  to  flush  or  close  the  file  descriptor
       successfully  shall  be ignored. The error and end-of-file indicators for the stream shall
       be cleared.

       The freopen() function shall open the file whose pathname is  the  string  pointed  to  by
       filename and associate the stream pointed to by stream with it. The mode argument shall be
       used just as in fopen().

       The original stream shall be closed regardless of whether the subsequent open succeeds.

       If filename is a null pointer, the freopen() function shall attempt to change the mode  of
       the stream to that specified by mode, as if the name of the file currently associated with
       the stream had been used. It is implementation-defined which changes of mode are permitted
       (if any), and under what circumstances.

       After  a successful call to the freopen() function, the orientation of the stream shall be
       cleared,    the encoding rule shall be cleared,  and the associated mbstate_t object shall
       be set to describe an initial conversion state.

       The  largest  value  that can be represented correctly in an object of type off_t shall be
       established as the offset maximum in the open file description.

RETURN VALUE

       Upon successful completion, freopen() shall return the value of stream. Otherwise, a  null
       pointer shall be returned,    and errno shall be set to indicate the error.

ERRORS

       The freopen() function shall fail if:

       EACCES Search  permission  is denied on a component of the path prefix, or the file exists
              and the permissions specified by mode are denied, or the file does  not  exist  and
              write permission is denied for the parent directory of the file to be created.

       EINTR  A signal was caught during freopen().

       EISDIR The named file is a directory and mode requires write access.

       ELOOP  A loop exists in symbolic links encountered during resolution of the path argument.

       EMFILE {OPEN_MAX} file descriptors are currently open in the calling process.

       ENAMETOOLONG

              The  length  of the filename argument exceeds {PATH_MAX} or a pathname component is
              longer than {NAME_MAX}.

       ENFILE The maximum allowable number of files is currently open in the system.

       ENOENT A component of filename does not name an existing file  or  filename  is  an  empty
              string.

       ENOSPC The  directory  or  file system that would contain the new file cannot be expanded,
              the file does not exist, and it was to be created.

       ENOTDIR
              A component of the path prefix is not a directory.

       ENXIO  The named file is a character  special  or  block  special  file,  and  the  device
              associated with this special file does not exist.

       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.

       EROFS  The named file resides on a read-only file system and mode requires write access.

       The freopen() function may fail if:

       EINVAL The value of the mode argument is not valid.

       ELOOP  More than {SYMLOOP_MAX} symbolic links were encountered during  resolution  of  the
              path argument.

       ENAMETOOLONG

              Pathname resolution of a symbolic link produced an intermediate result whose length
              exceeds {PATH_MAX}.

       ENOMEM Insufficient storage space is available.

       ENXIO  A request was made of  a  nonexistent  device,  or  the  request  was  outside  the
              capabilities of the device.

       ETXTBSY
              The  file  is  a  pure procedure (shared text) file that is being executed and mode
              requires write access.

       The following sections are informative.

EXAMPLES

   Directing Standard Output to a File
       The following example logs all standard output to the /tmp/logfile file.

              #include <stdio.h>
              ...
              FILE *fp;
              ...
              fp = freopen ("/tmp/logfile", "a+", stdout);
              ...

APPLICATION USAGE

       The freopen() function is typically used to attach the preopened streams  associated  with
       stdin, stdout, and stderr to other files.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       fclose()   ,   fopen()   ,   fdopen()  ,  mbsinit()  ,  the  Base  Definitions  volume  of
       IEEE Std 1003.1-2001, <stdio.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .