sourCEntral - mobile manpages

pdf

READDIR

BEZEICHNUNG

readdir, readdir_r − liest ein Verzeichnis

ÜBERSICHT

#include <dirent.h>

struct dirent *readdir(DIR *dirp);

int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);

Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):

readdir_r():

_POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE || _POSIX_SOURCE

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.

Unter Linux 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]; /* Dateiname */
};

The only fields in the dirent structure that are mandated by POSIX.1 are: d_name[], of unspecified size, with at most NAME_MAX characters preceding the terminating null byte ('\0'); and (as an XSI extension) d_ino. The other fields are unstandardized, and not present on all systems; see NOTES below for some further details.

Die von readdir() zurückgegebenen Daten können bei nachfolgenden Aufrufen von readdir() für den gleichen Verzeichnis−Stream überschrieben werden.

Die Funktion readdir_r() ist eine ablaufinvariante Version von readdir(). Sie liest den nächsten Verzeichniseintrag aus dem Verzeichnis−Stream dirp und gibt diesen in den vom aufrufenden Prozess bereitgestellten Puffer, auf den entry weist, zurück. (Siehe ANMERKUNGEN für Informationen über die Bereitstellung dieses Puffers.) Ein Zeiger auf den zurückgegebenen Eintrag wird in *result platziert; falls das Ende der Verzeichnis−Streams erreicht wurde, wird stattdessen NULL in *result zurückgegeben.

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.

Bei Erfolg gibt die Funktion readdir_r() 0 zurück; im Fehlerfall eine positive Fehlernummer (aufgelistet unter ERRORS). Wenn das Ende des Verzeichnis−Streams erreicht wird, gibt readdir_r() 0 zurück, der Rückgabewert von *result ist dann NULL.

FEHLER

EBADF

Unzulässiger Deskriptor für den Verzeichnis−Stream dirp.

ATTRIBUTES

Multithreading (see pthreads(7))
The readdir() function is not thread−safe.

The readdir_r() function is thread−safe.

KONFORM ZU

SVr4, 4.3BSD, POSIX.1−2001.

ANMERKUNGEN

Von POSIX.1−2001 werden nur die Felder d_name und d_ino beschrieben. 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.

The value returned in d_off is the same as would be returned by calling telldir(3) at the current position in the directory stream. Be aware that despite its type and name, the d_off field is seldom any kind of directory offset on modern file systems. Applications should treat this field as an opaque value, making no assumptions about its contents; see also telldir(3).

Das Feld d_type steht im Gegensatz zu Linux hauptsächlich nur auf BSD−Systemen zur Verfügung. Dieses Feld ermöglicht es, den Aufwand für den Aufruf von lstat(2) zu vermeiden, wenn weitere Aktionen von der Art der Datei abhängen. Wenn das Feature−Test−Makro _BSD_SOURCE definiert ist, definiert Glibc die folgenden Makro−Konstanten für den Rückgabewert von 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 ist unbekannt.

Wenn der Dateityp nicht bestimmt werden konnte, wird in d_type der Wert DT_UNKNOWN zurückgegeben.

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.

Da POSIX.1 die Größe des Feldes d_name nicht festlegt und weitere nicht standardisierte Felder diesem Feld innerhalb der dirent−Struktur vorausgehen können, sollten portable Anwendungen, die readdir_r () verwenden, den Puffer, dessen Adresse in entry übergeben wird, wie folgt bereitstellen:

name_max = pathconf(dirpath, _PC_NAME_MAX);
if (name_max == −1) /* Grenze nicht definiert, oder Fehler */
name_max = 255; /* etwas vermuten */
len = offsetof(struct dirent, d_name) + name_max + 1;
entryp = malloc(len);

(POSIX.1 fordert, dass d_name das letzte Feld in struct dirent ist.)

SIEHE AUCH

getdents(2), read(2), closedir(3), dirfd(3), ftw(3), offsetof(3), opendir(3), rewinddir(3), scandir(3), seekdir(3), telldir(3)

KOLOPHON

Diese Seite ist Teil der Veröffentlichung 3.52 des Projekts Linux−man−pages. Eine Beschreibung des Projekts und Informationen, wie Fehler gemeldet werden können, finden sich unter http://www.kernel.org/doc/man−pages/.

ÜBERSETZUNG

Die deutsche Übersetzung dieser Handbuchseite wurde von Markus Kaufmann <markus DOT kaufmann AT gmx DOT de>, Helge Kreutzmann <debian AT helgefjell DOT de> und Martin Eberhard Schauer <Martin DOT E DOT Schauer AT gmx DOT 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 AT lists DOT debian DOT org>.

pdf