Loading

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);

       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 maximum 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
       relativement à dirpath. 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 (voyez 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(). Nutilisez 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 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 « post-order » ; c’est-à-dire,
              appeler fn() pour le répertoire lui même aprs 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. Ceci 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().

CONFORMITÉ

       POSIX.1-2001,  SVr4,  SUSv1.  POSIX.1-2008  marque  ftw()  comme  étant
       obsolète.

NOTES

       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), feature_test_macros(7)

COLOPHON

       Cette  page  fait  partie  de  la  publication 3.23 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

       Cette page de manuel a été traduite  et  mise  à  jour  par  Christophe
       Blaess  <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par
       Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et  mise  à
       disposition sur http://manpagesfr.free.fr/.

       Les mises à jour et corrections de la version présente dans Debian sont
       directement gérées par Florentin Duneau <fduneau@gmail.com> et l’équipe
       francophone de traduction de Debian.

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