read - Bytes aus Datei lesen

Definition	#include <unistd.h> ssize_t read(int fildes, void *buf, size_t nbyte);
Beschreibung	read() liest nbyte Bytes aus der Datei, die dem Dateideskriptor fildes zugeordnet ist, in den Puffer, auf den buf zeigt. fildes ist ein Dateideskriptor, der von einem Aufruf von creat(), open(), dup(), fcntl() oder pipe() zurückgegeben wird. Wenn nbyte gleich 0 ist, liefert read() nur den Wert 0 und buf. In Dateien, die das Suchen unterstützen (z.B. normale Dateien), beginnt read() an einer Dateiposition, die vom mit fildes verbundenen Lese-/Schreibzeiger zur Verfügung gestellt wird. Der Lese-/Schreibzeiger wird um die Byteanzahl erhöht, die tatsächlich gelesen wurde. Dateien, die das Suchen nicht unterstützen (z.B. Terminal-Gerätedateien) lesen immer von der aktuellen Position. Der Wert des Lese-/Schreibzeigers einer solchen Datei ist nicht definiert. Nach dem aktuellen Dateiende findet keine Datenübertragung statt. Wenn die Anfangsposition am oder nach dem Dateiende liegt, wird der Wert 0 zurückgeliefert. Beim Versuch, von einer leeren Pipe oder FIFO zu lesen, geschieht Folgendes: Wenn kein Prozess die Pipe zum Schreiben geöffnet hat, liefert read() den Wert 0, um das Dateiende anzuzeigen. Wenn ein Prozess die Pipe zum Schreiben geöffnet hat und O_NONBLOCK gesetzt ist, liefert read() den Returnwert -1 und besetzt errno mit EAGAIN. Wenn ein Prozess die Pipe zum Schreiben geöffnet hat und O_NONBLOCK nicht gesetzt ist, blockiert read() solange, bis Daten geschrieben wurden oder bis die Pipe von allen Prozessen geschlossen wird, die diese zum Schreiben geöffnet hatten. Beim Versuch, aus einer Datei zu lesen, die keine Pipe oder FIFO ist, die nichtblockierendes Lesen unterstützt und für die zurzeit keine Daten verfügbar sind, geschieht Folgendes: Wenn O_NONBLOCK gesetzt ist, liefert read() den Wert -1 und besetzt errno mit EAGAIN. Wenn O_NONBLOCK nicht gesetzt ist, blockiert read() solange, bis Daten verfügbar werden. Die Verwendung des O_NONBLOCK-Flags hat keine Wirkung, wenn Daten verfügbar sind. read() liest Daten, die zuvor in eine Datei geschrieben wurden. Wenn ein Teil einer normalen Datei vor dem Dateiende nicht beschrieben wurde, liefert read() Nullbytes. lseek() z. B. erlaubt es, den Lese-/Schreibzeiger hinter das Ende von in einer Datei existierenden Daten zu positionieren. Werden später Daten an diese Position geschrieben, liefern nachfolgende Leseoperationen in der Lücke zwischen dem ehemaligen Dateiende und den neu geschriebenen Daten solange Nullbytes, bis Daten in die Lücke geschrieben werden. Bei erfolgreicher Beendigung und wenn nbyte größer als 0 ist, aktualisiert read() die Strukturkomponente st_atime der Datei (siehe sys/stat.h) und liefert die Anzahl der gelesenen Bytes. Diese Anzahl ist niemals größer als nbyte. Der Returnwert kann kleiner als nbyte sein, wenn die Anzahl der in der Datei verbleibenden Bytes kleiner als nbyte ist, wenn read() durch ein Signal unterbrochen wurde oder wenn die Datei eine Pipe, FIFO oder Gerätedatei ist und weniger als nbyte Bytes sofort zum Lesen verfügbar sind. So kann z.B. ein read-Aufruf für eine Datei, die einem Terminal zugeordnet ist, genau eine Eingabezeile liefern. Wenn ein read-Aufruf von einem Signal unterbrochen wird, bevor er Daten lesen kann, liefert er den Wert -1, wobei errno gleich EINTR gesetzt wird. Wenn ein read-Aufruf von einem Signal unterbrochen wird, nachdem er erfolgreich einige Daten lesen konnte, liefert er die Anzahl der gelesenen Bytes. Werden Threads verwendet, so wirkt sich die Funktion auf den Prozess oder auf einen Thread wie folgt aus: Beim Versuch, von einer leeren Pipe oder FIFO zu lesen, geschieht Folgendes: ... Wenn ein Prozess die Pipe zum Schreiben geöffnet hat und O_NONBLOCKnicht gesetzt ist, blockiert read() den aufrufenden Thread solange, bis Daten geschrieben wurden oder bis die Pipe von allen Prozessen geschlossen wird, die diese zum Schreiben geöffnet hatten. Beim Versuch, aus einer Datei zu lesen, die keine Pipe oder FIFO ist, die nichtblockierendes Lesen unterstützt und für die zurzeit keine Daten verfügbar sind, geschieht Folgendes: ... Wenn O_NONBLOCK nicht gesetzt ist, blockiert read() den aufrufenden Thread solange, bis Daten verfügbar werden.
Returnwert	Anzahl der tatsächlich gelesenen Bytes
		bei erfolgreicher Beendigung.
	0	bei Dateiende.
	-1	bei Fehler. Der Inhalt des Puffers, auf den buf zeigt, ist unbestimmt. errno  wird gesetzt, um den Fehler anzuzeigen.
Fehler	read() schlägt fehl, wenn gilt:
	EAGAIN	Das Flag O_NONBLOCK ist für den Dateideskriptor gesetzt und der Prozess würde durch die Leseoperation angehalten werden.
	Erweiterung
	EAGAIN	Der Systemspeicher, der für „raw“-Ein-/Ausgabe zur Verfügung steht, ist vorübergehend nicht ausreichend, oder in einer Terminal-Gerätedatei warten keine Daten darauf, gelesen zu werden, und O_NONBLOCK ist gesetzt, oder in einem Datenstrom wartet keine Nachricht darauf, gelesen zu werden, und O_NONBLOCK ist gesetzt. (Ende)
	EBADF	fildes ist kein gültiger, zum Lesen geöffneter Dateideskriptor.
	EFAULT	buf weist über den zugewiesenen Adressraum des Prozesses hinaus.
	EINTR	Die Leseoperation wurde durch ein Signal unterbrochen und es wurden keine Daten übertragen.
	EINVAL	Es wurde versucht, von einem Datenstrom zu lesen, der mit einem Multiplexer verbunden ist.
	EIO	Ein physikalischer Ein-/Ausgabefehler ist aufgetreten, oder der Prozess ist Mitglied einer Hintergrund-Prozessgruppe und versucht, von seinem steuernden Terminal zu lesen. Der Prozess ignoriert oder blockiert das Signal SIGTTIN, oder die Prozessgruppe ist verwaist.
	ENXIO	Eine Anforderung für ein nicht existierendes Gerät wurde gemacht, oder die Anforderung lag außerhalb der Fähigkeiten des Geräts.
Hinweise	Zum Lesen von Verzeichnissen wird dringend empfohlen, readdir() bzw. readdir64() anstelle von read() zu verwenden. Die Anzahl der tatsächlich gelesenen Bytes kann kleiner sein als die Angabe in nbytes, wenn vorher das Zeilenende erreicht wird (nur bei Textdateien), sowie bei Dateiende oder Fehler. Um sicherzugehen, dass nicht mehr Bytes gelesen werden, als der Puffer aufnehmen kann, sollte sizeof() verwendet werden. BS2000 Bei Textdateien mit der Zugriffsart SAM und variabler Satzlänge, für die zusätzlich eine maximale Satzlänge angegeben ist, gilt: Wenn bei open() die Angabe O_NOSPLIT gemacht wurde, werden Sätze maximaler Länge beim Lesen nicht mit dem darauffolgenden Satz verkettet. Standardmäßig (also ohne die Angabe O_NOSPLIT) wird beim Lesen eines Satzes mit maximaler Satzlänge angenommen, dass es sich bei dem Folgesatz um die Fortsetzung dieses Satzes handelt, und die Sätze werden verkettet. (Ende) Ob read() für eine BS2000- oder eine POSIX-Datei ausgeführt wird, hängt von der Programmumgebung ab.
Siehe auch	fcntl(), lseek(), open(), pipe(), readdir(), readdir64(), unistd.h, Abschnitt "Allgemeine Terminalschnittstelle“.