.\" Copyright (c) 1993 Michael Haardt (u31b3hs@pool.informatik.rwth-aachen.de), Sun Jul 18 17:47:18 MET DST 1993
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
.\"
.\" Traduction 26/10/1996 par Christophe Blaess (ccb@club-internet.fr)
.\" mj 11/12/1997 (LDP man-pages 1.18)
.\"
.\" Mise  jour 06/06/2001 - LDP-man-pages-1.36
.TH FTW 3 "6 juin 2001" Linux "Manuel du programmeur Linux" 
.SH NOM
ftw, nftw \- Parcours d'arborescence de fichiers.
.SH SYNOPSIS
.B #include <ftw.h>
.sp
.BI "int ftw (const char *" directory ", int (*" funcptr ")"
.BI "(const char *" file ", const struct stat *" sb ", int " flag "), int " depth );
.sp
.BI "int nftw (const char *" directory ", int (*" funcptr ")"
.BI "(const char *" file ", const struct stat *" sb ", int " flag ,
.BI "struct FTW *" s ),
.BI "int " depth ", int " flags );
.SH DESCRIPTION
La fonction \fBftw\fP() parcourt la hirarchie de fichiers commenant au
rpertoire \fIdirectory\fP.
Pour chaque fichier rencontr, elle appelle \fIfuncptr\fP avec le chemin
d'accs du fichier relativement  \fIdirectory\fP, un pointeur sur une
structure
.BR stat (2),
et un entier \fIflag\fP, dont la valeur signifie :
.TP
.B FTW_F
Fichier normal
.TP
.B FTW_D
Rpertoire
.TP
.B FTW_DNR
Rpertoire non lisible
.TP
.B FTW_SL
Lien symbolique
.TP
.B FTW_NS
Echec de stat sur cet lment
.LP
S'il s'agit d'un lien symbolique et que stat choue, XPG4v2 prcise que
FTW_NS ou FTW_SL peuvent tre utiliss.
.PP
\fBftw\fP() s'appelle lui-mme recursivement pour parcourir tous les
rpertoires trouvs. Afin d'viter d'utiliser tous les descripteurs de
fichiers disponibles pour le programme, la profondeur \fIdepth\fP
limite le nombre de rpertoires ouverts simultanment. Quand cette 
profondeur est atteinte, \fBftw\fP() va ralentir, car des rpertoires
devront tre ferms puis rouverts.
.PP
Pour arrter le parcours des fichiers, la fonction \fIfuncptr\fP peut
renvoyer une valeur non-nulle, qui deviendra la valeur de retour de \fBftw\fP().
Sinon, \fBftw\fP() continuera jusqu' atteindre la fin du parcours de
l'arbre, et renverra zro, ou jusqu' ce que se produise une erreur comme
celles de 
.BR malloc (3)
et renverra \-1.
.PP
Comme \fBftw()\fP utilise des structures de donnes alloues dynamiquement,
la seule manire propre de sortir d'un parcours est de renvoyer une valeur
non nulle.
Pour traiter les interruptions, par exemple, notez le numro d'interruption
survenue et renvoyez une valeur non nulle. N'utilisez jamais
.BR longjmp (3)
 moins que le programme ne soit prt  se terminer.

La fonction \fBnftw\fP() fait exactement la mme chose que \fBftw\fP(),
sauf qu'elle utilise un argument \fIflags\fP supplmentaire (et invoque
la fonction transmise avec un argument de plus).
L'argument \fIflags\fP est un OU regroupant zro ou certaines des constantes :
.TP
.B FTW_CHDIR
Faire un
.IR chdir ()
dans chaque rpertoire avant d'en traiter le contenu.
.TP
.B FTW_DEPTH
Faire une recherche en profondeur d'abord, c'est--dire n'appeler la fonction
pour le rpertoire lui-mme qu'aprs en avoir trait tout le contenu, y
compris les sous-rpertoires.
.TP
.B FTW_MOUNT
Rester uniquement dans le mme systme de fichiers.
.TP
.B FTW_PHYS
Ne pas suivre les liens symboliques (C'est classiquement ce que l'on veut).
Sinon, les liens symboliques sont suivis, mais aucun fichier n'est trait
plus d'une fois.
.LP
Si FTW_PHYS n'est pas demand, mais si FTW_DEPTH l'est, la fonction
. IR funcptr ()
n'est jamais appele sur un rpertoire que l'on retrouve dans ses descendants.
.LP
La fonction
.IR funcptr ()
est appele avec quatre arguments : le chemin de l'entre traite, un pointeur
sur une structure stat la concernant, un entier dcrivant son type, et un
pointeur sur une structure FTW. Le type sera FTW_F, FTW_D, FTW_DNR, FTW_SL,
ou FTW_NS (significations ci-dessus, FTW_SL uniquement si FTW_PHYS est
demand) ou
.TP
.B FTW_DP
Rpertoire dont tous les descendants on t dj traits.
Ceci ne se produit qu'avec FTW_DEPTH.
.TP
.B FTW_SLN
Lien symbolique pointant nulle part.
Ceci ne se produit qu'avec FTW_PHYS absent.
.LP
La structure FTW pointe par le quatrime argument de
.IR funcptr ()
contient au moins les champs
.IR base ,
la position du nom de fichier dans le chemin fourni par le premier
argument de
.IR funcptr (),
et
.IR level ,
la profondeur de l'objet par rapport au point de dpart
(de profondeur 0).
.SH NOTES
La fonction
.IR nftw ()
et l'usage de FTW_SL dans
.IR ftw ()
ont t introduits dans XPG4v2.
Sous Linux, les LibC 4, LibC 5, et GlibC 2.0.6 utilisent FTW_F pour tous
les objets (fichiers, liens symboliques, fifos, etc.) ne permettant pas un
stat, mais autres que les rpertoires.
La GlibC 2.1 supporte FTW_SL et
.IR nftw ().
.SH CONFORMIT
AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.
.SH "VOIR AUSSI"
.BR stat (2)
.SH TRADUCTION
Christophe Blaess, 1997.