fopen, _wfopen

Otevře soubor. K dispozici jsou bezpečnější verze těchto funkcí, které provádějí více ověření parametrů a návratové kódy chyb; viz fopen_s, _wfopen_s.

Syntaxe

FILE *fopen(
   const char *filename,
   const char *mode
);
FILE *_wfopen(
   const wchar_t *filename,
   const wchar_t *mode
);

Parametry

filename
Název souboru

mode
Druh přístupu, který je povolený.

Vrácená hodnota

Každá z těchto funkcí vrátí ukazatel na otevřený soubor. Hodnota ukazatele null označuje chybu. Pokud filename nebo je nebo je NULL prázdný mode řetězec, tyto funkce aktivují neplatnou obslužnou rutinu parametru, která je popsána v ověření parametru. Pokud provádění může pokračovat, tyto funkce se vrátí NULL a nastaví errno na EINVAL.

Další informace naleznete v tématu errno, _doserrno, _sys_errlista _sys_nerr.

Poznámky

Funkce fopen otevře soubor určený .filename Ve výchozím nastavení se úzký filename řetězec interpretuje pomocí znakové stránky ANSI (CP_ACP). V desktopových aplikacích pro Windows je možné ji změnit na znakovou stránku OEM (CP_OEMCP) pomocí SetFileApisToOEM funkce. Pomocí funkce můžete AreFileApisANSI určit, jestli filename se interpretuje pomocí ANSI nebo výchozí systémové znakové stránky OEM. _wfopen je verze širokého znaku fopen; _wfopen argumenty jsou řetězce širokého znaku. _wfopen V opačném případě se fopen chovejte stejně. Použití _wfopen nemá vliv na zakódovanou znakovou sadu, která se používá ve streamu souborů.

fopen přijímá cesty platné v systému souborů v okamžiku spuštění; fopen přijímá cesty UNC a cesty, které zahrnují mapované síťové jednotky, pokud systém, který spouští kód, má přístup ke sdílené nebo mapované jednotce v době provádění. Při vytváření cest pro fopen, ujistěte se, že jednotky, cesty nebo síťové sdílené složky jsou k dispozici 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 (\).

Před provedením jakýchkoli dalších operací se souborem vždy zkontrolujte návratové hodnoty, abyste zjistili, jestli je ukazatel null. Pokud dojde k chybě, nastaví se globální proměnná errno a může být použita k získání konkrétních informací o chybě. 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 podporuje streamy souborů Unicode. Chcete-li otevřít soubor Unicode, předejte ccs=encoding příznak, který určuje požadované kódování , fopennásledujícím způsobem.

FILE *fp = fopen("newfile.txt", "rt+, ccs=UTF-8");

Povolené hodnoty pro ccs kódování jsou UNICODE, UTF-8a UTF-16LE.

Když je soubor otevřen v režimu Unicode, vstupní funkce přeloží data načtená ze souboru do dat UTF-16 uložených jako typ wchar_t. Funkce, které zapisují do souboru otevřeného v režimu Unicode, očekávají vyrovnávací paměti obsahující data UTF-16 uložená jako typ wchar_t. Pokud je soubor kódovaný jako UTF-8, při zápisu se data UTF-16 přeloží do UTF-8. Obsah souboru s kódováním UTF-8 se při čtení přeloží do UTF-16. Pokus o čtení nebo zápis lichého počtu bajtů v režimu Unicode způsobí chybu ověření parametru. Pokud chcete číst nebo zapisovat data uložená v programu jako UTF-8, použijte místo režimu Unicode textový nebo binární soubor. Zodpovídáte za jakýkoli požadovaný překlad kódování.

Pokud soubor již existuje a je otevřen pro čtení nebo připojení, určuje kódování jakákoli značka pořadí bajtů (BOM) 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 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 používané pro různé ccs příznaky zadané fopen v souboru a značky pořadí bajtů v souboru.

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

ccs vlajka	Bez kusovníku (nebo nového souboru)	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 otevřené pro zápis v režimu Unicode mají kód BOM, který se do nich zapisuje automaticky.

Pokud mode se jedná a, ccs=encoding o nějakou encoding hodnotu, fopen nejprve se pokusí soubor otevřít pomocí přístupu pro čtení i zápis. Pokud tato akce proběhne úspěšně, funkce přečte kusovník, aby určila kódování souboru. Pokud selže, funkce použije výchozí kódování souboru. V obou případech fopen soubor znovu otevřete pomocí přístupu jen pro zápis. (Toto chování platí jenom pro "a" režim, ne pro "a+" režim.)

Mapování rutin obecného textu

TCHAR.H rutina	_UNICODE a _MBCS není definován	_MBCS definovaný	_UNICODE definovaný
_tfopen	fopen	fopen	_wfopen

Ř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 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" přístupového typu nebo "a+" typu přístupu dojde ke všem operacím zápisu na konci souboru. Ukazatel souboru lze přemístit pomocí fseek nebo rewind, ale vždy se přesune zpět na konec souboru před provedením jakékoli operace zápisu. Existující data se proto nedají přepsat.

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 připojená k souboru. Než se připojí k souboru, "a+" režim odebere značku EOF. Po připojení příkaz MS-DOS TYPE zobrazí 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.

Je-li "r+"zadán typ přístupu , "w+"nebo "a+" čtení i zápis jsou povoleny (soubor je otevřen pro "aktualizaci"). Když ale přepnete z čtení na zápis, vstupní operace musí narazit na značku EOF. Pokud neexistuje žádný 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.

Kromě předchozích hodnot je možné k zadání režimu překladu pro znaky nového řádku připojit 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. Příkaz CTRL+Z je na vstupu interpretován 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 režimu CTRL+se Z při zadávání interpretuje jako znak EOF. V souborech, které jsou otevřeny pro čtení a zápis pomocí "a+", fopen zkontroluje CTRL+na konci souboru Z a odebere ho, pokud je to možné. 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 kombinace návratového řádku řádku (CRLF) přeloženy do znaků jednořádkového kanálu (LF) na vstupu a LF znaky jsou přeloženy na kombinace 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ů. Proto funkce zadávání datových proudů 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 tom, jak používat textové a binární režimy v kódování Unicode a multibajtové stream-I/O, naleznete v tématu Vstupně-výstupní a binární režim souboru textového a binárního režimu a vstupně-výstupních operací datového proudu Unicode v textových a binárních režimech.

K určení dalšího chování je možné připojit mode následující možnosti.

mode modifikátor	Chování
x	Vynutí, aby funkce selhala, pokud filename už existuje. Lze použít pouze se specifikátory "w" nebo "w+".
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 "no-commit", pokud program explicitně propojit s COMMODE. OBJ (viz možnosti propojení).
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=encoding	Určuje zakódovanou znakové sady, která se má pro tento soubor použít (jedna z UTF-8, UTF-16LEnebo UNICODE). Pokud chcete kódování ANSI, nechte nezadanou. Tento příznak je oddělený od příznaků, které před ním předchází čárkou (,). Příklad: FILE *f = fopen("newfile.txt", "rt+, ccs=UTF-8");

Platné znaky pro mode řetězec, který se používá fopen , 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)
x	_O_EXCL
c	Nic
n	Nic
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

Pokud používáte rb režim, nemusíte portovat svůj kód a pokud očekáváte, že budete číst většinu velkého souboru nebo se nezajímáte o výkon sítě, můžete také zvážit, jestli jako možnost použít soubory Win32 mapované paměti.

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 .

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

Požadavky

Function	Požadovaný hlavičkový soubor
fopen	<stdio.h>
_wfopen	<stdio.h> nebo <wchar.h>

_wfopen je rozšíření Microsoftu. Další informace o kompatibilitě naleznete v tématu Kompatibilita.

Možnosti c, , n, t, RTSa D mode jsou rozšíření Microsoftu pro fopen a _fdopen neměli by se používat tam, kde je požadovaná přenositelnost ANSI.

Příklad 1

Následující program otevře dva soubory. Slouží fclose k zavření prvního souboru a _fcloseall k zavření všech zbývajících souborů.

// crt_fopen.c
// compile with: /W3
// 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 )
{
   int numclosed;

   // Open for read (will fail if file "crt_fopen.c" does not exist)
   if( (stream  = fopen( "crt_fopen.c", "r" )) == NULL ) // C4996
   // Note: fopen is deprecated; consider using fopen_s instead
      printf( "The file 'crt_fopen.c' was not opened\n" );
   else
      printf( "The file 'crt_fopen.c' was opened\n" );

   // Open for write
   if( (stream2 = fopen( "data2", "w+" )) == NULL ) // C4996
      printf( "The file 'data2' was not opened\n" );
   else
      printf( "The file 'data2' was opened\n" );

   // Close stream if it is not NULL
   if( stream)
   {
      if ( fclose( stream ) )
      {
         printf( "The file 'crt_fopen.c' was not closed\n" );
      }
   }

   // All other files are closed:
   numclosed = _fcloseall( );
   printf( "Number of files closed by _fcloseall: %u\n", numclosed );
}

The file 'crt_fopen.c' was opened
The file 'data2' was opened
Number of files closed by _fcloseall: 1

Příklad 2

Následující program vytvoří soubor (nebo ho přepíše, pokud existuje), v textovém režimu, který má kódování Unicode. Potom zapíše do souboru dva řetězce a zavře ho. Výstup je soubor s názvem _wfopen_test.xml, který obsahuje data z výstupní části.

// crt__wfopen.c
// compile with: /W3
// This program creates a file (or overwrites one if
// it exists), in text mode using Unicode encoding.
// It then writes two strings into the file
// and then closes the file.

#include <stdio.h>
#include <stddef.h>
#include <stdlib.h>
#include <wchar.h>

#define BUFFER_SIZE 50

int main(int argc, char** argv)
{
    wchar_t str[BUFFER_SIZE];
    size_t  strSize;
    FILE*   fileHandle;

    // Create an the xml file in text and Unicode encoding mode.
    if ((fileHandle = _wfopen( L"_wfopen_test.xml",L"wt+,ccs=UNICODE")) == NULL) // C4996
    // Note: _wfopen is deprecated; consider using _wfopen_s instead
    {
        wprintf(L"_wfopen failed!\n");
        return(0);
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"<xmlTag>\n");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"</xmlTag>");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Close the file.
    if (fclose(fileHandle))
    {
        wprintf(L"fclose failed!\n");
    }
    return 0;
}

Viz také

Vstupně-výstupní operace streamu
Interpretace vícebajtových sekvencí znaků
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode
_sopen, _wsopen