table of contents
- stretch 1.22-1
- testing 2.12-1
- stretch-backports 2.11-1~bpo9+2
- unstable 2.12-1
READDIR(3) | Linux-Programmierhandbuch | READDIR(3) |
BEZEICHNUNG¶
readdir - liest ein VerzeichnisÜBERSICHT¶
#include <dirent.h> struct dirent *readdir(DIR *dirp);
BESCHREIBUNG¶
Die Funktion readdir() liefert einen Zeiger auf eine dirent-Struktur zurück, welche den nächsten Eintrag in dem Verzeichnis darstellt, auf das dirp weist. Falls das Dateiende erreicht wurde oder ein Fehler auftrat, wird ein NULL-Zeiger 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]; /* Null-terminierter 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-Datenstrom 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 Null-terminierten 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 entsprechend gesetzt. 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 dirp.
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 the current POSIX.1 specification (POSIX.1-2008), readdir() is not required to be thread-safe. However, in modern implementations (including the glibc implementation), concurrent calls to readdir() that specify different directory streams are thread-safe. In cases where multiple threads must read from the same directory stream, using readdir() with external synchronization is still preferable to the use of the deprecated readdir_r(3) function. It is expected that a future version of POSIX.1 will require that readdir() be thread-safe when concurrently employed on different directory streams.
KONFORM ZU¶
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 sortiert 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 definierten Felder überprüfen. Dazu müssen sie prüfen, 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 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 abschließenden Null-Byte ('\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) zu Ermittlung der Größe des Datensatze 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 Windows-SMB-Servern) der Null-terminierte Dateiname, der (korrekterweise) in d_name zurückgeliefert 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)KOLOPHON¶
Diese Seite ist Teil der Veröffentlichung 4.09 des Projekts Linux-man-pages. Eine Beschreibung des Projekts, Informationen, wie Fehler gemeldet werden können sowie die aktuelle Version dieser Seite finden sich unter https://www.kernel.org/doc/man-pages/.ÜBERSETZUNG¶
Die deutsche Übersetzung dieser Handbuchseite wurde von Markus Kaufmann <markus.kaufmann@gmx.de>, Helge Kreutzmann <debian@helgefjell.de> und Martin Eberhard Schauer <Martin.E.Schauer@gmx.de> 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 <debian-l10n-german@lists.debian.org>.
15. März 2016 |