fts(3) | Library Functions Manual | fts(3) |
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 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; /* structure de boucle */ struct stat *fts_statp; /* information [l]stat(2) */ } FTSENT;
Les membres ont les significations suivantes :
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 NULL 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 tampon du chemin 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 NULL.
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 :
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 flux de 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é à 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 :
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 :
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 [l]stat(2).
De plus fts_children(), fts_open() et fts_set() peuvent échouer et mettre dans errno l'une des erreurs suivantes :
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 <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Jean-Pierre Giraud <jean-pierregiraud@neuf.fr>
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 à debian-l10n-french@lists.debian.org.
15 décembre 2022 | Pages du manuel de Linux 6.03 |