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 « 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 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; /* 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) */
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 attributs 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
« preorder ».
- 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. C'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
« 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 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
(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 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 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 indiqué comme racine du parcours sera
immédiatement suivi (déréférencé), que
l'option FTS_LOGICAL soit indiqué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 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 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() 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, 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 « preorder »,
et une 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 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
(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 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 « postorder ».
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 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 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 « 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().
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.
4.4BSD.
BOGUES¶
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).
VOIR AUSSI¶
find(1),
chdir(2),
stat(2),
ftw(3),
qsort(3)
COLOPHON¶
Cette page fait partie de la publication 3.65 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¶
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a
<
http://po4a.alioth.debian.org/> par l'équipe de traduction
francophone au sein du projet perkamon
<
http://perkamon.alioth.debian.org/>.
Christophe Blaess <
http://www.blaess.fr/christophe/> (1996-2003), Alain
Portal <
http://manpagesfr.free.fr/> (2003-2006). Florentin Duneau et
l'équipe francophone de traduction de Debian (2006-2009).
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> ».