Fopen error codes

ОБЗОР

#include <stdio.h>

FILE *fopen(const char *path, const char *mode);
FILE *fdopen(int fd, const char *mode);
FILE *freopen(const char *path, const char *mode, FILE *stream);

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

fdopen(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

ОПИСАНИЕ

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

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

r

Открыть текстовый файл для чтения. Поток совмещается с началом файла.

r+

Открыть для чтения и записи. Поток совмещается с началом файла.

w

Обрезать файл до нулевой длины или создать текстовый файл для записи. Поток
совмещается с началом файла.

w+

Открыть для чтения и записи. Файл создаётся, если его не существует, в
противном случае он обрезается. Поток совмещается с началом файла.

a

Открыть для добавления (записи в конец файла). Файл создаётся, если его не
существует. Поток совмещается с концом файла.

a+

Открыть для чтения и добавления (записи в конец файла). Файл создаётся, если
не существует. Начальное положение в файле для чтения устанавливается в
начало файла, но вывод всегда добавляется в конец файла.

Строка 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);

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

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

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

При успешном выполнении fopen(), fdopen() и freopen() возвращается
указатель FILE. В противном случае возвращается NULL и errno
присваивается код ошибки.

ОШИБКИ

EINVAL

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

Функции fopen(), fdopen() и freopen() могут также завершаться с
ошибками и устанавливают значение errno равным какому-либо значению из
определённых в malloc(3).

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

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

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

АТРИБУТЫ

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

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

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

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

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

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

c (начиная с glibc 2.3.3)

Не выполнять операцию открытия, последующие чтение и запись, точки отмены
нити (thread cancellation points). Этот флаг игнорируется для fdopen().

e (начиная с glibc 2.7)

Открыть файл с флагом O_CLOEXEC. Подробности смотрите в open(2). Этот
флаг игнорируется для fdopen().

m (начиная с glibc 2.3)

Пытаться получить доступ к файлу с помощью mmap(2), а не с помощью
системных операций ввода-вывода (read(2), write(2)). В настоящее время
mmap(2) используется только для файла, открытого на чтение.

x

Открыть файл в монопольном режиме (как с флагом O_EXCL у
open(2)). Если файл уже существует, то fopen() завершается с ошибкой и
устанавливает значение errno равное EEXIST. Этот флаг игнорируется для
fdopen().

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

,ccs=строка

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

FILE *fopen( const char *filename, const char *mode );

FILE *fopen( const char *restrict filename, const char *restrict mode );

errno_t fopen_s( FILE *restrict *restrict streamptr,
                 const char *restrict filename,
                 const char *restrict mode );

1) Открывает файл, указанный в filename и возвращает указатель на поток файлов, связанный с этим файлом. mode используется для определения режима доступа к файлу.

Parameters

Флаги доступа к файлам

Return value

1) В случае успеха возвращает указатель на новый файловый поток. Поток полностью буферизуется, если filename относится к интерактивному устройству. В случае ошибки возвращает null pointer . POSIX требует, чтобы в этом случае было установлено значение errno .

2) В случае успеха возвращает ноль и указатель на новый файловый поток записывается в *streamptr . При ошибке возвращает ненулевой код ошибки и записывает нулевой указатель в *streamptr (если только streamptr не является нулевым указателем).

Notes

Формат имени filename определяется реализацией и не обязательно относится к файлу (например, это может быть консоль или другое устройство, доступное через API файловой системы). На платформах, которые их поддерживают, filename может содержать абсолютный или относительный путь файловой системы.

Example

#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
    int is_ok = EXIT_FAILURE;
    const char* fname = "/tmp/unique_name.txt"; 
    FILE* fp = fopen(fname, "w+");
    if(!fp) {
        perror("File opening failed");
        return is_ok;
    }
    fputs("Hello, world!n", fp);
    rewind(fp);
 
    int c; 
    while ((c = fgetc(fp)) != EOF) { 
       putchar(c);
    }
 
    if (ferror(fp)) {
        puts("I/O error when reading");
    } else if (feof(fp)) {
        puts("End of file reached successfully");
        is_ok = EXIT_SUCCESS;
    }
 
    fclose(fp);
    remove(fname);
    return is_ok;
}

Hello, world!
End of file reached successfully

References

• Стандарт С17 (ISO/IEC 9899:2018):
• 7.21.5.3 Функция fopen (p:223-224)
• K.3.5.2.1 Функция fopen_s (p:428-429)
• Стандарт C11 (ISO/IEC 9899:2011):
• 7.21.5.3 Функция открытия (стр.305-306)
• K.3.5.2.1 Функция fopen_s (стр.588-590)
• Стандарт С99 (ISO/IEC 9899:1999):
• 7.19.5.3 Функция открытия (стр.271-272)
• Стандарт C89/C90 (ISO/IEC 9899:1990):
• 4.9.5.3 Функция отпирания

See also

C

• fgetws

• FILE

• fpos_t

• printf, fprintf, sprintf, snprintf, printf_s, fprintf_s, sprintf_s, snprintf_s

fopen, fopen_s

FILE *fopen( const char *filename, const char *mode );

FILE *fopen( const char *restrict filename, const char *restrict mode );

errno_t fopen_s( FILE *restrict *restrict streamptr,
                 const char *restrict filename,
                 const char *restrict mode );

1) Opens a file indicated by filename and returns a pointer to the file stream associated with that file. mode is used to determine the file access mode.

Parameters

File access flags

Return value

1) If successful, returns a pointer to the new file stream. The stream is fully buffered unless filename refers to an interactive device. On error, returns a null pointer. POSIX requires that errno be set in this case.

2) If successful, returns zero and a pointer to the new file stream is written to *streamptr. On error, returns a non-zero error code and writes the null pointer to *streamptr (unless streamptr is a null pointer itself).

Notes

The format of filename is implementation-defined, and does not necessarily refer to a file (e.g. it may be the console or another device accessible though filesystem API). On platforms that support them, filename may include absolute or relative filesystem path.

Example

#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
    int is_ok = EXIT_FAILURE;
    const char* fname = "/tmp/unique_name.txt"; // or tmpnam(NULL);
    FILE* fp = fopen(fname, "w+");
    if(!fp) {
        perror("File opening failed");
        return is_ok;
    }
    fputs("Hello, world!n", fp);
    rewind(fp);
 
    int c; // note: int, not char, required to handle EOF
    while ((c = fgetc(fp)) != EOF) { // standard C I/O file reading loop
       putchar(c);
    }
 
    if (ferror(fp)) {
        puts("I/O error when reading");
    } else if (feof(fp)) {
        puts("End of file reached successfully");
        is_ok = EXIT_SUCCESS;
    }
 
    fclose(fp);
    remove(fname);
    return is_ok;
}

Hello, world!
End of file reached successfully

References

• C17 standard (ISO/IEC 9899:2018):
• 7.21.5.3 The fopen function (p: 223-224)
• K.3.5.2.1 The fopen_s function (p: 428-429)
• C11 standard (ISO/IEC 9899:2011):
• 7.21.5.3 The fopen function (p: 305-306)
• K.3.5.2.1 The fopen_s function (p: 588-590)
• C99 standard (ISO/IEC 9899:1999):
• 7.19.5.3 The fopen function (p: 271-272)
• C89/C90 standard (ISO/IEC 9899:1990):
• 4.9.5.3 The fopen function

See also