fopen_s, _wfopen_s

Статья
04/10/2013

Файл будет открыт.Эти версии 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 об этих кодах ошибок.

Условия возникновения ошибки

pFile	filename	mode	Возвращаемое значение	Содержимое pFile
NULL	любое значение	любое значение	EINVAL	unchanged
любое значение	NULL	любое значение	EINVAL	unchanged
любое значение	любое значение	NULL	EINVAL	unchanged

Заметки

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

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

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

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

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

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

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

fopen_s(&fp, "newfile.txt", "rw, ccs=encoding");

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

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

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

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

Кодирования используется на основе флажке и спецификации ccs

Флаг ccs	Нет спецификации (или нового файла)	Спецификация: UTF-8	Спецификация: UTF-16
UNICODE	UTF-16LE	UTF-8	UTF-16LE
UTF-8	UTF-8	UTF-8	UTF-16LE
UTF-16LE	UTF-16LE	UTF-8	UTF-16LE

Файлы, открыт для записи в режиме юникода имеет спецификацию XML на них автоматически.

Если mode "a, ccs=<encoding>", то fopen_s сначала пытается открыть файл с доступом на чтение, и с записью.В случае успеха функция считывает спецификацию для определения кода для файла; если операция завершилась неудачей, функция использует кодирование по умолчанию для файлов.В любом случае, fopen_s затем снова откроет файл доступен только с доступом на запись.(Это применяется к только режим a, а не как a+).

Универсальное текстовое сопоставление функций

Функция TCHAR.H	неопределенные _UNICODE & _MBCS	определенные _MBCS	Определение _UNICODE
_tfopen_s	fopen_s	fopen_s	_wfopen_s

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

"r"
Открывает для чтения.Если файл не существует или не найдено, то вызов fopen_s завершается с ошибкой.
"w"
Открывается пустой файл для записи.Если файл существует, то его содержимое удаляется.
"a"
Открывает для записи в конце файла (добавление) без удаления маркер конца файла) перед записью новых данных в файл.Создает файл, если он не существует.
"r+"
Будет открыт как для чтения, так и для записи.(Файл должен существовать).
"w+"
Открывается пустой файл как для чтения, так и для записи.Если файл существует, то его содержимое удаляется.
"a+"
Открывает для чтения и добавить.При добавлении операция включает в себя удаление маркера конца файла) до новые данные записываются в файл и маркер конца файла) восстанавливается после завершения записи.Создает файл, если он не существует.

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

Режим "a" не удаляет маркер конца файла) перед добавлением в файл.После добавления выполняется команда ТИПА MS-DOS отображаются только данные до первоначальной разметки, не любых данных конца файла), которые добавляются в файл.Режим "a+" удаляет маркер конца файла) перед добавлением в файл.После добавления команда ТИПА MS-DOS отображаются все данные в файле.Режим "a+" необходим для добавления в файл потока, завершен с помощью маркера CTRL+Z конца файла).

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

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

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

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

b
Открыть в бинарном (непреобразованный) режиме; переводы, символы возврата каретки и перевода строки отключены.

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

Дополнительные сведения об использовании режимов текста и бинарный в юникоде и многобайтовой stream-I/O см. в разделах Вводом-выводом режима текста и бинарный и Потока ВВОДА-ВЫВОДА юникода в режимах текста и бинарный.

c
Включите флажок фиксации для связанного объекта filename, чтобы содержимое файлового буфера будут записываются непосредственно на диск, если fflush или _flushall вызываются.
n
Сбросьте флажок фиксации для связанного объекта filename "," фиксации. Задано по умолчанию.Она также переопределяет глобальный флажок фиксации при соединении программы с COMMODE.OBJ.Глобальное значение по умолчанию флажка фиксации ", фиксация", если явно не рассматривается связывание программы с COMMODE.OBJ (см. Параметры соединения).
N
Указывает, что файл не наследуется дочерними процессами.
S
Указывает, что помещающ кэширование оптимизирует, но не для ограничения, последовательный с диска.
R
Указывает, что помещающ кэширование оптимизирует, но не для ограничения, прямой доступ с диска.
T
Определяет, как временный файл.Если возможно, он не потоплен на диск.
D
Определяет, как временный файл.Он удаляется, когда последний указатель файла закрыт.
ccs=ENCODING
Определите закодированную кодировки для использования (UTF-8, UTF-16LE и ЮНИКОДА) для этого файла.Оставьте данное unspecified, если требуется кодирование ANSI.

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

Символы в строке режима	Эквивалентно oflag значение _open или _sopen
a	обычно _O_WRONLY \| _O_CREAT \|_O_WRONLY \| _O_APPEND (_O_APPEND)
a+	_O_RDWR \| _O_APPEND (обычно это _O_RDWR \| _O_APPEND \| _O_CREAT )
r	_O_RDONLY
r+	_O_RDWR
w	обычно _O_WRONLY \|_O_WRONLY (_O_CREAT \| _O_TRUNC)
w+	_O_RDWR (обычно это _O_RDWR \| _O_CREAT \| _O_TRUNC)
b	_O_BINARY
t	_O_TEXT
c	None
n	None
S	_O_SEQUENTIAL
R	_O_RANDOM
T	_O_SHORTLIVED
D	_O_TEMPORARY
ccs=UNICODE	_O_WTEXT
ccs=UTF-8	_O_UTF8
ccs=UTF-16LE	_O_UTF16

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

Требования

Функция	Требуемый заголовок
fopen_s	<stdio.h>
_wfopen_s	<stdio.h> или <wchar.h>

Дополнительные сведения о совместимости см. в разделе Совместимость во введении.

Библиотеки

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

c, n и tmode расширения Майкрософт для fopen_s и _fdopen и не должны использоваться, переносимость ANSI пожелана.

Пример

// 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" does not 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+" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

   // Close stream if it is not 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 );
}