`fopen_s`, `_wfopen_s`

Artikel
10/12/2023

Ö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

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

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.

Hinweis

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

`ccs` -Flag	Keine BOM (oder neue Datei)	BOM: UTF-8	BOM: UTF-16
`UNICODE`	`UTF-8`	`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 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.

`mode`	Access
`"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 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 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:

`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. STRG+Z wird als End-of-File-Zeichen bei eingaben interpretiert.
`b`	Im Binärmodus (nicht translatiert) öffnen; Übersetzungen mit Wagenrücklauf- und Zeilenvorschubzeichen werden unterdrückt.

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.

`mode` Modifizierer	Verhalten
`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. Außerdem wird das globale Commit-Flag außer Kraft gesetzt, wenn Sie Ihr 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=UNICODE`	Gibt UNICODE als codierten Zeichensatz an, der für diese Datei verwendet werden soll. Machen Sie keine Angabe, wenn Sie ANSI-Codierung wünschen.
`ccs=UTF-8`	Gibt UTF-8 als codierten Zeichensatz an, der für diese Datei verwendet werden soll. Machen Sie keine Angabe, wenn Sie ANSI-Codierung wünschen.
`ccs=UTF-16LE`	Gibt UTF-16LE als codierten Zeichensatz an, der für diese Datei verwendet werden soll. Machen Sie keine Angabe, wenn Sie ANSI-Codierung wünschen.

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

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` (in der Regel **`_O_RDWR \| _O_CREAT \| _O_TRUNC`)
`b`	`_O_BINARY`
`t`	`_O_TEXT` (übersetzt)
`c`	Keine
`n`	Keine
`D`	`_O_TEMPORARY`
`R`	`_O_RANDOM`
`S`	`_O_SEQUENTIAL`
`T`	`_O_SHORTLIVED`
`ccs=UNICODE`	`_O_WTEXT`
`ccs=UTF-8`	`_O_UTF8`
`ccs=UTF-16LE`	`_O_UTF16`

Die c, n, , SR, t, TDmode 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_TEMPORARYDatei-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

Funktion	Erforderlicher Header	C++-Header
`fopen_s`	`<stdio.h>`	`<cstdio>`
`_wfopen_s`	`<stdio.h>` oder `<wchar.h>`	`<cstdio>`

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

Generische Textroutinzuordnungen

`<tchar.h>` Routine	`_UNICODE` und `_MBCS` nicht definiert	`_MBCS` Definiert	`_UNICODE` Definiert
`_tfopen_s`	`fopen_s`	`fopen_s`	`_wfopen_s`

Bibliotheken

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

`fopen_s`, `_wfopen_s`

Syntax

Parameter

Rückgabewert

Fehlerbedingungen

Hinweise

Unicode-Unterstützung

Basierend auf `ccs` Kennzeichnung und BOM verwendete Codierungen

Anforderungen

Generische Textroutinzuordnungen

Bibliotheken

Beispiel

Siehe auch

Feedback

Feedback

Zusätzliche Ressourcen

fopen_s, _wfopen_s

Syntax

Parameter

Rückgabewert

Fehlerbedingungen

Hinweise

Unicode-Unterstützung

Basierend auf ccs Kennzeichnung und BOM verwendete Codierungen

Anforderungen

Generische Textroutinzuordnungen

Bibliotheken

Beispiel

Siehe auch

Feedback

Feedback

Zusätzliche Ressourcen

`fopen_s`, `_wfopen_s`

Basierend auf `ccs` Kennzeichnung und BOM verwendete Codierungen