readdir(3)

NOM
readdir - Consulter un rpertoire

BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)

SYNOPSIS
#include <dirent.h>

struct dirent *readdir(DIR *dirp);

DESCRIPTION
La fonction readdir() renvoie un pointeur sur une structure dirent reprsentant l'entre suivante du flux rpertoire point par dirp. Elle renvoie NULL la fin du rpertoire ou en cas d'erreur.

Dans l'implmentation de la glibc, la structure dirent est dfinie comme suit :

    struct dirent {
        ino_t          d_ino;       /* numro d'inud */
        off_t          d_off;       /* pas une position ; consultez NOTES */
        unsigned short d_reclen;    /* longueur de cet enregistrement */
        unsigned char  d_type;      /* type du fichier ; pas pris en
                                       charge par tous les types de
                                       systme de fichiers */
        char           d_name[256]; /* nom du fichier termin par l'octet NULL */
    };

Les seuls champs exigs par POSIX.1 pour la structure dirent sont d_name et d_ino. Les autres champs ne sont pas normaliss et ne sont pas prsents sur tous les systmes; consultez les NOTES ci-dessous pour plus de dtails.

Les champs de la structure dirent sont les suivants:

d_ino
    Le numro d'inode du fichier.

d_off
    La valeur renvoye dans d_off est celle qui serait renvoye en appelant telldir(3) la position actuelle dans le flux rpertoire. Soyez conscient que, malgr son type et son nom, le champ d_off ne reprsente que rarement une sorte de position de rpertoire sur les systmes de fichiers modernes. Les applications devraient traiter ce champ comme une valeur opaque, sans faire de supposition sur son contenu. Consultez aussi telldir(3).

d_reclen
    La taille (en octets) de l'enregistrement renvoy. Elle peut ne pas correspondre la taille de la dfinition de la structure montre plus haut; voir NOTES.

d_type
    Ce champ contient une valeur indiquant le type du fichier, permettant d'viter le cot d'un appel lstat(2) si d'autres actions dpendent du type du fichier.

    Lorsqu'une macro de test de fonctionnalit est dfinie (_DEFAULT_SOURCE depuis la glibc2.19, ou _BSD_SOURCE pour la glibc2.19 ou antrieure), la glibc dfinit les constantes de macro suivantes pour les valeurs renvoyes dans d_type:

    DT_BLK
        Il s'agit d'un périphérique bloc.

    DT_CHR
        Il s'agit d'un périphérique caractère.

    DT_DIR
        Il s'agit d'un répertoire

    DT_FIFO
        Il s'agit d'un tube nommé (FIFO).

    DT_LNK
        Il s'agit d'un lien symbolique.

    DT_REG
        Il s'agit d'un fichier ordinaire.

    DT_SOCK
        Il s'agit d'un socket de domaine UNIX.

    DT_UNKNOWN
        Le type du fichier n'a pu tre dtermin.

    Actuellement, seuls certains systèmes de fichiers (parmi lesquels Btrfs, ext2, ext3 et ext4) prennent complètement en charge le renvoi du type de fichier dans d_type. Toutes les applications doivent gérer correctement une valeur de retour valant DT_UNKNOWN.

d_name
    Ce champ contient le nom de fichier termin par l'octet NULL. Voir NOTES.

Les donnes renvoyes par readdir() sont crases lors de l'appel suivant readdir() sur le mme flux rpertoire.

VALEUR RENVOYÉE
En cas de succs, readdir() renvoie un pointeur sur une structure dirent (cette structure peut avoir t alloue statiquement; n'essayez pas de la dsallouer avec free(3)).

Lorsque la fin du flux rpertoire est atteinte, NULL est renvoy et errno n'est pas modifie. En cas d'erreur, NULL est renvoye et errno contient le code d'erreur. Pour distinguer la fin du flux d'une erreur, il faut assigner errno zro avant d'appeler readdir() puis ensuite tester la valeur de errno si NULL est renvoy.

ERREURS

EBADF
    Le descripteur de flux rpertoire dirp n'est pas valable.

ATTRIBUTS
Pour une explication des termes utilisés dans cette section, consulter attributes(7).
Interface | Attribut | Valeur
readdir() | Sécurité des threads | MT-Unsafe race:dirstream

Dans la spcification POSIX.1 courante (POSIX.1-2008), il n'est pas requis que readdir(3) soit sr vis--vis des threads. Cependant, dans les implmentations modernes, incluant la glibc, des appels concurrents readdir(3) pour des flux rpertoire diffrents sont srs vis--vis des threads. Dans le cas o de multiples threads doivent lire depuis un flux de rpertoire identique, l'utilisation de readdir(3) avec une synchronisation externe est toujours prfrable l'utilisation de readdir_r(3). Il est attendu quune future version de POSIX.1 demande que readdir() soit sr vis--vis des threads lorsquil est employ simultanment sur des flux rpertoire diffrents.

VERSIONS
Seuls les champs d_name et (comme extension XSI) d_ino sont spcifis dans POSIX.1. Ailleurs que sur Linux, le champ d_type est principalement disponible sur les systmes BSD. Les autres champs sont disponibles sur beaucoup de systmes, mais pas sur tous. Avec la glibc, les programmes peuvent vrifier la disponibilit des champs non dfinis dans 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 dfinies.

  Le champ d_name
La dfinition de la structure dirent donne ci-dessus est reprise des en-ttes de la glibc et montre le champ d_name avec une taille fixe.

Avertissement: les applications devraient viter tout dpendance sur la taille du champ d_name. POSIX la dfinit comme char d_name[], un tableau de caractres de taille non spcifie, avec au plus NAME_MAX caractres avant l'octet NULL final ('\0').

POSIX.1 est explicite sur le fait que ce champ ne doit pas tre utilis comme une lvalue. La norme ajoute que l'utilisation de sizeof(d_name) est incorrecte; utilisez strlen(d_name) la place. Sur certains systmes, ce champ est dfini comme char d_name[1]! Cela implique que l'utilisation de sizeof(struct dirent) pour dterminer la taille de l'enregistrement, y compris du champ d_name, est galement incorrecte.

Notez que bien que l'appel

    fpathconf(fd, _PC_NAME_MAX)

renvoie la valeur 255 pour la plupart des systmes de fichiers, le nom de fichier termin par l'octet NULL qui est (correctement) renvoy dans d_name peut en fait dpasser cette taille sur certains systmes de fichiers (CIFS ou les serveurs Windows SMB par exemple). Dans de tels cas, le champ d_reclen contiendra une valeur qui dpasse la taille de la structure dirent de la glibc montre plus haut.

STANDARDS
POSIX.1-2008.

HISTORIQUE
POSIX.1-2001, SVr4, 4.3BSD.

NOTES
Un flux rpertoire est ouvert avec opendir(3).

L'ordre dans lequel les noms de fichier sont lus par des appels successifs readdir() dpend de l'implmentation du systme de fichiers; il est peu probable que les noms soient tris d'une quelconque faon.

VOIR AUSSI
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)

TRADUCTION
La traduction française de cette page de manuel a été créée par #-#-#-#-# min-002-occurences.po (perkamon) #-#-#-#-#, Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org>, Jean-Philippe MENGUAL <jpmengual@debian.org>, Jean-Pierre Giraud <jean-pierregiraud@neuf.fr>, #-#-#-#-# min-003-occurences.po (perkamon) #-#-#-#-#, Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org>, Jean-Philippe MENGUAL <jpmengual@debian.org>, Jean-Pierre Giraud <jean-pierregiraud@neuf.fr>, #-#-#-#-# min-004-occurences.po (perkamon) #-#-#-#-#, Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org>, Jean-Philippe MENGUAL <jpmengual@debian.org>, Jean-Pierre Giraud <jean-pierregiraud@neuf.fr>, #-#-#-#-# min-010-occurences.po (perkamon) #-#-#-#-#, Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org>, Thomas Vincent <tvincent@debian.org>, #-#-#-#-# min-020-occurences.po (perkamon) #-#-#-#-#, Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org>, Jean-Philippe MENGUAL <jpmengual@debian.org>, Jean-Pierre Giraud <jean-pierregiraud@neuf.fr>, #-#-#-#-# min-100-occurences.po (perkamon) #-#-#-#-#, Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org>, Jean-Philippe MENGUAL <jpmengual@debian.org>, Jean-Pierre Giraud <jean-pierregiraud@neuf.fr> et #

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 (https://www.gnu.org/licenses/gpl-3.0.html) concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à debian-l10n-french@lists.debian.org.