`fopen`, `_wfopen`

Artikel
10/12/2023

Öffnet eine Datei. Sicherere Versionen dieser Funktionen, die mehr Parameterüberprüfung ausführen und Fehlercodes zurückgeben, sind verfügbar; siehe fopen_s, _wfopen_s.

Syntax

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

Parameter

filename
Dateiname.

mode
Art des Zugriffs, der aktiviert ist.

Rückgabewert

Jede dieser Funktionen gibt einen Zeiger auf die geöffnete Datei zurück. Ein NULL-Zeigerwert gibt einen Fehler an. Wenn filename oder mode eine leere Zeichenfolge ist NULL , lösen diese Funktionen den ungültigen Parameterhandler aus, der in der Parameterüberprüfung beschrieben wird. Wenn die weitere Ausführung zugelassen wird, geben diese Funktionen NULL zurück und stellen errno auf EINVAL ein.

Weitere Informationen finden Sie untererrno, _doserrno, _sys_errlistund _sys_nerr.

Hinweise

Die fopen Funktion öffnet die durch filename. Standardmäßig wird eine schmale filename Zeichenfolge mithilfe der ANSI-Codepage (CP_ACP) interpretiert. In Windows-Desktopanwendungen kann sie mithilfe der Funktion auf die SetFileApisToOEM OEM-Codepage (CP_OEMCP) geändert werden. Mit der AreFileApisANSI Funktion können Sie ermitteln, ob filename sie mithilfe der ANSI oder der standardmäßigen OEM-Codepage des Systems interpretiert wird. _wfopen ist eine Breitzeichenversion von fopen; die _wfopen Argumente sind Zeichenfolgen mit breitem Zeichen. Andernfalls verhalten sich _wfopen und fopen identisch. Die Verwendung _wfopen wirkt sich nicht auf den codierten Zeichensatz aus, der im Dateidatenstrom verwendet wird.

fopen akzeptiert Pfade, die zum Zeitpunkt der Ausführung im Dateisystem gültig sind. fopen akzeptiert UNC-Pfade und Pfade mit zugeordneten Netzlaufwerken, solange das System, das den Code ausführt, zum Zeitpunkt der Ausführung Zugriff auf die Freigabe oder das zugeordnete Netzlaufwerk hat. Stellen Sie beim Erstellen von Pfaden sicher fopen, dass Laufwerke, Pfade oder Netzwerkfreigaben in der Ausführungsumgebung verfügbar sind. Sie können schräge Schrägstriche (/) oder umgekehrte Schrägstriche (\) als Verzeichnistrennzeichen in einem Pfad verwenden.

Überprüfen Sie immer den Rückgabewert, um festzustellen, ob der Zeiger NULL ist, bevor Sie andere Vorgänge für die Datei ausführen. Wenn ein Fehler auftritt, wird die globale Variable errno festgelegt und kann verwendet werden, um bestimmte Fehlerinformationen zu erhalten. Weitere Informationen finden Sie untererrno, _doserrno, _sys_errlistund _sys_nerr.

Standardmäßig gilt der globale Zustand dieser Funktion für die Anwendung. Informationen zum Ändern finden Sie im Global state in the CRT.

Unicode-Unterstützung

fopen unterstützt Unicode-Dateistreams. Um eine Unicode-Datei zu öffnen, geben Sie ein ccs=encoding -Flag, das die gewünschte Codierung angibt, wie folgt an fopenweiter.

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

Zulässige Werte für ccs die Codierung sind UNICODE, UTF-8und UTF-16LE.

Wenn eine Datei im Unicode-Modus geöffnet wird, übersetzen die Eingabefunktionen die aus der Datei gelesenen Daten in UTF-16-Daten, die als Datentyp wchar_tgespeichert werden. Funktionen, die in eine im Unicode-Modus geöffnete Datei schreiben, erwarten Puffer, die UTF-16-Daten, die als Datentyp wchar_tgespeichert sind. Wenn die Datei als UTF-8 codiert ist, werden UTF-16-Daten beim Schreiben in UTF-8 übersetzt. Der UTF-8-codierte Inhalt der Datei wird beim Lesen in UTF-16 übersetzt. Der Versuch, eine ungerade Anzahl von Bytes im Unicode-Modus zu lesen oder zu schreiben, führt zu einem Parametervalidierungsfehler . Wenn Sie Daten lesen oder schreiben möchten, die in Ihrem Programm als UTF-8 gespeichert sind, verwenden Sie den Text- oder Binärdateienmodus anstelle eines Unicode-Modus. Sie sind für alle erforderlichen Codierungsübersetzungen verantwortlich.

Wenn die Datei bereits vorhanden ist und zum Lesen oder Anfügen geöffnet wird, bestimmt eine beliebige Bytereihenfolgemarke (BYTE Order Mark, BOM) in der Datei die Codierung. Die BOM-Codierung hat Vorrang vor der durch das ccs Flag angegebenen Codierung. Die ccs -Codierung wird nur verwendet, wenn keine BOM vorhanden ist oder wenn die Datei neu ist.

Hinweis

Die BOM-Erkennung gilt nur für Dateien, die im Unicode-Modus geöffnet sind (das heißt durch Übergeben des ccs -Flags).

Die folgende Tabelle fasst die Modi zusammen, die für verschiedene ccs -Flags für fopen sowie für die Bytereihenfolge-Marken in der Datei verwendet werden.

Auf ccs-Flag und BOM basierende Codierungen

`ccs` -Flag	Keine BOM (oder neue Datei)	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`

In Dateien, die zum Schreiben im Unicode-Modus geöffnet sind, wird automatisch eine BOM geschrieben.

Wenn mode es sich um einen encoding Wert handelta, ccs=encoding, versucht zuerst, fopen die Datei mit Lese- und Schreibzugriff zu öffnen. Wenn diese Aktion erfolgreich ist, liest die Funktion die BOM, um die Codierung für die Datei zu bestimmen. Wenn ein Fehler auftritt, verwendet die Funktion die Standardcodierung für die Datei. In beiden Fällen fopen wird die Datei mit schreibgeschütztem Zugriff erneut geöffnet. (Dieses Verhalten gilt nur für den "a" Modus, nicht für den "a+" Modus.)

Mapping generischer Textroutinen

`TCHAR.H`-Routine	`_UNICODE` und `_MBCS` nicht definiert	`_MBCS` definiert	`_UNICODE` definiert
`_tfopen`	`fopen`	`fopen`	`_wfopen`

Die Zeichenfolge mode gibt die Art des Zugriffs, der für die Datei angefordert wird, wie folgt an.

`mode`	Access
`"r"`	Öffnet zum Lesen. Wenn die Datei nicht vorhanden ist oder nicht gefunden werden kann, schlägt der `fopen` Aufruf fehl.
`"w"`	Öffnet eine leere Datei zum Schreiben. Wenn die angegebene Datei vorhanden ist, wird ihr Inhalt zerstört.
`"a"`	Wird vor dem Schreiben neuer Daten in die Datei zum Schreiben am Ende der Datei (Anfügen) geöffnet, ohne die EOF-Markierung (end-of-file, Dateiende) zu entfernen. Erstellt die Datei, wenn sie nicht vorhanden ist.
`"r+"`	Öffnet sowohl zum Lesen als auch zum Schreiben. Die Datei muss vorhanden sein.
`"w+"`	Öffnet eine leere Datei zum Lesen und Schreiben. Wenn die Datei vorhanden ist, wird ihr Inhalt zerstört.
`"a+"`	Öffnet sich zum Lesen und Anfügen. Der Anfügevorgang umfasst das Entfernen der EOF-Markierung, bevor neue Daten in die Datei geschrieben werden. Die EOF-Markierung wird nach Abschluss des Schreibens nicht wiederhergestellt. Erstellt die Datei, wenn sie nicht vorhanden ist.

Bei einer mit dem Zugriffstyp "a" oder "a+" geöffneten Datei erfolgen alle Schreibvorgänge am Ende der Datei. Der Dateizeiger kann mit fseek oder rewindneu angeordnet werden, er wird jedoch immer wieder zurück an das Ende der Datei verschoben, bevor ein Schreibvorgang durchgeführt wird. Daher können vorhandene Daten nicht überschrieben werden.

Der "a" Modus entfernt die EOF-Markierung nicht, bevor sie an die Datei angefügt wird. Nach dem Anfügen werden durch den MS-DOS-Befehl TYPE nur Daten bis zur ursprünglichen EOF-Markierung angezeigt, aber keine Daten, die an die Datei angefügt wurden. Bevor sie an die Datei angefügt wird, entfernt der "a+" -Modus die EOF-Markierung. Nach dem Anhängen werden mit dem Befehl MS-DOS TYPE alle Daten in der Datei angezeigt. Der "a+" Modus ist für das Anfügen an eine Streamdatei erforderlich, die mit demCTRL+ Z EOF-Marker beendet wird.

Wenn als Zugriffstyp "r+", "w+"oder "a+" angegeben wird, sind sowohl Lese- als auch Schreibvorgänge zulässig (die Datei ist zum Aktualisieren geöffnet). Wenn Sie jedoch vom Lesevorgang in den Schreibvorgang wechseln, muss die Eingabeoperation eine EOF-Markierung antreffen. Wenn kein EOF vorhanden ist, müssen Sie einen dazwischen liegenden Aufruf einer Dateipositionierungsfunktion verwenden. Die dateipositionierenden Funktionen sind fsetpos, fseekund rewind. Wenn Sie vom Schreibvorgang in den Lesevorgang wechseln, müssen Sie einen zwischenzeitlichen Aufruf von fflush oder einer dateipositionierenden Funktion ausführen.

Neben früheren Werte können die folgenden Zeichen an mode angefügt werden, um den Übersetzungsmodus für Zeilenumbruchzeichen anzugeben.

`mode`-Modifizierer	Übersetzungsmodus
`t`	Öffnen im Textmodus (übersetzt). Wagenrücklauflinieneinzugskombinationen (CR-LF) werden in einzeilige Feeds (LF) für Eingabe- und LF-Zeichen in CR-LF-Kombinationen für die Ausgabe übersetzt. Außerdem wird STRG+Z bei der Eingabe als EOF-Zeichen interpretiert.
`b`	Im Binärmodus (nicht translatiert) öffnen; Übersetzungen mit Wagenrücklauf- und Zeilenvorschubzeichen werden unterdrückt.

Im Textmodus CTRL+wird Z als EOF-Zeichen für die Eingabe interpretiert. In Dateien, die mithilfe von "a+"Lese-/Schreibvorgängen geöffnet werden, fopen wird am Ende der Datei nach ZCTRL+ gesucht und entfernt, sofern dies möglich ist. Sie wird entfernt, da die Verwendung fseek und ftell das Verschieben in einer Datei, die mit CTRL+Z endet, dazu führen fseek kann, dass sich das Verhalten am Ende der Datei falsch verhält.

Im Textmodus werden Wagenrücklaufeinzugskombinationen (CRLF) in Einfügezeichen (Single Line Feed, LF) für Eingaben übersetzt, und LF-Zeichen werden in CRLF-Kombinationen für die Ausgabe übersetzt. Wenn eine Stream-E/A-Funktion von Unicode im Textmodus (Standard) funktioniert, wird angenommen, dass es sich bei Quell- oder Zielstream um eine Sequenz von Multibytezeichen handelt. Daher konvertieren die Unicode Streameingabefunktionen Multibytezeichen in Breitzeichen (wie bei einem Aufruf der mbtowc -Funktion). Aus demselben Grund konvertieren die Unicode-Streamausgabefunktionen Breitzeichen in Multibytezeichen (wie bei einem Aufruf der wctomb -Funktion).

Wenn t oder b nicht angegeben modewird, wird der Standardübersetzungsmodus durch die globale Variable _fmodedefiniert. Wenn dem Argument t oder b vorangestellt wird, schlägt die Funktion fehl und gibt NULLzurück.

Weitere Informationen zur Verwendung von Text- und Binärmodi in Unicode und Multibyte stream-I/O finden Sie unter "Text- und Binärmodusdatei-E/A " und "Unicode-Datenstrom-E/A" im Text- und Binärmodus.

Die folgenden Optionen können angefügt werden, mode um weitere Verhaltensweisen anzugeben.

`mode`-Modifizierer	Behavior
`x`	Erzwingt, dass die Funktion fehlschlägt, wenn `filename` sie bereits vorhanden ist. Kann nur mit den Bezeichnern "w" oder "w+" verwendet werden.
`c`	Aktivieren Sie das Commitflag für den zugeordneten Parameter `filename` , sodass der Inhalt des Dateipuffers direkt auf einen Datenträger geschrieben wird, wenn `fflush` oder `_flushall` aufgerufen wird.
`n`	Setzen Sie das Commit-Flag für das zugeordnete `filename` "no-commit" zurück. Dieses Kennzeichen ist die Standardeinstellung. Dabei wird auch das globale Commitflag überschrieben, wenn Sie das Programm mit COMMODE.OBJ verknüpfen. Der Standardwert für das globale Commit-Flag lautet "no-commit", es sei denn, Sie verknüpfen Ihr Programm explizit mit COMMODE. OBJ (siehe Linkoptionen).
`N`	Gibt an, dass die Datei nicht von untergeordneten Prozessen geerbt wird.
`S`	Gibt an, dass das Zwischenspeichern für den sequenziellen Zugriff vom Datenträger optimiert, aber nicht darauf beschränkt ist.
`R`	Gibt an, dass das Zwischenspeichern für den zufälligen Zugriff vom Datenträger optimiert, aber nicht darauf beschränkt ist.
`T`	Gibt eine Datei an, die nicht auf den Datenträger geschrieben wird, es sei denn, der Arbeitsspeicherdruck erfordert sie.
`D`	Gibt eine temporäre Datei an, die beim Schließen des letzten Dateizeigers gelöscht wird.
`ccs=encoding`	Gibt den codierten Zeichensatz an, der (einer von `UTF-8`, `UTF-16LE`oder `UNICODE`) für diese Datei verwendet werden soll. Machen Sie keine Angabe, wenn Sie ANSI-Codierung wünschen. Diese Kennzeichnung wird von Flags getrennt, die einem Komma (`,`) vorangehen. Beispiel: `FILE *f = fopen("newfile.txt", "rt+, ccs=UTF-8");`

Gültige Zeichen für die Zeichenfolge, die mode verwendet fopen wird und _fdopen den oflag Argumenten entspricht, die in _open und _sopen, wie folgt verwendet werden.

Zeichen in der `mode`-Zeichenfolge	Der entsprechende `oflag` -Wert für `_open`/`_sopen`
`a`	`_O_WRONLY \| _O_APPEND` (meistens `_O_WRONLY \| _O_CREAT \| _O_APPEND`)
`a+`	`_O_RDWR \| _O_APPEND` (meistens `_O_RDWR \| _O_APPEND \| _O_CREAT` )
`r`	`_O_RDONLY`
`r+`	`_O_RDWR`
`w`	`_O_WRONLY` (meistens `_O_WRONLY \| _O_CREAT \| _O_TRUNC`)
`w+`	`_O_RDWR` (meistens `_O_RDWR \| _O_CREAT \| _O_TRUNC`)
`b`	`_O_BINARY`
`t`	`_O_TEXT` (übersetzt)
`x`	`_O_EXCL`
`c`	Keine
`n`	Keine
`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`

Wenn Sie den Modus verwenden rb , müssen Sie Ihren Code nicht portieren. Wenn Sie davon ausgehen, dass sie die meisten großen Dateien lesen oder sich nicht um die Netzwerkleistung kümmern, können Sie auch überlegen, ob Sie win32-Dateien als Option verwenden möchten.

Bezüglich T und D:

T verhindert, dass die Datei auf den Datenträger geschrieben wird, solange kein Arbeitsspeicherdruck erforderlich ist. Weitere Informationen finden Sie in FILE_ATTRIBUTE_TEMPORARY Datei-Attributkonstanten und auch in diesem Blogbeitrag Es ist nur temporär.
D Gibt eine normale Datei an, die auf den Datenträger geschrieben wird. Der Unterschied besteht darin, dass sie beim Schließen automatisch gelöscht wird. Sie können kombinieren TD , um beide Semantik abzurufen.

Die c, n, , SR, t, TD mode und Optionen sind Microsoft-Erweiterungen für fopen und _wfopen sollten nicht verwendet werden, wenn Sie ANSI-Portabilität wünschen.

Anforderungen

Funktion	Erforderlicher Header
`fopen`	`<stdio.h>`
`_wfopen`	`<stdio.h>` oder `<wchar.h>`

_wfopen ist eine Microsoft-Erweiterung. Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Die Microsoft-Erweiterungen SRD nTmode tund -Optionen sind die cMicrosoft-Erweiterungen fopen und _fdopen sollten nicht verwendet werden, wenn die ANSI-Portabilität gewünscht wird.

Beispiel 1

Das folgende Programm öffnet zwei Dateien. Es verwendet fclose , um die erste Datei zu schließen, und _fcloseall , um alle übrigen Dateien zu schließen.

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

Beispiel 2

Das folgende Programm erstellt eine Datei (oder überschreibt eine, sofern vorhanden) im Textmodus mit Unicode-Codierung. Anschließend schreibt es zwei Zeichenfolgen in die Datei und schließt sie. Die Ausgabe ist eine Datei mit dem Namen _wfopen_test.xml, die die Daten aus dem Ausgabeabschnitt enthält.

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

Siehe auch

Stream-E/A
Interpretation von Multibytezeichensequenzen
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode
_sopen, _wsopen

Freigeben über

`fopen`, `_wfopen`

Syntax

Parameter

Rückgabewert

Hinweise

Unicode-Unterstützung

Auf ccs-Flag und BOM basierende Codierungen

Mapping generischer Textroutinen

Anforderungen

Beispiel 1

Beispiel 2

Siehe auch

Feedback

Zusätzliche Ressourcen

Freigeben über

fopen, _wfopen

Syntax

Parameter

Rückgabewert

Hinweise

Unicode-Unterstützung

Auf ccs-Flag und BOM basierende Codierungen

Mapping generischer Textroutinen

Anforderungen

Beispiel 1

Beispiel 2

Siehe auch

Feedback

Zusätzliche Ressourcen

`fopen`, `_wfopen`