man ftw (Fonctions bibliothèques) - Parcours d'arborescence de fichiers.

NOM

ftw, nftw - Parcours d'arborescence de fichiers.

SYNOPSIS

#include <ftw.h> int ftw (const char *directory, int (*funcptr) (const char *file, const struct stat *sb, int flag), int depth); int nftw (const char *directory, int (*funcptr) (const char *file, const struct stat *sb, int flag, struct FTW *s), int depth, int flags);

DESCRIPTION

La fonction ftw() parcourt la hiérarchie de fichiers commençant au répertoire directory. Pour chaque fichier rencontré, elle appelle funcptr avec le chemin d'accès du fichier relativement à directory, un pointeur sur une structure stat(2), et un entier flag, dont la valeur signifie :

FTW_F
Fichier normal
FTW_D
Répertoire
FTW_DNR
Répertoire non lisible
FTW_SL
Lien symbolique
FTW_NS
Échec de stat sur cet élément

S'il s'agit d'un lien symbolique et que stat échoue, XPG4v2 précise que FTW_NS ou FTW_SL peuvent être utilisés.

ftw() s'appelle lui-même récursivement pour parcourir tous les répertoires trouvés. Afin d'éviter d'utiliser tous les descripteurs de fichiers disponibles pour le programme, la profondeur depth limite le nombre de répertoires ouverts simultanément. Quand cette profondeur est atteinte, ftw() va ralentir, car des répertoires devront être fermés puis réouverts.

Pour arrêter le parcours des fichiers, la fonction funcptr peut renvoyer une valeur non-nulle, qui deviendra la valeur de retour de ftw(). Sinon, ftw() continuera jusqu'à atteindre la fin du parcours de l'arbre, et renverra zéro, ou jusqu'à ce que se produise une erreur comme celles de malloc(3) et renverra -1.

Comme ftw() utilise des structures de données allouées dynamiquement, la seule manière propre de sortir d'un parcours est de renvoyer une valeur non nulle. Pour traiter les interruptions, par exemple, notez le numéro d'interruption survenue et renvoyez une valeur non nulle. N'utilisez jamais longjmp(3) à moins que le programme ne soit prêt à se terminer.

La fonction nftw() fait exactement la même chose que ftw(), sauf qu'elle utilise un argument flags supplémentaire (et invoque la fonction transmise avec un argument de plus). L'argument flags est un OU regroupant zéro ou certaines des constantes :

FTW_CHDIR
Faire un chdir() dans chaque répertoire avant d'en traiter le contenu.
FTW_DEPTH
Faire une recherche en profondeur d'abord, c'est-à-dire n'appeler la fonction pour le répertoire lui-même qu'après en avoir traité tout le contenu, y compris les sous-répertoires.
FTW_MOUNT
Rester uniquement dans le même système de fichiers.
FTW_PHYS
Ne pas suivre les liens symboliques (C'est classiquement ce que l'on veut). Sinon, les liens symboliques sont suivis, mais aucun fichier n'est traité plus d'une fois.

Si FTW_PHYS n'est pas demandé, mais si FTW_DEPTH l'est, la fonction n'est jamais appelée sur un répertoire que l'on retrouve dans ses descendants.

La fonction funcptr() est appelée avec quatre arguments : le chemin de l'entrée traitée, un pointeur sur une structure stat la concernant, un entier décrivant son type, et un pointeur sur une structure FTW. Le type sera FTW_F, FTW_D, FTW_DNR, FTW_SL, ou FTW_NS (significations ci-dessus, FTW_SL uniquement si FTW_PHYS est demandé) ou

FTW_DP
Répertoire dont tous les descendants ont déjà été traités. Ceci ne se produit qu'avec FTW_DEPTH.
FTW_SLN
Lien symbolique pointant nulle part. Ceci ne se produit qu'avec FTW_PHYS absent.

La structure FTW pointée par le quatrième argument de funcptr() contient au moins les champs base, la position du nom de fichier dans le chemin fourni par le premier argument de funcptr(), et level, la profondeur de l'objet par rapport au point de départ (de profondeur 0).

NOTES

La fonction nftw() et l'usage de FTW_SL dans ftw() ont été introduits dans XPG4v2.

Sur certains systèmes, ftw() n'utilise jamais FTW_SL, sur d'autres, FTW_SL ne se présente que pour les liens symboliques pointant dans le vide, sur d'autres encore, ftw() utilisera FTW_SL pour chaque lien symbolique. Pour un fonctionnement prévisible, employez nftw().

Sous Linux, les LibC 4, LibC 5, et GlibC 2.0.6 utilisent FTW_F pour tous les objets (fichiers, liens symboliques, fifos, etc.) ne permettant pas un stat, mais autres que les répertoires. La fonction nftw() est disponible depuis la GlibC 2.1.

CONFORMITÉ

AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.

VOIR AUSSI

TRADUCTION

Christophe Blaess, 1996-2003.

CETTE PAGE DOCUMENTE AUSSI :