NOM
readdir, readdir_r - Consulter un répertoire
SYNOPSIS
#include <dirent.h>
struct dirent *readdir(DIR *dirp);
int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);
Exigences de macros de test de fonctionnalités pour la glibc (voir
feature_test_macros(7)) :
readdir_r() : _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE ||
_SVID_SOURCE || _POSIX_SOURCE
La fonction readdir() renvoie un pointeur sur une structure dirent
représentant l’entrée suivante du flux répertoire pointé par dirp. Elle
renvoie NULL a la fin du répertoire, ou en cas d’erreur.
Avec Linux, la structure dirent est définie comme suit :
struct dirent {
ino_t d_ino; /* numéro de l’inode */
off_t d_off; /* décalage vers le prochain dirent */
unsigned short d_reclen; /* longueur de cet enregistrement */
unsigned char d_type; /* type du fichier ; pas pris en
charge par tous les types de
système de fichiers */
char d_name[256]; /* nom du fichier */
};
Les seuls champs exigés par POSIX.1 pour la structure dirent sont :
d_name[], de taille non définie, avec au plus NAME_MAX caractères avant
le caractère nul final ; et (en tant qu’extension XSI) d_ino. Les
autres champs ne sont pas standard, et ne sont pas présents sur tous
les systèmes ; voyez les NOTES ci-dessous 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
dirp, 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
En cas de succès, readdir() renvoie un pointeur sur une structure
dirent (cette structure peut avoir été alouée statiquement ; n’essayez
pas de la désalouer avec free(3)). Lorsque la fin du répertoire est
atteinte, NULL est renvoyé et errno n’est pas modifiée. En cas
d’erreur, NULL est renvoyée et 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 du répertoire, dirp, n’est pas valable.
CONFORMITÉ
SVr4, BSD 4.3, POSIX.1-2001.
NOTES
Seuls les champs d_name et d_ino sont spécifiés dans POSIX.1-2001. les
autres champs sont disponibles sur beaucoup de systèmes, mais pas sur
tous. Sur la glibc, les programmes peuvent vérifier la disponibilités
des champs non définis dans POSIX.1 en testant sir les macros
_DIRENT_HAVE_D_NAMLEN, _DIRENT_HAVE_D_RECLEN, _DIRENT_HAVE_D_OFF ou
_DIRENT_HAVE_D_TYPE sont définie.
En dehors de Linux, le champ d_type est disponible presque uniquement
sur les systèmes BSD. Ce champ évite d’avoir à appeler lstat(2) si les
actions qui suivent dépendent du type de fichier. Si la macro de test
de fonctionnalités _BSD_SOURCE est définie, alors la glibc définie les
macros suivantes pour les valeurs renvoyées dans d_type :
DT_BLK Il s’agit d’un périphérique en mode blocs.
DT_CHR Il s’agit d’un périphérique en mode caractères.
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 régulier
DT_SOCK Il s’agit d’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.
Actuellement, seuls certains systèmes de fichiers (parmi lesquels
Btrfs, ext2, ext3 et ext4) prennent complètement en charge le type de
fichier dans d_type. Toutes les applications doivent gérer correctement
une valeur de retour valant DT_UNKNOWN.
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
getdents(2), read(2), closedir(3), dirfd(3), ftw(3), offsetof(3),
opendir(3), rewinddir(3), scandir(3), seekdir(3), telldir(3),
feature_test_macros(7)
COLOPHON
Cette page fait partie de la publication 3.23 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse
http://www.kernel.org/doc/man-pages/.
TRADUCTION
Cette page de manuel a été traduite et mise à jour par Christophe
Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par
Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Nicolas François
<nicolas.francois@centraliens.net> et l’équipe francophone de
traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document
en utilisant la commande « man -L C <section> <page_de_man> ».
4 juillet 2009 READDIR(3)