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

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.

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

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.

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:

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.

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.

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

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

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