Provided by:
manpages-fr-dev_3.27fr1.4-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
#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 situee dans le
repertoire dirpath et appelle fn() pour chaque entree de
l'arborescence. Par defaut, les repertoires sont traites avant les
fichiers et sous-repertoires qu'ils contiennent.
Afin d'eviter d'utiliser tous les descripteurs de fichier disponibles
pour le programme, nopenfd specifie le nombre maximal de repertoires
que ftw() peut ouvrir de maniere simultanee. Lorsque la profondeur de
recherche est superieure a cette valeur, ftw() ralentit car les
repertoires doivent etre fermes puis reouverts. ftw() utilise au plus
un descripteur de fichier pour chaque niveau dans l'arborescence des
fichiers.
Pour chaque entree trouvee dans l'arbre, ftw() appelle fn() avec trois
arguments : fpath, sb et typeflag. fpath est le chemin de l'entree , il
est soit defini comme un chemin relatif au repertoire actuel de travail
du processus appelant a l'instant de l'appel a 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 renvoyee par un appel
a stat(2) pour fpath. typeflag est un entier qui a une des valeurs
suivantes :
FTW_F fpath est un fichier regulier.
FTW_D fpath est un repertoire.
FTW_DNR
fpath est un repertoire non lisible.
FTW_NS L'appel stat(2) a echoue sur fpath, qui n'est pas un lien
symbolique.
Si fpath est un lien symbolique et que stat(2) echoue,
POSIX.1-2001 precise que c'est indefini si FTW_NS ou FTW_SL sont
passes a typeflag (consultez ci-dessous).
Pour arreter 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'a la fin du
parcours de l'arborescence, et dans ce cas renverra zero, ou jusqu'a ce
que une erreur se produise (comme pour malloc(3)) et renverra -1.
Comme ftw() utilise des structures de donnees allouees dynamiquement,
la seule maniere propre de sortir d'un parcours d'arborescence est de
renvoyer une valeur non nulle depuis fn(). Pour permettre a un signal
de terminer le parcours sans causer de fuite de memoire, utilisez un
<< handler >> qui definit un drapeau verifie par fn(). N'utilisez pas
longjmp(3) a moins que le programme ne soit pret a se terminer.
nftw()
La fonction nftw() fait exactement la meme chose que ftw(), sauf
qu'elle utilise un argument flags et appelle fn() avec un argument
supplementaire ftwbuf.
L'argument flags est un OU regroupant zero ou certains des drapeaux
suivants :
FTW_ACTIONRETVAL (depuis la glibc 2.3.3)
Si ce drapeau, specifique a la glibc, est positionne, alors
nftw() gere la valeur de retour de fn() differemment. 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 entrees courantes seront passees, et la procedure
continuera avec le parent.
FTW_SKIP_SUBTREE
Si fn() est appelee avec une entree qui est un repertoire
(typeflag vaut FTW_D), cette valeur de retour previent
les objets dans ce repertoire d'etre passes comme
argument a fn(). nftw() continue avec le << sibling >>
suivant du repertoire.
FTW_STOP
nftw() retourne immediatement avec la valeur de retour
FTW_STOP.
Les autres valeurs de retour pourront etre associees avec une
nouvelle action dans le futur ; fn ne devrait retourner 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.h>.
FTW_CHDIR
Si defini, faire un chdir(2) avec chaque repertoire avant de
traiter son contenu. C'est utile si le programme doit executer
des actions dans le repertoire ou fpath reside.
FTW_DEPTH
Si defini, faire une recherche << postorder >> ; c'est-a-dire,
appeler fn() pour le repertoire lui meme apr`es avoir traite son
contenu et celui de ses sous-repertoires (par defaut chaque
repertoire est traite avant son contenu).
FTW_MOUNT
Si defini, rester uniquement dans le meme systeme de fichiers
(p. ex. : ne pas parcourir un point de montage).
FTW_PHYS
Si defini, ne pas suivre les liens symboliques (c'est ce que
l'on veut). Si non 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 que l'on
retrouve dans ses propres descendants.
Pour chaque entree de l'arbre du repertoire, nftw() appelle fn() avec
quatre arguments : fpath et sb sont les memes que pour ftw(). typeflag
peut prendre l'une des valeurs definies par ftw() ou l'une des valeurs
suivantes :
FTW_DP fpath est un repertoire, et FTW_DEPTH a ete defini dans flags.
Tous les fichiers et les sous-repertoires dans fpath ont ete
traites.
FTW_SL fpath est un lien symbolique, et FTW_PHYS a ete defini dans
flags.
FTW_SLN
fpath est un lien symbolique pointant nulle part. Ceci ne se
produit que si FTW_PHYS n'est pas defini.
Le quatrieme argument qu'utilise nftw() lorsqu'elle appelle fn est une
structure du type FTW :
struct FTW {
int base;
int level;
};
base est le decalage du nom de fichier (<< basename >>) du chemin donne
par fpath. level est la profondeur de fpath dans l'arbre des
repertoires, relative a la racine de l'arbre (dirpath qui a une
profondeur nulle).
VALEUR RENVOY'EE
Ces fonctions renvoie 0 en cas de succes et -1 en cas d'erreur.
Si fn() renvoie une valeur non nulle, 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 appele avec le drapeau FTW_ACTIONRETVAL, alors la seule
valeur non nulle qui pourra etre utilisee par fn() pour terminer le
parcours de l'arbre est FTW_STOP, et cette valeur est renvoyee comme le
resultat de nftw().
CONFORMIT'E
POSIX.1-2001, SVr4, SUSv1. POSIX.1-2008 marque ftw() comme etant
obsolete.
NOTES
POSIX.1-2001 indique que les resultats sont imprevisibles si fn ne
preserve pas le repertoire de travail actuel.
La fonction nftw() et l'utilisation de FTW_SL() avec ftw() ont ete
introduites dans SUSv1.
Sur certains systemes, 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 previsible, 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
repertoires, qui peuvent etre utilises par stat.
La fonction nftw() est disponible depuis la glibc 2.1.
FTW_ACTIONRETVAL est specifique a la glibc.
EXEMPLE
Le programme suivant parcours l'arbre des repertoires du chemin donne
en premier argument de la ligne de commande ou du repertoire courant
s'il n'est pas specifie. Il affiche divers informations a propos de
chaque fichier. Le second argument de la ligne de commande peut etre
utilise pour specifier les caracteres assignes a 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.27 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent etre trouvees a l'adresse
<URL:http://www.kernel.org/doc/man-pages/>.
TRADUCTION
Depuis 2010, cette traduction est maintenue a l'aide de l'outil po4a
<URL:http://po4a.alioth.debian.org/> par l'equipe de traduction
francophone au sein du projet perkamon
<URL:http://perkamon.alioth.debian.org/>.
Christophe Blaess <URL:http://www.blaess.fr/christophe/> (1996-2003),
Alain Portal <URL:http://manpagesfr.free.fr/> (2003-2006). Florentin
Duneau et l'equipe francophone de traduction de Debian (2006-2009).
Veuillez signaler toute erreur de traduction en ecrivant a
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir acces a la version anglaise de ce document
en utilisant la commande << man -L C <section> <page_de_man> >>.