Provided by: manpages-fr-dev_2.80.1-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 à traverser des hiérarchies  de
       fichiers.  Rapidement,  disons  que  la fonction fts_open() renvoie une
       sorte de descripteur de la hiérarchie de  fichiers,  que  l’on  fournit
       ensuite  aux autres fonctions de la famille fts. La fonction fts_read()
       renvoie un pointeur sur une structure décrivant l’un  des  fichiers  de
       l’arborescence.  La fonction fts_children() renvoie un pointeur sur une
       liste chaînée  de  structures,  chacune  décrivant  l’un  des  fichiers
       contenu   dans   le  répertoire  de  la  hiérarchie.  En  général,  les
       répertoires sont visités à deux reprises,  distinctes.  Un  passage  en
       ordre  « pre-order »  avant  d’avoir  parcouru leurs descendants, et un
       passage  en  ordre  « post-order »  après   avoir   visité   tous   les
       sous-répertoires.  Les  fichiers ne sont examinés qu’une seule fois. Il
       est possible de parcourir la hiérarchie  « logiquement »  (en  ignorant
       les  liens  symboliques)  ou  « physiquement »  (en  visitant les liens
       symboliques). On peut ordonner le parcours de la hiérarchie, ignorer ou
       visiter plusieurs fois certaines parties.

       Deux  structures sont définies (avec typedef) dans le fichier d’en-tête
       <fts.h>. La première est FTS, une structure représentant l’arborescence
       des  fichiers  elle-même,  et  la  seconde  est  FTSENT,  une structure
       représentant un fichier dans la hiérarchie. Normalement, une  structure
       FTSENT  est  renvoyée pour chaque fichier rencontré dans la hiérarchie.
       Dans cette page  de  manuel,  les  termes  « fichier »  et  « structure
       FTSENT »   sont  généralement  interchangeables.  La  structure  FTSENT
       contient au moins les champs suivants, décrits en détail ci-dessous :

           typedef struct _ftsent {
               unsigned short fts_info;     /* drapeau de la structure FTSENT */
               char          *fts_accpath;  /* chemin d’accès */
               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 à N) */
               int            fts_errno;    /* fichier errno */
               long           fts_number;   /* valeur numérique locale */
               void          *fts_pointer;  /* valeur de l’adresse locale */
               struct ftsent *fts_parent;   /* répertoire 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 attribut suivants, décrivant la  structure  FTSENT
                   et  le  fichier qu’elle représente. Toutes ces entrées sont
                   terminales (sauf les répertoires FTS_D  ne  présentant  pas
                   d’erreur),  ce  qui  signifie  qu’elle  ne  seront visitées
                   qu’une seule fois, et que leur éventuels  descendants  (cas
                   des répertoires en erreur) ne seront pas visités.

                   FTS_D       Un répertoire visité en phase « pre-order ».

                   FTS_DC      Un  répertoire  introduisant  une  boucle  dans
                               l’arborescence.  Le  champ  fts_cycle   de   la
                               structure FTSENT sera également remplis.

                   FTS_DEFAULT Toute  structure FTSENT représentant un type de
                               fichier non décrit explicitement par l’une  des
                               autres valeurs de fts_info.

                   FTS_DNR     Un  répertoire  ne  pouvant  être  lu. Ceci est
                               considéré  comme  une  erreur,  et   le   champ
                               fts_errno sera défini avec une valeur décrivant
                               sa cause.

                   FTS_DOT     Un fichier nommé « . » ou « .. »  qui  n’a  pas
                               été  indiqué  explicitement  comme  argument de
                               fts_open() (consultez FTS_SEEDOT).

                   FTS_DP      Un répertoire visité en  phase  « post-order ».
                               Le  contenu  de la structure FTSENT ne sera pas
                               différent de ce  qu’il  était  après  la  phase
                               « pre-order ».   C’est-à-dire  quand  le  champ
                               fts_info valait FTS_D.

                   FTS_ERR     Il  s’agit  d’un  retour  d’erreur,  le   champ
                               fts_errno  étant  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  indéfini.  Il
                               s’agit  d’un  cas  d’erreur  dont  la cause est
                               indiquée dans fts_errno.

                   FTS_NSOK    Un  fichier  pour  lequel  aucune   information
                               provenant  de  stat(2)  n’a  été  demandée.  Le
                               contenu du champ fts_statp est indéfini.

                   FTS_SL      Un lien symbolique.

                   FTS_SLNONE  Un lien symbolique pointant dans  le  vide.  Le
                               contenu   du   champ   fts_statp  contient  les
                               caractéristiques du lien lui-même.

       fts_accpath Un  chemin  permettant  d’accéder  au  fichier  depuis   le
                   répertoire courant.

       fts_path    Le chemin d’accès au fichier à partir du point de départ du
                   parcours. Il contient en préfixe le chemin fourni  lors  de
                   l’invocation de fts_open().

       fts_pathlen La longueur de la chaîne pointée par fts_path.

       fts_name    Le nom du fichier.

       fts_namelen La longueur de la chaîne pointée par fts_name.

       fts_level   La   profondeur   où   le   fichier   a   été  trouvé  dans
                   l’arborescence, numérotée de -1 à N.  La  structure  FTSENT
                   représentant le parent du point de départ est numérotée -1.
                   La  structure  FTSENT  représentant  la  racine  de  départ
                   elle-même est numérotée 0.

       fts_errno   Dans   une   structure   FTSENT   renvoyée   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
                   défini  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 indéfini.

       fts_number  Ce  champ  est  mis  à  la   disposition   des   programmes
                   applicatifs,  et  n’est  modifié  par aucune fonction de la
                   famille fts. Il est toutefois initialisé à zéro.

       fts_pointer Ce  champ  est  mis  à  la   disposition   des   programmes
                   applicatifs,  et  n’est  modifié  par aucune fonction de la
                   famille fts. Il est toutefois initialisé à NULL.

       fts_parent  Un pointeur sur la structure FTSENT référençant le  fichier
                   dans  la  hiérarchie  immédiatement au dessus du fichier en
                   cours, c’est-à-dire le répertoire auquel il appartient. Une
                   structure  parente  pour  le  point  d’entrée  initial  est
                   également  fournie,  mais  seuls  ses  membres   fts_level,
                   fts_number et fts_pointer sont garantis d’être initialisés.

       fts_link    Au retour de la fonction fts_children(), le champ  fts_link
                   pointe  sur la structure suivante dans la liste chaînée des
                   membres du répertoires, liste terminée par  un  NULL.  Dans
                   les  autres  situations,  le  contenu du champ fts_link est
                   indéterminé.

       fts_cycle   Si un répertoire introduit une boucle  dans  la  hiérarchie
                   (voyez  FTS_DC),soit  à cause d’un lien physique entre deux
                   répertoires, soit à cause  d’un  lien  symbolique  pointant
                   vers  un  répertoire,  le  champ fts_cycle pointera vers la
                   structure FTSENT de la hiérarchie  qui  référence  le  même
                   fichier  que  celui  représenté  par  la  structure FTSENT.
                   Sinon, le contenu du champ fts_cycle est indéfini.

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

       Un tampon unique est utilisé pour tous les chemins d’accès de tous  les
       fichiers de la hiérarchie. Ainsi, les champs fts_path et fts_accpath ne
       sont assurés d’être terminés par un caractère  nul  seulement  pour  le
       dernier  fichier  renvoyé par fts_read(). Pour utiliser ces champs pour
       référencer  un  fichier  représenté  par  une  autre  structure  FTSENT
       nécessite  que  le  chemin  du  tampon  soit modifié avec l’information
       contenu dans le champ fts_pathlen de cette structure FTSENT. Tout autre
       modification  devra être défaite avant que d’autres appels à fts_read()
       ne soient tentés.  Le  champ  fts_name  est  toujours  terminé  par  un
       caractère nul.

   fts_open()
       La  fonction fts_open() reçoit un pointeur vers une table de chaînes de
       caractères représentant un ou plusieurs chemins décrivant la hiérarchie
       de  fichiers  à 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
       sélectionnées par un ou logique entre les valeurs suivantes :

       FTS_COMFOLLOW
                    Tout lien symbolique spécifié  comme  racine  du  parcours
                    sera   immédiatement  suivi  (déréférencé),  que  l’option
                    FTS_LOGICAL soit spécifiée ou non.

       FTS_LOGICAL  Cette option indique aux fonctions  fts  de  renvoyer  des
                    structures   FTSENT   concernant   les  cibles  des  liens
                    symboliques plutôt que les  liens  eux-mêmes.  Avec  cette
                    option,  les  seuls  liens  symboliques  pour lesquels une
                    structure FTSENT est renvoyée sont ceux pointant  dans  le
                    vide. Il faut préciser soit FTS_LOGICAL, soit FTS_PHYSICAL
                    à la fonction fts_open().

       FTS_NOCHDIR  Pour  optimiser  les  performances,  les   fonctions   fts
                    changent  de  répertoire  au  cours  de la traversée de la
                    hiérarchie de fichiers. En contrepartie, l’application  ne
                    peut  pas  savoir  à  l’avance où elle se trouve durant la
                    traversée.    L’option    FTS_NOCHDIR    supprime    cette
                    optimisation  et  les  fonctions  fts ne changeront pas de
                    répertoire de travail. Remarquez que les  applications  ne
                    doivent  pas  modifier elles-même le répertoire de travail
                    et  essayer  d’accéder  aux  fichiers  sans  que  l’option
                    FTS_NOCHDIR  ne  soit spécifiée et que des chemins d’accès
                    absolus soient transmis à fts_open().

       FTS_NOSTAT   Par défaut, les structures  FTSENT  renvoyées  contiennent
                    les  caractéristiques  (voir  le  champ  statp)  de chaque
                    fichier visité. Cette option relâche cette contrainte pour
                    optimiser  les  performances,  en autorisant les fonctions
                    fts à remplir le champ fts_info avec FTS_NSOK  et  laisser
                    le contenu du membre statp indéfini.

       FTS_PHYSICAL Avec   cette   option,  les  routines  fts  renvoient  des
                    structures FTSENT pour les liens symboliques eux-mêmes  et
                    non  pas les fichiers qu’ils pointent. Si cette option est
                    définie,  des  structures  FTSENT  pour  tous  les   liens
                    symboliques    de   la   hiérarchie   sont   renvoyées   à
                    l’application. Soit FTS_LOGICAL ou soit FTS_PHYSICAL  doit
                    être fourni à la fonction fts_open().

       FTS_SEEDOT   Par  défaut,  à  moins  d’être  fournis  explicitement  en
                    argument à fts_open() ,tout fichier nommé « . » ou  « .. »
                    rencontré  dans  la  hiérarchie  est  ignoré.  Avec  cette
                    option, les routines fts renvoient des  structures  FTSENT
                    pour ces fichiers.

       FTS_XDEV     Cette option empêche fts de descendre dans les répertoires
                    se trouvant sur un périphérique différent  de  celui  dans
                    lequel le parcours a commencé.

       L’argument  compar()  spécifie  une  fonction définie par l’utilisateur
       pour ordonner la traversée de la hiérarchie.  Elle  prend  en  argument
       deux  pointeurs  sur  des  pointeurs sur des structures FTSENT, et doit
       renvoyer une valeur négative, nulle, ou positive pour indiquer  que  le
       fichier  représenté  par  le  premier  argument  doit  venir  avant,  à
       n’importe quel moment, ou après le  fichier  référencé  par  le  second
       argument.   Les   champs   fts_accpath,  fts_path  et  fts_pathlen  des
       structures  FTSENT  ne  doivent  jamais  être   utilisés   dans   cette
       comparaison.  Si  le  champ  fts_info  contient  FTS_NS ou FTS_NSOK, le
       membre fts_statp ne doit pas  être  utilisé  non  plus.  Si  l’argument
       compar()  est  NULL,  l’ordre de traversée des répertoires est celui de
       l’argument  path_argv  pour  les  racines,  et  l’ordre   interne   des
       répertoires pour le reste.

   fts_read()
       La  fonction  fts_read()  renvoie  un pointeur sur une structure FTSENT
       décrivant un fichier de la hiérarchie. Les répertoires lisibles  et  ne
       causant  pas  de boucles sont parcourus au moins deux fois, une fois en
       phase  « pre-order »,  et  une  en  phase  « post-order ».  Les  autres
       fichiers  ne sont examinés qu’une seule fois. Les liens physiques entre
       répertoires qui ne causent pas de boucles,  ou  les  liens  symboliques
       vers  des liens symboliques peuvent entraîner des fichiers visités plus
       d’une fois, ou des répertoires plus de deux fois.

       Si tous les membres de  la  hiérarchie  ont  été  examinés,  fts_read()
       renvoie  NULL  et  définit  la variable externe errno avec un 0. Si une
       erreur sans rapport avec un fichier particulier se produit,  fts_read()
       renvoie  NULL et définit errno en conséquence. Si une erreur concernant
       le fichier en cours se produit, un pointeur sur  une  structure  FTSENT
       est renvoyé, et errno peut ou non être défini (voyez fts_info).

       Les  structures  FTSENT  renvoyées par fts_read() peuvent être écrasées
       après un appel à fts_close() sur le même descripteur de  hiérarchie  ou
       après  un  appel  à  fts_read()  sur  la même hiérarchie, sauf si elles
       représentent un répertoire, auquel cas elles  ne  seront  pas  écrasées
       avant l’appel fts_read() renvoyant la structure FTSENT du répertoire en
       phase « post-order ».

   fts_children()
       La fonction fts_children() renvoie un pointeur sur une structure FTSENT
       décrivant  la  première entrée d’une liste chaînée terminée par un NULL
       et représentant les fichiers se trouvant dans le répertoire indiqué par
       la dernière structure FTSENT renvoyée par un appel fts_read(). La liste
       est chaînée par le biais du membre fts_link de la structure FTSENT,  et
       est   ordonnée   suivant   la   routine   de  comparaison  fournie  par
       l’utilisateur, si elle existe.  Des  appels  répétés  à  fts_children()
       recréeront la liste chaînée.

       Un cas particulier se présente si fts_read() n’a pas encore été appelée
       pour une hiérarchie. Alors, fts_children() renverra un pointeur sur les
       fichiers  du  répertoire logique spécifié dans fts_open(), c’est-à-dire
       les arguments fournis à fts_open(). Sinon, si la  structure  FTSENT  la
       plus  récemment  renvoyée par fts_read() n’est pas un répertoire visité
       en phase « pre-order », ou si le répertoire ne contient aucun  fichier,
       fts_children() renvoie NULL et met la variable externe errno à zéro. Si
       une erreur se produit, fts_children() renvoie NULL et définit errno  en
       conséquence.

       Les  structures   FTSENT  renvoyées  par  fts_children()   peuvent être
       écrasées après un appel à fts_children(), fts_close() ou fts_read() sur
       la même hiérarchie de fichiers.

       Option peut contenir l’une des valeurs suivantes :

       FTS_NAMEONLY Seuls  les  noms des fichiers sont nécessaires. Le contenu
                    des  membres  des  structures  de  la  liste  chaînée  est
                    indéfini sauf pour fts_name et fts_namelen.

   fts_set()
       La   fonction   fts_set()  permet  à  l’application  de  paramétrer  le
       traitement à venir du fichier f sur la  hiérarchie  ftsp.  La  fonction
       fts_set()  renvoie  0  si elle réussit, et -1 si une erreur se produit.
       Option doit contenir l’une des valeurs suivantes :

       FTS_AGAIN    Revisiter à nouveau le fichier.  N’importe  quel  type  de
                    fichier  peut être revisité. L’appel suivant de fts_read()
                    renverra le  fichier  indiqué.  Les  membres  fts_stat  et
                    fts_info de la structure seront réinitialisés à ce moment,
                    mais aucun autre champ ne sera modifié. Cette  option  n’a
                    de   sens   que   pour  le  dernier  fichier  renvoyé  par
                    fts_read(). L’utilisation habituelle de cette  possibilité
                    concerne les répertoires en phase « post-order », qui sont
                    alors ré-examinés (aussi bien en phase  « pre-order »  que
                    « post-order »), ainsi que leurs descendants.

       FTS_FOLLOW   Le  fichier  référencé doit être un lien symbolique. Si ce
                    fichier est  le  dernier  renvoyé  par  fts_read(),  alors
                    l’appel  suivant  de  fts_read() renverra le fichier, avec
                    les  champs  fts_info  et  fts_statp  réinitialisés   pour
                    représenter la cible du lien symbolique plutôt que le lien
                    lui-même.  Si  le  fichier  est  le  dernier  renvoyé  par
                    fts_children(), alors les membres fts_info et fts_statp de
                    la structure, lorsqu’elle sera  renvoyée  par  fts_read(),
                    représenteront  la  cible du lien symbolique plutôt que le
                    lien lui-même. Dans tous les cas,  si  la  cible  du  lien
                    symbolique  n’existe  pas,  les membres de la structure ne
                    seront pas  modifiés,  et  le  champ  fts_info  contiendra
                    FTS_SLNONE.

                    Si la cible du lien est un répertoire, il y aura un retour
                    « pre-order », suivi d’un retour pour  chaque  descendant,
                    suivi d’un retour « post-order ».

       FTS_SKIP     Aucun  descendant de ce fichier ne sera visité. Le fichier
                    doit  être  le  dernier  renvoyé  par  fts_children()   ou
                    fts_read().

   fts_close()
       La  fonction  fts_close()  ferme  un  descripteur ftsp de hiérarchie de
       fichier, et restitue le répertoire de travail qui était en vigueur lors
       de  l’appel  fts_open()  qui  avait  permit  d’ouvrir ftsp. La fonction
       fts_close() renvoie 0 si elle réussit, et -1 en cas d’erreur.

ERREURS

       La fonction fts_open() peut échouer, et mettre  dans  errno  l’une  des
       erreurs indiquées pour les fonctions open(2) et malloc(3).

       La  fonction  fts_close()  peut échouer, et mettre dans errno l’une des
       erreurs indiquées pour les fonctions chdir(2) et close(2).

       Les fonctions fts_read() et fts_children() peuvent échouer,  et  mettre
       dans  errno  l’une  des  erreurs indiquées pour les fonctions chdir(2),
       malloc(3), opendir(3), readdir(3) et stat(2).

       De plus fts_children(), fts_open() et  fts_set()  peuvent  échouer,  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É

       4.4BSD.

VOIR AUSSI

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

COLOPHON

       Cette  page  fait  partie  de  la  publication 2.80 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> ».