fopen

FOPEN(3)                    Linux-Programmierhandbuch                   FOPEN(3)



BEZEICHNUNG
       fopen, fdopen, freopen - Funktionen zum Öffnen von Datenströmen

ÜBERSICHT
       #include <stdio.h>

       FILE *fopen(const char *pfadname, const char *modus);

       FILE *fdopen(int fd, const char *modus);

       FILE *freopen(const char *pfadname, const char *modus, FILE *datenstrom);

   Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):

       fdopen(): _POSIX_C_SOURCE

BESCHREIBUNG
       Die Funktion fopen() öffnet die Datei, deren Name die Zeichenkette ist,
       auf die pfadname zeigt, und erzeugt einen damit verbundenen Datenstrom.

       Das Argument modus zeigt auf eine Zeichenkette, die mit einer der
       folgenden Sequenzen beginnt (möglicherweise gefolgt von zusätzlichen
       Zeichen, wie nachfolgend beschrieben):

       r      eine Textdatei zum Lesen öffnen. Der Datenstrom wird auf den
              Dateianfang positioniert.

       r+     die Textdatei zum Lesen und Schreiben öffnen. Der Datenstrom wird
              auf den Dateianfang positioniert.

       w      die Datei auf die Länge Null kürzen oder eine Textdatei zum
              Schreiben erzeugen. Der Datenstrom wird auf den Dateianfang
              positioniert.

       w+     die Datei zum Lesen und Schreiben öffnen. Die Datei wird erzeugt,
              wenn sie nicht existiert, ansonsten abgeschnitten. Der Datenstrom
              wird auf den Dateianfang positioniert.

       a      zum Anhängen (Schreiben am Dateiende) öffnen. Die Datei wird
              erzeugt, wenn sie nicht existiert. Der Datenstrom wird auf das
              Dateiende positioniert.

       a+     zum Lesen und Anhängen (Schreiben am Dateiende) öffnen. Die Datei
              wird erzeugt, wenn sie nicht existiert. Die Ausgabe wird immer am
              Ende der Datei angehängt. POSIX legt nicht fest, was die
              anfängliche Leseposition ist, wenn dieser Modus verwandt wird. Für
              Glibc ist die anfängliche Dateiposition zum Lesen am Dateianfang,
              aber für Android/BSD/MacOS ist die anfängliche Dateiposition zum
              Lesen am Ende der Datei.

       Die Zeichenkette modus kann auch den Buchstaben »b« enthalten, entweder
       als ein letztes Zeichen oder zwischen den Zeichen in einem der oben
       beschriebenen Zeichenketten aus zwei Buchstaben. Dies ist ausschließlich
       aus Kompatibilitätsgründen zu C89 so und hat keinerlei Auswirkungen; das
       »b« wird auf allen POSIX-konformen Systemen einschließlich Linux
       ignoriert. (Andere Systeme könnten Text- und Binärdateien unterschiedlich
       behandeln und das »b« hinzuzufügen könnte sich als klug erweisen, falls
       Sie E/As auf die Binärdatei ausführen und erwarten, dass Ihr Programm auf
       Nicht-UNIX-Umgebungen portiert wird.)

       Lesen Sie die folgenden ANMERKUNGEN, um Einzelheiten über
       Glibc-Erweiterungen für modus zu erfahren.

       Jede erstellte Datei wird den Modus S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP
       | S_IROTH | S_IWOTH (0666) haben, wie er durch den Umask-Wert des
       Prozesses geändert wurde (siehe umask(2)).

       Lese- und Schreibzugriffe können in Lese-/Schreibdatenströmen in
       beliebiger Reihenfolge gemischt werden. Beachten Sie, dass ANSI-C
       verlangt, dass zwischen einer Eingabe- und einer Ausgabeaktion eine
       Dateipositionierungsfunktion ausgeführt wird, außer wenn eine Eingabe auf
       das Dateiende traf. (Falls diese Bedingung nicht eingehalten wird, darf
       beim Lesen etwas anderes als das zuletzt geschriebene zurückgegeben
       werden.)  Daher ist es ein bewährtes Verfahren (und tatsächlich manchmal
       unter Linux nötig) eine fseek(3)- oder fgetpos-Aktion zwischen Schreib-
       und Leseaktionen eines solchen Datenstroms einzuschieben. Diese Aktion
       könnte der Aufruf eines scheinbaren Leerbefehls (wie z.B. fseek(…, 0L,
       SEEK_CUR) sein, der für seinen synchroniserenden Nebeneffekt aufgerufen
       wird).

       Eine Datei im Anhänge-Modus zu öffnen (a als erstes Zeichen von modus)
       hat zur Folge, dass alle nachfolgenden Schreibaktionen in diesen
       Datenstrom am Dateiende erscheinen, als ob ihnen folgender Aufruf
       vorausgegangen wäre:

           fseek(stream, 0, SEEK_END);

       Der dem Strom zugeordnete Dateideskriptor wird geöffnet, als ob ein
       Aufruf von open(2) mit den folgenden Schaltern stattgefunden hätte:

              ┌──────────────┬───────────────────────────────┐
              │fopen()-Modus open()-Schalter               │
              ├──────────────┼───────────────────────────────┤
              │      r       │ O_RDONLY                      │
              ├──────────────┼───────────────────────────────┤
              │      w       │ O_WRONLY | O_CREAT | O_TRUNC  │
              ├──────────────┼───────────────────────────────┤
              │      a       │ O_WRONLY | O_CREAT | O_APPEND │
              ├──────────────┼───────────────────────────────┤
              │     r+       │ O_RDWR                        │
              ├──────────────┼───────────────────────────────┤
              │     w+       │ O_RDWR | O_CREAT | O_TRUNC    │
              ├──────────────┼───────────────────────────────┤
              │     a+       │ O_RDWR | O_CREAT | O_APPEND   │
              └──────────────┴───────────────────────────────┘
   fdopen()
       Die Funktion fdopen() erzeugt einen mit einem existierenden
       Dateideskriptor fd verbundenen Datenstrom. Der modus der Zeichenkette
       (einer der Werte »r«, »r+«, »w«, »w+«, »a«, »a+«) muss kompatibel mit dem
       Modus des Dateideskriptors sein. Der Dateipositionsanzeiger des neuen
       Datenstroms wird den von fd gesetzt und die Anzeigen von Fehlern und
       Dateienden werden geleert. Die Modi »w« und »w+« verursachen kein Kürzen
       der Datei. dup() wird nicht aufgerufen und der Dateideskriptor wird
       geschlossen, wenn der mit fdopen() erzeugte Datenstrom geschlossen wird.
       Wenn fdopen() auf gemeinsam benutzten Speicher angewandt wird, ist das
       Ergebnis nicht definiert.

   freopen()
       Die Funktion freopen öffnet die Datei, deren Name die Zeichenkette ist,
       auf die pfadname zeigt, und verbindet damit den Datenstrom, auf den
       datenstrom zeigt. Der Originaldatenstrom wird geschlossen (wenn er
       existiert). Das Argument modus wird genauso wie in der Funktion fopen()
       benutzt.

       Falls das Argument pfadname ein Null-Zeiger ist, ändert freopen() den
       Modus des Datenstroms auf den in modus angegebenen, d.h. freopen() öffnet
       den dem Pfadnamen zugeordneten Datenstrom erneut. Die Spezifikation für
       dieses Verhalten wurde in dem Standard C99 hinzugefügt, bei dem es heißt:

              In diesem Fall muss der dem Datenstrom zugeordnete Dateideskriptor
              nicht geschlossen werden, falls der Aufruf von freopen()
              erfolgreich ist. Es ist implementierungsabhängig, welche
              Modusänderungen erlaubt sind (falls überhaupt) und unter welchen
              Umständen.

       Die primäre Verwendung der Funktion freopen() ist es, die Datei zu
       ändern, die mit einem Standard-Textdatenstrom (stderr, stdin oder stdout)
       verbunden ist.

RÜCKGABEWERT
       Bei erfolgreichem Abschluss geben fopen(), fdopen() und freopen() einen
       FILE-Zeiger zurück. Anderenfalls wird NULL zurückgegeben und errno dem
       Fehler entsprechend gesetzt.

FEHLER
       EINVAL Der modus für fopen(), fdopen() oder freopen() war ungültig.

       Die Funktionen fopen(), fdopen() und freopen() können auch fehlschlagen
       und errno wegen Fehlern setzen, die für die Routine malloc(3)
       spezifiziert sind.

       Die Funktion fopen() kann auch fehlschlagen und errno wegen Fehlern
       setzen, die für die Routine open(2) spezifiziert sind.

       Die Funktion fdopen() kann auch fehlschlagen und errno wegen Fehlern
       setzen, die für die Routine fcntl(2) spezifiziert sind.

       Die Funktion freopen() kann auch fehlschlagen und errno wegen Fehlern
       setzen, die für die Routinen open(2), fclose(3) und fflush(3)
       spezifiziert sind.

ATTRIBUTE
       Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt
       verwandten Ausdrücke.

       ┌─────────────────────────────┬───────────────────────┬─────────┐
       │Schnittstelle                Attribut              Wert    │
       ├─────────────────────────────┼───────────────────────┼─────────┤
       │fopen(), fdopen(), freopen() │ Multithread-Fähigkeit │ MT-Safe │
       └─────────────────────────────┴───────────────────────┴─────────┘
KONFORM ZU
       fopen(), freopen(): POSIX.1-2001, POSIX.1-2008, C89, C99.

       fdopen(): POSIX.1-2001, POSIX.1-2008.

ANMERKUNGEN
   Anmerkungen zur Glibc
       Die C-Bibliothek von GNU erlaubt die folgenden Erweiterungen für die in
       modus angegebene Zeichenkette:

       c (seit Glibc 2.3.3)
              keine »Öffnen«-Transaktion der Thread-Annulierungspunkte,
              nachfolgende Lese- und Schreibaktionen oder Thread-Abbruchpunkte
              durchführen. Dieser Schalter wird bei fdopen() ignoriert.

       e (seit Glibc 2.7)
              die Datei mit dem Schalter O_CLOEXEC öffnen. Siehe open(2) für
              weitere Informationen. Dieser Schalter wird bei fdopen()
              ignoriert.

       m (seit Glibc 2.3)
              versuchen mit mmap(2) auf die Datei zuzugreifen, anstatt der
              E/A-Aufrufe (read(2), write(2)). Derzeit wird mmap(2) nur für
              Dateien probiert, die zum Lesen geöffnet sind.

       x      die Datei exklusiv öffnen (entspricht dem Schalter O_EXCL von
              open(2)). Falls die Datei bereits exisitiert, schlägt fopen() fehl
              und setzt errno auf EEXIST. Dieser Schalter wird für fdopen()
              ignoriert.

       Zusätzlich zu den vorhergehenden Zeichen unterstützen fopen() und
       freopen() die folgende Syntax in modus:

        ,ccs=zeichenkette

       Die angegebene Zeichenkette wird als Name eines kodierten Zeichensatzes
       genommen und der Datenstrom wird als an der Breite ausgerichtet
       gekennzeichnet. Danach wandeln interne Umwandlungsfunktionen die Ein- und
       Ausgaben vom und in den Zeichensatz zeichenkette um. Falls die Syntax
       ,ccs=zeichenkette nicht angegeben wurde, wird die Breitenausrichtung des
       Datenstroms durch die erste Dateitransaktion festgelegt. Falls diese
       Transaktion eine Wide-Charakter-Transaktion ist, wird die Zeichenkette
       als breitenorientiert gekennzeichnet und Funktionen zum Umwandeln des
       kodierten Zeichensatzes werden geladen.

FEHLER
       Wenn der modus auf individuelle Schalterzeichen hin ausgewertet wird
       (d.h. die Zeichen, die der »ccs«-Spezifikation vorausgehen), beschränkt
       die Glibc-Implementierung von fopen() und freopen() die Anzahl der
       untersuchten Zeichen in modus auf sieben (oder, in Glibc-Versionen vor
       2.14, auf sechs, was nicht ausreichte, um mögliche Spezifikationen wie
       »rb+cmxe« aufzunehmen). Die aktuelle Implementierung von fdopen() wertet
       höchstens fünf Zeichen in Modus aus.

SIEHE AUCH
       open(2), fclose(3), fileno(3), fmemopen(3), fopencookie(3),
       open_memstream(3)

KOLOPHON
       Diese Seite ist Teil der Veröffentlichung 5.10 des Projekts
       Linux-man-pages. Eine Beschreibung des Projekts, Informationen, wie
       Fehler gemeldet werden können sowie die aktuelle Version dieser Seite
       finden sich unter https://www.kernel.org/doc/man-pages/.


ÜBERSETZUNG
       Die deutsche Übersetzung dieser Handbuchseite wurde von Patrick Rother
       <krd@gulu.net>, Chris Leick <c.leick@vollbio.de>, Mario Blättermann
       <mario.blaettermann@gmail.com>, Dr. Tobias Quathamer <toddy@debian.org>
       und Helge Kreutzmann <debian@helgefjell.de> erstellt.

       Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General
       Public License Version 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ oder
       neuer bezüglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG
       übernommen.

       Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken
       Sie bitte eine E-Mail an die Mailingliste der Übersetzer ⟨debian-l10n-
       german@lists.debian.org⟩.



GNU                             21. Dezember 2020                       FOPEN(3)