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 spécifie 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.
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
drapeau 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 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 (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. 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 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().
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 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)
COLOPHON¶
Cette page fait partie de la publication 3.44 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> ».