FTS
Section : Manuel du programmeur Linux (
3)
Mise à jour de la version anglaise : 28 décembre 2007
Index
Menu principal
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 « 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'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 {
unsigned short fts_info; /* attributs pour 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; /* nom 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 d'adresse locale */
struct ftsent *fts_parent; /* répertoire parent */
struct ftsent *fts_link; /* structure de fichier suivante */
struct ftsent *fts_cycle; /* cycle structure */
struct stat *fts_statp; /* information de 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 ne présentant pas d'erreur
FTS_D),
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 rempli).
- 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 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 ordinaire.
- 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 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
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
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épertoire, 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 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 octet nul
que
pour le dernier fichier renvoyé par
fts_read().
L'utilisation de ces champs pour référencer tout fichier représenté
par d'autres structures
FTSENT
nécessitera que le tampon du chemin soit modifié avec les informations
contenues dans le champ
fts_pathlen
de cette structure
FTSENT.
De telles modifications doivent être annulées avant que d'autres appels ultérieurs à
fts_read()
ne soient tentés.
Le champ
fts_name
est toujours terminé par un octet 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 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
-
Les structures
FTSENT
renvoyées concerneront les liens symboliques eux-mêmes
et non pas leurs cibles.
Si cette option est définie, des structures
FTSENT
pour tous les liens symboliques de la hiérarchie sont renvoyés
à l'application.
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 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 renseigne la variable externe
errno
avec un 0.
Si une erreur sans rapport avec un fichier particulier se produit,
fts_read()
renvoie NULL et renseigne
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 renseignée (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'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 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 « 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 renseigne
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 permis 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 valides.
VERSIONS
Ces fonctions sont disponibles sous Linux depuis la glibc 2.
CONFORMITÉ
BSD 4.4.
VOIR AUSSI
find(1),
chdir(2),
stat(2),
ftw(3),
qsort(3)
TRADUCTION
Ce document est une traduction réalisée par Christophe Blaess
<http://www.blaess.fr/christophe/> le 1er septembre 2000
et révisée le 17 juillet 2008.
L'équipe de traduction a fait le maximum pour réaliser une adaptation
française de qualité. La version anglaise la plus à jour de ce document est
toujours consultable via la commande : « LANG=C man 3 fts ».
N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute
erreur dans cette page de manuel.
Index
- NOM
-
- SYNOPSIS
-
- DESCRIPTION
-
- fts_open()
-
- fts_read()
-
- fts_children()
-
- fts_set()
-
- fts_close()
-
- ERREURS
-
- VERSIONS
-
- CONFORMITÉ
-
- VOIR AUSSI
-
- TRADUCTION
-
Dernière mise à jour : 17 juillet 2008