Man page 3 : ftw

ftw, nftw - Parcourir des arborescences de fichiers

La fonction ftw() parcourt une arborescence de fichiers située dans le répertoire dirpath et appelle fn() pour chaque entrée de l'arborescence. Par défaut, les répertoires sont traités avant les fichiers et sous-répertoires qu'ils contiennent. Afin d'éviter d'utiliser tous les descripteurs de fichier disponibles pour le programme, nopenfd spécifie le nombre maximal de répertoires que ftw() peut ouvrir de manière simultanée. Lorsque la profondeur de recherche est supérieure à cette valeur, ftw() ralentit car les répertoires doivent être fermés puis réouverts. ftw() utilise au plus un descripteur de fichier pour chaque niveau dans l'arborescence des fichiers. Pour chaque entrée trouvée dans l'arbre, ftw() appelle fn() avec trois arguments : fpath, sb et typeflag. fpath est le chemin de l'entrée , il est soit défini comme un chemin relatif au répertoire actuel de travail du processus appelant à l'instant de l'appel à ftw() si dirpath est un chemin relatif, ou soit comme un chemin absolu si dirpath est un chemin absolu. sb est un pointeur vers la structure stat renvoyée par un appel à stat(2) pour fpath. typeflag est un entier qui a une des valeurs suivantes :

• FTW_F
      fpath est un fichier régulier.
• FTW_D
      fpath est un répertoire.
• FTW_DNR
      fpath est un répertoire non lisible.
• FTW_NS
      L'appel stat(2) a échoué sur fpath, qui n'est pas un lien symbolique.
  
  Si fpath est un lien symbolique et que stat(2) échoue, POSIX.1-2001 précise que c'est indéfini si FTW_NS ou FTW_SL sont passés à typeflag (consultez ci-dessous).

Pour arrêter le parcours des arborescences de fichiers, la fonction fn() renvoie une valeur non nulle, qui deviendra la valeur de retour de ftw(). Tant que fn() renvoie 0, ftw() continuera jusqu'à la fin du parcours de l'arborescence, et dans ce cas renverra zéro, ou jusqu'à ce que une erreur se produise (comme pour 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 d'arborescence est de renvoyer une valeur non nulle depuis fn(). Pour permettre à un signal de terminer le parcours sans causer de fuite de mémoire, utilisez un « handler » qui définit un drapeau vérifié par fn(). N'utilisez pas longjmp(3) à moins que le programme ne soit prêt à se terminer.

3.1. nftw() ▲

struct FTW {
    int base;
    int level;
};

Ces fonctions renvoie 0 en cas de succès et -1 en cas d'erreur. Si fn() renvoie une valeur non nulle, alors le parcours de l'arbre se termine et la valeur renvoyée par fn() est renvoyée comme résultat de ftw() ou nftw(). Si nftw() est appelé avec le drapeau FTW_ACTIONRETVAL, alors la seule valeur non nulle qui pourra être utilisée par fn() pour terminer le parcours de l'arbre est FTW_STOP, et cette valeur est renvoyée comme le résultat de nftw().

POSIX.1-2001, SVr4, SUSv1. POSIX.1-2008 marque ftw() comme étant obsolète.

POSIX.1-2001 indique que les résultats sont imprévisibles si fn ne préserve pas le répertoire de travail actuel.

La fonction nftw() et l'utilisation de FTW_SL() avec ftw() ont été introduites dans SUSv1.

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

Sous Linux, les libc4, libc5 et glibc 2.0.6 utilisent FTW_F pour tous les objets (fichier, lien symbolique, fifo, etc.), sauf pour les répertoires, qui peuvent être utilisés par stat. La fonction nftw() est disponible depuis la glibc 2.1. FTW_ACTIONRETVAL est spécifique à la glibc.

Le programme suivant parcours l'arbre des répertoires du chemin donné en premier argument de la ligne de commande ou du répertoire courant s'il n'est pas spécifié. Il affiche divers informations à propos de chaque fichier. Le second argument de la ligne de commande peut être utilisé pour spécifier les caractères assignés à l'argument flags lors des appels de nftw().

#define _XOPEN_SOURCE 500
#include <ftw.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stdint.h>
static int
display_info(const char *fpath, const struct stat *sb,
             int tflag, struct FTW *ftwbuf)
{
    printf("%-3s %2d %7jd   %-40s %d %s\n",
        (tflag == FTW_D) ?   "d"   : (tflag == FTW_DNR) ? "dnr" :
        (tflag == FTW_DP) ?  "dp"  : (tflag == FTW_F) ?   "f" :
        (tflag == FTW_NS) ?  "ns"  : (tflag == FTW_SL) ?  "sl" :
        (tflag == FTW_SLN) ? "sln" : "???",
        ftwbuf->level, (intmax_t) sb->st_size,
        fpath, ftwbuf->base, fpath + ftwbuf->base);
    return 0;           /* To tell nftw() to continue */
}
int
main(int argc, char *argv[])
{
    int flags = 0;
    if (argc > 2 && strchr(argv[2], d) != NULL)
        flags |= FTW_DEPTH;
    if (argc > 2 && strchr(argv[2], p) != NULL)
        flags |= FTW_PHYS;
    if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
            == -1) {
        perror("nftw");
        exit(EXIT_FAILURE);
    }
    exit(EXIT_SUCCESS);
}

stat(2), fts(3), readdir(3)

Cette page fait partie de la publication 3.52 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies peuvent être trouvées à l'adresse http://www.kernel.org/doc/man-pages/.

Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <http://perkamon.alioth.debian.org/>.

Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain Portal <http://manpagesfr.free.fr/> (2003-2006). Florentin Duneau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <>.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « LC_ALL=C man <section> <page_de_man> ».