fopen_s, _wfopen_s

Öffnet eine Datei. Bei diesen Versionen von fopen, _wfopen wurde die Sicherheit wie unter Sicherheitsfunktionen in der CRT beschrieben verbessert.

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

Parameter

• [out] pFile
  Ein Zeiger auf den Dateizeiger, der den Zeiger auf die geöffnete Datei erhält.

• [in] filename
  Dateiname.

• [in] mode
  Zugriffstyp zulässig.

Rückgabewert

Null, wenn erfolgreich, ein Fehlercode, wenn ein Fehler auftritt. Weitere Informationen zu diesen Fehlercodes finden Sie unter errno, _doserrno, _sys_errlist und _sys_nerr.

Fehlerbedingungen

Hinweise

Dateien, die von fopen_s und _wfopen_s geöffnet werden, können nicht freigegeben werden. Wenn eine Datei freigegeben werden soll, verwenden Sie _fsopen, _wfsopen sowie die entsprechende Freigabemoduskonstante – z. B. _SH_DENYNO für Lese-/Schreibfreigabe.

Die fopen_s-Funktion öffnet die Datei, die von filename angegeben wird. _wfopen_s ist eine Breitzeichenversion von fopen_s. Die Argumente für _wfopen_s sind Zeichenfolgen mit Breitzeichen. _wfopen_s und fopen_s verhalten sich andernfalls identisch.

fopen_s akzeptiert Pfade, die zum Zeitpunkt der Ausführung im Dateisystem gültig sind. UNC-Pfade und Pfade mit zugeordneten Netzlaufwerken werden von fopen_s akzeptiert, 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_s erstellen, machen Sie keine Annahmen über die Verfügbarkeit von Laufwerken, Pfaden oder Netzwerkfreigaben in der Ausführungsumgebung. Als Verzeichnistrennzeichen in einem Pfad können Sie entweder den Schrägstrich (/) oder den umgekehrten Schrägstrich (\) verwenden.

Diese Funktionen überprüfen ihre Parameter. Wenn pFile, filename oder mode ein NULL-Zeiger ist, generieren diese Funktionen eine Ausnahme wegen eines ungültigen Parameters, wie in Parametervalidierung beschrieben ist.

Überprüfen Sie stets den Rückgabewert, um festzustellen, ob die Funktion erfolgreich war, bevor Sie mit der Datei andere Vorgänge ausführen. Wenn ein Fehler auftritt, wird der Fehlercode zurückgegeben und die globale Variable errno wird festgelegt. Weitere Informationen finden Sie unter errno, _doserrno, _sys_errlist und _sys_nerr.

Unterstützung für Unicode

fopen_s unterstützt Unicode-Dateistreams. Um eine neue oder vorhandene Unicode-Datei zu öffnen, geben Sie ein ccs-Flag, das die gewünschte Codierung angibt, an fopen_s weiter:

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

Zulässige Werte von encoding sind UNICODE, UTF-8 und UTF-16LE. Wenn dort kein Wert für encoding angegeben ist, verwendet fopen_s ANSI-Codierung.

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 für verschiedene ccs-Flags für fopen_s sowie für die Bytereihenfolge-Marken in der Datei zusammen.

Verwendete Codierungen auf Grundlage von ccs-Flag und BOM

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

Wenn mode "a, ccs=<encoding>" ist, versucht fopen_s 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_s dann die Datei nur mit Schreibzugriff erneut. (Dies gilt nur für den a-Modus, nicht für a+.)

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_s-Aufruf fehl.

• "w"
  Öffnet eine leere Datei zum Schreiben. Wenn die 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 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 des EOF-Markers, bevor neue Daten in die Datei geschrieben werden. Nachdem der Schreibvorgang abgeschlossen ist, wird die EOF-Markierung 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, noch bevor der Schreibvorgang ausgeführt wird, damit vorhandene Daten nicht überschrieben werden können.

Bei dem Modus "a" wird die EOF-Markierung nicht entfernt, bevor Daten an die Datei angefügt werden. 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. Bei dem Modus "a+" wird die EOF-Markierung entfernt, bevor Daten an die Datei angefügt werden. 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 "r+","w+", oder "a+" Zugriffstyp, angegeben wird, wird das Lesen und Schreiben zulässt. (Die Datei ist dann für ein "Update" 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 den obigen Werte können die folgenden Zeichen in mode enthalten sein, um den Übersetzungsmodus für Zeilenumbruchzeichen anzugeben:

• t
  Öffnen im Textmodus (übersetzt). In diesem Modus wird STRG+Z als Dateiendezeichen bei Eingabe interpretiert. In den Dateien, die für das Lesen/Schreiben mit "a+" geöffnet sind, überprüft fopen_s 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 ordnungsgemäß verhält.

Auch 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 zur Anwendung von Text- und Binärmodi in Unicode- und Multibyte-Stream-E/A finden Sie unter Text- und Binärmodus-Datei-E/A und Unicode-Stream-E/A in Text- und Binärmodi.

• 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 der Standardwert. 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
  Geben Sie den für diese Datei zu verwendenden codierten Zeichensatz an (UTF-8, UTF-16LE und UNICODE). Machen Sie keine Angabe, wenn Sie ANSI-Codierung wünschen.

Gültige Zeichen für die mode-Zeichenfolge, die in fopen_s und _fdopen verwendet wird, entsprechen oflag-Argumenten, die in _open und _sopen verwendet werden (siehe unten).

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

Anforderungen

Zusätzliche Informationen zur Kompatibilität finden Sie unter Kompatibilität in der Einführung.

Bibliotheken

Alle Versionen C-Laufzeitbibliotheken.

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

Beispiel

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

.NET Framework-Entsprechung

• System::IO::File::Open

• System::IO::FileStream::FileStream

Siehe auch

Referenz

Stream-E/A

fclose, _fcloseall

_fdopen, _wfdopen

ferror

_fileno

freopen, _wfreopen

_open, _wopen

_setmode