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().
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.65 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> ».