NOM
ftw, nftw - Parcourir des arborescences de fichiers
SYNOPSIS
#include <ftw.h>
int ftw(const char *dirpath,
int (*fn) (const char *fpath, const struct stat *sb,
int typeflag),
int nopenfd);
#define _XOPEN_SOURCE 500
#include <ftw.h>
int nftw(const char *dirpath,
int (*fn) (const char *fpath, const struct stat *sb,
int typeflag, struct FTW *ftwbuf),
int nopenfd, int flags);
La fonction ftw() parcourt une arborescence de fichiers située dans le
répertoire dirpath et appelle fn() 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.
Afin d’éviter d’utiliser tous les descripteurs de fichier disponibles
pour le programme, nopenfd spécifie le nombre maximum de répertoires
que ftw() peut ouvrir de manière simultanée. Lorsque la profondeur de
recherche est supérieure à cette valeur, ftw() ralentit car les
répertoires doivent être fermés puis ré-ouverts. ftw() utilise au plus
un descripteur de fichier pour chaque niveau dans l’arborescence des
fichiers.
Pour chaque entrée trouvée dans l’arbre, ftw() appelle fn() avec trois
arguments : fpath, sb et typeflag. fpath est le chemin de l’entrée
relativement à dirpath. sb est un pointeur vers la structure stat
renvoyée par un appel à stat(2) pour fpath. typeflag est un entier qui
a une des valeurs suivantes :
FTW_F fpath est un fichier régulier.
FTW_D fpath est un répertoire.
FTW_DNR
fpath est un répertoire non lisible.
FTW_NS L’appel stat(2) a échoué sur fpath, qui n’est pas un lien
symbolique.
Si fpath est un lien symbolique et que stat(2) échoue,
POSIX.1-2001 précise que c’est indéfini si FTW_NS ou FTW_SL sont
passés à typeflag (voyez ci-dessous).
Pour arrêter le parcours des arborescences de fichiers, la fonction
fn() renvoie une valeur non nulle, qui deviendra la valeur de retour de
ftw(). Tant que fn() renvoie 0, ftw() continuera jusqu’à la fin du
parcours de l’arborescence, et dans ce cas renverra zéro, ou jusqu’à ce
que une erreur se produise (comme pour malloc(3)) et renverra -1.
Comme ftw() utilise des structures de données allouées dynamiquement,
la seule manière propre de sortir d’un parcours d’arborescence est de
renvoyer une valeur non nulle depuis fn(). Pour permettre à un signal
de terminer le parcours sans causer de fuite de mémoire, utilisez un
« handler » qui définit un drapeau vérifié par fn(). Nutilisez pas
longjmp(3) à moins que le programme ne soit prêt à se terminer.
nftw()
La fonction nftw() fait exactement la même chose que ftw(), sauf
qu’elle utilise un argument flags et appelle fn() avec un argument
supplémentaire ftwbuf.
L’argument flags est un OU regroupant zéro ou certains des drapeaux
suivants :
FTW_ACTIONRETVAL (depuis la glibc 2.3.3)
Si ce drapeau, spécifique à la glibc, est positionné, alors
nftw() gère la valeur de retour de fn() différemment. fn()
devrait renvoyer l’une des valeurs suivantes :
FTW_CONTINUE
nftw() va continuer normalement.
FTW_SKIP_SIBLINGS
Si fn() renvoie cette valeur, alors les « siblings » des
entrées courantes seront passées, et la procédure
continuera avec le parent.
FTW_SKIP_SUBTREE
Si fn() est appelée avec une entrée qui est un répertoire
(typeflag vaut FTW_D), cette valeur de retour prévient
les objets dans ce répertoire d’être passés comme
argument à fn(). nftw() continue avec le « sibling »
suivant du répertoire.
FTW_STOP
nftw() retourne immédiatement avec la valeur de retour
FTW_STOP.
Les autres valeurs de retour pourront être associées avec une
nouvelle action dans le futur ; fn ne devrait retourner que les
valeurs citées ci-dessus.
La macro de test _GNU_SOURCE doit être définie afin d’obtenir la
définition de FTW_ACTIONRETVAL depuis <ftw.h>.
FTW_CHDIR
Si défini, faire un chdir(2) avec chaque répertoire avant de
traiter son contenu. C’est utile si le programme doit exécuter
des actions dans le répertoire où fpath réside.
FTW_DEPTH
Si défini, faire une recherche « post-order » ; c’est-à-dire,
appeler fn() pour le répertoire lui même aprs avoir traité son
contenu et celui de ses sous-répertoires (par défaut chaque
répertoire est traité avant son contenu).
FTW_MOUNT
Si défini, rester uniquement dans le même système de fichiers
(p. ex. : ne pas parcourir un point de montage).
FTW_PHYS
Si défini, ne pas suivre les liens symboliques (c’est ce que
l’on veut). Si non défini, les liens symboliques sont suivis,
mais aucun fichier n’est traité plus d’une fois.
Si FTW_PHYS n’est pas défini, mais si FTW_DEPTH l’est, alors la
fonction fn() n’est jamais appelée pour un répertoire que l’on
retrouve dans ses propres descendants.
Pour chaque entrée de l’arbre du répertoire, nftw() appelle fn() avec
quatre arguments : fpath et sb sont les mêmes que pour ftw(). typeflag
peut prendre l’une des valeurs définies par ftw() ou l’une des valeurs
suivantes :
FTW_DP fpath est un répertoire, et FTW_DEPTH a été défini dans flags.
Tous les fichiers et les sous-répertoires dans fpath ont été
traités.
FTW_SL fpath est un lien symbolique, et FTW_PHYS a été défini dans
flags.
FTW_SLN
fpath est un lien symbolique pointant nulle part. Ceci ne se
produit que si FTW_PHYS n’est pas défini.
Le quatrième argument qu’utilise nftw() lorsqu’elle appelle fn est une
structure du type FTW :
struct FTW {
int base;
int level;
};
base est le décalage du nom de fichier (« basename ») du chemin donné
par fpath. level est la profondeur de fpath dans l’arbre des
répertoires, relative à la racine de l’arbre (dirpath qui a une
profondeur nulle).
VALEUR RENVOYÉE
Ces fonctions renvoie 0 en cas de succès et -1 en cas d’erreur.
Si fn() renvoie une valeur non nulle, 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é avec le drapeau FTW_ACTIONRETVAL, alors la seule
valeur non nulle qui pourra être utilisée par fn() pour terminer le
parcours de l’arbre est FTW_STOP, et cette valeur est renvoyée comme le
résultat de nftw().
CONFORMITÉ
POSIX.1-2001, SVr4, SUSv1. POSIX.1-2008 marque ftw() comme étant
obsolète.
NOTES
La fonction nftw() et l’utilisation de FTW_SL() avec ftw() ont été
introduites dans SUSv1.
Sur certains systèmes, ftw() n’utilise jamais FTW_SL, sur d’autres,
FTW_SL ne survient que pour les liens symboliques pointant nulle part,
sur d’autres encore, ftw() utilise FTW_SL pour chaque lien symbolique.
Pour un fonctionnement prévisible, employez nftw().
Sous Linux, les libc4, libc5 et glibc 2.0.6 utilisent FTW_F pour tous
les objets (fichier, lien symbolique, fifo, etc.), sauf pour les
répertoires, qui peuvent être utilisés par stat.
La fonction nftw() est disponible depuis la glibc 2.1.
FTW_ACTIONRETVAL est spécifique à la glibc.
EXEMPLE
Le programme suivant parcours 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 spécifié. Il affiche divers informations à propos de
chaque fichier. Le second argument de la ligne de commande peut être
utilisé pour spécifier les caractères assignés à l’argument flags lors
des appels de nftw().
#define _XOPEN_SOURCE 500
#include <ftw.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stdint.h>
static int
display_info(const char *fpath, const struct stat *sb,
int tflag, struct FTW *ftwbuf)
{
printf("%-3s %2d %7jd %-40s %d %s\n",
(tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" :
(tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" :
(tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" :
(tflag == FTW_SLN) ? "sln" : "???",
ftwbuf->level, (intmax_t) sb->st_size,
fpath, ftwbuf->base, fpath + ftwbuf->base);
return 0; /* To tell nftw() to continue */
}
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), 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 Florentin Duneau <fduneau@gmail.com> 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> ».