Scroll to navigation

FOPEN(3) Руководство программиста Linux FOPEN(3)

ИМЯ

fopen, fdopen, freopen - функции для открытия потоков

СИНТАКСИС

#include <stdio.h>
FILE *fopen(const char *pathname, const char *mode);
FILE *fdopen(int fd, const char *mode);
FILE *freopen(const char *pathname, const char *mode, FILE *stream);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

fdopen(): _POSIX_C_SOURCE

ОПИСАНИЕ

Функция fopen() открывает файл с именем, которое задано в виде строки в pathname, и связывает его с потоком.

Параметр mode указывает на строку, начинающуюся с одной из следующих последовательностей (за ними могут следовать дополнительные символы, описанные далее):

Открыть текстовый файл для чтения. Поток совмещается с началом файла.
Открыть для чтения и записи. Поток совмещается с началом файла.
Обрезать файл до нулевой длины или создать текстовый файл для записи. Поток совмещается с началом файла.
Открыть для чтения и записи. Файл создаётся, если его не существует, в противном случае он обрезается. Поток совмещается с началом файла.
Открыть для добавления (записи в конец файла). Файл создаётся, если его не существует. Поток совмещается с концом файла.
Открыть для чтения и добавления (записи в конец файла). Файл создаётся, если не существует. Вывод всегда добавляется в конец файла. В POSIX ничего не упоминается о начальном положении при чтении, когда используется данный режим. В glibc начальное положение в файле для чтения устанавливается в начало файла, но в Android/BSD/MacOS начальное положение в файле для чтения устанавливается в конец файла.

Строка mode может также содержать символ «b» в качестве последнего символа или символа между двумя символами в любых описанных выше двухсимвольных комбинациях. Это требуется только для совместимости с C89 и не оказывает никакого влияния; символ «b» игнорируется во всех POSIX-совместимых системах, включая Linux. Другие системы могут по-разному обращаться с текстовыми и двоичными файлами, и добавление «b» может оказаться полезным, если вы осуществляете ввод-вывод в двоичный файл и ожидаете, что ваша программа может быть перенесена в не UNIX окружение.

О имеющихся расширениях mode в glibc смотрите ЗАМЕЧАНИЯ далее.

Любой созданный файл будет иметь атрибуты S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH (0666), как изменённые в соответствии со значением umask процесса (смотрите umask(2)).

Чтение и запись могут перемешиваться друг с другом в потоке, открытом для чтения/записи, в любом порядке). Заметим, что в ANSI C требуется, чтобы между выводом и вводом использовались функции позиционирования в файле, если операция ввода не встретила конец файла. Если это условие не выполняется, то при чтении разрешается возвращать результат, не совпадающий с данными самой последней записи. Поэтому рекомендуется (а иногда и действительно необходимо в Linux) использовать функции fseek(3) или fgetpos(3) между операциями чтения и записи в одном потоке. Эти операции могут фактически быть пустыми (например, fseek(..., 0L, SEEK_CUR), вызванная для того, чтобы возник её побочный эффект синхронизации).

Открытие файла в режиме дописывания (a в качестве первого символа mode) приводит к тому, что все последующие операции записи в этот поток производятся в конец файла, как если бы перед ними была вызвана:


fseek(stream, 0, SEEK_END);

Файловый дескриптор, связанный с потоком, открывается как при вызове open(2) со следующими флагами:

режим fopen() флаги open()
r O_RDONLY
w O_WRONLY | O_CREAT | O_TRUNC
a O_WRONLY | O_CREAT | O_APPEND
r+ O_RDWR
w+ O_RDWR | O_CREAT | O_TRUNC
a+ O_RDWR | O_CREAT | O_APPEND

fdopen()

Функция fdopen() связывает поток с существующим дескриптором файла fd. Режим mode потока (одно из следующих значений: «r», «r+», «w», ,w+», «a», «a+») должен быть совместим с режимом дескриптора файла. Указатель положения в файле в новом потоке принимает значение, равное значению у fd, а указатели ошибок и конца файла очищаются. Режимы «w» или «w+» не обрезают файл. При этом не делается копия дескриптора файла и он будет закрыт одновременно с закрытием потока, созданного fdopen(). Результат применения fdopen() к общему объекту памяти не определён.

freopen()

Функция freopen() открывает файл с именем pathname и связывает его с потоком, указанным в stream. Исходный поток (если такой существовал) закрывается. Значение параметра mode такое же как для функции fopen().

Если значение pathname равно указателю null, то freopen() изменяет режим потока на указанный в mode; то есть, freopen() переоткрывает pathname, связанный с потоком. Описание этого поведения было добавлено в стандарт C99, где сказано:

В этом случае файловый дескриптор, связанный с потоком, не нужно закрывать, если вызов freopen() завершился без ошибок. Допустимость изменения режима и при каких условиях определяется реализацией.

Основной задачей функции freopen() является смена файла, связанного со стандартным текстовым потоком (stderr, stdin или stdout).

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Upon successful completion fopen(), fdopen(), and freopen() return a FILE pointer. Otherwise, NULL is returned and errno is set to indicate the error.

ОШИБКИ

Передано неверное значение mode в fopen(), fdopen() или freopen().

The fopen(), fdopen(), and freopen() functions may also fail and set errno for any of the errors specified for the routine malloc(3).

Функция fopen() при ошибках устанавливает значение errno равным какому-либо значению из определённых в open(2).

Функция fdopen() при ошибках устанавливает значение errno равным какому-либо значению из определённых в fcntl(2).

Функция freopen() при ошибках устанавливает errno равным какому-либо значению из определённых в open(2), fclose(3) и fflush(3).

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс Атрибут Значение
fopen(), fdopen(), freopen() Безвредность в нитях MT-Safe

СООТВЕТСТВИЕ СТАНДАРТАМ

fopen(), freopen(): POSIX.1-2001, POSIX.1-2008, C89, C99.

fdopen(): POSIX.1-2001, POSIX.1-2008.

ЗАМЕЧАНИЯ

Замечания по glibc

Библиотека GNU C предоставляет следующие расширения строки в mode:

Не выполнять операцию открытия, последующие чтение и запись, точки отмены нити (thread cancellation points). Этот флаг игнорируется для fdopen().
Открыть файл с флагом O_CLOEXEC. Подробности смотрите в open(2). Этот флаг игнорируется для fdopen().
Пытаться получить доступ к файлу с помощью mmap(2), а не с помощью системных операций ввода-вывода (read(2), write(2)). В настоящее время mmap(2) используется только для файла, открытого на чтение.
Открыть файл в монопольном режиме (как с флагом O_EXCL у open(2)). Если файл уже существует, то fopen() завершается с ошибкой и устанавливает значение errno равное EEXIST. Этот флаг игнорируется для fdopen().

В дополнении к этим символам, для fopen() и freopen() поддерживается следующий синтаксис в mode:

,ccs=строка

Передаваемая строка используется как имя набора символов и поток помечается как широкосимвольный. С того момента внутренние функции преобразования перекодируют данные ввода-вывода в соответствии с набором символов с именем строка. Если синтаксис ,ccs=строка не указан, то широкосимвольность потока определяется по первой файловой операции. Если это операция является широкосимвольной, то поток помечается как широкосимвольный и загружаются функции для перекодировки.

ДЕФЕКТЫ

При анализе отдельных флагов в mode (т. е., символов перед «ccs») реализация glibc для fopen() и freopen() ограничивает количество обрабатываемых в mode символов 7-ю (или, в glibc до версии 2.14, 6-ю, что было недостаточно для включения всех возможных флагов, например «rb+cmxe»). Текущая реализация fdopen() анализирует в mode не более 5 символов.

СМ. ТАКЖЕ

open(2), fclose(3), fileno(3), fmemopen(3), fopencookie(3), open_memstream(3)

ЗАМЕЧАНИЯ

Эта страница является частью проекта Linux man-pages версии 5.10. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу https://www.kernel.org/doc/man-pages/.

ПЕРЕВОД

Русский перевод этой страницы руководства был сделан Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.

21 декабря 2020 г. GNU