Provided by: manpages-fr-dev_3.57d1p1-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   /* 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().

CONFORMITÉ

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