plucky (3) readdir.3.gz

Provided by: manpages-de-dev_4.25.1-1_all bug

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 Versatz; siehe unten */
               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 VERSIONEN.

       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 VERSIONEN.

       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 VERSIONEN.

       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.

       ┌───────────────────────────────────────────────────┬───────────────────────┬────────────────────────────┐
       │SchnittstelleAttributWert                       │
       ├───────────────────────────────────────────────────┼───────────────────────┼────────────────────────────┤
       │readdir()                                          │ Multithread-Fähigkeit │ MT-Unsicher race:dirstream │
       └───────────────────────────────────────────────────┴───────────────────────┴────────────────────────────┘
       In  der  aktuellen  POSIX.1-Spezifikation  (POSIX.1-2008)  muss  readdir()  nicht Thread-sicher sein. Bei
       modernen Implementierungen (einschließlich der  Glibc-Implementierung)  sind  gleichzeitige  Aufrufe  von
       readdir(),  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
       Synchronisation  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.

VERSIONEN

       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 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 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
       Windows-SMB-Servern)  der  mit  einem  Nullbyte  abgeschlossene 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.

STANDARDS

       POSIX.1-2008.

GESCHICHTE

       POSIX.1-2001, 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.

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
       ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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 ⟨debian-l10n-german@lists.debian.org⟩.