fopen_s _wfopen_s

Článek
03/26/2013

Otevře soubor.Tyto verze fopen, _wfopen mají vylepšení zabezpečení, jak je popsáno v Funkce zabezpečení v 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 
);

Parametry

[výstup]pFile
Ukazatel na ukazatel souboru, která získá ukazatel na otevřený soubor.
[v]filename
Název souboru.
[v]mode
Typ oprávněného přístupu.

Vrácená hodnota

Nula v případě úspěchu; kód chyby při selhání.Viz Kód chyby, _doserrno, _sys_errlist a _sys_nerr Další informace o těchto kódech chyb.

Chybové stavy

pFile	filename	mode	Vrácená hodnota	ObsahpFile
NULL	všechny	všechny	EINVAL	beze změny
všechny	NULL	všechny	EINVAL	beze změny
všechny	všechny	NULL	EINVAL	beze změny

Poznámky

Soubory, které jsou otevírány pomocí fopen_s a _wfopen_s nejsou sdílet.Pokud požadujete, aby sdílet soubor, použijte _fsopen _wfsopen s příslušnou konstantu sdílení režimu – například _SH_DENYNO pro sdílení pro čtení a zápis.

fopen_s Funkce otevře soubor, který je určen filename._wfopen_sje verzí širokého znaku fopen_s; argumenty pro _wfopen_s jsou řetězci širokého znaku._wfopen_sa fopen_s jinak chovat identicky.

fopen_spřijímá cesty, které jsou platné v systému souborů místě provádění; Cesty UNC a cesty, které se týkají namapované síťové jednotky jsou přijímány fopen_s tak dlouho, dokud systému, který spouští kód má přístup ke sdílené složce nebo mapované síťové jednotky v době spuštění.Při vytvoření cesty k fopen_s, označovat předpoklady o dostupnosti jednotky, cesty nebo síťové sdílené položky v prostředí pro spouštění.Lomítka (/) nebo zpětná lomítka (\) lze použít jako oddělovače adresáře v cestě.

Tyto funkce ověření jejich parametrů.Pokud pFile, filename, nebo mode je nulový ukazatel, tyto funkce generovat výjimku neplatného parametru, jak je popsáno v Ověření parametrů.

Vždy zkontrolujte vrácenou hodnotu zobrazíte, pokud byla úspěšná funkce před provedením jakékoli další operace na souboru.Pokud dojde k chybě, je vrácen kód chyby a globální proměnné errno je nastavena.Další informace naleznete v tématu Kód chyby, _doserrno, _sys_errlist a _sys_nerr.

Podpora kódování Unicode

fopen_spodporuje datové proudy souboru ve formátu Unicode.Chcete-li otevřít novou nebo existující soubor ve formátu Unicode, předejte ccs příznak, který určuje požadované kódování fopen_s:

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

Allowed values of encoding are UNICODE, UTF-8, and UTF-16LE.Pokud není zadána žádná hodnota pro encoding, fopen_s používá kódování ANSI.

Pokud soubor již existuje a je otevřen pro čtení nebo připojením, Byte pořadí značka (BOM), pokud je k dispozici v souboru Určuje kódování.Kódování Kusovníku přednost přes kódování, který je určen ccs příznak.ccs Kódování se používá pouze při žádné Kusovníku je současné nebo pokud je soubor nový soubor.

[!POZNÁMKA]

Detekce Kusovníku se vztahuje pouze na soubory, které jsou otevírány v režimu podporujícím kódování Unicode; To znamená po předání ccs příznak.

Následující tabulka shrnuje způsoby pro různé ccs příznaky, které jsou uvedeny na fopen_s a Byte pořadí značek v souboru.

Kódování použité na základě ccs příznak a Kusovníku

ccsPříznak	Žádné Kusovníku (nebo nový soubor)	KUSOVNÍK: UTF-8	KUSOVNÍK: 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

Soubory, které jsou otevřeny pro psaní v režimu podporujícím kódování Unicode mají Kusovníku automaticky zapisovat na ně.

Pokud mode je "a, ccs=<encoding>", fopen_s nejprve pokusí otevřít soubor s přístup pro čtení a zápis.V případě úspěchu funkce přečte Kusovníku k určení kódování souboru; Pokud neúspěšně, využívá funkce výchozí kódování souboru.V obou případech fopen_s pak komprimována souboru s přístupem jen pro zápis.(To platí pro a pouze, není v režimu a+.)

Mapování rutiny obecného textu

TCHAR.Byla zahájena rutina h	_UNICODE & _MBCS není definováno	_MBCS, definice	_UNICODE definována
_tfopen_s	fopen_s	fopen_s	_wfopen_s

Řetězec znaků mode Určuje typ přístupu, který je požadováno pro soubor, takto.

"r"
Otevře pro čtení.Pokud soubor neexistuje nebo nemůže být nalezen fopen_s volání se nezdaří.
"w"
Otevře prázdný soubor pro zápis.Pokud soubor existuje, jeho obsah jsou zničeny.
"a"
Otevře se pro zápis na konci souboru (připojení), aniž byste odebrali značku EOF před zápisem nových dat do souboru.V případě, že neexistuje, vytvoří se soubor.
"r+"
Otevře pro čtení i zápis.(Soubor musí existovat.)
"w+"
Otevře prázdný soubor pro čtení i zápis.Pokud soubor existuje, jeho obsah jsou zničeny.
"a+"
Otevře pro čtení a přidávání.Operace připojení zahrnuje odstranění značku EOF před nová data zapsána do souboru a značku EOF je obnoven po dokončení zápisu.V případě, že neexistuje, vytvoří se soubor.

Při otevření souboru pomocí "a" nebo "a+" přístupu k typu, všechny zapisovat operací dojít na konci souboru.Ukazatel souboru můžete přemístit pomocí fseek nebo rewind, ale je vždy přesunuta zpět na konec souboru dříve, než některý zápisu, operace se provádí tak, že nelze přepsat existující data.

"a" Režimu nedojde k odebrání značky EOF před připojením k souboru.Poté, co došlo k připojení, příkaz systému MS-DOS TYPE zobrazí pouze data do původní značku EOF a není žádná data, která je přidána do souboru."a+" Režimu odebrat značku EOF před připojením k souboru.Po připojení, zobrazí příkaz systému MS-DOS zadejte všechna data v tomto souboru."a+" Režim je vyžadován pro přidávání soubor datového proudu, která je ukončena pomocí značky CTRL + Z EOF.

Když "r+","w+", nebo "a+" je určen typ přístupu, je povoleno čtení i zápis. (Soubor se říká otevřen pro "update".) Avšak po přepnutí z čtení k psaní vstupní operace musí nastat značku EOF.Pokud není k dispozici žádné EOF, je nutné použít požadovanými volání funkce umístění souboru.Funkce umístění souboru jsou fsetpos, fseek, a rewind.Přepnete-li se v zápisu ke čtení, je nutné použít požadovanými volání buď fflush nebo funkci umístění souboru.

Kromě výše uvedených hodnot lze zahrnout následující znaky v mode Chcete-li určit režim překladu pro znaky nového řádku:

t
Otevřít jako text (překlad) režimu.V tomto režimu je interpretován CTRL + Z jako znak konce souboru na vstupu.V souborech otevřen pro čtení nebo zápis s "a+", fopen_s kontroluje CTRL + Z na konci souboru a odstraní jej, pokud je to možné.Je důvodem, že pomocí fseek a ftell k přesunům v souboru, který má na konci CTRL + Z, může způsobit, že fseek se chovají nesprávně poblíž konce souboru.

Také v textovém režimu, přepravu return–linefeed kombinace jsou přeloženy do jediného přečtené na vstupu a znaky konce řádku jsou převedeny na přepravu return–linefeed kombinace na výstupu.Po proudu I/O funkci Unicode pracuje v textovém režimu (výchozí), zdroj nebo cílový datový proud považován za posloupnost vícebajtových znaků.Proto funkce Unicode vstupní proud převést vícebajtových znaků na široké znaky (jako Pokud voláním mbtowc funkce).Ze stejného důvodu Unicode datový proud výstupu funkce převést široké znaky na vícebajtové znaky (jako Pokud voláním wctomb funkce).

b
V binárním režimu (nepřeložený); překlady zahrnující znaky carriage return a linefeed potlačeny.

Pokud t nebo b není uveden v mode, globální proměnná je definována výchozí režim překladu _fmode.Pokud t nebo b je předponou argument, funkce se nezdaří a vrátí NULL.

Další informace o použití textu a binární režim v Unicode a vícebajtové datový proud I/O, viz textu a binární režim souboru v/v a Vstupně -výstupního proudu Unicode v textu a binární režim.

c
Povolit potvrzení příznak přidružených filename tak, aby obsah vyrovnávací paměti souboru zapsány přímo na disk v případě obou fflush nebo _flushall je volána.
n
Obnovit příznak potvrzení přidružených filename "potvrzení č." Toto nastavení je výchozí.Také přepisuje příznak globálního potvrzení, pokud propojíte váš program s COMMODE.OBJ.Výchozí příznak globálního potvrzení je "Ne potvrzení", není-li explicitně propojit váš program s COMMODE.OBJ (see Možnosti propojení).
N
Určuje, že soubor není děděna podřízenými procesy.
S
Určuje, že ukládání do mezipaměti je optimalizována pro, ale nejsou omezeny na sekvenční přístup z disku.
R
Určuje, že ukládání do mezipaměti je optimalizována pro, ale nejsou omezeny na random access z disku.
T
Určuje jako dočasný soubor.Pokud je to možné, nejsou zapsány na disk.
D
Určuje jako dočasný soubor.Odstraní se při zavření poslední ukazatel souboru.
ccs=ENCODING
Určete sada kódovaných znaků použít pro tento soubor (UTF-8, UTF-16LE a UNICODE).Nechte to neuvedete, pokud chcete, aby kódování ANSI.

Platné znaky pro mode řetězec používaný v fopen_s a _fdopen odpovídají oflag argumenty použité v _Otevřít b a _sopen, takto.

Znaky v řetězci režimu	Rovnocenné oflag hodnotu pro _open/_sopen
a	_O_WRONLY \| _O_APPEND(usually _O_WRONLY \| _O_CREAT \|_O_APPEND)
a+	_O_RDWR \| _O_APPEND(usually _O_RDWR \| _O_APPEND \| _O_CREAT )
r	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY(usually _O_WRONLY \|_O_CREAT \| _O_TRUNC)
w+	_O_RDWR(usually _O_RDWR \| _O_CREAT \| _O_TRUNC)
b	_O_BINARY
t	_O_TEXT
c	Žádná
n	Žádná
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

Používáte-li rb režimu, nebudou muset port vašeho kódu a očekávají čtení velkého souboru a/nebo není nakonfigurováno o výkonu sítě, Win32 soubory mapované paměti může být také možnost.

Požadavky

Function	Požadované záhlaví
fopen_s	<stdio.h>
_wfopen_s	<stdio.h> nebo <wchar.h>

Další informace o kompatibilitě, viz Compatibility v úvodu.

Knihovny

Všechny verze C run-time libraries.

c, n, A tmode jsou možnosti rozšíření společnosti Microsoft pro fopen_s a _fdopen a neměl by sloužit, kde je žádoucí přenositelnost ANSI.

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