Ubuntu Manpage: fopen, fdopen, freopen - Funktionen zum Öffnen von Datenströmen

bezeichnung
übersicht
beschreibung
rückgabewert
fehler
attribute
konform zu
anmerkungen
fehler
siehe auch
kolophon
übersetzung

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.

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⟩.