readdir(3) Library Functions Manual readdir(3) BEZEICHNUNG readdir - liest ein Verzeichnis BIBLIOTHEK Standard-C-Bibliothek (libc, -lc) UBERSICHT #include struct dirent *readdir(DIR *Verzz); BESCHREIBUNG Die Funktion readdir() liefert einen Zeiger auf eine dirent-Struktur zuruck, welche den nachsten Eintrag in dem Verzeichnis-Stream darstellt, auf das Verzz weist. Falls das Dateiende erreicht wurde oder ein Fehler auftrat, wird NULL zuruckgegeben. 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; /* Lange dieses Datensatzes */ unsigned char d_type; /* Dateityp; nicht von allen Dateisystemtypen unterstutzt */ 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 fur 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 zuruckgegebene Wert ist der gleiche, als wenn telldir(3) an der aktuellen Position im Verzeichnis-Stream aufgerufen werden wurde. 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 uber dessen Inhalt anstellen; siehe auch telldir(3). d_reclen Dies ist die Grosse (in Bytes) des zuruckgelieferten Datensatzes. Dies konnte auf die Grosse der oben gezeigten Strukturdefinition nicht passen; siehe ANMERKUNGEN. d_type Dieses Feld enthalt einen Wert, der den Dateityp anzeigt und es damit ermoglicht, die Kosten fur den Aufruf von lstat(2) zu vermeiden, falls weitere Aktionen von dem Dateityp abhangen. Falls ein geeignetes Feature-Test-Makro (_DEFAULT_SOURCE unter Glibc-Versionen seit 2.19 oder _BSD_SOURCE unter Glibc-Versionen 2.19 und alter) definiert ist, definiert Glibc die folgenden Makrokonstanten fur den in d_type zuruckgelieferten Wert: DT_BLK Dies ist ein blockorientiertes Gerat. DT_CHR Dies ist ein zeichenorientiertes Gerat. 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 regulare Datei. DT_SOCK Dies ist ein UNIX Domain Socket. DT_UNKNOWN Der Dateityp konnte nicht ermittelt werden. Derzeit unterstutzen nur ein paar Dateisysteme (darunter Btrfs, ext2, ext3 und ext4) die Ruckgabe des Dateityps in d_type vollstandig. Alle Anwendungen mussen mit dem Ruckgabewert DT_UNKNOWN umgehen konnen. d_name Dieses Feld enthalt den mit einem Nullbyte abgeschlossenen Dateinamen. Siehe ANMERKUNGEN. Die von readdir() zuruckgegebenen Daten konnen bei nachfolgenden Aufrufen von readdir() fur den gleichen Verzeichnis-Stream uberschrieben werden. RUCKGABEWERT Nach erfolgreichem Abschluss gibt readdir() einen Zeiger auf eine dirent-Struktur zuruck. (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 Ruckgabewert NULL und errno wird nicht geandert. Wenn ein Fehler eintritt, wird NULL zuruckgegeben 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 prufen dann den Wert von errno, falls NULL zuruckgeliefert wurde. FEHLER EBADF Unzulassiger Deskriptor fur den Verzeichnis-Stream Verzz. ATTRIBUTE Siehe attributes(7) fur eine Erlauterung der in diesem Abschnitt verwandten Ausdrucke. +---------------+-------------------------+----------------------------+ |Schnittstelle | Attribut | Wert | +---------------+-------------------------+----------------------------+ |readdir() | Multithread-Fahigkeit | MT-Unsicher race:dirstream | +---------------+-------------------------+----------------------------+ In der aktuellen POSIX.1-Spezifikation (POSIX.1-2008) muss readdir() nicht Thread-sicher sein. Bei modernen Implementierungen (einschliesslich der Glibc-Implementierung) sind gleichzeitige Aufrufe von readdir(), die verschiedene Verzeichnis-Streams festlegen, Thread-sicher. In Fallen, in denen mehrere Threads vom gleichen Verzeichnis-Stream lesen mussen, wird die Verwendung von readdir() mit externere Synchronisation immer noch der Verwendung der veralteten Funtion readdir_r(3) vorgezogen. Es wird erwartet, dass zukunftige Versionen von POSIX.1 verlangen werden, dass readdir() Thread-sicher ist, wenn es parallel auf verschiedene Verzeichnis-Streams angewandt wird. VERSIONEN Von POSIX.1 werden nur die Felder d_name und (als XSI-Erweiterung) d_ino beschrieben. Neben Linux ist das Feld d_type hauptsachlich auf BSD-Systemen verfugbar. Die restlichen Felder sind auf vielen, aber nicht allen Systemen verfugbar. Unter Glibc konnen Programme die Verfugbarkeit der nicht von POSIX.1 definierten Felder uberprufen. Dazu mussen sie prufen, ob die Makros _DIRENT_HAVE_D_NAMLEN, _DIRENT_HAVE_D_RECLEN, _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 Grosse. Warnung: Anwendungen sollten Abhangigkeiten von der Grosse des Feldes d_name vermeiden. POSIX definiert es als char d_name[], ein Zeichenfeld von unbestimmter Grosse, mit hochstens NAME_MAX Zeichen vor dem abschliessenden 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 Verwendung von sizeof(struct dirent) zur Ermittlung der Grosse des Datensatzes einschliesslich der Grosse von d_name auch nicht korrekt ist. Beachten Sie, dass obwohl der Aufruf fpathconf(fd, _PC_NAME_MAX) fur die meisten Dateisysteme den Wert 255 zuruckliefert, auf einigen Dateisystemen (z.B. CIFS und Windows-SMB-Servern) der mit einem Nullbyte abgeschlossene Dateiname, der (korrekterweise) in d_name zuruckgeliefert wird, diese Grosse tatsachlich uberschreiten kann. In diesen Fallen wird das Feld d_reclen einen Wert enthalten, der die Grosse der oben gezeigten Glibc-Struktur dirent uberschreitet. STANDARDS POSIX.1-2008. GESCHICHTE POSIX.1-2001, SVr4, 4.3BSD. ANMERKUNGEN Ein Verzeichnis-Stream wurde mittels opendir(3) geoffnet. Die Reihenfolge, in der Dateinamen durch sukzessive Aufrufe von readdir() gelesen werden, hangt von der Dateisystemimplementierung ab; es ist daher unwahrscheinlich, dass die Namen in irgendeiner Weise sortiert sein werden. 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) UBERSETZUNG Die deutsche Ubersetzung dieser Handbuchseite wurde von Markus Kaufmann , Martin Eberhard Schauer , Helge Kreutzmann und Mario Blattermann erstellt. Diese Ubersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezuglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG ubernommen. Wenn Sie Fehler in der Ubersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Ubersetzer . Linux man-pages 6.8 2. Mai 2024 readdir(3)