fopen_s, _wfopen_s

Otevře soubor. Tyto verze fopenmají _wfopen vylepšení zabezpečení, jak je popsáno v funkcích zabezpečení v CRT.

Syntaxe

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
);

Parametry

pFile
Ukazatel na ukazatel souboru, který obdrží ukazatel na otevřený soubor.

filename
Název souboru, který se má otevřít.

mode
Typ povoleného přístupu.

Vrácená hodnota

Nula v případě úspěchu; kód chyby při selhání. Další informace o těchto kódech chyb naleznete v tématu errno, _doserrno, _sys_errlista _sys_nerr.

Chybové podmínky

pFile	filename	mode	Návratová hodnota	Obsah pFile
NULL	jakékoliv	jakékoliv	EINVAL	nezměněný
jakékoliv	NULL	jakékoliv	EINVAL	nezměněný
jakékoliv	jakékoliv	NULL	EINVAL	nezměněný

Poznámky

_wfopen_s Funkce fopen_s nemůžou otevřít soubor pro sdílení. Pokud potřebujete soubor sdílet, použijte _fsopen nebo _wfsopen s příslušnou konstantou režimu sdílení – například pro _SH_DENYNO sdílení pro čtení a zápis.

Funkce fopen_s otevře soubor určený .filename _wfopen_s je verze širokého znaku fopen_s a argumenty, které mají _wfopen_s být řetězce širokého znaku. _wfopen_s a fopen_s chovat se stejně, jinak.

fopen_s přijímá cesty platné v systému souborů v okamžiku spuštění; Cesty UNC a cesty, které zahrnují mapované síťové jednotky, jsou přijímány fopen_s , pokud systém, který spouští kód, má přístup ke sdílené nebo mapované síťové jednotce v době provádění. Při vytváření cest pro fopen_s, nedělejte předpoklady o dostupnosti jednotek, cest nebo síťových sdílených složek v spouštěcím prostředí. Jako oddělovače adresářů v cestě můžete použít lomítka (/) nebo zpětná lomítka (\).

Tyto funkce ověřují své parametry. Pokud pFile, filenamenebo mode je null ukazatel, tyto funkce generují neplatnou výjimku parametru, jak je popsáno v ověření parametru.

Vždy zkontrolujte vrácenou hodnotu, abyste zjistili, jestli byla funkce úspěšná, a teprve potom proveďte další operace se souborem. Pokud dojde k chybě, vrátí se kód chyby a nastaví se globální proměnná errno . Další informace naleznete v tématu errno, _doserrno, _sys_errlista _sys_nerr.

Ve výchozím nastavení je globální stav této funkce vymezen na aplikaci. Pokud ho chcete změnit, přečtěte si téma Globální stav v CRT.

Podpora kódování Unicode

fopen_s podporuje streamy souborů Unicode. Pokud chcete otevřít nový nebo existující soubor Unicode, předejte ccs příznak, který určuje požadované kódování fopen_s, například:

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

Povolené hodnoty příznaku ccs jsou UNICODE, UTF-8a UTF-16LE. Pokud není zadána ccsžádná hodnota , fopen_s použije kódování ANSI.

Pokud soubor již existuje a je otevřen pro čtení nebo připojování, určuje kódování znak pořadí bajtů (BOM), pokud je v souboru. Kódování kusovníku má přednost před kódováním určeným příznakem ccs . Kódování ccs se používá pouze v případě, že není k dispozici žádný kusovník nebo pokud je soubor novým souborem.

Poznámka:

Detekce kusovníku se vztahuje pouze na soubory, které jsou otevřeny v režimu Unicode; to znamená předáním příznaku ccs .

Následující tabulka shrnuje režimy pro různé ccs hodnoty příznaků, které jsou uvedeny fopen_s v souboru a pro kusovníky v souboru.

Kódování používaná na ccs základě příznaku a kusovníku

ccs vlajka	Bez kusovníku (nebo nového souboru)	KUSOVNÍK: UTF-8	KUSOVNÍK: UTF-16
UNICODE	UTF-8	UTF-8	UTF-16LE
UTF-8	UTF-8	UTF-8	UTF-16LE
UTF-16LE	UTF-16LE	UTF-8	UTF-16LE

Soubory, které jsou otevřeny pro zápis v režimu Unicode, mají do nich automaticky zapsaný kusovník.

Pokud mode je , "a, ccs=UTF-8""a, ccs=UNICODE"nebo "a, ccs=UTF-16LE", fopen_s nejprve se pokusí otevřít soubor s přístupem pro čtení i zápis. V případě úspěchu funkce přečte kusovník, aby určila kódování souboru; v případě neúspěchu funkce použije výchozí kódování souboru. V obou případech fopen_s znovu otevřete soubor s přístupem jen pro zápis. (Toto chování se vztahuje pouze na a režim, nikoli a+na .)

Řetězec mode znaků určuje typ přístupu, který je požadován pro soubor, následujícím způsobem.

mode	Access
"r"	Otevře se pro čtení. Pokud soubor neexistuje nebo ho nejde najít, fopen_s volání selže.
"w"	Otevře prázdný soubor pro zápis. Pokud daný soubor existuje, jeho obsah se zničí.
"a"	Otevře se pro zápis na konec souboru (připojování) bez odebrání značky end-of-file (EOF) před zápisem nových dat do souboru. Vytvoří soubor, pokud neexistuje.
"r+"	Otevře se pro čtení i zápis. Soubor musí existovat.
"w+"	Otevře prázdný soubor pro čtení i zápis. Pokud soubor existuje, jeho obsah se zničí.
"a+"	Otevře se pro čtení a připojení. Operace připojení zahrnuje odebrání značky EOF před zápisem nových dat do souboru. Po dokončení zápisu se značka EOF neobnoví. Vytvoří soubor, pokud neexistuje.

Při otevření souboru pomocí "a" typu nebo "a+" přístupu dojde ke všem operacím zápisu na konci souboru. Ukazatel souboru lze přemístit pomocí fseek nebo rewind, ale před provedením jakékoli operace zápisu se vždy přesune zpět na konec souboru, aby existující data nemohla být přepsána.

Režim "a" před připojením k souboru neodebere značku EOF. Po připojení příkaz MS-DOS TYPE zobrazí data pouze do původní značky EOF a ne žádná data, která jsou připojena k souboru. Režim "a+" odebere značku EOF před připojením k souboru. Po připojení zobrazí příkaz MS-DOS TYPE všechna data v souboru. Režim "a+" se vyžaduje pro připojení k souboru streamu, který je ukončen značkouCTRL+ Z EOF.

"r+"Pokud je zadán typ přístupu nebo "a+" , "w+"jsou povoleny čtení i zápis. (Soubor je otevřen pro "update".) Když ale přepnete z čtení na zápis, musí vstupní operace narazit na značku EOF. Pokud není žádná značka EOF, musíte použít intervenující volání funkce umístění souboru. Funkce umístění souboru jsou fsetpos, fseeka rewind. Když přepnete z zápisu na čtení, musíte použít intervenující volání fflush funkce umístění souboru nebo do funkce umístění souboru.

Počínaje jazykem C11 můžete funkci připojit "x" "w" nebo "w+" způsobit selhání, pokud soubor existuje, a nemusíte ho přepisovat.

Kromě předchozích hodnot mohou být do režimu překladu pro znaky nového řádku zahrnuty mode následující znaky:

mode modifikátor	Režim překladu
t	Otevřete v textovém (přeloženém) režimu. Kombinace návratového odřádkování (CR-LF) se při vstupu překládají do jednořádkových kanálů (LF) a ZNAKY LF se při výstupu překládají na kombinace CR-LF. Kombinace kláves CTRL+Z se při zadávání interpretuje jako znak konce souboru.
b	Otevřít v binárním (nepřekláněném) režimu; jsou potlačeny překlady zahrnující znaky návratu na začátek řádku a odřádkování.

V textovém (přeloženém) režimu CTRL+se Z při zadávání interpretuje jako znak konce souboru. U souborů otevřených pro čtení a zápis pomocí "a+", fopen_s zkontrolujeCTRL+ na konci souboru Z a pokud je to možné, odebere ho. Odebere se, protože použití fseek a ftell přesunutí v souboru, který končí písmenemCTRL+ Z, může způsobit fseek nesprávné chování blízko konce souboru.

V textovém režimu jsou také kombinace návratu na začátek řádku (CRLF) přeloženy do znaků jednořádkových kanálů (LF) na vstupu a LF znaky jsou přeloženy do kombinací CRLF ve výstupu. Pokud funkce stream-V/V unicode funguje v textovém režimu (výchozí), předpokládá se, že zdrojový nebo cílový datový proud je posloupnost vícebajtových znaků. Vstupní funkce streamu Unicode převádějí vícebajtové znaky na široké znaky (jako by volání funkce mbtowc ). Z stejného důvodu funkce výstupu streamu Unicode převedou široké znaky na vícebajtové znaky (jako by voláním wctomb funkce).

Pokud t nebo b není uveden v mode, je výchozí režim překladu definován globální proměnnou _fmode. Pokud t nebo b je předpona argumentu, funkce selže a vrátí .NULL

Další informace o použití textových a binárních režimů v kódování Unicode a multibajtové stream-I/O naleznete v tématu Vstupně-výstupní operace textového a binárního režimu vstupně-výstupních operací a vstupně-výstupních operací datového proudu Unicode v textových a binárních režimech.

mode modifikátor	Chování
c	Povolte příznak potvrzení pro přidruženou filename , aby obsah vyrovnávací paměti souboru byl zapsán přímo na disk, pokud je fflush volána nebo _flushall je volána.
n	Resetujte příznak potvrzení přidruženého filename k "no-commit". Tento příznak je výchozí. Přepíše také příznak globálního potvrzení, pokud propojujete program s COMMODE.OBJ. Výchozí příznak globálního potvrzení je bez potvrzení, pokud program explicitně propojujete ( COMMODE.OBJ viz možnosti odkazu).
N	Určuje, že soubor není zděděný podřízenými procesy.
S	Určuje, že ukládání do mezipaměti je optimalizované pro sekvenční přístup z disku, ale není omezené na.
R	Určuje, že ukládání do mezipaměti je optimalizované pro náhodný přístup z disku, ale není omezené na.
T	Určuje soubor, který není zapsán na disk, pokud to nevyžaduje zatížení paměti.
D	Určuje dočasný soubor, který se odstraní při zavření posledního ukazatele na soubor.
ccs=UNICODE	Určuje unicode jako zakódovanou znakové sady, která se má použít pro tento soubor. Pokud chcete kódování ANSI, nechte nezadanou.
ccs=UTF-8	Určuje UTF-8 jako zakódovanou znakovou sadu, která se má pro tento soubor použít. Pokud chcete kódování ANSI, nechte nezadanou.
ccs=UTF-16LE	Určuje UTF-16LE jako zakódovanou znakovou sadu, která se má pro tento soubor použít. Pokud chcete kódování ANSI, nechte nezadanou.

Platné znaky pro mode řetězec použitý v fopen_s a _fdopen odpovídají argumentům použitým oflag v _open a _sopennásledujícím způsobem.

Znaky v mode řetězci	Ekvivalentní oflag hodnota pro _open/_sopen
a	_O_WRONLY | _O_APPEND (obvykle _O_WRONLY | _O_CREAT | _O_APPEND)
a+	_O_RDWR | _O_APPEND (obvykle _O_RDWR | _O_APPEND | _O_CREAT)
R	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY (obvykle _O_WRONLY | _O_CREAT | _O_TRUNC)
w+	_O_RDWR (obvykle **_O_RDWR | _O_CREAT | _O_TRUNC)
b	_O_BINARY
t	_O_TEXT (přeloženo)
c	Nic
n	Nic
D	_O_TEMPORARY
R	_O_RANDOM
S	_O_SEQUENTIAL
T	_O_SHORTLIVED
ccs=UNICODE	_O_WTEXT
ccs=UTF-8	_O_UTF8
ccs=UTF-16LE	_O_UTF16

Rozšíření c, n, R, S, tTa D mode možnosti jsou microsoft rozšíření fopen_s _wfopen_s a neměli by být použity, pokud chcete přenositelnost ANSI.

Pokud používáte rb režim, můžou být i soubory Win32 mapované v paměti, pokud nepotřebujete portovat kód, očekáváte, že si přečtete většinu souboru nebo se nezajímáte o výkon sítě.

Týkající se T a D:

• T zabraňuje zápisu souboru na disk, pokud ho zatížení paměti nevyžaduje. Další informace najdete FILE_ATTRIBUTE_TEMPORARY v konstantách atributu File a také tento blogový příspěvek Je pouze dočasný.
• D určuje běžný soubor, který je zapsán na disk. Rozdíl je v tom, že se po zavření automaticky odstraní. Sémantiku můžete zkombinovat TD .

Požadavky

Function	Požadovaný hlavičkový soubor	Hlavička jazyka C++
fopen_s	<stdio.h>	<cstdio>
_wfopen_s	<stdio.h> nebo <wchar.h>	<cstdio>

Další informace o dodržování standardů a zásadách vytváření názvů v knihovně modulu runtime jazyka C naleznete v tématu Kompatibilita.

Mapování rutin obecného textu

<tchar.h> rutina	_UNICODE a _MBCS není definován	_MBCS definovaný	_UNICODE definovaný
_tfopen_s	fopen_s	fopen_s	_wfopen_s

Knihovny

Všechny verze knihoven runtime jazyka C.

Příklad

// 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

Viz také

Vstupně-výstupní operace streamu
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode