fopen_s, _wfopen_s

Открывает файл. Эти версии имеют fopenулучшения безопасности, как описано в функциях _wfopenбезопасности в CRT.

Синтаксис

errno_t fopen_s(
   FILE** pFile,
   const char *filename,
   const char *mode
);
errno_t _wfopen_s(
   FILE** pFile,
   const wchar_t *filename,
   const wchar_t *mode
);

Параметры

pFile
Указатель на указатель на файл, который получает указатель на открытый файл.

filename
Имя файла, который необходимо открыть.

mode
Тип разрешенного доступа.

Возвращаемое значение

Возвращает нуль в случае успеха или код ошибки в случае неудачи. Дополнительные сведения об этих кодах ошибок см. в разделе errno, _doserrno_sys_errlistи _sys_nerr.

Условия ошибок

Замечания

fopen_s Функции _wfopen_s не могут открывать файл для общего доступа. Если необходимо предоставить общий доступ к файлу, использовать _fsopen или _wfsopen с соответствующей константой режима общего доступа, например использовать _SH_DENYNO для совместного использования чтения и записи.

Функция fopen_s открывает файл, указанный в filenameфайле. _wfopen_s — это версия расширенных fopen_s символов и аргументы _wfopen_s для строк с широкими символами. _wfopen_s и fopen_s ведет себя одинаково, в противном случае.

Функция fopen_s принимает пути, допустимые в файловой системе во время выполнения; UNC-пути и пути, в которых фигурируют сопоставленные сетевых диски, принимаются функцией fopen_s, если система, которая выполняет код, имеет доступ к общему или сетевому диску в момент выполнения. При построении путей для fopen_s убедитесь, что драйверы, пути или сетевые общие папки будут доступны в среде выполнения. Вы можете использовать косую черту (/) или обратные косые черты (\) в качестве разделителей каталогов в пути.

Эти функции проверяют свои параметры. Если pFile, filenameили mode является пустым указателем, эти функции создают недопустимое исключение параметров, как описано в проверке параметров.

Всегда проверяйте возвращаемое значение, чтобы узнать, выполнена ли функция успешно, прежде чем выполнять дальнейшие операции с файлом. Если возникает ошибка, возвращается код ошибки, а глобальная переменная errno устанавливается. Дополнительные сведения см. в разделе errno, _doserrno, _sys_errlist, и _sys_nerr.

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить его, ознакомьтесь с глобальным состоянием в CRT.

Поддержка Юникода

fopen_s поддерживает файловые потоки Юникода. Чтобы открыть новый или существующий файл Юникода, передайте ccs флаг, указывающий нужную кодировку fopen_s, например:

fopen_s(&fp, "newfile.txt", "w+, ccs=UNICODE");

Допустимые значения флагаccs: UNICODEи UTF-8UTF-16LE. Если для этого значения не указано ccs, fopen_s используется кодировка ANSI.

Если файл уже существует и открыт для чтения или добавления, то метка порядка байтов (BOM), если она присутствует в файле, определяет кодировку. Кодировка, заданная меткой BOM, имеет приоритет над кодировкой, заданной флагом ccs. Заданная флагом ccs кодировка используется, только если метка BOM отсутствует или речь идет о новом файле.

В следующей таблице приведены сведения о режимах для различных ccs значений флагов, которые предоставляются fopen_s и для boms в файле.

Кодировки, используемые на ccs основе флагов и BOM

В файлы, открываемые для записи в режиме Юникода, метка BOM записывается автоматически.

Если mode имеет "a, ccs=UNICODE"значение , "a, ccs=UTF-8"или "a, ccs=UTF-16LE"fopen_s сначала пытается открыть файл с доступом на чтение и записью. Если эта операция завершается успешно, функция считывает метку BOM, чтобы определить кодировку для файла; если операция завершается сбоем, функция использует для файла кодировку по умолчанию. В любом случае fopen_s повторно открывает файл с доступом только для записи. (Это поведение применяется только к режиму a , а не a+к .)

Символьная строка mode указывает тип доступа, который запрошен для файла, следующим образом.

Если файл открывается с использованием типа доступа "a" или "a+", все операции записи выполняются в конце файла. Указатель на файл может быть перемещен с помощью fseek или rewind, но он всегда перемещается обратно в конец файла перед выполнением любой операции записи, чтобы существующие данные не могли быть перезаписаны.

Режим "a" не удаляет маркер EOF перед добавлением в файл. После добавления команда MS-DOS TYPE отображает только данные до исходного маркера EOF, а не какие-либо данные, добавленные в файл. Перед добавлением в файл режим "a+" удаляет маркер конца файла. После добавления команда MS-DOS TYPE отображает все данные в файле. Этот "a+" режим необходим для добавления в потоковый файл, который завершается маркеромCTRL+ Z EOF.

"r+"Если указан тип доступа "w+", или "a+" тип доступа, разрешено чтение и запись. (Файл, как сообщается, открыт для "обновления".) Однако при переходе с чтения на запись входная операция должна возникнуть через маркер EOF. Если маркер EOF отсутствует, необходимо использовать промежуточный вызов функции размещения файлов. Функции позиционирования в файле — это fsetpos, fseek и rewind. При переходе от записи к чтению необходимо воспользоваться промежуточным вызовом либо функции fflush, либо функции позиционирования в файле.

Начиная с C11, можно добавить "x""w" или "w+" вызвать сбой функции, если файл существует, а не перезаписывать его.

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

В режиме CTRL+преобразования текста Z интерпретируется как символ конца файла во входных данных. Если это возможно, для файлов, открытых для чтения и записи"a+", fopen_s проверяет наличиеCTRL+ Z в конце файла и удаляет его. Он удаляется из-за использования fseek и ftell перемещения в файл, который заканчивается CTRL+Z, может привести fseek к неправильному ведении в конце файла.

Кроме того, в текстовом режиме сочетания возврата и строки каретки (CRLF) превратятся в символы однострочного канала (LF) для входных данных, а символы LF переводятся в сочетания CRLF для выходных данных. Если функция ввода-вывода потока Юникода работает в текстовом режиме (по умолчанию) исходный или конечный поток рассматривается как последовательность многобайтовых символов. Функции потокового ввода Юникода преобразуют многобайтовые символы в широкие символы (как будто вызовом mbtowc функции). По той же причине выходные функции потока Юникода преобразуют расширенные символы в многобайтовые (как если бы для этого вызывалась функция wctomb ).

Если t или b нет mode, режим перевода по умолчанию определяется глобальной переменной _fmode. Если символ t или b указан как префикс аргумента, функция завершается с ошибкой и возвращает NULL.

Дополнительные сведения об использовании текстовых и двоичных режимов в Юникоде и многобайтовом потоке ввода-вывода см. в разделе "Текстовый и двоичный режим ввода-вывода" и потокового ввода-вывода Юникода в текстовых и двоичных режимах.

Допустимые символы строки, используемой modefopen_s в и _fdopen соответствующие oflag аргументам, используемым в _open и _sopen, как показано ниже.

<a0/>, c, nRStи TD параметры — это расширения Майкрософт для mode и fopen_s не должны использоваться, если требуется переносимость ANSI.

Если вы используете rb режим, сопоставленные с Win32-файлами памяти, также могут быть вариантом, если вам не нужно переносить код, вы ожидаете, что считываете большую часть файла или не заботитесь о производительности сети.

Относительно T и D:

• T избегает записи файла на диск до тех пор, пока не требуется давление на память. Дополнительные сведения см. в разделе FILE_ATTRIBUTE_TEMPORARY "Константы атрибутов файла", а также в этой записи блога Только временный.
• D указывает обычный файл, записанный на диск. Разница заключается в том, что он автоматически удаляется при закрытии. Вы можете объединить оба TD семантики.

Требования

Дополнительные сведения о соответствии стандартам и соглашениях об именовании в библиотеке среды выполнения C см. в разделе "Совместимость".

Сопоставления подпрограмм универсального текста

Библиотеки

Все версии библиотек времени выполнения языка C.

Пример

// crt_fopen_s.c
// This program opens two files. It uses
// fclose to close the first file and
// _fcloseall to close all remaining files.

#include <stdio.h>

FILE *stream, *stream2;

int main( void )
{
   errno_t err;

   // Open for read (will fail if file "crt_fopen_s.c" doesn't exist)
   err  = fopen_s( &stream, "crt_fopen_s.c", "r" );
   if( err == 0 )
   {
      printf( "The file 'crt_fopen_s.c' was opened\n" );
   }
   else
   {
      printf( "The file 'crt_fopen_s.c' was not opened\n" );
   }

   // Open for write
   err = fopen_s( &stream2, "data2", "w+, ccs=UTF-8" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

   // Close stream if it isn't NULL
   if( stream )
   {
      err = fclose( stream );
      if ( err == 0 )
      {
         printf( "The file 'crt_fopen_s.c' was closed\n" );
      }
      else
      {
         printf( "The file 'crt_fopen_s.c' was not closed\n" );
      }
   }

   // All other files are closed:
   int numclosed = _fcloseall( );
   printf( "Number of files closed by _fcloseall: %u\n", numclosed );
}

The file 'crt_fopen_s.c' was opened
The file 'data2' was opened
Number of files closed by _fcloseall: 1

См. также

Потоковый ввод-вывод
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode