| ftw(3) | Library Functions Manual | ftw(3) |
ftw, nftw - Parcourir des arborescences de fichiers
Bibliothèque C standard (libc, -lc)
#include <ftw.h>
int nftw(const char *chemin_répertoire,
int (*fn)(const char *chemin_fichier, const struct stat *sb,
int symbole_type, struct FTW *tampon_ftw),
int nb_descripteurs_fichier_ouverts, int drapeaux);
[[deprecated]]
int ftw(const char *chemin_répertoire,
int (*fn) (const char *chemin_fichier, const struct stat *sb,
int symbole_type),
int nb_descripteurs_fichier_ouverts);
nftw() :
_XOPEN_SOURCE >= 500
La fonction nftw() parcourt l'arborescence de fichiers située dans le répertoire chemin_répertoire et appelle fn() 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 »).
Afin d'éviter d'utiliser tous les descripteurs de fichier du processus appelant, nb_descripteurs_fichier_ouverts indique le nombre maximal de répertoires que nftw() peut ouvrir simultanément. Lorsque la profondeur de recherche est supérieure à cette valeur, nftw() ralentit car les répertoires doivent être fermés puis réouverts. nftw() utilise au plus un descripteur de fichier pour chaque niveau dans l'arborescence des fichiers.
Pour chaque entrée trouvée dans l'arbre, nftw() appelle fn() avec quatre arguments : chemin_fichier, sb, symbole_type et tampon_ftw. chemin_fichier 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 à nftw() si chemin_répertoire est un chemin relatif, ou comme un chemin absolu si chemin_répertoire est un chemin absolu. sb est un pointeur vers la structure stat renvoyée par un appel à stat(2) pour chemin_fichier.
L'argument symbole_type passé à fn() est un entier qui peut prendre une des valeurs suivantes :
Le quatrième argument (tampon_ftw), spécifié 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 décalage du nom de fichier (c’est-à-dire le composant « basename ») du chemin donné par chemin_fichier. level est la profondeur de chemin_fichier dans l'arbre des répertoires, relative à la racine de l'arbre (chemin_répertoire qui a une profondeur de 0).
Pour arrêter le parcours de l'arborescence des fichiers, la fonction fn() renvoie une valeur différente de 0, qui deviendra la valeur de retour de nftw(). Tant que fn() renvoie 0, nftw() continuera jusqu'à la fin du parcours de l'arborescence, et dans ce cas renverra 0, ou jusqu'à ce qu'une erreur se produise (comme un échec de malloc(3)) et dans ce cas renverra -1.
Comme nftw() utilise des structures de données allouées dynamiquement, la seule manière propre de sortir d'un parcours d'arborescence consiste à faire que fn() renvoie une valeur différente de 0. 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 fn(). N'utilisez pas longjmp(3) à moins que le programme ne soit sur le point de se terminer.
L'argument drapeaux de nftw() est un OU binaire entre zéro ou plusieurs des attributs suivants :
D'autres valeurs de retour pourront être associées à de nouvelles actions dans le futur ; fn ne devrait renvoyer que les valeurs citées ci-dessus.
La macro de test _GNU_SOURCE doit être définie (avant toute inclusion de fichiers d'en-tête) afin d'obtenir la définition de FTW_ACTIONRETVAL depuis <ftw.h>.
ftw() est une fonction plus ancienne qui prend en charge un sous-ensemble des fonctionnalités de nftw(). Les différences notables sont les suivantes :
Ces fonctions renvoient 0 en cas de succès et -1 en cas d'erreur.
Si fn() renvoie une valeur différente de 0, alors le parcours de l'arbre se termine et la valeur renvoyée par fn() est renvoyée comme résultat de ftw() ou nftw().
Si nftw() est appelée avec l’attribut FTW_ACTIONRETVAL, alors la seule valeur différente de 0 qui pourra être utilisée par fn() pour terminer le parcours de l'arbre est FTW_STOP, et cette valeur est renvoyée comme résultat de nftw().
La fonction nftw() est disponible depuis la glibc 2.1.
Pour une explication des termes utilisés dans cette section, consulter attributes(7).
| Interface | Attribut | Valeur |
| nftw() | Sécurité des threads | MT-Safe cwd |
| ftw() | Sécurité des threads | MT-Safe |
POSIX.1-2001, POSIX.1-2008, SVr4, SUSv1. POSIX.1-2008 marque ftw() comme étant obsolète.
POSIX.1-2008 indique que les résultats sont imprévisibles si fn ne préserve pas le répertoire de travail actuel.
La fonction nftw() et l'utilisation de FTW_SL avec ftw() ont été introduites dans SUSv1.
Dans certaines implémentations (par exemple la glibc), ftw() n'utilise jamais FTW_SL ; sur d'autres systèmes, FTW_SL n'apparaît 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) échoue, POSIX.1-2008 indique que le résultat est indéfini si FTW_NS ou FTW_SL sont définis dans symbole_type. Pour un fonctionnement prévisible, employez nftw().
Selon POSIX.1-2008, lorsque l'argument symbole_type passé à fn() contient FTW_SLN, le tampon pointé par sb doit contenir des informations à propos du lien symbolique pointant nulle part (obtenues en appelant lstat(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 sb devint indéfini lorsque FTW_SLN était défini dans symbole_type (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.
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 drapeaux lors des appels à nftw().
#define _XOPEN_SOURCE 500 #include <ftw.h> #include <stdint.h> #include <stdio.h> #include <stdlib.h> #include <string.h> 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\n",
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], '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); }
La traduction française de cette page de manuel a été créée par 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> et Lucien Gentis <lucien.gentis@waika9.com>
Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 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.
| 5 février 2023 | Pages du manuel de Linux 6.03 |