fopen_s, _wfopen_s

Otevře soubor.Tyto verze fopen, _wfopen mají rozšíření zabezpečení popsaná v tématu 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

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

• [in] filename
  Název souboru.

• [in] mode
  Typ oprávněného přístupu.

Vrácená hodnota

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

Chybové podmínky

pFile	filename	mode	Návratová hodnota	Obsah ukazatelepFile
NULL	any	any	EINVAL	beze změny
any	NULL	any	EINVAL	beze změny
any	any	NULL	EINVAL	beze změny

Poznámky

Soubory otevřené strukturami fopen_s a _wfopen_s nelze sdílet.Požadujete-li, aby soubor bylo možné sdílet, použijte struktury _fsopen, _wfsopen s příslušnou konstantou režimu sdílení, například _SH_DENYNO pro sdílení pro čtení a zápis.

Funkce fopen_s otevře soubor zadaný parametrem filename._wfopen_s je širokoznaká verze fopen_s. Argumenty pro _wfopen_s jsou širokoznaké řetězce._wfopen_s a fopen_s se jinak chovají stejně.

Funkce fopen_s přijímá cesty platné v systému souborů v bodě spuštění. Cesty UNC a cesty zahrnující mapované síťové disky lze ve funkci fopen_s použít, pokud systém, který kód vykonává, má v době spuštění ke sdílenému prostředku nebo mapovanému síťovému disku přístup.Při vytváření cest pro funkci fopen_s nepředpokládejte dostupnost disků, cest nebo síťových sdílených prostředků v prostředí spuštění.Jako oddělovač v cestě je možné použít buď lomítka (/), nebo zpětná lomítka (\).

Tyto funkce ověřují své parametry.Byl-li parametru pFile, filename nebo mode předán ukazatel na typ null, vygenerují tyto funkce výjimku neplatného parametru tak, jak je popsáno v tématu Ověření parametru.

Před provedením jakékoliv další operace se souborem je třeba se ujistit, zda funkce proběhla úspěšně.Dojde-li k chybě, je vrácen chybový kód a nastavena globální proměnná errno.Další informace naleznete v tématu errno, _doserrno, _sys_errlist, and _sys_nerr.

Podpora kódování Unicode

Funkce fopen_s podporuje datové proudy souborů typu Unicode.Chcete-li otevřít nový nebo existující soubor Unicode, předejte funkci fopen_s příznak ccs, který určuje požadované kódování:

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

Povolené hodnoty parametru encoding jsou UNICODE, UTF-8 a UTF-16LE.Není-li parametru encoding zadána žádná hodnota, funkce fopen_s použije kódování ANSI.

Pokud soubor již existuje a je otevřen v režimu čtení nebo zobrazení, pak, pokud je v souboru přítomno, určí kódování Označení pořadí bajtů (BOM).BOM kódování má přednost před kódováním, které je zadáno parametrem ccs.Kódování ccs je použito pouze, pokud není přítomno označení BOM nebo pokud se jedná o nový soubor.

[!POZNÁMKA]

Detekce BOM je aplikována pouze pro soubory, které jsou otevřeny v módu Unicode (tj. zadáním příznaku ccs).

Následující tabulka shrnuje režimy pro různé parametry ccs předané funkci fopen_s a pro Označení pořadí bajtů v rámci souboru.

Kódování použitá na základě parametru ccs a BOM

Parametr ccs	Žádný BOM (nebo nový soubor)	BOM: UTF-8	BOM: 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 otevřené pro zápis v módu Unicode mají automaticky zapsaný BOM.

Pokud je mode "a, ccs=<encoding>", pak se fopen_s nejdříve pokusí otevřít soubor s přístupem pro zápis i čtení.Pokud se toto povede, funkce přečte označení BOM a určí kódování souboru. Pokud ne, použije funkce pro soubor výchozí kódování.V obou případech funkce fopen_s znovu otevře soubor pouze pro zápis. (Toto se týká pouze režimu a, nikoliv režimu a+.)

Rutinní mapování obecného textu

Rutina TCHAR.H	_UNICODE & _MBCS není definováno	_MBCS definováno	_UNICODE definováno
_tfopen_s	fopen_s	fopen_s	_wfopen_s

Řetězec znaků mode určuje druh přístupu, který je vyžadován pro přístup k souboru.

• "r"
  Otevře pro čtení.Pokud soubor neexistuje nebo nemůže být nalezen, volání fopen_s se nezdaří.

• "w"
  Otevře prázdný soubor pro zápis.Pokud soubor existuje, je jeho obsah zničen.

• "a"
  Otevře v režimu zápisu na konci souboru (přidáním), aniž by byla před zápisem do souboru odebrána značka EOF.Pokud soubor neexistuje, vytvoří jej.

• "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, je jeho obsah zničen.

• "a+"
  Otevře pro čtení a zobrazení.Operace přidání zahrnuje odstranění značky EOF před zápisem nových dat do souboru a její obnovení po dokončení zápisu.Pokud soubor neexistuje, vytvoří jej.

Pokud je soubor otevřen použitím přístupového typu "a" nebo "a+", objeví se všechny operace zápisu na konci souboru.Ukazatel souboru lze přesunout pomocí funkce fseek nebo rewind, před jakoukoliv operací zápisu je však vždy přesunut na konec souboru, aby nemohla být přepsána existující data.

Režim "a" neodstraní značku EOF před připojením k souboru.Po připojení zobrazí příkaz MS-DOS TYPE pouze data do původní značky EOF, nikoliv data, která byla k souboru připojena.Režim "a+" odstraní značku EOF před připojením k souboru.Po připojení zobrazí příkaz MS-DOS TYPE všechna data v souboru.Pro soubor datového proudu, který je přerušen použitím značky EOF CTRL+Z, je pro připojení vyžadován režim "a+".

Pokud je zadán přístupový typ "r+",, "w+", nebo "a+", je povoleno čtení i zápis. (Soubor je označen jako otevřený pro "aktualizaci".) Avšak po přepnutí ze čtení na zápis musí vstupní operace narazit na značku EOF.Pokud není dostupný žádná značka EOF, je třeba použít opětovné volání funkce polohování souboru.Funkce polohování souboru jsou fsetpos, fseek a rewind.Po přepnutí ze zápisu na čtení je třeba použít opětovné volání na fflush nebo na funkci polohování souboru.

Kromě hodnot výše mohou být pro určení režimu překladu pro znaky nového řádku zahrnuty následující znaky v režimu mode:

• t
  Otevřít v textovém (přeloženém) režimu.V tomto režimu je CTRL+Z interpretováno jako znak end-of-file na vstupu.V rámci souborů, které jsou otevřeny pro čtení a zápis v režimu "a+", vyhledá funkce fopen_s znak CTRL+Z na konci souboru a pokud je to možné, odstraní jej.Toto je provedeno, protože použití funkce fseek a ftell pro přesun v rámci souboru, který končí CTRL+Z, může způsobit neočekávané chování funkce fseek v blízkosti konce souboru.

V textovém režimu jsou také kombinace typu návrat na začátek řádku a znak odřádkování přeloženy na vstupu jako znak odřádkování a znaky odřádkování jsou na výstupu přeloženy na kombinace typu návrat na začátek řádku a znak odřádkování.Pokud pracuje funkce se vstupně-výstupním datovým proudem sady Unicode v textovém režimu (výchozí), je zdrojový nebo cílový datový proud brán jako sekvence vícebajtových znaků.A proto funkce se vstupním datovým proudem sady Unicode mění vícebajtové znaky na široké znaky (jako by tomu bylo u volání funkce mbtowc).Ze stejného důvodu mění funkce se vstupním datovým proudem sady Unicode široké znaky na vícebajtové znaky (jako by tomu bylo u volání funkce wctomb).

• b
  Otevřít v binárním (nepřeloženém) režimu; překlady typů návrat na začátek řádku a znak odřádkování jsou potlačeny.

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

Další informace o použití textových a binárních režimů v rámci sady Unicode a vícebajtových vstupně-výstupních datových proudů naleznete v tématech Vstupy a výstup souborů v textovém a binárním režimu a Vstupy a výstupy datových proudů Unicode v textovém a binárním režimu.

• c
  Pro přidružený filename povolte parametr pro zápis, aby byl obsah vyrovnávací paměti souboru zapsán přímo na disk při zavolání fflush nebo _flushall.

• n
  Resetovat parametr pro zápis pro přidružený filename na "neukládat". Toto nastavení je výchozí.Po propojení programu s COMMODE.OBJ přepíše také globální parametr pro zápis.Výchozí hodnota pro globální parametr pro zápis je "neukládat", pokud výslovně nedojde k propojení s COMMODE.OBJ (viz Možnosti odkazů).

• N
  Určuje, zda je soubor zděděný podřízenými procesy.

• S
  Určuje, zda je mezipaměť optimalizovaná, ale nikoliv omezená pro disk se sekvenčním přístupem.

• R
  Určuje, zda je mezipaměť optimalizovaná, ale nikoliv omezená pro disk s náhodným přístupem.

• T
  Označí soubor jako dočasný.Pokud je to možné, není zapsán na disk.

• D
  Označí soubor jako dočasný.Je smazán po uzavření posledního ukazatele na soubor.

• ccs=ENCODING
  Určete kódovanou znakovou sadu (UTF-8, UTF-16LE a UNICODE), která má být použita pro tento soubor.Ponechte nevyplněné, pokud chcete používat kódování ANSI.

Platné znaky pro řetězec mode, který je použitý v rámci fopen_s a _fdopen odpovídá argumentům oflag, které jsou použity v _open a _sopen.

Znaky v řetězci režimu	Ekvivalentní hodnota oflag 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
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 režim rb, nepotřebujete-li přizpůsobit kód, očekáváte-li čtení velké části souboru a/nebo nemusíte-li se obávat o výkon sítě, lze také zvážit použití souborů Win32 mapovaných do paměti.

Požadavky

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

Další informace o kompatibilitě naleznete v úvodu tématu Kompatibilita.

Knihovny

Všechny verze běhových knihoven C.

Možnosti c, n a t režimu mode jsou rozšířeními funkce fopen_s a _fdopen společnosti Microsoft a měly by být použity tam, kde je požadována 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 );
}

Ekvivalent v rozhraní .NET Framework

• System::IO::file::Open

• System::IO::FileStream::FileStream

Viz také

Referenční dokumentace

I/O proudu

fclose, _fcloseall

_fdopen, _wfdopen

ferror

_fileno

freopen, _wfreopen

_open, _wopen

_setmode