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);
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 3.23 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> ».