ftw, nftw − Parcours d’arborescence de fichiers.

#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);

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

Echec 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 recursivement 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 funcptr() 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 on été déjà 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).

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.

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

stat(2)

Christophe Blaess, 1997.