Provided by: manpages-fr-dev_2.64.1-1_all bug

NOM

     fts, fts_open, fts_read, fts_children, fts_set, fts_close - Traverser des
     hiérarchies 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 (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 {
             u_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       A directory being visited in post-order.  The
                               contents of the FTSENT structure will be
                               unchanged from when it was returned in pre-
                               order, that is, with the fts_info field set to
                               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   A pointer to the FTSENT structure referencing the file in
                  the hierarchy immediately above the current file, that is,
                  the directory of which this file is a member.  A parent
                  structure for the initial entry point is provided as well,
                  however, only the fts_level, fts_number and fts_pointer
                  fields are guaranteed to be initialized.

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

     As a special case, if fts_read() has not yet been called for a hierarchy,
     fts_children() will return a pointer to the files in the logical
     directory specified to fts_open(), that is, the arguments specified to
     fts_open().  Otherwise, if the FTSENT structure most recently returned by
     fts_read() is not a directory being visited in pre-order, or the
     directory does not contain any files, fts_children() returns NULL and
     sets errno to zero.  If an error occurs, fts_children() returns NULL and
     sets errno appropriately.

     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.  The fts utility is expected to be included in a future IEEE Std
     1003.1-1988 (“POSIX.1”) revision.

VOIR AUSSI

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

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