freopen, freopen_s

Определено в заголовке `<stdio.h>`
	(1)
FILE freopen( const char filename, const char mode, FILE stream );		(до C99)
FILE freopen( const char restrict filename, const char restrict mode, FILE restrict stream );		(с C99)
errno_t freopen_s( FILE restrict restrict newstreamptr, const char restrict filename, const char restrict mode, FILE *restrict stream );	(2)	(с C11)

1) Сначала пытается закрыть файл, связанный с stream, игнорируя любые ошибки. Затем, если filename не является нулевым указателем, пытается открыть файл, указанный filename, используя mode как если бы это было сделано с помощью fopen, и связывает этот файл с потоком файла, на который указывает stream. Если filename является нулевым указателем, функция пытается повторно открыть файл, уже связанный с stream (в этом случае изменяемые режимы работы файла определяются реализацией).

2) То же, что и (1), за исключением того, что mode обрабатывается как в fopen_s, и указатель на поток файла записывается в newstreamptr. При этом следующие ошибки обнаруживаются во время выполнения, и вызывается установленная в настоящее время функция обработчика ограничений обработчика ограничений:

newstreamptr является нулевым указателем
stream является нулевым указателем
mode является нулевым указателем

Как и во всех функциях с проверкой границ, freopen_s гарантированно доступна только в том случае, если __STDC_LIB_EXT1__ определена реализацией и если пользователь определит __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 перед включением <stdio.h>.

Параметры

filename	-	имя файла для ассоциации с потоком файла
mode	-	строка символов с нулевым завершением, определяющая новый режим доступа к файлу
stream	-	поток файла для изменения
newstreamptr	-	указатель на указатель, куда функция записывает результат (параметр вывода)

Режимы доступа к файлам

Строка режима доступа к файлу	Значение	Объяснение	Действие, если файл уже существует	Действие, если файл не существует
`"r"`	чтение	Открыть файл для чтения	чтение с начала	ошибка открытия
`"w"`	запись	Создать файл для записи	уничтожить содержимое	создать новый
`"a"`	добавление	Добавить к файлу	запись в конец	создать новый
`"r+"`	расширенное чтение	Открыть файл для чтения/записи	чтение с начала	ошибка
`"w+"`	расширенная запись	Создать файл для чтения/записи	уничтожить содержимое	создать новый
`"a+"`	расширенное добавление	Открыть файл для чтения/записи	запись в конец	создать новый
Флаг режима доступа к файлам `"b"` можно указать для открытия файла в двоичном режиме. Этот флаг не имеет эффекта в системах POSIX, но в Windows он отключает специальную обработку `'\n'` и `'\x1A'` . При режимах доступа к файлам «добавление» данные записываются в конец файла независимо от текущей позиции указателя позиции файла.
Поведение не определено, если режим не соответствует ни одной из перечисленных строк. Некоторые реализации определяют дополнительные поддерживаемые режимы (например, Windows).
В режиме обновления (`'+'`) могут выполняться как ввод, так и вывод, но вывод не может следовать за вводом без промежуточного вызова `fflush`, `fseek`, `fsetpos` или `rewind`, и ввод не может следовать за выводом без промежуточного вызова `fseek`, `fsetpos` или `rewind`, если операция ввода не встретила конец файла. В режиме обновления реализации могут использовать двоичный режим даже при указании текстового режима.
Флаг режима доступа к файлам `"x"` можно дополнительно добавить к спецификаторам `"w"` или `"w+"`. Этот флаг заставляет функцию завершиться неудачно, если файл существует, вместо того, чтобы перезаписывать его. (C11)
При использовании `fopen_s` или `freopen_s`, права доступа к файлам для любого файла, созданного с помощью `"w"` или `"a"`, предотвращают доступ других пользователей к нему. Флаг режима доступа к файлам `"u"` можно дополнительно добавить к любому спецификатору, начинающемуся с `"w"` или `"a"`, чтобы разрешить стандартные права доступа `fopen`. (C11)

Значение результата

1) Копия значения stream при успешном выполнении, нулевой указатель при ошибке.

2) Ноль при успешном выполнении (и копия значения stream записывается в *newstreamptr, ненулевое значение при ошибке (и нулевой указатель записывается в *newstreamptr, если только newstreamptr не является сам по себе нулевым указателем).

Примечания

freopen — единственный способ изменить узко/широкую ориентацию потока после его установки операцией ввода-вывода или fwide.

Версия Microsoft CRT функции freopen не поддерживает никаких изменений режима, когда filename является нулевым указателем, и обрабатывает это как ошибку (см. документацию). Возможным обходным путём является нестандартная функция _setmode().

Пример

Следующий код перенаправляет stdout в файл.

#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
    puts("stdout is printed to console");
    if (freopen("redir.txt", "w", stdout) == NULL)
    {
       perror("freopen() failed");
       return EXIT_FAILURE;
    }
    puts("stdout is redirected to a file"); // this is written to redir.txt
    fclose(stdout);
    return EXIT_SUCCESS;
}

Вывод:

stdout is printed to console

Ссылки

Стандарт C17 (ISO/IEC 9899:2018):

7.21.5.4 Функция freopen (стр: 224-225)
K.3.5.2.2 Функция freopen_s (стр: 429-430)

Стандарт C11 (ISO/IEC 9899:2011):

7.21.5.4 Функция freopen (стр: 307)
K.3.5.2.2 Функция freopen_s (стр: 590)

Стандарт C99 (ISO/IEC 9899:1999):

7.19.5.4 Функция freopen (стр: 272-273)

Стандарт C89/C90 (ISO/IEC 9899:1990):

4.9.5.4 Функция freopen

См. также

fopenfopen_s (C11)	открывает файл (функция)
fclose	закрывает файл (функция)
Документация C++ для `freopen`

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/c/io/freopen