.TH MPU_FREOPEN 3 "Август 2026" "libmpuio" "Руководство программиста LIBMPUIO"
.SH ИМЯ
mpu_freopen \- повторно открыть существующий поток LIBMPUIO реального файла
.SH ОБЗОР
.nf
#include <libmpuio.h>

mpu_FILE *mpu_freopen( const char *filename, const char *mode,
                       mpu_FILE *stream );
.fi
.SH ОПИСАНИЕ
.B mpu_freopen
перенаправляет существующий поток реального файла
.I stream
на путь UTF-8
.IR filename .
Сам объект потока и его рекурсивная блокировка при успехе сохраняются.
Ожидающий вывод синхронизируется до закрытия старого дескриптора.  Затем новый
файл открывается с использованием той же строгой грамматики режима, что и
.BR mpu_fopen (3).
.PP
Операция допустима только для обычного потока реального файла.  Потоки памяти
или строк UCS-2 и пользовательские cookie-потоки не могут быть преобразованы
этой функцией в потоки на основе дескрипторов.  Командные потоки, возвращённые
.BR mpu_popen (3),
также отвергаются: жизненный цикл их дочернего процесса должен оставаться
связанным с
.BR mpu_pclose (3).
.PP
При успехе прежние состояния EOF/ошибки, pushback и направление
чтения/записи отбрасываются.  Существующая политика буферизации сохраняется:
буфер, предоставленный вызывающей стороной, остаётся таким же, а выбор
построчного или небуферизованного режима сохраняется.
.PP
Если открыть новый путь не удалось, прежняя файловая ассоциация уже была
синхронизирована и закрыта.  LIBMPUIO оставляет выделенный объект потока в
определённом закрытом состоянии ошибки: mpu_fileno() возвращает -1 с EBADF,
операции ввода-вывода завершаются ошибкой, mpu_ferror() возвращает истину, а
вызывающая сторона может безопасно передать объект в mpu_fclose() для
окончательного уничтожения.  Прежняя ассоциация не восстанавливается.
.SH ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успехе
.B mpu_freopen
возвращает тот же указатель, который был передан как
.IR stream .
При ошибке возвращается NULL и устанавливается
.BR errno .
.SH ОШИБКИ
.B EINVAL
используется для NULL-имени файла, недопустимого режима, потока памяти/cookie
или командного потока.
Другие ошибки соответствуют ошибкам синхронизации/закрытия прежнего файла или
открытия нового пути.  Неудача при открытии замены никогда не открывает заново
и не восстанавливает прежний дескриптор.
.SH ПОТОКОБЕЗОПАСНОСТЬ
На время операции захватывается mutex потока.  Как и в случае libc freopen(),
приложение не должно одновременно использовать тот же поток из другого потока
выполнения, если этот переход жизненного цикла не синхронизирован извне.
.SH ПРИМЕР
.nf
mpu_FILE *fp = mpu_fopen( "first.txt", "w+" );
if( fp == NULL )
  /* обработать ошибку */;

mpu_fputs( MPU_UCS2("before\n"), fp );
if( mpu_freopen("second.txt", "w+", fp) == NULL )
  /* поток не был повторно открыт */;
else
  mpu_fputs( MPU_UCS2("after\n"), fp );
.fi
.SH СМ. ТАКЖЕ
.BR libmpuio (3),
.BR mpu_fopen (3),
.BR mpu_fclose (3),
.BR mpu_fflush (3),
.BR mpu_popen (3)