ftw(3) Library Functions Manual ftw(3) NOM ftw, nftw - Parcourir des arborescences de fichiers BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include int nftw(const char *chemin_repertoire, int (*fn)(const char *chemin_fichier, const struct stat *sb, int symb_type, struct FTW *tampon_ftw), int nb_descripteurs_fichier_ouverts, int drapeaux); [[deprecated]] int ftw(const char *chemin_repertoire, int (*fn) (const char *chemin_fichier, const struct stat *sb, int symb_type), int nb_descripteurs_fichier_ouverts); Exigences de macros de test de fonctionnalites pour la glibc (consulter feature_test_macros(7)) : nftw() : _XOPEN_SOURCE >= 500 DESCRIPTION La fonction nftw() parcourt l'arborescence de fichiers situee dans le repertoire chemin_repertoire et appelle fn() une fois pour chaque entree de l'arborescence. Par defaut, les repertoires sont traites avant les fichiers et sous-repertoires qu'ils contiennent (methode de parcours << preorder >>). Afin d'eviter d'utiliser tous les descripteurs de fichier du processus appelant, nb_descripteurs_fichier_ouverts indique le nombre maximal de repertoires que nftw() peut ouvrir simultanement. Lorsque la profondeur de recherche est superieure a cette valeur, nftw() ralentit car les repertoires doivent etre fermes puis reouverts. nftw() utilise au plus un descripteur de fichier pour chaque niveau dans l'arborescence des fichiers. Pour chaque entree trouvee dans l'arbre, nftw() appelle fn() avec quatre arguments : chemin_fichier, sb, symb_type et tampon_ftw. chemin_fichier est le chemin de l'entree ; il est defini comme un chemin relatif au repertoire de travail actuel du processus appelant au moment de l'appel a nftw() si chemin_repertoire est un chemin relatif, ou comme un chemin absolu si chemin_repertoire est un chemin absolu. sb est un pointeur vers la structure stat renvoyee par un appel a stat(2) pour chemin_fichier. L'argument symb_type passe a fn() est un entier qui peut prendre une des valeurs suivantes : FTW_F chemin_fichier est un fichier ordinaire. FTW_D chemin_fichier est un repertoire. FTW_DNR chemin_fichier est un repertoire qui ne peut etre lu. FTW_DP chemin_fichier est un repertoire et FTW_DEPTH a ete defini dans drapeaux (si FTW_DEPTH n'est pas defini dans drapeaux, alors les repertoires seront toujours visites avec symb_type defini a FTW_D). Tous les fichiers et sous-repertoires dans chemin_fichier ont ete traites. FTW_NS L'appel stat(2) a echoue sur chemin_fichier qui n'est pas un lien symbolique. Cela est probablement du au fait que l'appelant avait les droits de lecture sur le repertoire parent de telle sorte que chemin_fichier etait visible, mais n'avait pas les droits d'execution, et donc le fichier ne pouvait pas etre atteint pour stat(2). Le contenu du tampon pointe par sb est indetermine. FTW_SL chemin_fichier est un lien symbolique et FTW_PHYS a ete defini dans drapeaux. FTW_SLN chemin_fichier est un lien symbolique pointant vers un fichier qui n'existe pas (ce qui ne se produira que si FTW_PHYS n'est pas defini). Dans ce cas, l'argument sb passe a fn() contiendra les informations renvoyees par l'execution de lstat(2) sur le lien symbolique pointant nulle part (voir a ce sujet BOGUES). Le quatrieme argument (tampon_ftw), specifie par nftw() lors de l'appel de fn, est un pointeur vers une structure du type FTW : struct FTW { int base; int level; }; base est le decalage du nom de fichier (c'est-a-dire le composant << basename >>) du chemin donne par chemin_fichier. level est la profondeur de chemin_fichier dans l'arbre des repertoires, relative a la racine de l'arbre (chemin_repertoire qui a une profondeur de 0). Pour arreter le parcours de l'arborescence des fichiers, la fonction fn() renvoie une valeur differente de 0, qui deviendra la valeur de retour de nftw(). Tant que fn() renvoie 0, nftw() continuera jusqu'a la fin du parcours de l'arborescence, et dans ce cas renverra 0, ou jusqu'a ce qu'une erreur se produise (comme un echec de malloc(3)) et dans ce cas renverra -1. Comme nftw() utilise des structures de donnees allouees dynamiquement, la seule maniere propre de sortir d'un parcours d'arborescence consiste a faire que fn() renvoie une valeur differente de 0. Pour permettre a un signal de terminer le parcours sans causer de fuite de memoire, utilisez un gestionnaire qui definit un attribut global verifie par fn(). N'utilisez pas longjmp(3) a moins que le programme ne soit sur le point de se terminer. L'argument drapeaux de nftw() est un OU binaire entre zero ou plusieurs des attributs suivants : FTW_ACTIONRETVAL (depuis la glibc 2.3.3) Si cet attribut, specifique a la glibc, est positionne, alors nftw() gere la valeur de retour de fn() differemment. fn() doit renvoyer l'une des valeurs suivantes : FTW_CONTINUE nftw() doit continuer normalement. FTW_SKIP_SIBLINGS Si fn() renvoie cette valeur, alors les entrees de meme niveau que l'entree courante seront sautees, et la procedure continuera avec le parent. FTW_SKIP_SUBTREE Si fn() est appelee avec une entree qui est un repertoire (symb_type a pour valeur FTW_D), cette valeur de retour empechera le passage des objets de ce repertoire comme arguments a fn() et nftw() continuera avec l'entree suivante de meme niveau du repertoire. FTW_STOP nftw() doit quitter immediatement avec la valeur de retour FTW_STOP. D'autres valeurs de retour pourront etre associees a de nouvelles actions dans le futur ; fn ne devrait renvoyer que les valeurs citees ci-dessus. La macro de test _GNU_SOURCE doit etre definie (avant toute inclusion de fichiers d'en-tete) afin d'obtenir la definition de FTW_ACTIONRETVAL depuis . FTW_CHDIR Si cet attribut est defini, faire un chdir(2) vers chaque repertoire avant de traiter son contenu. Cela est utile si le programme doit executer des actions dans le repertoire ou chemin_fichier reside (preciser ce drapeau n'a aucun effet sur le nom de chemin passe dans l'argument de chemin_fichier de fn). FTW_DEPTH Si cet attribut est defini, faire une recherche << postorder >> ; c'est-a-dire, appeler fn() pour le repertoire lui-meme apres avoir traite son contenu et celui de ses sous-repertoires (par defaut chaque repertoire est traite avant son contenu). FTW_MOUNT Si cet attribut est defini, rester dans le meme systeme de fichiers (c'est-a-dire, ne pas traverser vers d'autres points de montage). FTW_PHYS Si cet attribut est defini, ne pas suivre les liens symboliques (c'est ce que l'on veut). S'il n'est pas defini, les liens symboliques sont suivis, mais aucun fichier n'est traite plus d'une fois. Si FTW_PHYS n'est pas defini, mais si FTW_DEPTH l'est, alors la fonction fn() n'est jamais appelee pour un repertoire qui ferait partie de ses propres descendants. ftw() ftw() est une fonction plus ancienne qui prend en charge un sous-ensemble des fonctionnalites de nftw(). Les differences notables sont les suivantes : - ftw() n'a pas d'argument drapeaux. Elle se comporte comme nftw() lorsque cette derniere est appelee avec l'argument drapeaux defini a zero. - La fonction de rappel fn() est fournie sans le quatrieme argument. - Le jeu de valeurs passees a l'aide de l'argument symb_type a fn() est plus petit : les seules valeurs valables sont FTW_F, FTW_D, FTW_DNR, FTW_NS et (peut-etre) FTW_SL. VALEUR RENVOYEE Ces fonctions renvoient 0 en cas de succes et -1 en cas d'erreur. Si fn() renvoie une valeur differente de 0, alors le parcours de l'arbre se termine et la valeur renvoyee par fn() est renvoyee comme resultat de ftw() ou nftw(). Si nftw() est appelee avec l'attribut FTW_ACTIONRETVAL, alors la seule valeur differente de 0 qui pourra etre utilisee par fn() pour terminer le parcours de l'arbre est FTW_STOP, et cette valeur est renvoyee comme resultat de nftw(). ATTRIBUTS Pour une explication des termes utilises dans cette section, consulter attributes(7). +-----------------------------+--------------------------+-------------+ |Interface | Attribut | Valeur | +-----------------------------+--------------------------+-------------+ |nftw() | Securite des threads | MT-Safe cwd | +-----------------------------+--------------------------+-------------+ |ftw() | Securite des threads | MT-Safe | +-----------------------------+--------------------------+-------------+ VERSIONS Dans certaines implementations (par exemple la glibc), ftw() n'utilise jamais FTW_SL ; sur d'autres systemes, FTW_SL n'apparait que pour les liens symboliques qui ne pointent vers aucun fichier existant ; sur d'autres encore, ftw() utilise FTW_SL pour chaque lien symbolique. Si chemin_fichier est un lien symbolique et si stat(2) echoue, POSIX.1-2008 indique que le resultat est indefini si FTW_NS ou FTW_SL sont definis dans symbole_type. Pour un fonctionnement previsible, employez nftw(). STANDARDS POSIX.1-2008. HISTORIQUE ftw() POSIX.1-2001, SVr4, SVr4, SUSv1. POSIX.1-2008 marque la fonction comme etant obsolete. nftw() glibc 2.1. POSIX.1-2001, SUSv1. FTW_SL POSIX.1-2001, SUSv1. NOTES POSIX.1-2008 indique que les resultats sont imprevisibles si fn ne preserve pas le repertoire de travail actuel. BOGUES Selon POSIX.1-2008, lorsque l'argument symb_type passe a fn() contient FTW_SLN, le tampon pointe par sb doit contenir des informations a propos du lien symbolique pointant nulle part (obtenues en appelant lstat(2) sur le lien), et les premieres versions de la glibc respectaient la specification POSIX sur ce point. Cependant, suite a une regression introduite dans la version 2.4 de la glibc, le contenu du tampon pointe par sb devint indefini lorsque FTW_SLN etait defini dans symb_type (plus precisement, le contenu du tampon restait inchange dans ce cas). Cette regression fut finalement corrigee dans la version 2.30 de la glibc de facon a ce que l'implementation de la glibc suive a nouveau la specification POSIX. EXEMPLES Le programme suivant parcourt l'arbre des repertoires du chemin donne en premier argument de la ligne de commande ou du repertoire courant s'il n'est pas indique. Il affiche diverses informations a propos de chaque fichier. Le second argument de la ligne de commande peut etre utilise pour indiquer les caracteres qui controlent la valeur assignee a l'argument drapeaux lors des appels a nftw(). Source du programme #define _XOPEN_SOURCE 500 #include #include #include #include #include static int display_info(const char *fpath, const struct stat *sb, int tflag, struct FTW *ftwbuf) { printf("%-3s %2d ", (symb_type == FTW_D) ? "d" : (symb_type == FTW_DNR) ? "dnr" : (symb_type == FTW_DP) ? "dp" : (symb_type == FTW_F) ? "f" : (symb_type == FTW_NS) ? "ns" : (symb_type == FTW_SL) ? "sl" : (symb_type == FTW_SLN) ? "sln" : "???", tampon_ftw->level); if (tflag == FTW_NS) printf("-------"); else printf("%7jd", (intmax_t) sb->st_size); printf(" %-40s %d %s\n", chemin_fichier, tampon_ftw->base, chemin_fichier + tampon_ftw->base); return 0; /* Pour dire a nftw() de continuer */ } int main(int argc, char *argv[]) { int flags = 0; if (argc > 2 && strchr(argv[2], 'd') != NULL) flags |= FTW_DEPTH; if (argc > 2 && strchr(argv[2], 'p') != NULL) flags |= FTW_PHYS; if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) == -1) { perror("nftw"); exit(EXIT_FAILURE); } exit(EXIT_SUCCESS); } VOIR AUSSI stat(2), fts(3), readdir(3) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Lucien Gentis Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 ftw(3)