Namespaces
Variants

freopen, freopen_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Definiert in Header <stdio.h>
(1)
FILE * freopen ( const char * filename, const char * mode,
FILE * stream ) ;
(bis C99)
FILE * freopen ( const char * restrict filename, const char * restrict mode,
FILE * restrict stream ) ;
(seit C99)
errno_t freopen_s ( FILE * restrict * restrict newstreamptr,

const char * restrict filename, const char * restrict mode,

FILE * restrict stream ) ;
(2) (seit C11)
1) Zunächst wird versucht, die mit stream assoziierte Datei zu schließen, wobei etwaige Fehler ignoriert werden. Dann, falls filename nicht null ist, wird versucht, die durch filename spezifizierte Datei mit mode zu öffnen, wie durch fopen , und assoziiert diese Datei mit dem durch stream gezeigten Dateistrom. Wenn filename ein Nullzeiger ist, dann versucht die Funktion, die bereits mit stream assoziierte Datei erneut zu öffnen (es ist implementierungsdefiniert, welche Modusänderungen in diesem Fall erlaubt sind).
2) Gleich wie (1) , außer dass mode wie in fopen_s behandelt wird und dass der Zeiger auf den Dateistrom in newstreamptr geschrieben wird und die folgenden Fehler zur Laufzeit erkannt werden und den aktuell installierten constraint handler aufrufen:
  • newstreamptr ist ein Nullzeiger
  • stream ist ein Nullzeiger
  • mode ist ein Nullzeiger
Wie bei allen bounds-checked-Funktionen ist freopen_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf den Integer-Konstantenwert 1 setzt, bevor <stdio.h> eingebunden wird.

Inhaltsverzeichnis

Parameter

filename - Dateiname, der dem Dateistrom zugeordnet werden soll
mode - nullterminierte Zeichenkette, die den neuen Dateizugriffsmodus bestimmt
stream - der zu modifizierende Dateistrom
newstreamptr - Zeiger auf einen Zeiger, in dem die Funktion das Ergebnis speichert (ein Out-Parameter)

Dateizugriffsflags

Dateizugriffsmodus-String
Bedeutung Erklärung Aktion wenn Datei
bereits existiert 		Aktion wenn Datei
nicht existiert
"r" read Datei zum Lesen öffnen Lesen vom Anfang Fehler beim Öffnen
"w" write Datei zum Schreiben erstellen Inhalt zerstören Neue Datei erstellen
"a" append An Datei anhängen Schreiben ans Ende Neue Datei erstellen
"r+" read extended Datei zum Lesen/Schreiben öffnen Lesen vom Anfang Fehler
"w+" write extended Datei zum Lesen/Schreiben erstellen Inhalt zerstören Neue Datei erstellen
"a+" append extended Datei zum Lesen/Schreiben öffnen Schreiben ans Ende Neue Datei erstellen
Dateizugriffsmodus-Flag "b" kann optional angegeben werden, um eine Datei im Binärmodus zu öffnen. Dieses Flag hat keine Auswirkung auf POSIX-Systemen, aber unter Windows deaktiviert es die spezielle Behandlung von ' \n ' und ' \x1A ' .
Bei den Anhänge-Dateizugriffsmodi werden Daten unabhängig von der aktuellen Position des Dateipositionsindikators ans Ende der Datei geschrieben.
Das Verhalten ist undefiniert, wenn der Modus nicht einer der oben aufgeführten Strings ist. Einige Implementierungen definieren zusätzlich unterstützte Modi (z.B. Windows ).
Im Aktualisierungsmodus ( '+' ) können sowohl Eingabe als auch Ausgabe durchgeführt werden, aber Ausgabe kann nicht von Eingabe gefolgt werden ohne einen zwischengeschalteten Aufruf von fflush , fseek , fsetpos oder rewind , und Eingabe kann nicht von Ausgabe gefolgt werden ohne einen zwischengeschalteten Aufruf von fseek , fsetpos oder rewind , es sei denn, der Eingabevorgang hat das Dateiende erreicht. Im Aktualisierungsmodus ist es Implementierungen erlaubt, den Binärmodus zu verwenden, selbst wenn der Textmodus angegeben ist.
Dateizugriffsmodus-Flag "x" kann optional an "w" oder "w+" angehängt werden. Dieses Flag zwingt die Funktion zu scheitern, wenn die Datei existiert, anstatt sie zu überschreiben. (C11)
Bei Verwendung von fopen_s oder freopen_s verhindern Dateizugriffsberechtigungen für jede mit "w" oder "a" erstellte Datei den Zugriff durch andere Benutzer. Dateizugriffsmodus-Flag "u" kann optional jedem Specifier vorangestellt werden, der mit "w" oder "a" beginnt, um die Standard- fopen -Berechtigungen zu aktivieren. (C11)

Rückgabewert

1) Eine Kopie des Werts von stream bei Erfolg, Nullzeiger bei Fehlschlag.
2) null bei Erfolg (und eine Kopie des Werts von stream wird in * newstreamptr geschrieben), ungleich null bei Fehler (und ein Nullzeiger wird in * newstreamptr geschrieben, es sei denn newstreamptr ist selbst ein Nullzeiger).

Hinweise

freopen ist die einzige Möglichkeit, die Narrow/Wide-Orientierung eines Streams zu ändern, nachdem sie durch einen I/O-Vorgang oder durch fwide festgelegt wurde.

Die Microsoft CRT-Version von freopen unterstützt keine Modusänderungen, wenn filename ein Nullzeiger ist, und behandelt dies als Fehler (siehe Dokumentation ). Eine mögliche Problemumgehung ist die nicht standardisierte Funktion _setmode() .

Beispiel

Der folgende Code leitet stdout in eine Datei um.

Diesen Code ausführen 
#include <stdio.h>
#include <stdlib.h>
int main(void)
{
    puts("stdout is printed to console");
    if (freopen("redir.txt", "w", stdout) == NULL)
    {
       perror("freopen() failed");
       return EXIT_FAILURE;
    }
    puts("stdout is redirected to a file"); // this is written to redir.txt
    fclose(stdout);
    return EXIT_SUCCESS;
}

Ausgabe: 

stdout is printed to console

Referenzen

  • C17-Standard (ISO/IEC 9899:2018):
  • 7.21.5.4 Die freopen-Funktion (S: 224-225)
  • K.3.5.2.2 Die freopen_s-Funktion (S: 429-430)
  • C11-Standard (ISO/IEC 9899:2011):
  • 7.21.5.4 Die freopen-Funktion (S. 307)
  • K.3.5.2.2 Die freopen_s-Funktion (S. 590)
  • C99-Standard (ISO/IEC 9899:1999):
  • 7.19.5.4 Die freopen-Funktion (S. 272-273)
  • C89/C90 Standard (ISO/IEC 9899:1990):
  • 4.9.5.4 Die freopen-Funktion

Siehe auch

(C11)
öffnet eine Datei
(Funktion)
schließt eine Datei
(Funktion)
C++-Dokumentation für freopen