Provided by:
manpages-fr-dev_3.27fr1.4-1_all 
NOM
fts, fts_open, fts_read, fts_children, fts_set, fts_close - Parcourir
une hierarchie 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 a traverser des hierarchies de
fichiers. Rapidement, disons que la fonction fts_open() renvoie une
sorte de descripteur de la hierarchie de fichiers, que l'on fournit
ensuite aux autres fonctions de la famille fts. La fonction fts_read()
renvoie un pointeur sur une structure decrivant l'un des fichiers de
l'arborescence. La fonction fts_children() renvoie un pointeur sur une
liste chainee de structures, chacune decrivant l'un des fichiers
contenu dans le repertoire de la hierarchie. En general, les
repertoires sont visites a deux reprises, distinctes. Un passage en
ordre << preorder >> avant d'avoir parcouru leurs descendants, et un
passage en ordre << postorder >> apres avoir visite tous les
sous-repertoires. Les fichiers ne sont examines qu'une seule fois. Il
est possible de parcourir la hierarchie << logiquement >> (en ignorant
les liens symboliques) ou << physiquement >> (en visitant les liens
symboliques). On peut ordonner le parcours de la hierarchie, ignorer ou
visiter plusieurs fois certaines parties.
Deux structures sont definies (avec typedef) dans le fichier d'en-tete
<fts.h>. La premiere est FTS, une structure representant l'arborescence
des fichiers elle-meme, et la seconde est FTSENT, une structure
representant un fichier dans la hierarchie. Normalement, une structure
FTSENT est renvoyee pour chaque fichier rencontre dans la hierarchie.
Dans cette page de manuel, les termes << fichier >> et << structure
FTSENT >> sont generalement interchangeables. La structure FTSENT
contient au moins les champs suivants, decrits en detail ci-dessous :
typedef struct _ftsent {
unsigned short fts_info; /* drapeau de la structure FTSENT */
char *fts_accpath; /* chemin d'acces */
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 a N) */
int fts_errno; /* fichier errno */
long fts_number; /* valeur numerique locale */
void *fts_pointer; /* valeur de l'adresse locale */
struct ftsent *fts_parent; /* repertoire 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, decrivant la structure FTSENT
et le fichier qu'elle represente. Toutes ces entrees sont
terminales (sauf les repertoires FTS_D ne presentant pas
d'erreur), ce qui signifie qu'elle ne seront visitees
qu'une seule fois, et que leur eventuels descendants (cas
des repertoires en erreur) ne seront pas visites.
FTS_D Un repertoire visite en phase << preorder >>.
FTS_DC Un repertoire introduisant une boucle dans
l'arborescence. Le champ fts_cycle de la
structure FTSENT sera egalement remplis.
FTS_DEFAULT Toute structure FTSENT representant un type de
fichier non decrit explicitement par l'une des
autres valeurs de fts_info.
FTS_DNR Un repertoire ne pouvant etre lu. Ceci est
considere comme une erreur, et le champ
fts_errno sera defini avec une valeur decrivant
sa cause.
FTS_DOT Un fichier nomme << . >> ou << .. >> qui n'a
pas ete indique explicitement comme argument de
fts_open() (consultez FTS_SEEDOT).
FTS_DP Un repertoire visite en phase << postorder >>.
Le contenu de la structure FTSENT ne sera pas
different de ce qu'il etait apres la phase
<< preorder >>. C'est-a-dire quand le champ
fts_info valait FTS_D.
FTS_ERR Il s'agit d'un retour d'erreur, le champ
fts_errno etant 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 indefini. Il
s'agit d'un cas d'erreur dont la cause est
indiquee dans fts_errno.
FTS_NSOK Un fichier pour lequel aucune information
provenant de stat(2) n'a ete demandee. Le
contenu du champ fts_statp est indefini.
FTS_SL Un lien symbolique.
FTS_SLNONE Un lien symbolique pointant dans le vide. Le
contenu du champ fts_statp contient les
caracteristiques du lien lui-meme.
fts_accpath Un chemin permettant d'acceder au fichier depuis le
repertoire courant.
fts_path Le chemin d'acces au fichier a partir du point de depart du
parcours. Il contient en prefixe le chemin fourni lors de
l'invocation de fts_open().
fts_pathlen La longueur de la chaine pointee par fts_path.
fts_name Le nom du fichier.
fts_namelen La longueur de la chaine pointee par fts_name.
fts_level La profondeur ou le fichier a ete trouve dans
l'arborescence, numerotee de -1 a N. La structure FTSENT
representant le parent du point de depart est numerotee -1.
La structure FTSENT representant la racine de depart
elle-meme est numerotee 0.
fts_errno Dans une structure FTSENT renvoyee 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
defini 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 indefini.
fts_number Ce champ est mis a la disposition des programmes
applicatifs, et n'est modifie par aucune fonction de la
famille fts. Il est toutefois initialise a zero.
fts_pointer Ce champ est mis a la disposition des programmes
applicatifs, et n'est modifie par aucune fonction de la
famille fts. Il est toutefois initialise a NULL.
fts_parent Un pointeur sur la structure FTSENT referencant le fichier
dans la hierarchie immediatement au dessus du fichier en
cours, c'est-a-dire le repertoire auquel il appartient. Une
structure parente pour le point d'entree initial est
egalement fournie, mais seuls ses membres fts_level,
fts_number et fts_pointer sont garantis d'etre initialises.
fts_link Au retour de la fonction fts_children(), le champ fts_link
pointe sur la structure suivante dans la liste chainee des
membres du repertoires, liste terminee par un NULL. Dans
les autres situations, le contenu du champ fts_link est
indetermine.
fts_cycle Si un repertoire introduit une boucle dans la hierarchie
(consultez FTS_DC),soit a cause d'un lien physique entre
deux repertoires, soit a cause d'un lien symbolique
pointant vers un repertoire, le champ fts_cycle pointera
vers la structure FTSENT de la hierarchie qui reference le
meme fichier que celui represente par la structure FTSENT.
Sinon, le contenu du champ fts_cycle est indefini.
fts_statp Un pointeur vers les informations fournies par stat(2).
Un tampon unique est utilise pour tous les chemins d'acces de tous les
fichiers de la hierarchie. Ainsi, les champs fts_path et fts_accpath
sont assures d'etre termines par un caractere nul seulement pour le
fichier renvoye le plus recemment par fts_read(). Pour utiliser ces
champs pour referencer un fichier represente par une autre structure
FTSENT, il faut que le chemin du tampon soit modifie avec l'information
contenu dans le champ fts_pathlen de cette structure FTSENT. Tout autre
modification devra etre defaite avant que d'autres appels a fts_read()
ne soient tentes. Le champ fts_name est toujours termine par un
caractere nul.
fts_open()
La fonction fts_open() recoit un pointeur vers une table de chaines de
caracteres representant un ou plusieurs chemins decrivant la hierarchie
de fichiers a 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
selectionnees par un ou logique entre les valeurs suivantes :
FTS_COMFOLLOW
Tout lien symbolique specifie comme racine du parcours
sera immediatement suivi (dereference), que l'option
FTS_LOGICAL soit specifiee ou non.
FTS_LOGICAL Cette option indique aux fonctions fts de renvoyer des
structures FTSENT concernant les cibles des liens
symboliques plutot que les liens eux-memes. Avec cette
option, les seuls liens symboliques pour lesquels une
structure FTSENT est renvoyee sont ceux pointant dans le
vide. Il faut preciser soit FTS_LOGICAL, soit FTS_PHYSICAL
a la fonction fts_open().
FTS_NOCHDIR Pour optimiser les performances, les fonctions fts
changent de repertoire au cours de la traversee de la
hierarchie de fichiers. En contrepartie, l'application ne
peut pas savoir a l'avance ou elle se trouve durant la
traversee. L'option FTS_NOCHDIR supprime cette
optimisation et les fonctions fts ne changeront pas de
repertoire de travail. Remarquez que les applications ne
doivent pas modifier elles-meme le repertoire de travail
et essayer d'acceder aux fichiers sans que l'option
FTS_NOCHDIR ne soit specifiee et que des chemins d'acces
absolus soient transmis a fts_open().
FTS_NOSTAT Par defaut, les structures FTSENT renvoyees contiennent
les caracteristiques (voir le champ statp) de chaque
fichier visite. Cette option relache cette contrainte pour
optimiser les performances, en autorisant les fonctions
fts a remplir le champ fts_info avec FTS_NSOK et laisser
le contenu du membre statp indefini.
FTS_PHYSICAL Avec cette option, les routines fts renvoient des
structures FTSENT pour les liens symboliques eux-memes et
non pas les fichiers qu'ils pointent. Si cette option est
definie, des structures FTSENT pour tous les liens
symboliques de la hierarchie sont renvoyees a
l'application. Soit FTS_LOGICAL ou soit FTS_PHYSICAL doit
etre fourni a la fonction fts_open().
FTS_SEEDOT Par defaut, a moins d'etre fournis explicitement en
argument a fts_open() ,tout fichier nomme << . >> ou
<< .. >> rencontre dans la hierarchie est ignore. Avec
cette option, les routines fts renvoient des structures
FTSENT pour ces fichiers.
FTS_XDEV Cette option empeche fts de descendre dans les repertoires
se trouvant sur un peripherique different de celui dans
lequel le parcours a commence.
L'argument compar() specifie une fonction definie par l'utilisateur
pour ordonner la traversee de la hierarchie. Elle prend en argument
deux pointeurs sur des pointeurs sur des structures FTSENT, et doit
renvoyer une valeur negative, nulle, ou positive pour indiquer que le
fichier represente par le premier argument doit venir avant, a
n'importe quel moment, ou apres le fichier reference par le second
argument. Les champs fts_accpath, fts_path et fts_pathlen des
structures FTSENT ne doivent jamais etre utilises dans cette
comparaison. Si le champ fts_info contient FTS_NS ou FTS_NSOK, le
membre fts_statp ne doit pas etre utilise non plus. Si l'argument
compar() est NULL, l'ordre de traversee des repertoires est celui de
l'argument path_argv pour les racines, et l'ordre interne des
repertoires pour le reste.
fts_read()
La fonction fts_read() renvoie un pointeur sur une structure FTSENT
decrivant un fichier de la hierarchie. Les repertoires 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 examines qu'une seule fois. Les liens physiques entre
repertoires qui ne causent pas de boucles, ou les liens symboliques
vers des liens symboliques peuvent entrainer des fichiers visites plus
d'une fois, ou des repertoires plus de deux fois.
Si tous les membres de la hierarchie ont ete examines, fts_read()
renvoie NULL et definit la variable externe errno avec un 0. Si une
erreur sans rapport avec un fichier particulier se produit, fts_read()
renvoie NULL et definit errno en consequence. Si une erreur concernant
le fichier en cours se produit, un pointeur sur une structure FTSENT
est renvoye, et errno peut ou non etre defini (consultez fts_info).
Les structures FTSENT renvoyees par fts_read() peuvent etre ecrasees
apres un appel a fts_close() sur le meme descripteur de hierarchie ou
apres un appel a fts_read() sur la meme hierarchie, sauf si elles
representent un repertoire, auquel cas elles ne seront pas ecrasees
avant l'appel fts_read() renvoyant la structure FTSENT du repertoire en
phase << postorder >>.
fts_children()
La fonction fts_children() renvoie un pointeur sur une structure FTSENT
decrivant la premiere entree d'une liste chainee terminee par un NULL
et representant les fichiers se trouvant dans le repertoire indique par
la derniere structure FTSENT renvoyee par un appel fts_read(). La liste
est chainee par le biais du membre fts_link de la structure FTSENT, et
est ordonnee suivant la routine de comparaison fournie par
l'utilisateur, si elle existe. Des appels repetes a fts_children()
recreeront la liste chainee.
Un cas particulier se presente si fts_read() n'a pas encore ete appelee
pour une hierarchie. Alors, fts_children() renverra un pointeur sur les
fichiers du repertoire logique specifie dans fts_open(), c'est-a-dire
les arguments fournis a fts_open(). Sinon, si la structure FTSENT la
plus recemment renvoyee par fts_read() n'est pas un repertoire visite
en phase << preorder >>, ou si le repertoire ne contient aucun fichier,
fts_children() renvoie NULL et met la variable externe errno a zero. Si
une erreur se produit, fts_children() renvoie NULL et definit errno en
consequence.
Les structures FTSENT renvoyees par fts_children() peuvent etre
ecrasees apres un appel a fts_children(), fts_close() ou fts_read() sur
la meme hierarchie de fichiers.
Option peut contenir l'une des valeurs suivantes :
FTS_NAMEONLY Seuls les noms des fichiers sont necessaires. Le contenu
des membres des structures de la liste chainee est
indefini sauf pour fts_name et fts_namelen.
fts_set()
La fonction fts_set() permet a l'application de parametrer le
traitement a venir du fichier f sur la hierarchie ftsp. La fonction
fts_set() renvoie 0 si elle reussit, et -1 si une erreur se produit.
Option doit contenir l'une des valeurs suivantes :
FTS_AGAIN Revisiter a nouveau le fichier. N'importe quel type de
fichier peut etre revisite. L'appel suivant de fts_read()
renverra le fichier indique. Les membres fts_stat et
fts_info de la structure seront reinitialises a ce moment,
mais aucun autre champ ne sera modifie. Cette option n'a
de sens que pour le dernier fichier renvoye par
fts_read(). L'utilisation habituelle de cette possibilite
concerne les repertoires en phase << postorder >>, qui
sont alors reexamines (aussi bien en phase << preorder >>
que << postorder >>), ainsi que leurs descendants.
FTS_FOLLOW Le fichier reference doit etre un lien symbolique. Si ce
fichier est le dernier renvoye par fts_read(), alors
l'appel suivant de fts_read() renverra le fichier, avec
les champs fts_info et fts_statp reinitialises pour
representer la cible du lien symbolique plutot que le lien
lui-meme. Si le fichier est le dernier renvoye par
fts_children(), alors les membres fts_info et fts_statp de
la structure, lorsqu'elle sera renvoyee par fts_read(),
representeront la cible du lien symbolique plutot que le
lien lui-meme. Dans tous les cas, si la cible du lien
symbolique n'existe pas, les membres de la structure ne
seront pas modifies, et le champ fts_info contiendra
FTS_SLNONE.
Si la cible du lien est un repertoire, 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 visite. Le fichier
doit etre le dernier renvoye par fts_children() ou
fts_read().
fts_close()
La fonction fts_close() ferme un descripteur ftsp de hierarchie de
fichier, et restitue le repertoire de travail qui etait en vigueur lors
de l'appel fts_open() qui avait permit d'ouvrir ftsp. La fonction
fts_close() renvoie 0 si elle reussit, et -1 en cas d'erreur.
ERREURS
La fonction fts_open() peut echouer, et mettre dans errno l'une des
erreurs indiquees pour les fonctions open(2) et malloc(3).
La fonction fts_close() peut echouer, et mettre dans errno l'une des
erreurs indiquees pour les fonctions chdir(2) et close(2).
Les fonctions fts_read() et fts_children() peuvent echouer, et mettre
dans errno l'une des erreurs indiquees pour les fonctions chdir(2),
malloc(3), opendir(3), readdir(3) et stat(2).
De plus fts_children(), fts_open() et fts_set() peuvent echouer, 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'E
4.4BSD.
VOIR AUSSI
find(1), chdir(2), stat(2), ftw(3), qsort(3)
COLOPHON
Cette page fait partie de la publication 3.27 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent etre trouvees a l'adresse
<URL:http://www.kernel.org/doc/man-pages/>.
TRADUCTION
Depuis 2010, cette traduction est maintenue a l'aide de l'outil po4a
<URL:http://po4a.alioth.debian.org/> par l'equipe de traduction
francophone au sein du projet perkamon
<URL:http://perkamon.alioth.debian.org/>.
Christophe Blaess <URL:http://www.blaess.fr/christophe/> (1996-2003),
Alain Portal <URL:http://manpagesfr.free.fr/> (2003-2006). Florentin
Duneau et l'equipe francophone de traduction de Debian (2006-2009).
Veuillez signaler toute erreur de traduction en ecrivant a
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir acces a la version anglaise de ce document
en utilisant la commande << man -L C <section> <page_de_man> >>.
Linux 28 decembre 2007 FTS(3)