Ubuntu Manpages

ftw, nftw

Parcourir des arborescences de fichiers

Bibliothèque C standard (libc, -lc)

#include <ftw.h>
int nftw(const char *chemin_répertoire,
        typeof(int (const char *chemin_fichier, const struct stat *sb,
                    int typeflag, struct FTW *tampon_ftw),
            *fn,
        int nb_descripteurs_fichier_ouverts, int drapeaux);
[[deprecated]]
int ftw(const char *chemin_répertoire,
        typeof(int (const char *chemin_fichier, const struct stat *sb,
                    int typeflag))
            *fn,
        int nb_descripteurs_fichier_ouverts);

Exigences de macros de test de fonctionnalités pour la glibc (consulter feature_test_macros(7)) :

nftw() :

    _XOPEN_SOURCE >= 500

nftw() walks through the directory tree that is located under the directory dirpath, and calls fn() once for each entry in the tree. By default, directories are handled before the files and subdirectories they contain (preorder traversal).

Afin d'éviter d'utiliser tous les descripteurs de fichier du processus appelant, nb_descripteurs_fichier_ouverts indique le nombre maximal de répertoires que nftw() peut ouvrir simultanément. Lorsque la profondeur de recherche est supérieure à cette valeur, nftw() ralentit car les répertoires doivent être fermés puis réouverts. nftw() utilise au plus un descripteur de fichier pour chaque niveau dans l'arborescence des fichiers.

For each entry found in the tree, nftw() calls fn() with four arguments: fpath, sb, typeflag, and ftwbuf. fpath is the pathname of the entry, and is expressed either as a pathname relative to the calling process's current working directory at the time of the call to nftw(), if dirpath was expressed as a relative pathname, or as an absolute pathname, if dirpath was expressed as an absolute pathname. sb is a pointer to the stat structure returned by a call to stat(2) for fpath.

L'argument symb_type passé à fn() est un entier qui peut prendre une des valeurs suivantes :

chemin_fichier est un fichier ordinaire.
chemin_fichier est un répertoire.
chemin_fichier est un répertoire qui ne peut être lu.
chemin_fichier est un répertoire et FTW_DEPTH a été défini dans drapeaux (si FTW_DEPTH n’est pas défini dans drapeaux, alors les répertoires seront toujours visités avec symb_type défini à FTW_D). Tous les fichiers et sous-répertoires dans chemin_fichier ont été traités.
L'appel stat(2) a échoué sur chemin_fichier qui n'est pas un lien symbolique. Cela est probablement dû au fait que l’appelant avait les droits de lecture sur le répertoire parent de telle sorte que chemin_fichier était visible, mais n’avait pas les droits d’exécution, et donc le fichier ne pouvait pas être atteint pour stat(2). Le contenu du tampon pointé par sb est indéterminé.
chemin_fichier est un lien symbolique et FTW_PHYS a été défini dans drapeaux.
chemin_fichier est un lien symbolique pointant vers un fichier qui n'existe pas (ce qui ne se produira que si FTW_PHYS n'est pas défini). Dans ce cas, l'argument sb passé à fn() contiendra les informations renvoyées par l'exécution de lstat(2) sur le lien symbolique pointant nulle part (voir à ce sujet BOGUES).

Le quatrième argument (tampon_ftw), spécifié par nftw() lors de l'appel de fn, est un pointeur vers une structure du type FTW :


struct FTW {
    int base;
    int level;
};

base est le décalage du nom de fichier (c’est-à-dire le composant « basename ») du chemin donné par chemin_fichier. level est la profondeur de chemin_fichier dans l'arbre des répertoires, relative à la racine de l'arbre (chemin_répertoire qui a une profondeur de 0).

To stop the tree walk, fn() returns a nonzero value; this value will become the return value of nftw(). As long as fn() returns 0, nftw() will continue either until it has traversed the entire tree, in which case it will return zero, or until it encounters an error (such as a malloc(3) failure), in which case it will return -1.

Comme nftw() utilise des structures de données allouées dynamiquement, la seule manière propre de sortir d'un parcours d'arborescence consiste à faire que fn() renvoie une valeur différente de 0. Pour permettre à un signal de terminer le parcours sans causer de fuite de mémoire, utilisez un gestionnaire qui définit un attribut global vérifié par fn(). N'utilisez pas longjmp(3) à moins que le programme ne soit sur le point de se terminer.

L'argument drapeaux de nftw() est un OU binaire entre zéro ou plusieurs des attributs suivants :

Si cet attribut, spécifique à la glibc, est positionné, alors nftw() gère la valeur de retour de fn() différemment. fn() doit renvoyer l'une des valeurs suivantes :
nftw() doit continuer normalement.
If fn() returns this value, then siblings of the current entry will be skipped, and processing continues in the parent.
If fn() is called with an entry that is a directory (typeflag is FTW_D), this return value will prevent objects within that directory from being passed as arguments to fn(). nftw() continues processing with the next sibling of the directory.
nftw() doit quitter immédiatement avec la valeur de retour FTW_STOP.

Other return values could be associated with new actions in the future; fn() should not return values other than those listed above.

La macro de test _GNU_SOURCE doit être définie (avant toute inclusion de fichiers d'en-tête) afin d'obtenir la définition de FTW_ACTIONRETVAL depuis <ftw.h>.

Si cet attribut est défini, faire un chdir(2) vers chaque répertoire avant de traiter son contenu. Cela est utile si le programme doit exécuter des actions dans le répertoire où chemin_fichier réside (préciser ce drapeau n’a aucun effet sur le nom de chemin passé dans l’argument de chemin_fichier de fn).
If set, do a post-order traversal, that is, call fn() for the directory itself after handling the contents of the directory and its subdirectories. (By default, each directory is handled before its contents.)
Si cet attribut est défini, rester dans le même système de fichiers (c’est-à-dire, ne pas traverser vers d'autres points de montage).
Si cet attribut est défini, ne pas suivre les liens symboliques (c'est ce que l'on veut). S'il n'est pas défini, les liens symboliques sont suivis, mais aucun fichier n'est traité plus d'une fois.
Si FTW_PHYS n'est pas défini, mais si FTW_DEPTH l'est, alors la fonction fn() n'est jamais appelée pour un répertoire qui ferait partie de ses propres descendants.

ftw()

ftw() est une fonction plus ancienne qui prend en charge un sous-ensemble des fonctionnalités de nftw(). Les différences notables sont les suivantes :

  • ftw() n'a pas d'argument drapeaux. Elle se comporte comme nftw() lorsque cette dernière est appelée avec l'argument drapeaux défini à zéro.
  • La fonction de rappel fn() est fournie sans le quatrième argument.
  • Le jeu de valeurs passées à l'aide de l'argument symb_type à fn() est plus petit : les seules valeurs valables sont FTW_F, FTW_D, FTW_DNR, FTW_NS et (peut-être) FTW_SL.

Ces fonctions renvoient 0 en cas de succès et -1 en cas d'erreur.

If fn() returns nonzero, then the tree walk is terminated and the value returned by fn() is returned as the result of ftw() or nftw().

Si nftw() est appelée avec l’attribut FTW_ACTIONRETVAL, alors la seule valeur différente de 0 qui pourra être utilisée par fn() pour terminer le parcours de l'arbre est FTW_STOP, et cette valeur est renvoyée comme résultat de nftw().

Pour une explication des termes utilisés dans cette section, consulter attributes(7).

Interface Attribut Valeur
nftw() Sécurité des threads MT-Safe cwd
ftw() Sécurité des threads MT-Safe

Dans certaines implémentations (par exemple la glibc), ftw() n'utilise jamais FTW_SL ; sur d'autres systèmes, FTW_SL n'apparaît que pour les liens symboliques qui ne pointent vers aucun fichier existant ; sur d'autres encore, ftw() utilise FTW_SL pour chaque lien symbolique. Si chemin_fichier est un lien symbolique et si stat(2) échoue, POSIX.1-2008 indique que le résultat est indéfini si FTW_NS ou FTW_SL sont définis dans symbole_type. Pour un fonctionnement prévisible, employez nftw().

POSIX.1-2008.

POSIX.1-2001, SVr4, SVr4, SUSv1. POSIX.1-2008 marque la fonction comme étant obsolète.
glibc 2.1. POSIX.1-2001, SUSv1.
POSIX.1-2001, SUSv1.

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

Selon POSIX.1-2008, lorsque l'argument symb_type passé à fn() contient FTW_SLN, le tampon pointé par sb doit contenir des informations à propos du lien symbolique pointant nulle part (obtenues en appelant lstat(2) sur le lien), et les premières versions de la glibc respectaient la spécification POSIX sur ce point. Cependant, suite à une régression introduite dans la version 2.4 de la glibc, le contenu du tampon pointé par sb devint indéfini lorsque FTW_SLN était défini dans symb_type (plus précisément, le contenu du tampon restait inchangé dans ce cas). Cette régression fut finalement corrigée dans la version 2.30 de la glibc de façon à ce que l'implémentation de la glibc suive à nouveau la spécification POSIX.

Le programme suivant parcourt 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 indiqué. Il affiche diverses informations à propos de chaque fichier. Le second argument de la ligne de commande peut être utilisé pour indiquer les caractères qui contrôlent la valeur assignée à l'argument drapeaux lors des appels à nftw().

#define _XOPEN_SOURCE 500
#include <ftw.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
static int
display_info(const char *fpath, const struct stat *sb,
             int tflag, struct FTW *ftwbuf)
{
    printf("%-3s %2d ",
           (symb_type == FTW_D) ?   "d"   : (symb_type == FTW_DNR) ? "dnr" :
           (symb_type == FTW_DP) ?  "dp"  : (symb_type == FTW_F) ?   "f" :
           (symb_type == FTW_NS) ?  "ns"  : (symb_type == FTW_SL) ?  "sl" :
           (symb_type == FTW_SLN) ? "sln" : "???",
           tampon_ftw->level);
    if (tflag == FTW_NS)
        printf("-------");
    else
        printf("%7jd", (intmax_t) sb->st_size);
    printf("   %-40s %d %s\n",
           chemin_fichier, tampon_ftw->base, chemin_fichier + tampon_ftw->base);
    return 0;           /* Pour dire à nftw() de continuer */
}
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)

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 Lucien Gentis <lucien.gentis@waika9.com>

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.