focal (3) fts.3.gz

Provided by: manpages-fr-dev_3.65d1p1-1_all bug

NOM

       fts,  fts_open,  fts_read,  fts_children, fts_set, fts_close - Parcourir une hiérarchie 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 « preorder » avant d'avoir parcouru leurs descendants, et un passage en
       ordre « postorder » 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
       visitant les fichiers pointés par les liens symboliques) ou « physiquement » (en  visitant
       les  liens  symboliques eux-mêmes). 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;     /* attribut 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 attributs 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 « preorder ».

                   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.  C'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  « postorder ». Le contenu de la
                               structure FTSENT ne sera pas différent de ce qu'il était après  la
                               phase  « preorder ».  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   (consultez
                   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 sont assurés d'être terminés par  un
       caractère  nul  seulement  pour  le fichier renvoyé le plus récemment par fts_read(). Pour
       utiliser ces champs pour référencer un fichier représenté par une autre structure  FTSENT,
       il  faut  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 indiqué comme  racine  du  parcours  sera  immédiatement
                    suivi (déréférencé), que l'option FTS_LOGICAL soit indiqué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 indiqué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() indique 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 « preorder », et une en phase « postorder ». 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 (consultez 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
       « postorder ».

   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  indiqué  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   « preorder »,  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 « postorder », qui sont
                    alors réexaminés (aussi bien en phase « preorder » que « postorder »),  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 « preorder »,
                    suivi d'un retour pour chaque descendant, suivi d'un retour « postorder ».

       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.

BOGUES

       Aucune des interfaces de programmation décrites dans cette page de manuel n’est sûre  lors
       de  la  compilation  d’un  programme  utilisant  les  interfaces de programmation LFS (par
       exemple lors de la compilation avec -D_FILE_OFFSET_BITS=64).

VOIR AUSSI

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

COLOPHON

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