Provided by: manpages-fr_1.67.0-1_all bug

NOM

       fts,  fts_open,  fts_read,  fts_children, fts_set, fts_close - Descente
       d’arborescence 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 UNIX.

       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 (par typedef) dans le fichier d’entê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  plus
       bas :

       typedef struct _ftsent {
           u_short fts_info;          /* flags for FTSENT structure */
           char *  fts_accpath;       /* access path */
           char *  fts_path;          /* root path */
           short   fts_pathlen;       /* strlen(fts_path) */
           char *  fts_name;          /* file name */
           short   fts_namelen;       /* strlen(fts_name) */
           short   fts_level;         /* depth (-1 to N) */
           int     fts_errno;         /* file errno */
           long    fts_number;        /* local numeric value */
           void *  fts_pointer;       /* local address value */
           struct ftsent *fts_parent; /* parent directory */
           struct ftsent *fts_link;   /* next file structure */
           struct ftsent *fts_cycle;  /* cycle structure */
           struct stat *  fts_statp;  /* stat(2) information */
       } 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 pré-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 rempli 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 (voir 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
              durant  la phase pré-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 : 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
              courrant.

       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 rempli 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  référençant  le  fichier  dans  la
              hiérarchie  imédiatement  au dessus du fichier en cours, c’est à
              dire  le  répertoire  auquel  il  appartient.    Une   structure
              fts_parent 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 (voir
              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) pour le
              fichier.

       Un unique buffer 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  que  pour  le
       dernier  fichier  renvoyé  par fts_read.  Le champ fts_name est toujour
       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  (FTS_LOGICAL   ou   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
              aussi indiquée ou non.

       FTS_LOGICAL :
              Renvoyer  des  structures FTSENT concernant les cibles des liens
              symboliques plutôt que les liens eux-mêmes. Avec cette  options,
              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.

       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
              soit 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 :
              Les   structures   FTSENT   renvoyées   concerneront  les  liens
              symboliques eux-mêmes et non pas leurs cibles.  Il faut indiquer
              soit FTS_LOGICAL, soit FTS_PHYSICAL à 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 foix, une fois en
       phase pré-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 entrainer 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  remplit  la  variable externe errno avec un 0.  Si une erreur
       sans rapport avec un fichier particulier se produit,  fts_read  renvoie
       NULL  et  remplit  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 rempli (voir 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  la  structure  FTSENT
       décrivant la première entrée d’un 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 FTSEN,  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é
       pour cette hiérarchie. Alors, fts_children renverra un pointeur sur les
       fichiers  du  répertoire  logique  transmis  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
       pré-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 remplit errno comme il se doit.

       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 :
              Re-visiter  à nouveau le fichier. N’importe quel type de fichier
              peut être re-visité.  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 pré-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  pré-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  fts  de  hiérarchie de
       fichier, et restitue le répertoire de travail qui était en vigueur lors
       de  l’appel fts_open.  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 Une option est invalide.

VOIR AUSSI

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

CONFORMITÉ

       BSD  4.4.  La  famille de fonctions fts sera peut être incluse dans une
       future mise à jour de -p1003.1-88.

DISPONIBILITÉ

       Ces fonctions sont disponibles sous Linux depuis la bibliothèque  GlibC
       2.

TRADUCTION

       Christophe Blaess, 2000-2003.