readdir(3) 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
This is the size (in bytes) of the returned record. This may not match the size of the structure definition shown above; see NOTES.
d_type
This field contains a value indicating the file type, making it possible to avoid the expense of calling lstat(2) if further actions depend on the type of the file.
When a suitable feature test macro is defined (_DEFAULT_SOURCE on glibc versions since 2.19, or _BSD_SOURCE on glibc versions 2.19 and earlier), glibc defines the following macro constants for the value returned in d_type:
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.
SchnittstelleAttributWert
readdir() Multithread-FähigkeitMT-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.

The order in which filenames are read by successive calls to readdir() depends on the filesystem implementation; it us unlikely that the names will be sorted in any fashion.

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

The dirent structure definition shown above is taken from the glibc headers, and shows the d_name field with a fixed size.

Warning: applications should avoid any dependence on the size of the d_name field. POSIX defines it as char d_name[], a character array of unspecified size, with at most NAME_MAX characters preceding the terminating null byte ('\0').

POSIX.1 explicitly notes that this field should not be used as an lvalue. The standard also notes that the use of sizeof(d_name) is incorrect; use strlen(d_name) instead. (On some systems, this field is defined as char d_name[1]!) By implication, the use sizeof(struct dirent) to capture the size of the record including the size of d_name is also incorrect.

Note that while the call


    fpathconf(fd, _PC_NAME_MAX)

returns the value 255 for most filesystems, on some filesystems (e.g., CIFS, Windows SMB servers), the null-terminated filename that is (correctly) returned in d_name can actually exceed this size. In such cases, the d_reclen field will contain a value that exceeds the size of the glibc dirent structure shown above.

KOLOPHON

Diese Seite ist Teil der Veröffentlichung 4.06 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 <[email protected]>, Helge Kreutzmann <[email protected]> und Martin Eberhard Schauer <[email protected]> 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 <[email protected]>.

TRANSLATIONS

SIEHE AUCH

LAST GESUCHT