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

NOM

       fts,  fts_open,  fts_read, fts_children, fts_set, fts_close - Parcourir
       une hierarchie de fichiers

SYNOPSIS

       #include <sys/types.h>
       #include <sys/stat.h>
       #include <fts.h>

       FTS *fts_open(char * const *path_argv, int options,
                     int (*compar)(const FTSENT **, const FTSENT **));

       FTSENT *fts_read(FTS *ftsp);

       FTSENT *fts_children(FTS *ftsp, int options);

       int fts_set(FTS *ftsp, FTSENT *f, int options);

       int fts_close(FTS *ftsp);

DESCRIPTION

       Les fonctions de la famille fts servent a traverser des hierarchies  de
       fichiers.  Rapidement,  disons  que  la fonction fts_open() renvoie une
       sorte de descripteur de la hierarchie de  fichiers,  que  l'on  fournit
       ensuite  aux autres fonctions de la famille fts. La fonction fts_read()
       renvoie un pointeur sur une structure decrivant l'un  des  fichiers  de
       l'arborescence.  La fonction fts_children() renvoie un pointeur sur une
       liste chainee  de  structures,  chacune  decrivant  l'un  des  fichiers
       contenu   dans   le  repertoire  de  la  hierarchie.  En  general,  les
       repertoires sont visites a deux reprises,  distinctes.  Un  passage  en
       ordre  << preorder >>  avant  d'avoir parcouru leurs descendants, et un
       passage  en  ordre  << postorder >>  apres  avoir   visite   tous   les
       sous-repertoires.  Les  fichiers ne sont examines qu'une seule fois. Il
       est possible de parcourir la hierarchie << logiquement >> (en  ignorant
       les  liens  symboliques)  ou  << physiquement >> (en visitant les liens
       symboliques). On peut ordonner le parcours de la hierarchie, ignorer ou
       visiter plusieurs fois certaines parties.

       Deux  structures sont definies (avec typedef) dans le fichier d'en-tete
       <fts.h>. La premiere est FTS, une structure representant l'arborescence
       des  fichiers  elle-meme,  et  la  seconde  est  FTSENT,  une structure
       representant un fichier dans la hierarchie. Normalement, une  structure
       FTSENT  est  renvoyee pour chaque fichier rencontre dans la hierarchie.
       Dans cette page de manuel, les  termes  << fichier >>  et  << structure
       FTSENT >>  sont  generalement  interchangeables.  La  structure  FTSENT
       contient au moins les champs suivants, decrits en detail ci-dessous :

           typedef struct _ftsent {
               unsigned short fts_info;     /* drapeau de la structure FTSENT */
               char          *fts_accpath;  /* chemin d'acces */
               char          *fts_path;     /* chemin de la racine */
               short          fts_pathlen;  /* strlen(fts_path) */
               char          *fts_name;     /* non du fichier */
               short          fts_namelen;  /* strlen(fts_name) */
               short          fts_level;    /* profondeur (-1 a N) */
               int            fts_errno;    /* fichier errno */
               long           fts_number;   /* valeur numerique locale */
               void          *fts_pointer;  /* valeur de l'adresse locale */
               struct ftsent *fts_parent;   /* repertoire parent */
               struct ftsent *fts_link;     /* fichier de structure suivant */
               struct ftsent *fts_cycle;    /* cycle structure */
               struct stat   *fts_statp;    /* information sur stat(2) */
           } FTSENT;

       Les membres ont les significations suivantes :

       fts_info    L'un des attributs suivants, decrivant la structure  FTSENT
                   et  le  fichier qu'elle represente. Toutes ces entrees sont
                   terminales (sauf les repertoires FTS_D  ne  presentant  pas
                   d'erreur),  ce  qui  signifie  qu'elle  ne  seront visitees
                   qu'une seule fois, et que leur eventuels  descendants  (cas
                   des repertoires en erreur) ne seront pas visites.

                   FTS_D       Un repertoire visite en phase << preorder >>.

                   FTS_DC      Un  repertoire  introduisant  une  boucle  dans
                               l'arborescence.  Le  champ  fts_cycle   de   la
                               structure FTSENT sera egalement remplis.

                   FTS_DEFAULT Toute  structure FTSENT representant un type de
                               fichier non decrit explicitement par l'une  des
                               autres valeurs de fts_info.

                   FTS_DNR     Un  repertoire  ne  pouvant  etre  lu. Ceci est
                               considere  comme  une  erreur,  et   le   champ
                               fts_errno sera defini avec une valeur decrivant
                               sa cause.

                   FTS_DOT     Un fichier nomme << . >> ou  << .. >>  qui  n'a
                               pas ete indique explicitement comme argument de
                               fts_open() (consultez FTS_SEEDOT).

                   FTS_DP      Un repertoire visite en phase  << postorder >>.
                               Le  contenu  de la structure FTSENT ne sera pas
                               different de ce  qu'il  etait  apres  la  phase
                               << preorder >>.  C'est-a-dire  quand  le  champ
                               fts_info valait FTS_D.

                   FTS_ERR     Il  s'agit  d'un  retour  d'erreur,  le   champ
                               fts_errno  etant  rempli pour indiquer la cause
                               de l'erreur.

                   FTS_F       Un fichier normal.

                   FTS_NS      Un  fichier  pour  lequel  aucune   information
                               provenant   de  stat(2)  n'est  disponible.  Le
                               contenu du champ  fts_statp  est  indefini.  Il
                               s'agit  d'un  cas  d'erreur  dont  la cause est
                               indiquee dans fts_errno.

                   FTS_NSOK    Un  fichier  pour  lequel  aucune   information
                               provenant  de  stat(2)  n'a  ete  demandee.  Le
                               contenu du champ fts_statp est indefini.

                   FTS_SL      Un lien symbolique.

                   FTS_SLNONE  Un lien symbolique pointant dans  le  vide.  Le
                               contenu   du   champ   fts_statp  contient  les
                               caracteristiques du lien lui-meme.

       fts_accpath Un  chemin  permettant  d'acceder  au  fichier  depuis   le
                   repertoire courant.

       fts_path    Le chemin d'acces au fichier a partir du point de depart du
                   parcours. Il contient en prefixe le chemin fourni  lors  de
                   l'invocation de fts_open().

       fts_pathlen La longueur de la chaine pointee par fts_path.

       fts_name    Le nom du fichier.

       fts_namelen La longueur de la chaine pointee par fts_name.

       fts_level   La   profondeur   ou   le   fichier   a   ete  trouve  dans
                   l'arborescence, numerotee de -1 a N.  La  structure  FTSENT
                   representant le parent du point de depart est numerotee -1.
                   La  structure  FTSENT  representant  la  racine  de  depart
                   elle-meme est numerotee 0.

       fts_errno   Dans   une   structure   FTSENT   renvoyee   par  un  appel
                   fts_children()  ou  fts_read(),  dont  le  champ   fts_info
                   contient FTS_DNR, FTS_ERR ou FTS_NS, le champ fts_errno est
                   defini  avec  la  valeur  de  la  variable  externe   errno
                   indiquant  la  cause  de  l'erreur. Dans les autres cas, le
                   contenu du champ fts_errno est indefini.

       fts_number  Ce  champ  est  mis  a  la   disposition   des   programmes
                   applicatifs,  et  n'est  modifie  par aucune fonction de la
                   famille fts. Il est toutefois initialise a zero.

       fts_pointer Ce  champ  est  mis  a  la   disposition   des   programmes
                   applicatifs,  et  n'est  modifie  par aucune fonction de la
                   famille fts. Il est toutefois initialise a NULL.

       fts_parent  Un pointeur sur la structure FTSENT referencant le  fichier
                   dans  la  hierarchie  immediatement au dessus du fichier en
                   cours, c'est-a-dire le repertoire auquel il appartient. Une
                   structure  parente  pour  le  point  d'entree  initial  est
                   egalement  fournie,  mais  seuls  ses  membres   fts_level,
                   fts_number et fts_pointer sont garantis d'etre initialises.

       fts_link    Au  retour de la fonction fts_children(), le champ fts_link
                   pointe sur la structure suivante dans la liste chainee  des
                   membres  du  repertoires,  liste terminee par un NULL. Dans
                   les autres situations, le contenu  du  champ  fts_link  est
                   indetermine.

       fts_cycle   Si  un  repertoire  introduit une boucle dans la hierarchie
                   (consultez FTS_DC),soit a cause d'un  lien  physique  entre
                   deux   repertoires,  soit  a  cause  d'un  lien  symbolique
                   pointant vers un repertoire, le  champ  fts_cycle  pointera
                   vers  la structure FTSENT de la hierarchie qui reference le
                   meme fichier que celui represente par la structure  FTSENT.
                   Sinon, le contenu du champ fts_cycle est indefini.

       fts_statp   Un pointeur vers les informations fournies par stat(2).

       Un  tampon unique est utilise pour tous les chemins d'acces de tous les
       fichiers de la hierarchie. Ainsi, les champs  fts_path  et  fts_accpath
       sont  assures  d'etre  termines  par un caractere nul seulement pour le
       fichier renvoye le plus recemment par  fts_read().  Pour  utiliser  ces
       champs  pour  referencer  un fichier represente par une autre structure
       FTSENT, il faut que le chemin du tampon soit modifie avec l'information
       contenu dans le champ fts_pathlen de cette structure FTSENT. Tout autre
       modification devra etre defaite avant que d'autres appels a  fts_read()
       ne  soient  tentes.  Le  champ  fts_name  est  toujours  termine par un
       caractere nul.

   fts_open()
       La fonction fts_open() recoit un pointeur vers une table de chaines  de
       caracteres representant un ou plusieurs chemins decrivant la hierarchie
       de fichiers a traverser. Cette table doit se terminer par  un  pointeur
       NULL.

       Il   existe  un  certain  nombre  d'options,  dont  au  moins  une  est
       obligatoire (soit FTS_LOGICAL ou soit FTS_PHYSICAL). Les  options  sont
       selectionnees par un ou logique entre les valeurs suivantes :

       FTS_COMFOLLOW
                    Tout  lien  symbolique  specifie  comme racine du parcours
                    sera  immediatement  suivi  (dereference),  que   l'option
                    FTS_LOGICAL soit specifiee ou non.

       FTS_LOGICAL  Cette  option  indique  aux  fonctions fts de renvoyer des
                    structures  FTSENT  concernant  les   cibles   des   liens
                    symboliques  plutot  que  les  liens eux-memes. Avec cette
                    option, les seuls  liens  symboliques  pour  lesquels  une
                    structure  FTSENT  est renvoyee sont ceux pointant dans le
                    vide. Il faut preciser soit FTS_LOGICAL, soit FTS_PHYSICAL
                    a la fonction fts_open().

       FTS_NOCHDIR  Pour   optimiser   les  performances,  les  fonctions  fts
                    changent de repertoire au cours  de  la  traversee  de  la
                    hierarchie  de fichiers. En contrepartie, l'application ne
                    peut pas savoir a l'avance ou elle  se  trouve  durant  la
                    traversee.    L'option    FTS_NOCHDIR    supprime    cette
                    optimisation et les fonctions fts  ne  changeront  pas  de
                    repertoire  de  travail. Remarquez que les applications ne
                    doivent pas modifier elles-meme le repertoire  de  travail
                    et  essayer  d'acceder  aux  fichiers  sans  que  l'option
                    FTS_NOCHDIR ne soit specifiee et que des  chemins  d'acces
                    absolus soient transmis a fts_open().

       FTS_NOSTAT   Par  defaut,  les  structures FTSENT renvoyees contiennent
                    les caracteristiques  (voir  le  champ  statp)  de  chaque
                    fichier visite. Cette option relache cette contrainte pour
                    optimiser les performances, en  autorisant  les  fonctions
                    fts  a  remplir le champ fts_info avec FTS_NSOK et laisser
                    le contenu du membre statp indefini.

       FTS_PHYSICAL Avec  cette  option,  les  routines  fts   renvoient   des
                    structures  FTSENT pour les liens symboliques eux-memes et
                    non pas les fichiers qu'ils pointent. Si cette option  est
                    definie,   des  structures  FTSENT  pour  tous  les  liens
                    symboliques   de   la   hierarchie   sont   renvoyees    a
                    l'application.  Soit FTS_LOGICAL ou soit FTS_PHYSICAL doit
                    etre fourni a la fonction fts_open().

       FTS_SEEDOT   Par  defaut,  a  moins  d'etre  fournis  explicitement  en
                    argument  a  fts_open()  ,tout  fichier  nomme  << . >> ou
                    << .. >> rencontre dans la  hierarchie  est  ignore.  Avec
                    cette  option,  les  routines fts renvoient des structures
                    FTSENT pour ces fichiers.

       FTS_XDEV     Cette option empeche fts de descendre dans les repertoires
                    se  trouvant  sur  un peripherique different de celui dans
                    lequel le parcours a commence.

       L'argument compar() specifie une  fonction  definie  par  l'utilisateur
       pour  ordonner  la  traversee  de la hierarchie. Elle prend en argument
       deux pointeurs sur des pointeurs sur des  structures  FTSENT,  et  doit
       renvoyer  une  valeur negative, nulle, ou positive pour indiquer que le
       fichier  represente  par  le  premier  argument  doit  venir  avant,  a
       n'importe  quel  moment,  ou  apres  le fichier reference par le second
       argument.  Les  champs  fts_accpath,  fts_path   et   fts_pathlen   des
       structures   FTSENT   ne   doivent  jamais  etre  utilises  dans  cette
       comparaison. Si le champ  fts_info  contient  FTS_NS  ou  FTS_NSOK,  le
       membre  fts_statp  ne  doit  pas  etre  utilise non plus. Si l'argument
       compar() est NULL, l'ordre de traversee des repertoires  est  celui  de
       l'argument   path_argv   pour  les  racines,  et  l'ordre  interne  des
       repertoires pour le reste.

   fts_read()
       La fonction fts_read() renvoie un pointeur  sur  une  structure  FTSENT
       decrivant  un  fichier de la hierarchie. Les repertoires lisibles et ne
       causant pas de boucles sont parcourus au moins deux fois, une  fois  en
       phase  << preorder >>,  et  une  en  phase  << postorder >>. Les autres
       fichiers ne sont examines qu'une seule fois. Les liens physiques  entre
       repertoires  qui  ne  causent  pas de boucles, ou les liens symboliques
       vers des liens symboliques peuvent entrainer des fichiers visites  plus
       d'une fois, ou des repertoires plus de deux fois.

       Si  tous  les  membres  de  la  hierarchie ont ete examines, fts_read()
       renvoie NULL et definit la variable externe errno avec  un  0.  Si  une
       erreur  sans rapport avec un fichier particulier se produit, fts_read()
       renvoie NULL et definit errno en consequence. Si une erreur  concernant
       le  fichier  en  cours se produit, un pointeur sur une structure FTSENT
       est renvoye, et errno peut ou non etre defini (consultez fts_info).

       Les structures FTSENT renvoyees par fts_read()  peuvent  etre  ecrasees
       apres  un  appel a fts_close() sur le meme descripteur de hierarchie ou
       apres un appel a fts_read() sur  la  meme  hierarchie,  sauf  si  elles
       representent  un  repertoire,  auquel  cas elles ne seront pas ecrasees
       avant l'appel fts_read() renvoyant la structure FTSENT du repertoire en
       phase << postorder >>.

   fts_children()
       La fonction fts_children() renvoie un pointeur sur une structure FTSENT
       decrivant la premiere entree d'une liste chainee terminee par  un  NULL
       et representant les fichiers se trouvant dans le repertoire indique par
       la derniere structure FTSENT renvoyee par un appel fts_read(). La liste
       est  chainee par le biais du membre fts_link de la structure FTSENT, et
       est  ordonnee  suivant  la   routine   de   comparaison   fournie   par
       l'utilisateur,  si  elle  existe.  Des  appels repetes a fts_children()
       recreeront la liste chainee.

       Un cas particulier se presente si fts_read() n'a pas encore ete appelee
       pour une hierarchie. Alors, fts_children() renverra un pointeur sur les
       fichiers du repertoire logique specifie dans  fts_open(),  c'est-a-dire
       les  arguments  fournis  a fts_open(). Sinon, si la structure FTSENT la
       plus recemment renvoyee par fts_read() n'est pas un  repertoire  visite
       en phase << preorder >>, ou si le repertoire ne contient aucun fichier,
       fts_children() renvoie NULL et met la variable externe errno a zero. Si
       une  erreur se produit, fts_children() renvoie NULL et definit errno en
       consequence.

       Les structures   FTSENT  renvoyees  par  fts_children()   peuvent  etre
       ecrasees apres un appel a fts_children(), fts_close() ou fts_read() sur
       la meme hierarchie de fichiers.

       Option peut contenir l'une des valeurs suivantes :

       FTS_NAMEONLY Seuls les noms des fichiers sont necessaires.  Le  contenu
                    des  membres  des  structures  de  la  liste  chainee  est
                    indefini sauf pour fts_name et fts_namelen.

   fts_set()
       La  fonction  fts_set()  permet  a  l'application  de   parametrer   le
       traitement  a  venir  du  fichier f sur la hierarchie ftsp. La fonction
       fts_set() renvoie 0 si elle reussit, et -1 si une  erreur  se  produit.
       Option doit contenir l'une des valeurs suivantes :

       FTS_AGAIN    Revisiter  a  nouveau  le  fichier. N'importe quel type de
                    fichier peut etre revisite. L'appel suivant de  fts_read()
                    renverra  le  fichier  indique.  Les  membres  fts_stat et
                    fts_info de la structure seront reinitialises a ce moment,
                    mais  aucun  autre champ ne sera modifie. Cette option n'a
                    de  sens  que  pour  le  dernier   fichier   renvoye   par
                    fts_read().  L'utilisation habituelle de cette possibilite
                    concerne les repertoires  en  phase  << postorder >>,  qui
                    sont  alors reexamines (aussi bien en phase << preorder >>
                    que << postorder >>), ainsi que leurs descendants.

       FTS_FOLLOW   Le fichier reference doit etre un lien symbolique.  Si  ce
                    fichier  est  le  dernier  renvoye  par  fts_read(), alors
                    l'appel suivant de fts_read() renverra  le  fichier,  avec
                    les   champs  fts_info  et  fts_statp  reinitialises  pour
                    representer la cible du lien symbolique plutot que le lien
                    lui-meme.  Si  le  fichier  est  le  dernier  renvoye  par
                    fts_children(), alors les membres fts_info et fts_statp de
                    la  structure,  lorsqu'elle  sera renvoyee par fts_read(),
                    representeront la cible du lien symbolique plutot  que  le
                    lien  lui-meme.  Dans  tous  les  cas, si la cible du lien
                    symbolique n'existe pas, les membres de  la  structure  ne
                    seront  pas  modifies,  et  le  champ  fts_info contiendra
                    FTS_SLNONE.

                    Si la cible du lien est un repertoire, il y aura un retour
                    << preorder >>,  suivi d'un retour pour chaque descendant,
                    suivi d'un retour << postorder >>.

       FTS_SKIP     Aucun descendant de ce fichier ne sera visite. Le  fichier
                    doit   etre  le  dernier  renvoye  par  fts_children()  ou
                    fts_read().

   fts_close()
       La fonction fts_close() ferme un  descripteur  ftsp  de  hierarchie  de
       fichier, et restitue le repertoire de travail qui etait en vigueur lors
       de l'appel fts_open() qui  avait  permit  d'ouvrir  ftsp.  La  fonction
       fts_close() renvoie 0 si elle reussit, et -1 en cas d'erreur.

ERREURS

       La  fonction  fts_open()  peut  echouer, et mettre dans errno l'une des
       erreurs indiquees pour les fonctions open(2) et malloc(3).

       La fonction fts_close() peut echouer, et mettre dans  errno  l'une  des
       erreurs indiquees pour les fonctions chdir(2) et close(2).

       Les  fonctions  fts_read() et fts_children() peuvent echouer, et mettre
       dans errno l'une des erreurs indiquees  pour  les  fonctions  chdir(2),
       malloc(3), opendir(3), readdir(3) et stat(2).

       De  plus  fts_children(),  fts_open()  et fts_set() peuvent echouer, et
       mettre dans errno l'une des erreurs suivantes :

       EINVAL Les options ne sont pas valables.

VERSIONS

       Ces fonctions sont disponibles sous Linux depuis la glibc2.

CONFORMIT'E

       4.4BSD.

VOIR AUSSI

       find(1), chdir(2), stat(2), ftw(3), qsort(3)

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

Linux                          28 decembre 2007                         FTS(3)