READDIR(3)

NOM
readdir, readdir_r - Consulter un répertoire

SYNOPSIS
#include <dirent.h>

struct dirent *readdir(DIR *dir);

int readdir(DIR *dir, struct dirent *entry, struct dirent **result);

DESCRIPTION
La fonction readdir() renvoie un pointeur sur une structure dirent représentant l'entrée suivante du flux répertoire pointé par dir. Elle renvoie NULL à la fin du répertoire, ou en cas d'erreur.

Sous Linux, la structure dirent est définie de la façon suivante :

struct dirent {
    ino_t          d_ino;       /* numéro d'inœud */
    off_t          d_off;       /* décalage jusqu'à la dirent suivante */
    unsigned short d_reclen;    /* longueur de cet enregistrement */
    unsigned char  d_type;      /* type du fichier */
    char           d_name[256]; /* nom du fichier */
};

D'après POSIX, la structure dirent contient un champ char d_name[] de taille non spécifiée, avec au plus NAME_MAX caractères avant l'octet nul final. POSIX.1-2001 documente aussi le champ ino_t d_ino comme une extension XSI. Les autres champs ne sont pas normalisés et ne sont pas présents sur tous les systèmes ; voir la section NOTES plus loin pour plus de détails.

Les données renvoyées par readdir() sont écrasées lors de l'appel suivant à readdir() sur le même flux répertoire. La fonction readdir_r() est la version réentrante de readdir(). Elle lit la prochaine entrée de répertoire à partir du flux de répertoire dir, et la renvoie dans le tampon de l'appelant pointé par entry. (Voir la section NOTES pour des informations sur l'allocation de ce tampon.) Un pointeur vers l'élément renvoyé est placé dans *result ; si la fin du flux de répertoire est rencontrée, NULL est renvoyé dans *result.

VALEUR RENVOYÉE
La fonction readdir() renvoie un pointeur sur une structure dirent, ou NULL lorsqu'une erreur se produit, ou lorsque la fin du répertoire est atteinte. Si une erreur se produit, errno contient le code d'erreur. La fonction readdir_r() renvoie 0 si elle réussit. Si elle échoue, elle renvoie un code d'erreur positif. Si la fin du répertoire est atteinte, readdir_r() renvoie 0 et renvoie NULL dans *result.

ERREURS

EBADF
    Le descripteur de flux répertoire dir n'est pas valide.

CONFORMITÉ
SVr4, BSD 4.3, POSIX.1-2001.

NOTES
Seuls les champs d_name et d_ino sont spécifiés par POSIX.1-2001. Les autres champs sont disponibles sur beaucoup de systèmes, mais pas sur tous. Avec la glibc, les programmes peuvent vérifier la disponibilité des champs non définis par POSIX.1 en testant si les macros _DIRENT_HAVE_D_NAMLEN, _DIRENT_HAVE_D_RECLEN, _DIRENT_HAVE_D_OFF ou _DIRENT_HAVE_D_TYPE sont définies. Ailleurs que sous Linux, le champ d_type n'est principalement disponible que sur les systèmes BSD. Ce champ permet d'éviter de devoir appeler stat(2) si d'autres actions dépendent du type de fichier. Si la macro de test de fonctionnalités _BSD_SOURCE est définie, la glibc définit les constantes suivantes pour la valeur renvoyée dans d_type :

DT_BLK
    C'est un périphérique de blocs.

DT_CHR
    C'est un périphérique de caractères.

DT_DIR
    C'est un répertoire.

DT_FIFO
    C'est un tube nommé (FIFO).

DT_LNK
    C'est un lien symbolique.

DT_REG
    C'est un fichier ordinaire.

DT_SOCK
    C'est une socket de domaine Unix.

DT_UNKNOWN
    Le type de fichier est inconnu.

Si le type de fichier ne peut pas être déterminé, la valeur DT_UNKNOWN est renvoyée dans d_type. Puisque POSIX.1 ne spécifie pas la taille du champ d_name, et que d'autres champs non standard peuvent précéder ce champ dans la structure dirent, les applications portables utilisant readdir_r() devraient allouer le tampon dont l'adresse est passée dans entry de la façon suivante :
len = offsetof(struct dirent, d_name) +
          pathconf(dirpath, _PC_NAME_MAX) + 1
entryp = malloc(len);
(POSIX.1 demande que d_name soit le dernier champ d'une structure dirent.)

VOIR AUSSI
read(2), closedir(3), dirfd(3), ftw(3), offsetof(3), opendir(3), rewinddir(3), scandir(3), seekdir(3), telldir(3), feature_test_macros(7)

TRADUCTION

Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 5 novembre 1996 et révisée le 17 juillet 2008.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 readdir ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.