Editer un article - Informaticien.be

Editer un article

Titre
Mots Clés
Texte	[size=18] [b]Nom[/b] [/size] fts, fts_open, fts_read, fts_children, fts_set, fts_close - Descente d'arborescence de fichiers. [size=18] [b]Résumé[/b] [/size] .nf [b]#include <sys/types.h>[/b] [b]#include <sys/stat.h>[/b] [b]#include <fts.h>[/b] [b] FTS [/b] [b][i]fts_open (char const path_argv , int options , int (compar)(const FTSENT , const FTSENT ) );[/i][/b] [b] FTSENT [/b] [b][i]fts_read (FTS ftsp );[/i][/b] [b] FTSENT [/b] [b][i]fts_children (FTS ftsp , int options );[/i][/b] [b] int[/b] [b][i]fts_set (FTS * ftsp , FTSENT * f , int options );[/i][/b] [b] int[/b] [b][i]fts_close (FTS * ftsp );[/i][/b] .fi [size=18] [b]Description[/b] [/size] Les fonctions de la famille [b] fts[/b] servent à traverser des hiérarchies de fichiers [b]UNIX .[/b] Rapidement, disons que la fonction [b] fts_open[/b] renvoie une sorte de descripteur de la hiérarchie de fichiers, que l'on fournit ensuite aux autres fonctions de la famille [b][i]fts .[/i][/b] La fonction [b] fts_read[/b] renvoie un pointeur sur une structure décrivant l'un des fichiers de l'arborescence. La fonction [b] fts_children[/b] 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 [i]pre-order[/i] avant d'avoir parcouru leurs descendants, et un passage en ordre [i]post-order[/i] 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 (par typedef) dans le fichier d'entête [b]<fts.h> .[/b] La première est [b]FTS ,[/b] une structure représentant l'arborescence des fichiers elle-même, et la seconde est [b]FTSENT ,[/b] une structure représentant un fichier dans la hiérarchie. Normalement, une structure [b] FTSENT[/b] est renvoyée pour chaque fichier rencontré dans la hiérarchie. Dans cette page de manuel, les termes ``fichier'' et structure [b]FTSENT[/b] sont généralement interchangeables. La structure [b] FTSENT[/b] contient au moins les champs suivants, décrits en détail plus bas : .nf [b] typedef struct _ftsent {[/b] [b][i] u_short fts_info; /* flags for FTSENT structure /[/i][/b] [b][i] char fts_accpath; /* access path /[/i][/b] [b][i] char fts_path; /* root path /[/i][/b] [b][i] short fts_pathlen; / strlen(fts_path) /[/i][/b] [b][i] char fts_name; /* file name /[/i][/b] [b][i] short fts_namelen; / strlen(fts_name) /[/i][/b] [b][i] short fts_level; / depth (-1 to N) /[/i][/b] [b][i] int fts_errno; / file errno /[/i][/b] [b][i] long fts_number; / local numeric value /[/i][/b] [b][i] void fts_pointer; /* local address value /[/i][/b] [b][i] struct ftsent fts_parent; /* parent directory /[/i][/b] [b][i] struct ftsent fts_link; /* next file structure /[/i][/b] [b][i] struct ftsent fts_cycle; /* cycle structure /[/i][/b] [b][i] struct stat fts_statp; /* stat(2) information */[/i][/b] [b] } FTSENT;[/b] .fi Les membres ont les significations suivantes : [b]fts_info[/b] [table][row][col]    [/col][col]L'un des attribut suivants, décrivant la structure [b]FTSENT[/b] et le fichier qu'elle représente. Toutes ces entrées sont terminales (sauf les répertoires [i]FTS_D[/i] 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. [b]FTS_D :[/b] Un répertoire visité en phase pré-order. [b]FTS_DC :[/b] Un répertoire introduisant une boucle dans l'arborescence. (Le champ [b]fts_cycle[/b] de la structure [b]FTSENT[/b] sera également remplis). [b]FTS_DEFAULT :[/b] Toute structure [b] FTSENT[/b] représentant un type de fichier non décrit explicitement par l'une des autres valeurs de [b]fts_info .[/b] [b]FTS_DNR :[/b] Un répertoire ne pouvant être lu. Ceci est considéré comme une erreur, et le champ [b]fts_errno[/b] sera rempli avec une valeur décrivant sa cause. [b]FTS_DOT :[/b] Un fichier nommé [b]. ou ..[/b] qui n'a pas été indiqué explicitement comme argument de [b] fts_open[/b] (voir [b]FTS_SEEDOT ). [/b] [b]FTS_DP :[/b] Un répertoire visité en phase post-order. Le contenu de la structure [b]FTSENT[/b] ne sera pas différent de ce qu'il était durant la phase pré-order. C'est à dire quand le champ [b]fts_info[/b] valait [b]FTS_D .[/b] [b]FTS_ERR :[/b] Il s'agit d'un retour d'erreur, le champ [b]fts_errno[/b] étant rempli pour indiquer la cause de l'erreur. [b]FTS_F :[/b] Fichier normal. [b]FTS_NS :[/b] Un fichier pour lequel aucune information provenant de [b]stat (2)[/b] n'est disponible. Le contenu du champ [b]fts_statp[/b] est indéfini. Il s'agit d'un cas d'erreur dont la cause est indiquée dans [b]fts_errno .[/b] [b]FTS_NSOK :[/b] Un fichier pour lequel aucune information provenant de [b]stat (2)[/b] n'a été demandée. Le contenu du champ [b]fts_statp[/b] est indéfini. [b]FTS_SL :[/b] Un lien symbolique. [b]FTS_SLNONE :[/b] Un lien symbolique pointant dans le vide. Le contenu du champ [b]fts_statp[/b] contient les caractéristiques du lien lui-même.[/col][/row][/table] [b]fts_accpath[/b] [table][row][col]    [/col][col]Un chemin permettant d'accéder au fichier depuis le répertoire courrant.[/col][/row][/table] [b]fts_path[/b] [table][row][col]    [/col][col]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 [b]fts_open .[/b][/col][/row][/table] [b]fts_pathlen[/b] [table][row][col]    [/col][col]La longueur de la chaîne pointée par [b]fts_path .[/b][/col][/row][/table] [b]fts_name[/b] [table][row][col]    [/col][col]Le nom du fichier.[/col][/row][/table] [b]fts_namelen[/b] [table][row][col]    [/col][col]La longueur de la chaîne pointée par [b]fts_name .[/b][/col][/row][/table] [b]fts_level[/b] [table][row][col]    [/col][col]La profondeur où le fichier a été trouvé dans l'arborescence, numérotée de -1 à N. La structure [b]FTSENT[/b] représentant le parent du point de départ est numérotée -1. La structure [b]FTSENT[/b] représentant la racine de départ elle-même est numérotée 0.[/col][/row][/table] [b]fts_errno[/b] [table][row][col]    [/col][col]Dans une structure [b] FTSENT[/b] renvoyée par un appel [b]fts_children ()[/b] ou [b]fts_read (),[/b] dont le champ [b]fts_info[/b] contient [b]FTS_DNR ,[/b] [i] FTS_ERR[/i] ou [b]FTS_NS ,[/b] le champ [b] fts_errno[/b] est rempli avec la valeur de la variable externe [i] errno[/i] indiquant la cause de l'erreur. Dans les autres cas, le contenu du champ [b]fts_errno[/b] est indéfini.[/col][/row][/table] [b]fts_number[/b] [table][row][col]    [/col][col]Ce champ est mis à la disposition des programmes applicatifs, et n'est modifié par aucune fonction de la famille [b]fts .[/b] Il est toutefois initialisé à zéro.[/col][/row][/table] [b]fts_pointer[/b] [table][row][col]    [/col][col]Ce champ est mis à la disposition des programmes applicatifs, et n'est modifié par aucune fonction de la famille [b]fts .[/b] Il est toutefois initialisé à NULL.[/col][/row][/table] [b]fts_parent[/b] [table][row][col]    [/col][col]Un pointeur sur la structure .Fa FTSENT référençant le fichier dans la hiérarchie imédiatement au dessus du fichier en cours, c'est à dire le répertoire auquel il appartient. Une structure [b]fts_parent[/b] pour le point d'entrée initial est également fournie, mais seuls ses membres [b]fts_level ,[/b] [b]fts_number[/b] et [b]fts_pointer[/b] sont garantis d'être initialisés.[/col][/row][/table] [b]fts_link[/b] [table][row][col]    [/col][col]Au retour de la fonction [b]fts_children (),[/b] le champ [b] fts_link[/b] 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 [b] fts_link[/b] est indéterminé.[/col][/row][/table] [b]fts_cycle[/b] [table][row][col]    [/col][col]Si un répertoire introduit une boucle dans la hiérarchie (voir [b]FTS_DC ),[/b] soit à cause d'un lien physique entre deux répertoires, soit à cause d'un lien symbolique pointant vers un répertoire, le champ [b]fts_cycle[/b] pointera vers la structure [b] FTSENT[/b] de la hiérarchie qui référence le même fichier que celui représenté par la structure [b]FTSENT .[/b] Sinon, le contenu du champ [b] fts_cycle[/b] est indéfini.[/col][/row][/table] [b]fts_statp[/b] [table][row][col]    [/col][col]Un pointeur vers les informations fournies par [b]stat (2)[/b] pour le fichier.[/col][/row][/table] Un unique buffer est utilisé pour tous les chemins d'accès de tous les fichiers de la hiérarchie. Ainsi, les champs [b] fts_path[/b] et [b]fts_accpath[/b] ne sont assurés d'être terminés par un caractère nul [b]que[/b] pour le dernier fichier renvoyé par [b]fts_read .[/b] Le champ [b]fts_name[/b] est toujour terminé par un caractère nul. [size=18] [b]Fts_open[/b] [/size] La fonction [b]fts_open[/b] 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 [b]NULL .[/b] Il existe un certain nombre d'options, dont au moins une est obligatoire [b]( FTS_LOGICAL[/b] ou [b]FTS_PHYSICAL ).[/b] Les options sont sélectionnées par un [b]OU[/b] logique entre les valeurs suivantes : [b]FTS_COMFOLLOW :[/b] [table][row][col]    [/col][col]Tout lien symbolique spécifié comme racine du parcours sera immédiatement suivi (déréférencé), que l'option [i] FTS_LOGICAL[/i] soit aussi indiquée ou non.[/col][/row][/table] [b]FTS_LOGICAL :[/b] [table][row][col]    [/col][col]Renvoyer des structures [b] FTSENT[/b] concernant les cibles des liens symboliques plutôt que les liens eux-mêmes. Avec cette options, les seuls liens symboliques pour lesquels une structure [b] FTSENT[/b] est renvoyée sont ceux pointant dans le vide. Il [b]faut[/b] préciser soit [b] FTS_LOGICAL ,[/b] soit [b] FTS_PHYSICAL .[/b][/col][/row][/table] [b]FTS_NOCHDIR :[/b] [table][row][col]    [/col][col]Pour optimiser les performances, les fonctions [b] fts[/b] 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 [i] FTS_NOCHDIR[/i] supprime cette optimisation et les fonctions [b] fts[/b] 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 [i] FTS_NOCHDIR[/i] ne soit spécifiée et que des chemins d'accès absolus soit transmis à [b] fts_open .[/b][/col][/row][/table] [b]FTS_NOSTAT :[/b] [table][row][col]    [/col][col]Par défaut, les structures [b] FTSENT[/b] renvoyées contiennent les caractéristiques (voir le champ [b]statp )[/b] de chaque fichier visité. Cette option relâche cette contrainte pour optimiser les performances, en autorisant les fonctions [b] fts[/b] à remplir le champ [b] fts_info[/b] avec [i] FTS_NSOK[/i] et laisser le contenu du membre [b] statp[/b] indéfini.[/col][/row][/table] [b]FTS_PHYSICAL :[/b] [table][row][col]    [/col][col]Les structures [b] FTSENT[/b] renvoyées concerneront les liens symboliques eux-mêmes et non pas leurs cibles. Il [b]faut[/b] indiquer soit [b]FTS_LOGICAL ,[/b] soit [i] FTS_PHYSICAL[/i] à la fonction [b]fts_open .[/b][/col][/row][/table] [b]FTS_SEEDOT :[/b] [table][row][col]    [/col][col]Par défaut, à moins d'être fournis explicitement en argument à [b] fts_open ,[/b] tout fichier nommé [b].[/b] ou [b] ..[/b] rencontré dans la hiérarchie est ignoré. Avec cette option, les routines [b] fts[/b] renvoient des structures [b] FTSENT[/b] pour ces fichiers.[/col][/row][/table] [b]FTS_XDEV :[/b] [table][row][col]    [/col][col]Cette option empêche [b] fts[/b] de descendre dans les répertoires se trouvant sur un périphérique différent de celui dans lequel le parcours a commencé.[/col][/row][/table] L'argument [i] compar[/i] 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 [b] FTSENT ,[/b] 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 [b]fts_accpath ,[/b] [b] fts_path[/b] et [b] fts_pathlen[/b] des structures [b] FTSENT[/b] ne doivent [b] jamais[/b] être utilisés dans cette comparaison. Si le champ [b] fts_info[/b] contient [i] FTS_NS[/i] ou [b]FTS_NSOK ,[/b] le membre [b] fts_statp[/b] ne doit pas être utilisé non plus. Si l'argument [i] compar[/i] est [b] NULL ,[/b] l'ordre de traversée des répertoires est celui de l'argument [b] path_argv[/b] pour les racines, et l'ordre interne des répertoires pour le reste. [size=18] [b]Fts_read[/b] [/size] La fonction [b] fts_read[/b] renvoie un pointeur sur une structure [b] FTSENT[/b] décrivant un fichier de la hiérarchie. Les répertoires lisibles et ne causant pas de boucles sont parcourus au moins deux foix, une fois en phase pré-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 entrainer 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, [b] fts_read[/b] renvoie [i] NULL[/i] et remplit la variable externe [i] errno[/i] avec un 0. Si une erreur sans rapport avec un fichier particulier se produit, [b] fts_read[/b] renvoie [i] NULL[/i] et remplit [b] errno[/b] en conséquence. Si une erreur concernant le fichier en cours se produit, un pointeur sur une structure [b] FTSENT[/b] est renvoyé, et [i] errno[/i] peut ou non être rempli (voir [b] fts_info ) .[/b] Les structures [b] FTSENT[/b] renvoyées par [b] fts_read[/b] peuvent être écrasées après un appel à [b] fts_close[/b] sur le même descripteur de hiérarchie ou après un appel à [b] fts_read[/b] 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 [b] fts_read[/b] renvoyant la structure [b] FTSENT[/b] du répertoire en phase post-order. [size=18] [b]Fts_children[/b] [/size] La fonction [b] fts_children[/b] renvoie un pointeur sur la structure [b] FTSENT[/b] décrivant la première entrée d'un 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 [b] FTSENT[/b] renvoyée par un appel [b] fts_read .[/b] La liste est chaînée par le biais du membre [b] fts_link[/b] de la structure [b]FTSEN ,[/b] et est ordonnée suivant la routine de comparaison fournie par l'utilisateur, si elle existe. Des appels répétés à [b] fts_children[/b] recréeront la liste chaînée. Un cas particulier se présente si [b] fts_read[/b] n'a pas encore été appelé pour cette hiérarchie. Alors, [b] fts_children[/b] renverra un pointeur sur les fichiers du répertoire logique transmis [b] fts_open ,[/b] c'est à dire les arguments fournis à [b] fts_open .[/b] Sinon, si la structure [b] FTSENT[/b] la plus récemment renvoyée par [b] fts_read[/b] n'est pas un répertoire visité en phase pré-order, ou si le répertoire ne contient aucun fichier, [b] fts_children[/b] renvoie [i] NULL[/i] et met la variable externe [i] errno[/i] à zéro. Si une erreur se produit, [b] fts_children[/b] renvoie [i] NULL[/i] et remplit [i] errno[/i] comme il se doit. Les structures [b] FTSENT[/b] renvoyées par [b] fts_children[/b] peuvent être écrasées après un appel [b]fts_children ,[/b] [b] fts_close[/b] ou [b] fts_read[/b] sur la même hiérarchie de fichiers. [i] Option[/i] peut contenir l'une des valeurs suivantes : [b]FTS_NAMEONLY :[/b] [table][row][col]    [/col][col]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 [b] fts_name[/b] et [b] fts_namelen .[/b][/col][/row][/table] [size=18] [b]Fts_set[/b] [/size] La fonction [b] fts_set[/b] permet à l'application de paramétrer le traitement à venir du fichier [b] f[/b] sur la hiérarchie. [b] ftsp .[/b] La fonction [b] fts_set[/b] renvoie 0 si elle réussit, et -1 si une erreur se produit. [i] Option[/i] doit contenir l'une des valeurs suivantes : [b]FTS_AGAIN :[/b] [table][row][col]    [/col][col]Re-visiter à nouveau le fichier. N'importe quel type de fichier peut être re-visité. L'appel suivant de [b] fts_read[/b] renverra le fichier indiqué. Les membres [b] fts_stat[/b] et [b] fts_info[/b] 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 [b] fts_read .[/b] L'utilisation habituelle de cette possibilité concerne les répertoires en phase post-order, qui sont alors ré-examinés (aussi bien en phase pré-order que post-order), ainsi que leurs descendants.[/col][/row][/table] [b]FTS_FOLLOW :[/b] [table][row][col]    [/col][col]Le fichier référencé doit être un lien symbolique. Si ce fichier est le dernier renvoyé par [b] fts_read ,[/b] alors l'appel suivant de [b] fts_read[/b] renverra le fichier, avec les champs [b] fts_info[/b] et [b] fts_statp[/b] 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 [b] fts_children ,[/b] alors les membres [b] fts_info[/b] et [b] fts_statp[/b] de la structure, lorsqu'elle sera renvoyée par [b] fts_read ,[/b] 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 [b] fts_info[/b] contiendra [b]FTS_SLNONE .[/b] Si la cible du lien est un répertoire, il y aura un retour pré-order, suivi d'un retour pour chaque descendant, suivi d'un retour post-order.[/col][/row][/table] [b]FTS_SKIP :[/b] [table][row][col]    [/col][col]Aucun descendant de ce fichier ne sera visité. Le fichier doit être le dernier renvoyé par [b] fts_children[/b] ou [b]fts_read .[/b][/col][/row][/table] [size=18] [b]Fts_close[/b] [/size] La fonction [b] fts_close[/b] ferme un descripteur [i] fts[/i] de hiérarchie de fichier, et restitue le répertoire de travail qui était en vigueur lors de l'appel [b] fts_open .[/b] La fonction [b] fts_close[/b] renvoie 0 si elle réussit, et -1 en cas d'erreur. [size=18] [b]Erreurs[/b] [/size] La fonction [b] fts_open[/b] peut échouer, et mettre dans [i] errno[/i] l'une des erreurs indiquées pour les fonctions [b]open (2)[/b] et [b]malloc (3).[/b] La fonction [b] fts_close[/b] peut échouer, et mettre dans [i] errno[/i] l'une des erreurs indiquées pour les fonctions [b]chdir (2)[/b] et [b]close (2).[/b] Les fonctions [b] fts_read[/b] et [b] fts_children[/b] peuvent échouer, et mettre dans [i] errno[/i] l'une des erreurs indiquées pour les fonctions [b]chdir (2),[/b] [b]malloc (3),[/b] [b]opendir (3),[/b] [b]readdir (3)[/b] et [b]stat (2).[/b] De plus [b]fts_children ,[/b] [b] fts_open[/b] et [b] fts_set[/b] peuvent échouer, et mettre dans [i] errno[/i] l'une des erreurs suivantes : [b]EINVAL[/b] [table][row][col]    [/col][col]Une option est invalide.[/col][/row][/table] [size=18] [b]Voir aussi[/b] [/size] [b]find (1),[/b] [b]chdir (2),[/b] [b]stat (2),[/b] [b]qsort (3)[/b] [size=18] [b]Conformité[/b] [/size] BSD 4.4. La famille de fonctions [b] fts[/b] sera peut être incluse dans une future mise à jour de [b]-p1003.1-88 .[/b] [size=18] [b]Disponibilité[/b] [/size] Ces fonctions sont disponibles sous Linux depuis la bibliothèque GlibC 2. [size=18] [b]Traduction[/b] [/size] Christophe Blaess, 2000-2003.
Fichier