.TH MPU_FREOPEN 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
mpu_freopen \- reopen an existing LIBMPUIO real-file stream
.SH SYNOPSIS
.nf
#include <libmpuio.h>

mpu_FILE *mpu_freopen( const char *filename, const char *mode,
                       mpu_FILE *stream );
.fi
.SH DESCRIPTION
.B mpu_freopen
redirects an existing real-file
.I stream
to the UTF-8 pathname
.IR filename .
The stream object itself and its recursive lock are preserved on success.
Pending output is synchronized before the old descriptor is closed.  The new
file is then opened using the same strict mode grammar as
.BR mpu_fopen (3).
.PP
The operation is valid only for an ordinary real-file stream.  UCS-2
memory/string streams and custom-cookie streams cannot be converted into
descriptor-backed streams by this function.  Command-pipe streams returned by
.BR mpu_popen (3)
are also rejected: their child-process lifetime must remain paired with
.BR mpu_pclose (3).
.PP
On success the previous EOF/error state, pushback state, and read/write
direction state are discarded.  Existing buffering policy is retained: a
caller-supplied buffer remains caller supplied, and line/unbuffered selection
is preserved.
.PP
If opening the replacement pathname fails, the previous file association has
already been synchronized and closed.  LIBMPUIO leaves the allocated stream
object in a defined closed/error state: mpu_fileno() returns -1 with EBADF,
input/output operations fail, mpu_ferror() is true, and the caller may safely
pass the object to mpu_fclose() for final destruction.  The old association is
not restored.
.SH RETURN VALUE
On success,
.B mpu_freopen
returns the same pointer passed as
.IR stream .
On failure it returns NULL and sets
.BR errno .
.SH ERRORS
.B EINVAL
is used for a null filename, invalid mode, a memory/cookie stream, or a
command-pipe stream.
Other errors are those reported while synchronizing/closing the previous file
or opening the new pathname.  Failure to open the replacement never reopens or
restores the previous descriptor.
.SH THREAD SAFETY
The stream mutex is acquired for the operation.  As with libc freopen(), the
application must not concurrently use the same stream from another thread
unless that lifetime transition is externally synchronized.
.SH EXAMPLE
.nf
mpu_FILE *fp = mpu_fopen( "first.txt", "w+" );
if( fp == NULL )
  /* handle error */;

mpu_fputs( MPU_UCS2("before\n"), fp );
if( mpu_freopen("second.txt", "w+", fp) == NULL )
  /* stream was not reopened */;
else
  mpu_fputs( MPU_UCS2("after\n"), fp );
.fi
.SH SEE ALSO
.BR libmpuio (3),
.BR mpu_fopen (3),
.BR mpu_fclose (3),
.BR mpu_fflush (3),
.BR mpu_popen (3)