Provided by: manpages-de-dev_4.21.0-2_all 
BEZEICHNUNG
readdir - liest ein Verzeichnis
BIBLIOTHEK
Standard-C-Bibliothek (libc, -lc)
ÜBERSICHT
#include <dirent.h>
struct dirent *readdir(DIR *Verzz);
BESCHREIBUNG
Die Funktion readdir() liefert einen Zeiger auf eine dirent-Struktur zurück, welche den nächsten Eintrag
in dem Verzeichnis-Stream darstellt, auf das Verzz weist. Falls das Dateiende erreicht wurde oder ein
Fehler auftrat, wird NULL zurückgegeben.
In der Glibc-Implementierung ist die Struktur dirent wie folgt definiert:
struct dirent {
ino_t d_ino; /* Inode-Nummer */
off_t d_off; /* kein Offset; siehe ANMERKUNGEN */
unsigned short d_reclen; /* Länge dieses Datensatzes */
unsigned char d_type; /* Dateityp; nicht von allen
Dateisystemtypen unterstützt */
char d_name[256]; /* Mit Nullbyte abgeschlossener Dateiname */
};
POSIX.1 fordert in der dirent-Struktur lediglich die Felder d_name und d_ino. Die anderen Felder sind
nicht standardisiert und nicht auf allen Systemen vorhanden; siehe die folgenden ANMERKUNGEN für einige
weitere Details.
Die Felder der Struktur dirent sind wie folgt definiert:
d_ino Dies ist die Inode-Nummer der Datei.
d_off Der in d_off zurückgegebene Wert ist der gleiche, als wenn telldir(3) an der aktuellen Position im
Verzeichnis-Stream aufgerufen werden würde. Beachten Sie, dass ungeachtet des Typs und Namens das
d_off-Feld in modernen Dateisystemen selten ein Verzeichnis-Offset irgendeiner Art ist.
Anwendungen sollten dieses Feld als verdeckten Wert auffassen und keine Vermutungen über dessen
Inhalt anstellen; siehe auch telldir(3).
d_reclen
Dies ist die Größe (in Bytes) des zurückgelieferten Datensatzes. Dies könnte auf die Größe der
oben gezeigten Strukturdefinition nicht passen; siehe ANMERKUNGEN.
d_type Dieses Feld enthält einen Wert, der den Dateityp anzeigt und es damit ermöglicht, die Kosten für
den Aufruf von lstat(2) zu vermeiden, falls weitere Aktionen von dem Dateityp abhängen.
Falls ein geeignetes Feature-Test-Makro (_DEFAULT_SOURCE unter Glibc-Versionen seit 2.19 oder
_BSD_SOURCE unter Glibc-Versionen 2.19 und älter) definiert ist, definiert Glibc die folgenden
Makrokonstanten für den in d_type zurückgelieferten Wert:
DT_BLK Dies ist ein blockorientiertes Gerät.
DT_CHR Dies ist ein zeichenorientiertes Gerät.
DT_DIR Dies ist ein Verzeichnis.
DT_FIFO Dies ist ein FIFO (eine benannte Pipe).
DT_LNK Dies ist ein symbolischer Link.
DT_REG Dies ist eine reguläre Datei.
DT_SOCK Dies ist ein UNIX Domain Socket.
DT_UNKNOWN Der Dateityp konnte nicht ermittelt werden.
Derzeit unterstützen nur ein paar Dateisysteme (darunter Btrfs, ext2, ext3 und ext4) die Rückgabe
des Dateityps in d_type vollständig. Alle Anwendungen müssen mit dem Rückgabewert DT_UNKNOWN
umgehen können.
d_name Dieses Feld enthält den mit einem Nullbyte abgeschlossenen Dateinamen. Siehe ANMERKUNGEN.
Die von readdir() zurückgegebenen Daten können bei nachfolgenden Aufrufen von readdir() für den gleichen
Verzeichnis-Stream überschrieben werden.
RÜCKGABEWERT
Nach erfolgreichem Abschluss gibt readdir() einen Zeiger auf eine dirent-Struktur zurück. (Diese Struktur
kann statisch bereitgestellt worden sein; versuchen Sie nicht, den Speicher mittels free(3) freizugeben.)
Falls das Ende des Verzeichnis-Streams erreicht wird, ist der Rückgabewert NULL und errno wird nicht
geändert. Wenn ein Fehler eintritt, wird NULL zurückgegeben und errno wird gesetzt, um den Fehler
anzuzeigen. Um das Ende des Streams von einem Fehler zu unterscheiden, setzen Sie vor dem Aufruf von
readdir() errno auf Null und prüfen dann den Wert von errno, falls NULL zurückgeliefert wurde.
FEHLER
EBADF Unzulässiger Deskriptor für den Verzeichnis-Stream Verzz.
ATTRIBUTE
Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.
┌────────────────────────────────────────────────────┬───────────────────────┬──────────────────────────┐
│ Schnittstelle │ Attribut │ Wert │
├────────────────────────────────────────────────────┼───────────────────────┼──────────────────────────┤
│ readdir() │ Multithread-Fähigkeit │ MT-Unsafe race:dirstream │
└────────────────────────────────────────────────────┴───────────────────────┴──────────────────────────┘
In der aktuellen POSIX.1-Spezifikation (POSIX.1-2008) muss readdir() nicht Thread-sicher sein. Bei moder‐
nen Implementierungen (einschließlich der Glibc-Implementierung) sind gleichzeitige Aufrufe von read‐
dir(), die verschiedene Verzeichnis-Streams festlegen, Thread-sicher. In Fällen, in denen mehrere Threads
vom gleichen Verzeichnis-Stream lesen müssen, wird die Verwendung von readdir() mit externere Synchroni‐
sation immer noch der Verwendung der veralteten Funtion readdir_r(3) vorgezogen. Es wird erwartet, dass
zukünftige Versionen von POSIX.1 verlangen werden, dass readdir() Thread-sicher ist, wenn es parallel auf
verschiedene Verzeichnis-Streams angewandt wird.
STANDARDS
POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
ANMERKUNGEN
Ein Verzeichnis-Stream wurde mittels opendir(3) geöffnet.
Die Reihenfolge, in der Dateinamen durch sukzessive Aufrufe von readdir() gelesen werden, hängt von der
Dateisystemimplementierung ab; es ist daher unwahrscheinlich, dass die Namen in irgendeiner Weise sor‐
tiert sein werden.
Von POSIX.1 werden nur die Felder d_name und (als XSI-Erweiterung) d_ino beschrieben. Neben Linux ist das
Feld d_type hauptsächlich auf BSD-Systemen verfügbar. Die restlichen Felder sind auf vielen, aber nicht
allen Systemen verfügbar. Unter Glibc können Programme die Verfügbarkeit der nicht von POSIX.1 definier‐
ten Felder überprüfen. Dazu müssen sie prüfen, ob die Makros _DIRENT_HAVE_D_NAMLEN, _DIRENT_HAVE_D_RE‐
CLEN, _DIRENT_HAVE_D_OFF oder _DIRENT_HAVE_D_TYPE definiert sind.
Das Feld d_name
Die oben gezeigte Strukturdefinition dirent stammt aus den Glibc-Headern und zeigt das Feld d_name mit
einer festen Größe.
Warnung: Anwendungen sollten Abhängigkeiten von der Größe des Feldes d_name vermeiden. POSIX definiert es
als char d_name[], ein Zeichenfeld von unbestimmter Größe, mit höchstens NAME_MAX Zeichen vor dem ab‐
schließenden Nullbyte (»\0«).
POSIX.1 bemerkt explizit, dass dieses Feld nicht als Lvalue verwandt werden soll. Der Standard merkt auch
an, dass die Verwendung von sizeof(d_name) nicht korrekt ist; verwenden Sie stattdessen strlen(d_name).
(Auf einigen Systemen ist dieses Feld als char d_name[1] definiert!) Daraus ergibt sich, dass die Verwen‐
dung von sizeof(struct dirent) zur Ermittlung der Größe des Datensatzes einschließlich der Größe von
d_name auch nicht korrekt ist.
Beachten Sie, dass obwohl der Aufruf
fpathconf(fd, _PC_NAME_MAX)
für die meisten Dateisysteme den Wert 255 zurückliefert, auf einigen Dateisystemen (z.B. CIFS und Win‐
dows-SMB-Servern) der mit einem Nullbyte abgeschlossene Dateiname, der (korrekterweise) in d_name zurück‐
geliefert wird, diese Größe tatsächlich überschreiten kann. In diesen Fällen wird das Feld d_reclen einen
Wert enthalten, der die Größe der oben gezeigten Glibc-Struktur dirent überschreitet.
SIEHE AUCH
getdents(2), read(2), closedir(3), dirfd(3), ftw(3), offsetof(3), opendir(3), readdir_r(3), rewinddir(3),
scandir(3), seekdir(3), telldir(3)
ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von Markus Kaufmann <markus.kaufmann@gmx.de>, Martin
Eberhard Schauer <Martin.E.Schauer@gmx.de>, Helge Kreutzmann <debian@helgefjell.de> und Mario Blättermann
<mario.blaettermann@gmail.com> erstellt.
Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 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.
Linux man-pages 6.03 5. Februar 2023 readdir(3)