fopen_s, _wfopen_s

Öffnet eine Datei.Diese Versionen von fopen, _wfopen haben Sicherheitserweiterungen, wie in Sicherheitsfeatures im CRT beschrieben.

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 der geöffneten Datei empfängt.

• [in] filename
  Dateiname.

• [in] mode
  Typ des Zugriffs zulässig.

Rückgabewert

Null erfolgreich, wenn ein Fehlercode auf Fehler.Siehe errno, _doserrno, _sys_errlist und _sys_nerr weitere Informationen zu diesen Fehlercodes.

Fehlerbedingungen

pFile	filename	mode	Rückgabewert	Inhalt von pFile
NULL	any	any	EINVAL	unverändert
any	NULL	any	EINVAL	unverändert
any	any	NULL	EINVAL	unverändert

Hinweise

Dateien, die von fopen_s und _wfopen_s geöffnet werden, sind nicht teilbar.Wenn Sie erforderlich, dass eine Datei teilbar ist, verwendet _fsopen, _wfsopen mit dem entsprechenden Freigabenmodus Konstante – z. B. _SH_DENYNO für Lese-Schreibfreigabe.

Die fopen_s-Funktion wird die Datei, die von filename angegeben wird._wfopen_s ist eine Breitzeichen-Version von fopen_s; die Argumente zu _wfopen_s sind Breitzeichen-Zeichenfolgen._wfopen_s und fopen_s verhalten sich andernfalls identisch.

fopen_s akzeptiert Pfade, die im Dateisystem zum Zeitpunkt der Ausführung gültig sind; UNC-Pfade und Pfade, die zugeordnetes Netzlaufwerk auftreten, werden durch fopen_s akzeptiert, solange das System, das den Code ausführt, Zugriff auf die Freigabe oder zugeordnetes Netzlaufwerk zum Zeitpunkt der Ausführung verfügt.Wenn Sie Pfade für fopen_s erstellen, machen Sie keine Annahmen über die Verfügbarkeit des Laufwerks, der Pfade oder der Netzwerkfreigaben in der Ausführungsumgebung.Sie können entweder Schrägstriche (/) oder umgekehrte Schrägstriche (\) als Verzeichnistrennzeichen in einem Pfad verwenden.

Diese Funktionen überprüfen ihre Parameter.Wenn pFile, filename oder mode ein NULL-Zeiger ist, generieren diese Funktionen eine ungültige Parameterausnahme, wie in Parametervalidierung beschrieben.

Überprüfen Sie immer den Rückgabewert, um festzustellen, ob die Funktion erfolgreich war, bevor Sie alle anderen Vorgänge in der Datei 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.

Unicode-Unterstützung

fopen_s Unterstützungs-Unicode-Dateistreams.Um eine neue oder vorhandene Unicode-Datei zu öffnen, führen Sie ein ccs-Flag der die gewünschte Codierung zu fopen_s angibt:

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

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

Wenn die Datei bereits vorhanden ist und zum Lesen oder das Anhängen geöffnet ist, bestimmt die Bytereihenfolgemarkierung (BOM), falls vorhanden in der Datei, die Codierung.Das BOM-Codieren hat Vorrang gegenüber der Codierung, die vom ccs-Flag angegeben ist.Das ccs Code wird nur verwendet, wenn kein BOM vorhanden ist, oder wenn die Datei eine neue Datei.

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

In der folgenden Tabelle werden die Modi für verschiedene ccs-Flags zusammen, die fopen_s und für Bytereihenfolgemarkierungen in der Datei angegeben werden.

Codierungen verwendet auf Grundlage ccs Flag und BOM

ccs-Flag	Kein BOM (oder 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

Dateien, die zum Schreiben in Unicode-Modus geöffnet sind, haben BOM, das automatisch ihnen geschrieben wird.

Wenn mode "a, ccs=<encoding>" ist, versucht fopen_s zuerst, die Datei mit Lesezugriff und Schreibzugriff zu öffnen.Wenn erfolgreich, liest die Funktion BOM, um die Codierung für die Datei abrufen; wenn fehlschlägt, wird die - Funktion die Standardcodierung für die Datei.In jedem Fall wird fopen_s dann die Datei mit lesegeschütztem Zugriff erneut.(Dies gilt für a nur Modus, nicht a+.)

Zuordnung generische Textroutinen

TCHAR.H-Routine	_UNICODE & _MBCS nicht definiert.	_MBCS definiert	_UNICODE definiert
_tfopen_s	fopen_s	fopen_s	_wfopen_s

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

• "r"
  Der wird zum Lesen.Wenn die Datei nicht vorhanden ist oder nicht gefunden werden kann, schlägt der Aufruf fopen_s aus.

• "w"
  Öffnet eine leere Datei zum Schreiben.Wenn die Datei vorhanden ist, wird der Inhalt zerstört.

• "a"
  Vor dem Schreiben von neuen Daten geöffnet zum Schreiben am Ende der Datei (Anfügen) ohne den EOF-Marker, die Datei zu entfernen.Erstellt die Datei, wenn sie nicht vorhanden ist.

• "r+"
  Der wird für das Lesen und Schreiben.(Die Datei muss vorhanden sein.)

• "w+"
  Öffnet eine leere Datei für das Lesen und Schreiben.Wenn die Datei vorhanden ist, wird der Inhalt zerstört.

• "a+"
  Der wird zum Lesen und das Anfügen.Der anfügende Vorgang umfasst das Entfernen des EOF-Markers, bevor neue Daten in die Datei geschrieben werden und der EOF-Marker wiederhergestellt wird, nachdem das Schreiben vollständig ist.Erstellt die Datei, wenn sie nicht vorhanden ist.

Wenn eine Datei mit dem "a" oder "a+" Zugriffstyps geöffnet wird, werden alle Schreibvorgänge am Ende der Datei auf.Der Dateizeiger kann neu angeordnet werden, indem fseek oder rewind verwendet, jedoch wird immer wieder am Ende der Datei verschoben, bevor ein Schreibvorgang verlassen wird, sodass vorhandene Daten nicht überschrieben werden können.

Der "a" Modus entfernt den EOF-Marker nicht, bevor er zur Datei angefügt.Nachdem sie angefügt haben, sind die, MS-DOS Showdaten des TYPbefehls nur bis auf die Markierung der Vorlage EOF und keine Daten aufgetreten, die an die Datei angefügt wird.Der "a+" Modus entfernt den EOF-Marker, bevor er zur Datei angefügt.Nach dem angefügt hat zeigt der MS-DOS TYPbefehl alle Daten in der Datei an.Der "a+" Modus ist für das Anfügen an eine Streamdatei erforderlich, die beendet wird, indem Sie die Markierung STRG+Zs EOF verwendet.

Wenn "r+","w+", oder "a+" Zugriffstyp, angegeben wird, wird das Lesen und Schreiben zulässt.(Die Datei soll für "Update" geöffnet.) Wenn Sie jedoch von den Lesen zum Schreiben wechseln, muss die Eingabeoperation einen EOF-Marker auftreten.Wenn kein EOF gibt, müssen Sie einen zwischenzeitlichen Aufruf einer Funktion Datei-positionierenden verwenden.Die Datei-positionierenden Funktionen sind fsetpos, fseek und rewind.Wenn Sie im Schreiben lesenden wechseln, müssen Sie einen zwischenzeitlichen Aufruf entweder zu fflush oder einer Datei-positionierenden Funktion verwenden.

Zusätzlich zu den oben aufgeführten Werten können die folgenden Zeichen in mode eingeschlossen werden, um den Übersetzungsmodus für Zeilenumbruchzeichen anzugeben:

• t
  Öffnen Sie im Modus des Texts (übersetzt).In diesem Modus wird STRG+Z als Dateiendezeichen auf Eingabe interpretiert.In den Dateien, die zum Lesen/Schreiben mit "a+" geöffnet sind, entfernt fopen_s Überprüfungen für STRG+Z am Ende der Datei und sie, sofern möglich.Dies geschieht, da, fseek und ftell verwenden, um sich innerhalb einer Datei zu navigieren kann, die mit STRG+Z beendet, fseek bewirken, dass sich neben dem Ende der Datei nicht ordnungsgemäß verhält.

Außerdem im Textmodus, werden Wagenrücklauf/Zeilenvorschub-Kombinationen in einzelne Zeilenvorschübe auf Eingabe übersetzt, und Zeilenvorschubzeichen werden den Wagenrücklauf/Zeilenvorschub-Kombinationen auf Ausgabe übersetzt.Wenn eine Funktion von Unicode stream-I/O im Textmodus (Standard) funktioniert, die Quelle, oder Zielstream wird angenommen, dass eine Sequenz von Mehrbytezeichen zu sein.Daher konvertieren die Unicode-StreamEingabefunktionen Mehrbytezeichen zu den Breitzeichen (als ob durch einen Aufruf der mbtowc-Funktion).Aus demselben Grund konvertieren die Unicode Stream-ausgegebenen Funktionen Breitzeichen zu den Mehrbytezeichen (als ob durch einen Aufruf der wctomb-Funktion).

• b
  Öffnen Sie im binären (unübersetzten) Modus; die Übersetzungen, die Wagenrückkehr- und Zeilenvorschubzeichen einbeziehen, werden unterdrückt.

Wenn t oder b nicht in mode angegeben ist, wird der Standardwert Übersetzungsmodus durch die globale Variable _fmode definiert.Wenn t oder b das Argument vorangestellt wird, lässt die Funktion und gibt NULL zurück.

Weitere Informationen zur Verwendung von Text- und Binärdateimodi in Unicode und in Mehrbytem stream-I/O, finden Sie unter Text- Binärdatei-Modus Datei E/A und Unicode-Stream E/A in den Text Binärdatei-Modi.

• c
  Aktivieren Sie das Commitflag für zugeordnete filename, sodass der Inhalt des Dateipuffers direkt auf den Datenträger geschrieben wird, wenn entweder fflush oder _flushall aufgerufen wird.

• n
  Legen Sie das Commitflag für zugeordnete filename "NO-Commit" zurück. Dies ist die Standardeinstellung.Er überschreibt auch das globale Commitflag, wenn Sie das Programm mit COMMODE.OBJ verknüpfen.Der globale Commitflagsstandard ist "NO-Commit" es sei denn, Sie explizit das Programm mit COMMODE.OBJ verknüpfen (siehe Link-Optionen).

• N
  Gibt an, dass die Datei nicht durch untergeordnete Prozesse geerbt wird.

• S
  Gibt an, dass die Zwischenspeicherung für optimiert ist, aber nicht zu beschränkt, sequenzieller Zugriff von Datenträger an.

• R
  Gibt an, dass die Zwischenspeicherung für optimiert wird, aber die nicht zu, wahlfreier Zugriff von Datenträger an.

• T
  Gibt eine Datei an, wie temporär.Wenn möglich, wird sie nicht auf den Datenträger geleert.

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

• ccs=ENCODING
  Geben Sie den codierten Zeichensatz an, um UTF-8 (, UTF-16LE und UNICODE) für diese Datei aus.Führen Sie dieses nicht angegebene, wenn Sie ANSI-Codieren soll.

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

Zeichen in der Moduszeichenfolge	Entsprechender oflag-Wert für _open/_sopen
a	_O_WRONLY | _O_APPEND (normalerweise _O_WRONLY | _O_CREAT |_O_APPEND)
a+	_O_RDWR | _O_APPEND (normalerweise _O_RDWR | _O_APPEND | _O_CREAT )
r	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY (normalerweise _O_WRONLY |_O_CREAT | _O_TRUNC)
w+	_O_RDWR (normalerweise _O_RDWR | _O_CREAT | _O_TRUNC)
b	_O_BINARY
t	_O_TEXT
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 rb Modus verwenden, nicht werden müssen, um den Code zu portieren und erwarten, viel Datei lesen und/oder nicht der Speichermenge relevant, möglicherweise zugeordnete Arbeitsspeicher Win32-Dateien auch eine Option.

Anforderungen

Funktion	Erforderlicher Header
fopen_s	<stdio.h>
_wfopen_s	<stdio.h> oder <wchar.h>

So zusätzlicher Kompatibilitätsinformation finden Sie unter Kompatibilität in der Einführung.

Bibliotheken

Alle Versionen C-Laufzeitbibliotheken.

c, n und Optionen tmode sind Microsoft-Erweiterungen für fopen_s und _fdopen und sollten nicht verwendet werden, wo ANSI-Portabilität erforderlich ist.

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