freopen(3C)

NAME

     freopen - open a stream

SYNOPSIS

     #include <stdio.h>

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

DESCRIPTION

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

     The freopen() function opens the file whose pathname is  the
     string  pointed  to  by  filename  and associates the stream
     pointed to by stream with it. The mode argument is used just
     as in fopen(3C).

     The original stream is closed regardless of whether the sub-
     sequent open succeeds.

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

     The largest value that can be represented  correctly  in  an
     object  of type off_t will be established as the offset max-
     imum in the open file description.

RETURN VALUES

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

ERRORS

     The freopen() function will fail if:

     EACCES
           Search permission is denied on a component of the path
           prefix,  or the file exists and the permissions speci-
           fied by mode are denied, or the file  does  not  exist
           and  write  permission is denied for the parent direc-
           tory 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 Too many symbolic links were encountered in  resolving
           path.

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

     ENAMETOOLONG
           The length of the filename exceeds PATH_MAX or a path-
           name 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 current value  of  the  file  position  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.

     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 non-existent  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.

USAGE

     The freopen() function is typically used to attach the preo-
     pened  streams  associated  with stdin, stdout and stderr to
     other files. By default stderr is unbuffered, but the use of
     freopen() will cause it to become buffered or line-buffered.

     The freopen() function has a transitional interface for  64-
     bit file offsets.  See lf64(5).

     When a UFS file system is mounted with logging enabled, file
     system  transactions  that  free blocks from files might not
     actually add those freed blocks to the  file  system's  free
     list  until  some  unspecified  time  in  the  future.  This
     behavior improves file system performance but does not  con-
     form  to the POSIX, Single UNIX Specification, SPARC Confor-
     mance Definition, System  V  Application  Binary  Interface,
     System  V Interface Definition, and X/Open Portability Guide
     Standards, which  require  that  freed  space  be  available
     immediately.  To enable standards conformance regarding file
     deletions or to address the problem of  not  being  able  to
     grow  files  on a relatively full UFS file system even after
     files  have  been  deleted,   disable   UFS   logging   (see
     mount_ufs(1M).

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO

     mount_ufs(1M), fclose(3C), fdopen(3C), fopen(3C), stdio(3C),
     attributes(5), lf64(5)