fseek, fseek64, fseeko, fseeko64 - Lese-/Schreibzeiger im Datenstrom auf aktuellen Wert positionieren

Definition

#include <stdio.h>

int fseek(FILE *stream, long int offset, int whence);
int fseek64(FILE *stream, long long int offset, int whence);
int fseeko(FILE *stream, off_t offset, int whence);
int fseeko64(FILE *stream, off64_t offset, int whence);

Beschreibung

Wenn POSIX-Dateien ausgeführt werden, verhält sich die Funktion XPG-konform wie folgt:

fseek() setzt den Lese-/Schreibzeiger für den Datenstrom, auf den stream zeigt.

Die neue Position, gemessen in Bytes vom Anfang der Datei, wird durch die Addition von offset zu der durch whence angegebenen Position ermittelt. Der angegebene Punkt ist der Dateianfang bei SEEK_SET, der aktuelle Wert des Lese-/Schreibzeigers bei SEEK_CUR oder das Dateiende bei SEEK_END.

Sollen Ein-/Ausgabe-Funktionen für Langzeichen auf stream angewendet werden, mussoffset entweder 0 oder der Rückgabewert eines vorhergehenden ftell-Aufrufs in demselben Datenstrom sein; whence muss SEEK_SET sein

Ein erfolgreicher Aufruf von fseek() löscht das Kennzeichen für Dateiende und hebt jede Wirkung von ungetc() und ungetwc() für denselben Datenstrom auf. Nach einem Aufruf von fseek() kann die nächste Operation auf einem zum Aktualisieren geöffneten Datenstrom sowohl eine Eingabe- als auch eine Ausgabeoperation sein.

Wenn auf einem gegebenen Datenstrom die letzte Operation ungleich ftell() die Operation fflush() ist, dann wird die Dateiposition der zu Grunde liegenden Dateibeschreibung angepasst, um den durch fseek() vorgegebenen Ort widerzuspiegeln.

fseek() erlaubt, dass der Lese-/Schreibzeiger hinter das Ende der existierenden Daten in der Datei gesetzt wird. Werden später Daten an diese Stelle geschrieben, dann liefern anschließende Leseoperationen für Daten in dieser Lücke Nullbytes, bis wirklich Daten in diese Lücke geschrieben wurden.

Ist der Datenstrom zum Schreiben geöffnet und wurden gepufferte Daten noch nicht in die zu Grunde liegende Datei geschrieben, bewirkt fseek(), dass die noch nicht geschriebenen Daten in die Datei geschrieben werden und markiert die Felder st_ctime und st_mtime der Datei zum Aktualisieren.

Die Funktion fseek64() verhält sich wie fseek(), außer dass bei fseek64() der Offset-Typ long long verwendet wird.

Es besteht kein funktionaler Unterschied zwischen fseeko() und fseeko64(), außer dass fseeko64() die Struktur off64_t verwendet. Die Funktion fseeko() entspricht der modifizierten Funktion fseek(), mit der Ausnahme, dass das Offset-Argument den Typ off_t hat und der Fehler EOVERFLOW sich geändert hat.

BS2000
Wenn BS2000-Dateien ausgeführt werden, ist Folgendes zu beachten:

fseek() positioniert den Lese-/Schreibzeiger für die Datei mit stream gemäß den Angaben in offset und whence. Damit ist die Möglichkeit gegeben, eine Datei nicht-sequenziell zu bearbeiten.

In Textdateien (SAM im Textmodus, ISAM) kann man absolut auf Dateianfang und -ende positionieren sowie auf eine vorher mit ftell() gemerkte Position.

In Binärdateien (SAM im Binärmodus, PAM, INCORE) kann sowohl absolut (s.o.) als auch relativ um eine gewünschte Anzahl Bytes, bezogen auf Dateianfang, aktuelle Position oder Dateiende positioniert werden.

Für die Parameter offset und whence sind Bedeutung, Kombinationsmöglichkeiten und Wirkung für Text- und Binärdateien unterschiedlich und werden deshalb im Folgenden getrennt beschrieben:

Textdateien (SAM im Textmodus, ISAM)

Mögliche Werte:

offset	0L oder Wert, der durch einen vorhergehenden ftell-Aufruf ermittelt wurde.
whence	SEEK_SET (Dateianfang) SEEK_END (Dateiende)

Sinnvolle Kombinationsmöglichkeiten und Wirkung:

offset	whence	Wirkung
ftell-Wert	SEEK_SET	Positionieren auf die durch ftell() ermittelte Position.
0L	SEEK_SET	Positionieren auf Dateianfang.
0L	SEEK_END	Positionieren auf Dateiende.

Binärdateien (SAM im Binärmodus, PAM, INCORE)

Mögliche Werte:

offset	Anzahl der Bytes, um die der aktuelle Lese-/Schreibzeiger verschoben werden soll, und zwar positive Zahl: Vorwärts positionieren Richtung Dateiende negative Zahl: Rückwärts positionieren Richtung Dateianfang 0L: absolut Positionieren auf Dateianfang bzw. -ende.
whence	Bei absoluter Positionierung auf Dateianfang oder -ende, Zielpunkt, auf den der Lese-/Schreibzeiger verschoben werden soll und bei relativer Positionierung, Bezugspunkt, von dem aus der Lese-/Schreibzeiger um offset Bytes verschoben werden soll: SEEK_SET (Dateianfang) SEEK_CUR (aktuelle Position) SEEK_END (Dateiende)

Sinnvolle Kombinationsmöglichkeiten und Wirkung:

offset	whence	Wirkung
0L	SEEK_SET	Positionieren auf Dateianfang.
0L	SEEK_END	Positionieren auf Dateiende.
positive Zahl	SEEK_SET SEEK_CUR SEEK_END	Vorwärts positionieren ab Dateianfang, ab aktueller Position, ab Dateiende (über das Dateiende hinaus).
negative Zahl	SEEK_CUR SEEK_END	Rückwärts positionieren ab aktueller Position, ab Dateiende.
ftell-Wert	SEEK_SET	Positionieren auf die durch einen ftell-Aufruf gemerkte Position.

(Ende)

Returnwert

0

bei Erfolg.

 

-1

Ein Positionieren auf der angegebenen Datei ist nicht möglich. errno wird gesetzt, um den Fehler anzuzeigen.

Ungültiges Positionieren kann beispielsweise ein fseek() auf eine Datei sein, die nicht über fopen() geöffnet wurde. Insbesondere darf fseek() nicht für ein Terminal oder für eine Datei verwendet werden, die über popen() geöffnet wurde. Nachdem ein Datenstrom geschlossen wurde, sind keine weiteren Operationen auf diesem Datenstrom definiert.

Fehler

fseek() und fseeko() schlagen fehl, wenn entweder der Datenstrom nicht gepuffert ist oder der Puffer geleert werden muss und durch den fseek() bzw. fseeko()-Aufruf ein zu Grunde liegendes lseek() oder write() aufgerufen wird:

EAGAIN

Das Kennzeichen O_NONBLOCK für den stream zu Grunde liegenden Dateideskriptor ist gesetzt, und eine Schreiboperation würde den Prozess verzögern.

EBADF

Der stream zu Grunde liegende Dateideskriptor ist nicht zum Schreiben geöffnet oder der Puffer des Datenstroms muss geleert werden, und die Datei ist nicht geöffnet.

EFBIG

Es wurde versucht, in eine Datei zu schreiben, deren Größe die maximale Dateigröße oder die Grenze des Prozesses für die Dateigröße überschreitet (siehe auch ulimit() ).

EINTR

Die Schreiboperation wurde durch den Empfang eines Signals beendet, und es wurden keine Daten übertragen.

EINVAL

whence ist ein ungültiges Argument. Der sich daraus ergebende Wert des Lese-/Schreibzeigers ist negativ.

EIO

Ein Ein-/Ausgabefehler ist aufgetreten.

Der Prozess ist Mitglied einer Hintergrund-Prozessgruppe und versucht auf das steuernde Terminal zu schreiben, TOSTOP ist gesetzt, das Signal SIGTTOU wird vom Prozess weder ignoriert noch blockiert und die Prozessgruppe des Prozesses ist verwaist.

ENOSPC

Auf dem Datenträger, auf dem sich die Datei befindet, ist kein freier Platz mehr vorhanden.

EPIPE

Es wurde der Versuch unternommen, auf eine Pipe oder FIFO zu schreiben, die von keinem Prozess zum Lesen geöffnet war. Außerdem wird das Signal SIGPIPE an den Prozess gesendet.

Werden Threads verwendet, so wirkt sich die Funktion auf den Prozess oder auf einen Thread wie folgt aus: Beim EPIPE-Fehler wird das Signal SIGPIPE nicht an den Prozess, sondern an den aufrufenden Thread gesendet.

ENXIO

Das Gerät existiert nicht oder es kann darauf nicht zugegriffen werden.

EOVERFLOW

Für fseek(): der resultierende Datei-Offset-Wert kann in einem Objekt des Typs long nicht korrekt dargestellt werden.

EOVERFLOW

Für fseeko(): der resultierende Datei-Offset-Wert kann in einem Objekt des Typs off_t nicht korrekt dargestellt werden.

Hinweise

Obwohl in POSIX-Dateien eine von ftell() zurückgegebene Dateiposition in Bytes gemessen wird und es zulässig ist, relativ zu dieser Dateiposition zu positionieren, erfordert die Portabilität auf andere Systeme, dass fseek() eine direkte Dateiposition (d.h. den von ftell() zurückgegebenen Wert) erhält. Arithmetische Operationen an einer anderen Dateiposition, die nicht unbedingt in Bytes gemessen wird, können nicht immer sinnvoll ausgeführt werden.

Ob fseek() für eine BS2000- oder eine POSIX-Datei ausgeführt wird, hängt von der Programmumgebung ab.

BS2000 Der Aufruf fseek( stream,0L,SEEK_SET) ist äquivalent zu dem Aufruf rewind( stream ).

Werden in eine Textdatei neue Sätze geschrieben (geöffnet zum Neuerstellen oder Anfügen) und erfolgt ein fseek-Aufruf, dann werden zunächst ggf. restliche Daten aus dem Puffer in die Datei geschrieben und mit Zeilenende (\n) abgeschlossen.

Ausnahme bei ANSI-Funktionalität: Wenn die Daten einer ISAM-Datei im Puffer nicht mit einem Zeilenendezeichen enden, bewirkt fseek() keinen Zeilenwechsel bzw. Satzwechsel. D.h., die Daten werden beim Schreiben aus dem Puffer nicht automatisch mit einem Zeilenendezeichen abgeschlossen. Nachfolgende Daten verlängern den Satz in der Datei. Beim Lesen einer ISAM-Datei werden daher nur Zeilenendezeichen eingelesen, die vom Programm explizit geschrieben wurden.

Wird bei einer Binärdatei hinter das Dateiende positioniert, entsteht eine Lücke zwischen den letzten physisch gespeicherten Daten und den neu geschriebenen Daten. Lesen aus dieser Lücke liefert binäre Nullen.

Auf Systemdateien (SYSDTA, SYSLST, SYSOUT) kann nicht positioniert werden.

Ein erfolgreicher Aufruf von fseek() löscht das Kennzeichen EOF der Datei und hebt die Wirkung der vorangegangenen ungetc-Aufrufe für diese Datei auf.

Bei Satz-E/A kann fseek() nur zum Positionieren auf Dateianfang oder Dateiende benutzt werden.

fseek( stream,0L,SEEK_SET) positioniert auf den ersten Satz der Datei.

fseek( stream,0L,SEEK_END) positioniert hinter den letzten Satz der Datei.

Bei Aufrufen mit anderen Argumenten liefert fseek() EOF.

Siehe auch

fopen(), fsetpos(), ftell(), lseek(), rewind(), tell(), ungetc(), stdio.h.