fopen, _wfopen

Öffnet eine Datei. Sicherere Versionen dieser Funktionen sind verfügbar. Informationen dazu finden Sie unter fopen_s, _wfopen_s.

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 modeNULL oder eine leere Zeichenfolge ist, lösen diese Funktionen den Handler für ungültige Parameter aus, der in Parametervalidierung 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 unter errno, _doserrno, _sys_errlist und _sys_nerr.

Hinweise

Die fopen-Funktion öffnet die Datei, die von filename angegeben wird. _wfopen ist eine Breitzeichenversion von fopen. Die Argumente für _wfopen sind Zeichenfolgen mit Breitzeichen. Andernfalls verhalten sich _wfopen und fopen identisch. Wenn nur _wfopen verwendet wird, hat dies keine Auswirkungen auf den codierten Zeichensatz, der im Dateistream 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. Wenn Sie Pfade für fopen erstellen, überprüfen Sie, ob Laufwerke, Pfade oder Netzwerkfreigaben in der Ausführungsumgebung verfügbar sind. Als Verzeichnistrennzeichen in einem Pfad können Sie entweder den Schrägstrich (/) oder den umgekehrten Schrägstrich (\) verwenden.

Überprüfen Sie stets den Rückgabewert, um festzustellen, ob der Zeiger NULL ist, bevor Sie weitere Vorgänge mit der Datei ausführen. Wenn ein Fehler auftritt, wird die globale Variable errno festgelegt. Sie kann verwendet werden, um bestimmte Fehlerinformationen abzurufen. Weitere Informationen finden Sie unter errno, _doserrno, _sys_errlist und _sys_nerr.

Unterstützung für Unicode

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

fopen(&fp, "newfile.txt", "rt+, ccs=encoding");

Zulässige Werte von encoding sind UNICODE, UTF-8 und 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_t gespeichert werden. Funktionen, die in eine im Unicode-Modus geöffnete Datei schreiben, erwarten Puffer, die UTF-16-Daten, die als Datentyp wchar_t gespeichert sind. Wenn eine Datei als UTF-8 kodiert ist, dann werden UTF-16-Daten beim Schreiben in UTF-8 übersetzt, und die UTF-8-kodierten Inhalte der Datei werden beim Lesen in UTF-16 übersetzt. Der Versuch, in diesem Modus eine ungerade Anzahl von Bytes in Unicode 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 jede erforderliche Kodierungsübersetzung verantwortlich.

Wenn die Datei bereits vorhanden ist und zum Lesen oder Anhängen geöffnet ist, bestimmt die Bytereihenfolge-Marke (BOM), sofern in der Datei vorhanden, 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.

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.

Verwendete Codierungen auf Grundlage von ccs-Flag und BOM

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

Wenn mode "a, ccs=<encoding>" ist, versucht fopen zuerst, die Datei mit Lesezugriff und Schreibzugriff zu öffnen. Ist der Vorgang erfolgreich, liest die Funktion die BOM, um die Codierung für die Datei zu bestimmen. Schlägt der Vorgang fehl, verwendet die Funktion die Standardcodierung für die Datei. In jedem Fall öffnet fopen dann die Datei nur mit Schreibzugriff erneut. (Dies gilt nur für den a-Modus, nicht für den a+-Modus.)

Zuordnung generischer Textroutinen

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

• "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 Schreibvorgangs 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 rewind neu 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 Modus "a" 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 Modus "a+" ist für das Anfügen von Daten an eine Streamdatei erforderlich, die mit der EOF-Markierung STRG+Z 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 keine EOF-Markierung vorhanden ist, müssen Sie einen zwischenzeitlichen Aufruf einer dateipositionierenden Funktion verwenden. Die dateipositionierenden Funktionen sind fsetpos, fseek und 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.

• t
  Öffnen im Textmodus (übersetzt). In diesem Modus wird STRG+Z als EOF-Zeichen bei Eingabe interpretiert. In den Dateien, die für das Lesen/Schreiben mit "a+" geöffnet sind, überprüft fopen die Datei auf STRG+Z am Dateiende, und entfernt sofern möglich die Markierung. Dies geschieht, da ein Verwenden von fseek und ftell zum Navigieren innerhalb einer Datei, die mit Strg+Z endet, dazu führen kann, dass sich fseek in der Nähe des Dateiendes nicht richtig verhält.

Im Textmodus werden Kombinationen aus Wagenrücklauf- und Zeilenvorschubzeichen in einzelne Zeilenvorschübe bei Eingabe übersetzt, und Zeilenvorschubzeichen werden bei der Ausgabe in Kombinationen aus Wagenrücklauf- und Zeilenvorschubzeichen ü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).

• b
  Öffnen im binären (unübersetzten) Modus; Übersetzungen von Wagenrücklauf- und Zeilenvorschubzeichen werden unterdrückt.

Wenn t oder b nicht in mode angegeben ist, wird der Standardübersetzungsmodus durch die globale Variable _fmode definiert. Wenn dem Argument t oder b vorangestellt wird, schlägt die Funktion fehl und gibt NULL zurück.

Weitere Informationen darüber, wie Sie Textmodus und Binärmodus in Unicode und im Multibyte-Stream-E/A verwenden, finden Sie unter Text- und Binärmodusdatei-E/A und Unicodestream-E/A im Text- und Binärmodus.

• 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 Commitflag für den zugeordneten Parameter filename auf "no-commit" zurück. Dies ist die Standardeinstellung. Dabei wird auch das globale Commitflag überschrieben, wenn Sie das Programm mit COMMODE.OBJ verknüpfen. Der Standardwert des globalen Commitflags lautet "no-commit", es sei denn, Sie verknüpfen das 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 an, dass eine Datei temporär ist. Wenn möglich, wird sie nicht auf den Datenträger geschrieben.

• D
  Gibt an, dass eine Datei temporär ist. Sie wird gelöscht, wenn der letzte Dateizeiger geschlossen wird.

• ccs=ENCODING
  Gibt den codierten Zeichensatz an, der für diese Datei verwendet werden soll (UTF-8, UTF-16LE oder UNICODE). Machen Sie keine Angabe, wenn Sie ANSI-Codierung wünschen.

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

Wenn Sie den rb-Modus verwenden, keinen Code portieren müssen und davon ausgehen, den Großteil einer großen Datei zu lesen, oder die Netzwerkleistung nicht relevant ist, sind möglicherweise Win32-Dateien mit Speicherzuordnung auch eine Option.

Anforderungen

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

Die mode-Optionen c, n, t, S, R, T und D sind Microsoft-Erweiterungen für fopen und _fdopen und sollten nicht dort verwendet werden, wo ANSI-Portabilität gewünscht wird.

Beispiel

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

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 namens _wfopen_test.xml, die die Daten aus dem Ausgangsabschnitt 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;
}

.NET Framework-Entsprechung

• System::IO::File::Open

• System::IO::FileStream::FileStream

Siehe auch

Referenz

Stream-E/A

Interpretation von Mehrbytezeichensequenzen

fclose, _fcloseall

_fdopen, _wfdopen

ferror

_fileno

freopen, _wfreopen

_open, _wopen

_setmode

_sopen, _wsopen