.\" -*- coding: UTF-8 -*- .\" Copyright (c) 1993 Michael Haardt (michael@moria.de) .\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) .\" and copyright (c) 2006 Justin Pryzby .\" and copyright (c) 2006 Michael Kerrisk .\" .\" %%%LICENSE_START(GPLv2+_DOC_FULL) .\" This is free documentation; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License as .\" published by the Free Software Foundation; either version 2 of .\" the License, or (at your option) any later version. .\" .\" The GNU General Public License's references to "object code" .\" and "executables" are to be interpreted as the output of any .\" document formatting or typesetting system, including .\" intermediate and printed output. .\" .\" This manual is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public .\" License along with this manual; if not, see .\" . .\" %%%LICENSE_END .\" .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) .\" 2006-05-24, Justin Pryzby .\" document FTW_ACTIONRETVAL; include .SH RETURN VALUE; .\" 2006-05-24, Justin Pryzby and .\" Michael Kerrisk .\" reorganized and rewrote much of the page .\" 2006-05-24, Michael Kerrisk .\" Added an example program. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH FTW 3 "9 juin 2020" Linux "Manuel du programmeur Linux" .SH NOM ftw, nftw \- Parcourir des arborescences de fichiers .SH SYNOPSIS .nf \fB#include \fP .PP \fBint nftw(const char *\fP\fIchemin_répertoire\fP\fB,\fP \fB int (*\fP\fIfn\fP\fB) (const char *\fP\fIchemin_fichier\fP\fB, const struct stat *\fP\fIsb\fP\fB,\fP \fB int \fP\fIsymbole_type\fP\fB, struct FTW *\fP\fItampon_ftw\fP\fB),\fP \fB int \fP\fInb_descripteurs_fichier_ouverts\fP\fB, int \fP\fIdrapeaux\fP\fB);\fP .PP \fB#include \fP .PP \fBint ftw(const char *\fP\fIchemin_répertoire\fP\fB,\fP \fB int (*\fP\fIfn\fP\fB) (const char *\fP\fIchemin_fichier\fP\fB, const struct stat *\fP\fIsb\fP\fB,\fP \fB int \fP\fIsymbole_type\fP\fB),\fP \fB int \fP\fInb_descripteurs_fichier_ouverts\fP\fB);\fP .fi .PP .RS -4 Exigences de macros de test de fonctionnalités pour la glibc (consulter \fBfeature_test_macros\fP(7))\ : .RE .PP \fBnftw\fP(): _XOPEN_SOURCE >= 500 .SH DESCRIPTION La fonction \fBnftw\fP() parcourt l'arborescence de fichiers située dans le répertoire \fIchemin_répertoire\fP et appelle \fIfn\fP() une fois pour chaque entrée de l'arborescence. Par défaut, les répertoires sont traités avant les fichiers et sous\-répertoires qu'ils contiennent (méthode de parcours «\ preorder\ »). .PP Afin d'éviter d'utiliser tous les descripteurs de fichier du processus appelant, \fInb_descripteurs_fichier_ouverts\fP indique le nombre maximal de répertoires que \fBnftw\fP() peut ouvrir simultanément. Lorsque la profondeur de recherche est supérieure à cette valeur, \fBnftw\fP() ralentit car les répertoires doivent être fermés puis réouverts. \fBnftw\fP() utilise au plus un descripteur de fichier pour chaque niveau dans l'arborescence des fichiers. .PP Pour chaque entrée trouvée dans l'arbre, \fBnftw\fP() appelle \fIfn\fP() avec quatre arguments\ : \fIchemin_fichier\fP, \fIsb\fP, \fIsymbole_type\fP et \fItampon_ftw\fP. \fIchemin_fichier\fP est le chemin de l'entrée\ ; il est défini comme un chemin relatif au répertoire de travail actuel du processus appelant au moment de l'appel à \fBnftw\fP() si \fIchemin_répertoire\fP est un chemin relatif, ou comme un chemin absolu si \fIchemin_répertoire\fP est un chemin absolu. \fIsb\fP est un pointeur vers la structure \fIstat\fP renvoyée par un appel à \fBstat\fP(2) pour \fIchemin_fichier\fP. .PP L'argument \fIsymbole_type\fP passé à \fIfn\fP() est un entier qui peut prendre une des valeurs suivantes\ : .TP \fBFTW_F\fP \fIchemin_fichier\fP est un fichier ordinaire. .TP \fBFTW_D\fP \fIchemin_fichier\fP est un répertoire. .TP \fBFTW_DNR\fP \fIchemin_fichier\fP est un répertoire qui ne peut être lu. .TP \fBFTW_DP\fP \fIchemin_fichier\fP est un répertoire et \fBFTW_DEPTH\fP a été défini dans \fIdrapeaux\fP (si \fBFTW_DEPTH\fP n’est pas défini dans \fIdrapeaux\fP, alors les répertoires seront toujours visités avec \fIsymbole_type\fP défini à \fBFTW_D\fP). Tous les fichiers et sous\-répertoires dans \fIchemin_fichier\fP ont été traités. .TP \fBFTW_NS\fP L'appel \fBstat\fP(2) a échoué sur \fIchemin_fichier\fP qui n'est pas un lien symbolique. Cela est probablement dû au fait que l’appelant avait les droits de lecture sur le répertoire parent de telle sorte que \fIchemin_fichier\fP était visible, mais n’avait pas les droits d’exécution, et donc le fichier ne pouvait pas être atteint pour \fBstat\fP(2). Le contenu du tampon pointé par \fIsb\fP est indéterminé. .TP \fBFTW_SL\fP .\" To obtain the definition of this constant from .\" .IR , .\" either .\" .B _BSD_SOURCE .\" must be defined, or .\" .BR _XOPEN_SOURCE .\" must be defined with a value of 500 or more. \fIchemin_fichier\fP est un lien symbolique et \fBFTW_PHYS\fP a été défini dans \fIdrapeaux\fP. .TP \fBFTW_SLN\fP \fIchemin_fichier\fP est un lien symbolique pointant vers un fichier qui n'existe pas (ce qui ne se produira que si \fBFTW_PHYS\fP n'est pas défini). Dans ce cas, l'argument \fIsb\fP passé à \fIfn\fP() contiendra les informations renvoyées par l'exécution de \fBlstat\fP(2) sur le lien symbolique pointant nulle part (voir à ce sujet BOGUES). .PP Le quatrième argument (\fItampon_ftw\fP), spécifié par \fBnftw\fP() lors de l'appel de \fIfn\fP, est un pointeur vers une structure du type \fIFTW\fP\ : .PP .in +4n .EX struct FTW { int base; int level; }; .EE .in .PP \fIbase\fP est le décalage du nom de fichier (c’est\-à\-dire le composant «\ basename\ ») du chemin donné par \fIchemin_fichier\fP. \fIlevel\fP est la profondeur de \fIchemin_fichier\fP dans l'arbre des répertoires, relative à la racine de l'arbre (\fIchemin_répertoire\fP qui a une profondeur de\ \fB0\fP). .PP Pour arrêter le parcours de l'arborescence des fichiers, la fonction \fIfn\fP() renvoie une valeur différente de\ \fB0\fP, qui deviendra la valeur de retour de \fBnftw\fP(). Tant que \fIfn\fP() renvoie\ \fB0\fP, \fBnftw\fP() continuera jusqu'à la fin du parcours de l'arborescence, et dans ce cas renverra\ \fB0\fP, ou jusqu'à ce qu'une erreur se produise (comme un échec de \fBmalloc\fP(3)) et dans ce cas renverra\ \fB\-1\fP. .PP Comme \fBnftw\fP() utilise des structures de données allouées dynamiquement, la seule manière propre de sortir d'un parcours d'arborescence consiste à faire que \fIfn\fP() renvoie une valeur différente de\ \fB0\fP. Pour permettre à un signal de terminer le parcours sans causer de fuite de mémoire, utilisez un gestionnaire qui définit un attribut global vérifié par \fIfn\fP(). \fIN'utilisez pas\fP \fBlongjmp\fP(3) à moins que le programme ne soit sur le point de se terminer. .PP L'argument \fIdrapeaux\fP de \fBnftw\fP() est un OU binaire entre zéro ou plusieurs des attributs suivants\ : .TP \fBFTW_ACTIONRETVAL\fP (depuis la glibc\ 2.3.3) Si cet attribut, spécifique à la glibc, est positionné, alors \fBnftw\fP() gère la valeur de retour de \fIfn\fP() différemment. \fIfn\fP() doit renvoyer l'une des valeurs suivantes\ : .RS .TP \fBFTW_CONTINUE\fP \fBnftw\fP() doit continuer normalement. .TP \fBFTW_SKIP_SIBLINGS\fP .\" If \fBFTW_DEPTH\fP .\" is set, the entry's parent directory is processed next (with .\" \fIflag\fP set to \fBFTW_DP\fP). Si \fIfn\fP() renvoie cette valeur, alors les entrées de même niveau que l'entrée courante seront sautées, et la procédure continuera avec le parent. .TP \fBFTW_SKIP_SUBTREE\fP Si \fIfn\fP() est appelée avec une entrée qui est un répertoire (\fIsymbole_type\fP a pour valeur \fBFTW_D\fP), cette valeur de retour empêchera le passage des objets de ce répertoire comme arguments à \fIfn\fP() et \fBnftw\fP() continuera avec l'entrée suivante de même niveau du répertoire. .TP \fBFTW_STOP\fP \fBnftw\fP() doit quitter immédiatement avec la valeur de retour \fBFTW_STOP\fP. .PP D'autres valeurs de retour pourront être associées à de nouvelles actions dans le futur\ ; \fIfn\fP ne devrait renvoyer que les valeurs citées ci\-dessus. .PP La macro de test \fB_GNU_SOURCE\fP doit être définie (avant \fItoute\fP inclusion de fichiers d'en\-tête) afin d'obtenir la définition de \fBFTW_ACTIONRETVAL\fP depuis \fI\fP. .RE .TP \fBFTW_CHDIR\fP Si cet attribut est défini, faire un \fBchdir\fP(2) vers chaque répertoire avant de traiter son contenu. Cela est utile si le programme doit exécuter des actions dans le répertoire où \fIchemin_fichier\fP réside (préciser ce drapeau n’a aucun effet sur le nom de chemin passé dans l’argument de \fIchemin_fichier\fP de \fIfn\fP). .TP \fBFTW_DEPTH\fP Si cet attribut est défini, faire une recherche «\ postorder\ »\ ; c'est\-à\-dire, appeler \fIfn\fP() pour le répertoire lui\-même \fIaprès\fP avoir traité son contenu et celui de ses sous\-répertoires (par défaut chaque répertoire est traité \fIavant\fP son contenu). .TP \fBFTW_MOUNT\fP Si cet attribut est défini, rester dans le même système de fichiers (c’est\-à\-dire, ne pas traverser vers d'autres points de montage). .TP \fBFTW_PHYS\fP Si cet attribut est défini, ne pas suivre les liens symboliques (c'est ce que l'on veut). S'il n'est pas défini, les liens symboliques sont suivis, mais aucun fichier n'est traité plus d'une fois. .IP Si \fBFTW_PHYS\fP n'est pas défini, mais si \fBFTW_DEPTH\fP l'est, alors la fonction \fIfn\fP() n'est jamais appelée pour un répertoire qui ferait partie de ses propres descendants. .SS \fBftw()\fP \fBftw\fP() est une fonction plus ancienne qui prend en charge un sous\-ensemble des fonctionnalités de \fBnftw\fP(). Les différences notables sont les suivantes\ : .IP * 3 \fBftw\fP() n'a pas d'argument \fIdrapeaux\fP. Elle se comporte comme \fBnftw\fP() lorsque cette dernière est appelée avec l'argument \fIdrapeaux\fP défini à zéro. .IP * La fonction de rappel \fIfn\fP() est fournie sans le quatrième argument. .IP * Le jeu de valeurs passées à l'aide de l'argument \fIsymbole_type\fP à \fIfn\fP() est plus petit\ : les seules valeurs valables sont \fBFTW_F\fP, \fBFTW_D\fP, \fBFTW_DNR\fP, \fBFTW_NS\fP et (peut\-être) \fBFTW_SL\fP. .SH "VALEUR RENVOYÉE" Ces fonctions renvoient \fB0\fP en cas de succès et \fB\-1\fP en cas d'erreur. .PP Si \fIfn\fP() renvoie une valeur différente de \fB0\fP, alors le parcours de l'arbre se termine et la valeur renvoyée par \fIfn\fP() est renvoyée comme résultat de \fBftw\fP() ou \fBnftw\fP(). .PP Si \fBnftw\fP() est appelée avec l’attribut \fBFTW_ACTIONRETVAL\fP, alors la seule valeur différente de \fB0\fP qui pourra être utilisée par \fIfn\fP() pour terminer le parcours de l'arbre est \fBFTW_STOP\fP, et cette valeur est renvoyée comme résultat de \fBnftw\fP(). .SH VERSIONS La fonction \fBnftw\fP() est disponible depuis la version\ 2.1 de la glibc. .SH ATTRIBUTS Pour une explication des termes utilisés dans cette section, consulter \fBattributes\fP(7). .TS allbox; lb lb lb l l l. Interface Attribut Valeur T{ \fBnftw\fP() T} Sécurité des threads MT\-Safe cwd T{ \fBftw\fP() T} Sécurité des threads MT\-Safe .TE .sp 1 .SH CONFORMITÉ POSIX.1\-2001, POSIX.1\-2008, SVr4, SUSv1. POSIX.1\-2008 marque \fBftw\fP() comme étant obsolète. .SH NOTES POSIX.1\-2008 indique que les résultats sont imprévisibles si \fIfn\fP ne préserve pas le répertoire de travail actuel. .PP La fonction \fBnftw\fP() et l'utilisation de \fBFTW_SL\fP avec \fBftw\fP() ont été introduites dans SUSv1. .PP Dans certaines implémentations (par exemple la glibc), \fBftw\fP() n'utilise jamais \fBFTW_SL\fP\ ; sur d'autres systèmes, \fBFTW_SL\fP n'apparaît que pour les liens symboliques qui ne pointent vers aucun fichier existant\ ; sur d'autres encore, \fBftw\fP() utilise \fBFTW_SL\fP pour chaque lien symbolique. Si \fIchemin_fichier\fP est un lien symbolique et si \fBstat\fP(2) échoue, POSIX.1\-2008 indique que le résultat est indéfini si \fBFTW_NS\fP ou \fBFTW_SL\fP sont définis dans \fIsymbole_type\fP. Pour un fonctionnement prévisible, employez \fBnftw\fP(). .SH BOGUES .\" https://bugzilla.redhat.com/show_bug.cgi?id=1422736 .\" http://austingroupbugs.net/view.php?id=1121 .\" glibc commit 6ba205b2c35e3e024c8c12d2ee1b73363e84da87 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=23501 Selon POSIX.1\-2008, lorsque l'argument \fIsymbole_type\fP passé à \fIfn\fP() contient \fBFTW_SLN\fP, le tampon pointé par \fIsb\fP doit contenir des informations à propos du lien symbolique pointant nulle part (obtenues en appelant \fBlstat\fP(2) sur le lien), et les premières versions de la glibc respectaient la spécification POSIX sur ce point. Cependant, suite à une régression introduite dans la version\ 2.4 de la glibc, le contenu du tampon pointé par \fIsb\fP devint indéfini lorsque \fBFTW_SLN\fP était défini dans \fIsymbole_type\fP (plus précisément, le contenu du tampon restait inchangé dans ce cas). Cette régression fut finalement corrigée dans la version\ 2.30 de la glibc de façon à ce que l'implémentation de la glibc suive à nouveau la spécification POSIX. .SH EXEMPLES Le programme suivant parcourt l'arbre des répertoires du chemin donné en premier argument de la ligne de commande ou du répertoire courant s'il n'est pas indiqué. Il affiche diverses informations à propos de chaque fichier. Le second argument de la ligne de commande peut être utilisé pour indiquer les caractères qui contrôlent la valeur assignée à l'argument \fIdrapeaux\fP lors des appels à \fBnftw\fP(). .SS "Source du programme" \& .EX #define _XOPEN_SOURCE 500 #include #include #include #include #include static int display_info(const char *chemin_fichier, const struct stat *sb, int symbole_type, struct FTW *tampon_ftw) { printf("%\-3s %2d ", (symbole_type == FTW_D) ? "d" : (symbole_type == FTW_DNR) ? "dnr" : (symbole_type == FTW_DP) ? "dp" : (symbole_type == FTW_F) ? "f" : (symbole_type == FTW_NS) ? "ns" : (symbole_type == FTW_SL) ? "sl" : (symbole_type == FTW_SLN) ? "sln" : "???", tampon_ftw\->level); if (symbole_type == FTW_NS) printf("\-\-\-\-\-\-\-"); else printf("%7jd", (intmax_t) sb\->st_size); printf(" %\-40s %d %s\en", chemin_fichier, tampon_ftw\->base, chemin_fichier + tampon_ftw\->base); return 0; /* Pour dire à nftw() de continuer */ } int main(int argc, char *argv[]) { int flags = 0; if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL) flags |= FTW_DEPTH; if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL) flags |= FTW_PHYS; if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) == \-1) { perror("nftw"); exit(EXIT_FAILURE); } exit(EXIT_SUCCESS); } .EE .SH "VOIR AUSSI" \fBstat\fP(2), \fBfts\fP(3), \fBreaddir\fP(3) .SH COLOPHON Cette page fait partie de la publication\ 5.10 du projet \fIman\-pages\fP Linux. Une description du projet et des instructions pour signaler des anomalies et la dernière version de cette page peuvent être trouvées à l'adresse \%https://www.kernel.org/doc/man\-pages/. .PP .SH TRADUCTION La traduction française de cette page de manuel a été créée par Christophe Blaess , Stéphan Rafin , Thierry Vignaud , François Micaux, Alain Portal , Jean-Philippe Guérard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas François , Florentin Duneau , Simon Paillard , Denis Barbier , David Prévot et Lucien Gentis . .PP Cette traduction est une documentation libre ; veuillez vous reporter à la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3 .UE concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE. .PP Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à .MT debian-l10n-french@lists.debian.org .ME .