fopen_s, _wfopen_s

Öffnet eine Datei. Diese Versionen von fopen, _wfopen verfügen über Sicherheitsverbesserungen, wie in sicherheitsfeatures im CRT beschrieben.

Syntax

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

pFile
Ein Zeiger auf den Dateizeiger, der den Zeiger auf die geöffnete Datei empfängt.

filename
Der Name der zu öffnenden Datei.

mode
Zugriffstyp zulässig.

Rückgabewert

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

Fehlerbedingungen

Hinweise

Die fopen_s Und _wfopen_s Funktionen können keine Datei für die Freigabe öffnen. Wenn Sie die Datei freigeben müssen, verwenden _fsopen Sie oder _wfsopen mit der entsprechenden Freigabemoduskonstante, z. B. zum _SH_DENYNO Lesen/Schreiben der Freigabe.

Die fopen_s Funktion öffnet die durch filename. _wfopen_s ist eine breitzeichenige Version und fopen_s die Argumente, die _wfopen_s breitzeichenige Zeichenfolgen sind. _wfopen_s und fopen_s verhalten sich identisch, andernfalls.

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. Sie können schräge Schrägstriche (/) oder umgekehrte Schrägstriche (\) als Verzeichnistrennzeichen in einem Pfad verwenden.

Diese Funktionen überprüfen ihre Parameter. Wenn pFile, filename, oder mode ist ein Nullzeiger, generieren diese Funktionen eine ungültige Parameter-Ausnahme, wie in der Parameterüberprüfung beschrieben.

Überprüfen Sie immer den Rückgabewert, um festzustellen, ob die Funktion erfolgreich war, bevor Sie weitere Vorgänge für die Datei ausführen. Wenn ein Fehler auftritt, wird der Fehlercode zurückgegeben, und die globale Variable errno wird festgelegt. 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_s unterstützt Unicode-Dateistreams. Um eine neue oder vorhandene Unicode-Datei zu öffnen, übergeben Sie ein ccs Flag, das die gewünschte Codierung fopen_sangibt, z. B.:

fopen_s(&fp, "newfile.txt", "w+, ccs=UNICODE");

Zulässige Werte der ccs Kennzeichnung sind UNICODE, UTF-8und UTF-16LE. Wenn kein Wert angegeben ccsist, fopen_s verwendet die ANSI-Codierung.

Wenn die Datei bereits vorhanden ist und zum Lesen oder Anfügen geöffnet wird, bestimmt das Bytereihenfolgenzeichen (BYTE Order Mark, BOM), falls 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.

In der folgenden Tabelle sind die Modi für verschiedene ccs Flagwerte zusammengefasst, die für boolescher Werte in der Datei und für BOMs angegeben fopen_s werden.

Basierend auf ccs Kennzeichnung und BOM verwendete Codierungen

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

Wenn mode , "a, ccs=UNICODE""a, ccs=UTF-8"oder "a, ccs=UTF-16LE", fopen_s versucht 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 beiden Fällen fopen_s wird die Datei dann mit schreibgeschütztem Zugriff erneut geöffnet. (Dieses Verhalten gilt nur für den a Modus, nicht a+für .)

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

Bei einer mit dem Zugriffstyp "a" oder "a+" geöffneten Datei erfolgen alle Schreibvorgänge am Ende der Datei. Der Dateizeiger kann mithilfe fseek oder rewind, aber immer zurück zum Ende der Datei verschoben werden, bevor ein Schreibvorgang ausgeführt wird, sodass vorhandene Daten nicht überschrieben werden können.

Der "a" Modus entfernt die EOF-Markierung vor dem Anfügen an die Datei nicht. Nachdem das Anfügen aufgetreten ist, zeigt der BEFEHL MS-DOS TYPE nur Daten bis zur ursprünglichen EOF-Markierung und keine Daten an, die an die Datei angefügt werden. Bei dem Modus "a+" wird die EOF-Markierung entfernt, bevor Daten an die Datei angefügt werden. Nach dem Anfügen zeigt der BEFEHL MS-DOS TYPE alle Daten in der Datei an. Der "a+" Modus ist für das Anfügen an eine Streamdatei erforderlich, die mit demCTRL+ Z EOF-Marker beendet wird.

Wenn der "r+"Lese "w+"- oder "a+" Zugriffstyp angegeben ist, sind sowohl Lese- als auch Schreibzugriff zulässig. (Die Datei soll für "update" geöffnet sein.) Wenn Sie jedoch vom Lesen zum Schreiben wechseln, muss der Eingabevorgang über einen EOF-Marker verfügen. Wenn keine EOF-Markierung vorhanden ist, müssen Sie einen dazwischen liegenden Aufruf einer Dateipositionierungsfunktion 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.

Ab C11 können Sie anfügen "x" "w" oder "w+" dazu führen, dass die Funktion fehlschlägt, wenn die Datei vorhanden ist, anstatt sie zu überschreiben.

Zusätzlich zu den vorherigen Werten können die folgenden Zeichen eingeschlossen mode werden, um den Übersetzungsmodus für Neuzeilenzeichen anzugeben:

Im Textmodus CTRL+(übersetzt) wird Z als End-of-File-Zeichen für die Eingabe interpretiert. Bei Dateien, die mit Lese-/Schreibvorgängen "a+"geöffnet wurden, fopen_s sucht nach einemCTRL+ Z am Ende der Datei und entfernt sie, sofern möglich. Es wird entfernt, da die Verwendung fseek und ftell das Verschieben in einer Datei, die mit einem CTRL+Z endet, dazu führen fseek kann, dass sich das Verhalten am Ende der Datei nicht ordnungsgemäß verhält.

Darüber hinaus werden im Textmodus Wagenrücklauf-/Zeilenvorschubkombinationen (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. Die Unicode-Datenstromeingabefunktionen konvertieren Multibyte-Zeichen in breite Zeichen (wie durch einen 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.

Gültige Zeichen für die mode verwendete fopen_s Zeichenfolge und _fdopen entsprechen den oflag in und _sopen, wie folgt verwendeten _open Argumenten.

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

Wenn Sie den Modus verwenden rb , sind zugeordnete Win32-Dateien im Arbeitsspeicher möglicherweise auch eine Option, wenn Sie Ihren Code nicht portieren müssen, erwarten Sie, dass Sie einen Großteil der Datei lesen oder sich nicht um die Netzwerkleistung kümmern.

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.

Anforderungen

Weitere Informationen zur Standardskonformität und Benennungskonventionen in der C-Laufzeitbibliothek finden Sie unter Kompatibilität.

Mapping generischer Textroutinen

Libraries

Alle Versionen der C-Laufzeitbibliotheken.

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" doesn't 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+, ccs=UTF-8" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

   // Close stream if it isn't 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 );
}

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

Siehe auch

Stream-E/A
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode