ftw(3) Library Functions Manual ftw(3)
NOM
ftw, nftw - Parcourir des arborescences de fichiers
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
SYNOPSIS
#include <ftw.h>
int nftw(const char *chemin_répertoire,
int (*fn)(const char *chemin_fichier, const struct stat *sb,
int symbole_type, struct FTW *tampon_ftw),
int nb_descripteurs_fichier_ouverts, int drapeaux);
[[deprecated]]
int ftw(const char *chemin_répertoire,
int (*fn) (const char *chemin_fichier, const struct stat *sb,
int symbole_type),
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
DESCRIPTION
La fonction nftw() parcourt l'arborescence de fichiers située dans le
répertoire chemin_répertoire et appelle fn() une fois pour chaque en-
trée de l'arborescence. Par défaut, les répertoires sont traités avant
les fichiers et sous-répertoires qu'ils contiennent (méthode de par-
cours « preorder »).
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 fi-
chiers.
Pour chaque entrée trouvée dans l'arbre, nftw() appelle fn() avec
quatre arguments : chemin_fichier, sb, symbole_type et tampon_ftw. che-
min_fichier est le chemin de l'entrée ; il est défini comme un chemin
relatif au répertoire de travail actuel du processus appelant au moment
de l'appel à nftw() si chemin_répertoire est un chemin relatif, ou
comme un chemin absolu si chemin_répertoire est un chemin absolu. sb
est un pointeur vers la structure stat renvoyée par un appel à stat(2)
pour chemin_fichier.
L'argument symbole_type passé à fn() est un entier qui peut prendre une
des valeurs suivantes :
FTW_F chemin_fichier est un fichier ordinaire.
FTW_D chemin_fichier est un répertoire.
FTW_DNR
chemin_fichier est un répertoire qui ne peut être lu.
FTW_DP 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 symbole_type défini à
FTW_D). Tous les fichiers et sous-répertoires dans chemin_fi-
chier ont été traités.
FTW_NS 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 at-
teint pour stat(2). Le contenu du tampon pointé par sb est indé-
terminé.
FTW_SL chemin_fichier est un lien symbolique et FTW_PHYS a été défini
dans drapeaux.
FTW_SLN
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 « ba-
sename ») 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).
Pour arrêter le parcours de l'arborescence des fichiers, la fonction
fn() renvoie une valeur différente de 0, qui deviendra la valeur de re-
tour de nftw(). Tant que fn() renvoie 0, nftw() continuera jusqu'à la
fin du parcours de l'arborescence, et dans ce cas renverra 0, ou
jusqu'à ce qu'une erreur se produise (comme un échec de malloc(3)) et
dans ce cas renverra -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, uti-
lisez 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 :
FTW_ACTIONRETVAL (depuis la glibc 2.3.3)
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 :
FTW_CONTINUE
nftw() doit continuer normalement.
FTW_SKIP_SIBLINGS
Si fn() renvoie cette valeur, alors les entrées de même
niveau que l'entrée courante seront sautées, et la procé-
dure continuera avec le parent.
FTW_SKIP_SUBTREE
Si fn() est appelée avec une entrée qui est un répertoire
(symbole_type a pour valeur FTW_D), cette valeur de re-
tour empêchera le passage des objets de ce répertoire
comme arguments à fn() et nftw() continuera avec l'entrée
suivante de même niveau du répertoire.
FTW_STOP
nftw() doit quitter immédiatement avec la valeur de re-
tour FTW_STOP.
D'autres valeurs de retour pourront être associées à de nou-
velles actions dans le futur ; fn ne devrait renvoyer que les
valeurs citées ci-dessus.
La macro de test _GNU_SOURCE doit être définie (avant toute in-
clusion de fichiers d'en-tête) afin d'obtenir la définition de
FTW_ACTIONRETVAL depuis <ftw.h>.
FTW_CHDIR
Si cet attribut est défini, faire un chdir(2) vers chaque réper-
toire avant de traiter son contenu. Cela est utile si le pro-
gramme doit exécuter des actions dans le répertoire où che-
min_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).
FTW_DEPTH
Si cet attribut est défini, faire une recherche « postorder » ;
c'est-à-dire, appeler fn() pour le répertoire lui-même après
avoir traité son contenu et celui de ses sous-répertoires (par
défaut chaque répertoire est traité avant son contenu).
FTW_MOUNT
Si cet attribut est défini, rester dans le même système de fi-
chiers (c’est-à-dire, ne pas traverser vers d'autres points de
montage).
FTW_PHYS
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 sym-
boliques 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-en-
semble 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 symbole_type à fn()
est plus petit : les seules valeurs valables sont FTW_F, FTW_D,
FTW_DNR, FTW_NS et (peut-être) FTW_SL.
VALEUR RENVOYÉE
Ces fonctions renvoient 0 en cas de succès et -1 en cas d'erreur.
Si fn() renvoie une valeur différente de 0, 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é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().
VERSIONS
La fonction nftw() est disponible depuis la glibc 2.1.
ATTRIBUTS
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 │
└─────────────────────────────────┴──────────────────────┴─────────────┘
STANDARDS
POSIX.1-2001, POSIX.1-2008, SVr4, SUSv1. POSIX.1-2008 marque ftw()
comme étant obsolète.
NOTES
POSIX.1-2008 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é intro-
duites dans SUSv1.
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, PO-
SIX.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, em-
ployez nftw().
BOGUES
Selon POSIX.1-2008, lorsque l'argument symbole_type passé à fn()
contient FTW_SLN, le tampon pointé par sb doit contenir des informa-
tions à propos du lien symbolique pointant nulle part (obtenues en ap-
pelant 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 symbole_type (plus précisément, le contenu du tampon restait in-
changé 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.
EXEMPLES
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().
Source du programme
#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 *chemin_fichier, const struct stat *sb,
int symbole_type, struct FTW *tampon_ftw)
{
printf("%-3s %2d ",
(symbole_type == FTW_D) ? "d" : (symbole_type == FTW_DNR) ? "dnr" :
(symbole_type == FTW_DP) ? "dp" : (symbole_type == FTW_F) ? "f" :
(symbole_type == FTW_NS) ? "ns" : (symbole_type == FTW_SL) ? "sl" :
(symbole_type == FTW_SLN) ? "sln" : "???",
tampon_ftw->level);
if (symbole_type == 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);
}
VOIR AUSSI
stat(2), fts(3), readdir(3)
TRADUCTION
La traduction française de cette page de manuel a été créée par Chris-
tophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <ste-
phan.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.cou-
lon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centra-
liens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <si-
mon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@de-
bian.org>, David Prévot <david@tilapin.org> et Lucien Gentis <lu-
cien.gentis@waika9.com>
Cette traduction est une documentation libre ; veuillez vous reporter à
la GNU General Public License version 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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⟩.
Pages du manuel de Linux 6.03 5 février 2023 ftw(3)
Generated by dwww version 1.15 on Sat Jun 29 01:34:29 CEST 2024.