Provided by: manpages-fr-dev_3.57d1p1-1_all 
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 /* Consultez feature_test_macros(7) */
#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);
DESCRIPTION
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 indique le nombre maximal 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 , il est soit défini comme un chemin
relatif au répertoire actuel de travail du processus appelant à l'instant de l'appel à
ftw() si dirpath est un chemin relatif, ou soit comme un chemin absolu si dirpath est un
chemin absolu. 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. C’est
probablement dû au fait que l’appelant avait les droits de lecture dans le
répertoire parent, de tel sorte que fpath était visible, mais pas les droits
d’exécution, donc le fichier ne pouvait pas être atteint pour stat(2).
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 (consultez 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 attribut vérifié par fn(). N'utilisez 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 attributs suivants :
FTW_ACTIONRETVAL (depuis la glibc 2.3.3)
Si cet attribut, 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() quitte 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 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_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 « postorder » ; c'est-à-dire, appeler fn() pour le
répertoire lui-même après 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. (Si FTW_DEPTH
n’était pas défini dans flags, alors les répertoires seront toujours visités avec
typeflag défini à FTW_D.) 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. Cela 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 l’attribut 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
POSIX.1-2001 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.
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 indiqué. Il affiche divers
informations à propos de chaque fichier. Le second argument de la ligne de commande peut
être utilisé pour indiquer les caractères assignés à l'argument flags lors des appels de
nftw().
Source du programme
#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)
COLOPHON
Cette page fait partie de la publication 3.57 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
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a
<http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet
perkamon <http://perkamon.alioth.debian.org/>.
Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain Portal
<http://manpagesfr.free.fr/> (2003-2006). Florentin Duneau et l'équipe francophone de
traduction de Debian (2006-2009).
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> ».