fread - Daten binär einlesen

Definition	#include <stdio.h> size_t fread(void *ptr, size_t size, size_t nitems, FILE *stream);
Beschreibung	fread() liest nitems Elemente der Größe size aus dem Datenstrom, auf den stream zeigt, in den Vektor, auf den ptr zeigt. Der Lese-/Schreibzeiger des Datenstroms wird, wenn er definiert ist, um die Anzahl von Bytes weitergeschaltet, die erfolgreich gelesen wurden. Wenn ein Fehler auftritt, ist der sich daraus ergebende Wert des Lese-/Schreibzeigers unbestimmt. Wenn ein Element teilweise gelesen wird, ist sein Wert unbestimmt. fread() kann die Strukturkomponente st_atime für die Datei, der stream zugeordnet ist, zum Ändern markieren (siehe sys/stat.h). Die Strukturkomponente st_atime wird aktualisiert, sobald fgetc(), fgets(), fgetwc(), fgetws(), fread(), fscanf(), getc(), getchar(), gets() oder scanf() erfolgreich für stream aufgerufen werden und Daten zurückliefern, die nicht durch einen vorangegangenen Aufruf von ungetc() oder ungetwc() bereitgestellt wurden. BS2000 Satz-Ein-/Ausgabe fread() liest einen Satz (bzw. Block) von der aktuellen Dateiposition. Anzahl der einzulesenden Zeichen: Im folgenden sei n die Gesamtanzahl der einzulesenden Zeichen, d.h. n = size * nitems Ist n größer als die aktuelle Satzlänge, wird trotzdem nur dieser Satz gelesen. Ist n kleiner als die aktuelle Satzlänge, werden nur die ersten n Zeichen des Satzes gelesen. Beim nächsten Lesezugriff werden die Daten des nächsten Satzes gelesen. fread() liefert den gleichen Returnwert wie bei Datenstrom-Ein-/Ausgabe, nämlich die Anzahl der vollständig eingelesenen Elemente. Bei Satz-Ein-/Ausgabe ist es sinnvoll, ausschließlich die Elementgröße 1 zu verwenden, da in diesem Fall der Returnwert der Länge des gelesenen Satzes entspricht (ohne ein ggf. vorhandenes Satzlängenfeld). (Ende)
Returnwert	Anzahl der erfolgreich gelesenen Elemente
		bei erfolgreicher Beendigung. Der Returnwert ist nur dann kleiner als nitems, wenn das Dateiende erreicht wird oder ein Lesefehler auftritt.
	-1	wenn size oder nitems gleich 0 sind. Der Inhalt des Vektors, auf den ptr zeigt, und der Zustand des Datenstroms bleiben unverändert. errno wird nicht gesetzt. wenn ein Lesefehler auftritt. Das Fehlerkennzeichen für den Datenstrom wird gesetzt. errno wird gesetzt, um den Fehler anzuzeigen.
Fehler	Siehe fgetc().
Hinweise	ferror() oder feof() müssen verwendet werden, um zwischen dem Auftreten des Dateiendes und eines Lesefehlers zu unterscheiden. Der Vektor, auf den ptr zeigt, muss zum Abspeichern der eingelesenen Datenelemente ausreichen. Um sicherzugehen, dass size die richtige Anzahl Bytes für ein Datenelement angibt, sollte die Funktion sizeof() für die Größe der Dateneinheit verwenden, auf die ptr zeigt. fread() liest über Zeilenende (\n) hinweg und eignet sich daher dazu, Binärdateien einzulesen. 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 fopen() die Angabe split=no gemacht wurde, werden Sätze maximaler Länge beim Lesen nicht mit dem darauffolgenden Satz verkettet. Standardmäßig oder mit der Angabe split=yes 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 fread() für eine BS2000- oder eine POSIX-Datei ausgeführt wird, hängt von der Programmumgebung ab.
Siehe auch	feof(), ferror(), fgetc(), fopen(), getc(), gets(), scanf(), stdio.h, sys/stat.h.