freopen, freopen_s

Определено в заголовочном файле <stdio.h>

Определено в заголовочном файле `<stdio.h>`
FILE* freopen( const char* filename, const char* mode, FILE* stream );	(1)	(до 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)

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

(1)

(до 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.

Версия freopen в Microsoft CRT не поддерживает изменение режима, если 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

Ссылки

Стандарт C23 (ISO/IEC 9899:2024):

7.21.5.4 Функция freopen (с. TBD)
K.3.5.2.2 Функция freopen_s (с. TBD)

Стандарт 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/c/io/freopen