Provided by: manpages-fr-dev_3.27fr1.4-1_all bug

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> >>.