fts, fts_open, fts_read, fts_children, fts_set, fts_close - Parcourir une
hiérarchie de fichiers
Bibliothèque C standard (
libc,
-lc)
#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 instr);
int fts_set(FTS *ftsp, FTSENT *f, int instr);
int fts_close(FTS *ftsp);
Les fonctions de la famille fts servent à traverser des
hiérarchies de fichiers. Disons rapidement que la fonction
fts_open() renvoie un descripteur
(« handler » — de type
FTS *) qui fait référence à un
« flux de hiérarchie de fichiers. Ce descripteur
est ensuite fourni 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 un 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 (et les types associés) sont définies dans le
fichier include
<fts.h>. Le premier type est
FTS, une
structure représentant l'arborescence des fichiers elle-même. Le
second est
FTSENT, la 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 :
La structure
FTSENT contient les champs décrivant un ficher. La
structure contient au moins les champs suivants (il y a des champs
supplémentaires qui doivent être considérés comme
réservés à l'implémentation).
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) +
strlen(fts_name) */
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 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 renvoyée et le fichier qu'elle représente.
À l'exception des répertoires FTS_D ne
présentant pas d'erreur, toutes ces entrées sont terminales,
ce qui signifie qu'elles ne seront visitées qu'une seule fois et
que leur éventuels descendants (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 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. C'est
considéré comme une erreur, et le champ fts_errno
sera défini pour indiquer la cause de l'erreur.
- 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
[l] stat(2) n'est disponible. Le contenu du champ
fts_statp est indéfini. Il s'agit d'un cas d'erreur et le
champ fts_errno sera défini pour indiquer la cause de
l'erreur.
- FTS_NSOK
- Un fichier pour lequel aucune information provenant de
[l] 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 informations caractéristiques
de fichier 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 somme des longueurs des chaînes pointées
par fts_path et fts_name.
- 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 (ou racine) 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 le numéro d'erreur
(c'est-à-dire, la valeur de 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 initialisé à 0.
- 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é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 (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
[l]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 contenue 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.
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, soit
FTS_PHYSICAL). Les options sont
sélectionnées par un
ou logique entre les valeurs
suivantes :
- 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 des fichiers qui n'existent
pas : le champ fts_statp est obtenu au moyen de
stat(2) avec un repli vers lstat(2).
- 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 : le
champ fts_statp est obtenu au moyen de lstat(2).
- FTS_COMFOLLOW
- Tout lien symbolique indiqué comme racine du
parcours sera immédiatement suivi, comme au moyen de
FTS_LOGICAL, indépendamment du mode primaire.
- 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. Cette option 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
fts_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 fts_statp
indéfini.
- FTS_SEEDOT
- Par défaut, à moins d'être fourni
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, zéro 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.
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 fois 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 pour indiquer l'erreur. 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 flux de hiérarchie de fichiers 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 ».
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 pour
indiquer l'erreur.
Les structures
FTSENT renvoyées par
fts_children() peuvent
être écrasées après un appel à
fts_children(),
fts_close() ou
fts_read() sur le
même flux de hiérarchie de fichiers.
L'argument
flags est soit zéro, soit la valeur suivante :
- 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.
La fonction
fts_set() permet à l'application de l'utilisateur de
paramétrer le traitement à venir du fichier
f du flux
ftsp. La fonction
fts_set() renvoie
0 si elle
réussit, et
-1 si une erreur se produit.
L'argument
instr est un
0 (signifiant « ne rien
faire ») ou 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().
La fonction
fts_close() ferme le flux de hiérarchie de fichiers
auquel
ftsp fait référence 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.
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 ou les instr ne sont pas
valables.
Ces fonctions sont disponibles sous Linux depuis la glibc2.
Pour une explication des termes utilisés dans cette section, consulter
attributes(7).
| Interface |
Attribut |
Valeur |
|
fts_open(), fts_set(), fts_close() |
Sécurité des threads |
MT-Safe |
|
fts_read(), fts_children() |
Sécurité des threads |
MT-Unsafe |
4.4BSD.
Avant la glibc 2.23, 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).
find(1),
chdir(2),
lstat(2),
stat(2),
ftw(3),
qsort(3)
La traduction française de cette page de manuel a été
créée par Christophe Blaess
<
https://www.blaess.fr/christophe/>, Stéphan Rafin
<
[email protected]>, Thierry Vignaud
<
[email protected]>, François Micaux, Alain Portal
<
[email protected]>, Jean-Philippe Guérard
<
[email protected]>, Jean-Luc Coulon (f5ibh)
<
[email protected]>, Julien Cristau
<
[email protected]>, Thomas Huriaux <
[email protected]>,
Nicolas François <
[email protected]>, Florentin
Duneau <
[email protected]>, Simon Paillard
<
[email protected]>, Denis Barbier
<
[email protected]>, David Prévot <
[email protected]> et
Jean-Pierre Giraud <
[email protected]>
Cette traduction est une documentation libre ; veuillez vous reporter
à la
GNU
General Public License version 3 concernant les conditions de copie
et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel,
veuillez envoyer un message à
[email protected]