Provided by:
manpages-fr_1.67.0-1_all 
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.