NOM

glob, globfree - Rechercher un chemin d'accès correspondant à un motif

BIBLIOTHÈQUE

Bibliothèque C standard ( libc, -lc)

SYNOPSIS

#include <glob.h>

int glob(const char *restrict pattern, int flags,
         int (*errfunc)(const char *epath, int eerrno),
         glob_t *restrict pglob);
void globfree(glob_t *pglob);

DESCRIPTION

La fonction glob() recherche tous les chemins d'accès correspondant au motif pattern en utilisant les règles du shell (consultez glob(7)). Aucun remplacement de tilde ou substitution de paramètre n'est effectué. Si vous avez besoin de ces fonctionnalités, utilisez wordexp(3).
La fonction globfree() libère la mémoire allouée dynamiquement lors d'un appel précédent à glob().
Les résultats d'un appel à glob() sont stockés dans une structure pointée par pglob. Cette structure est de type glob_t (défini dans <glob.h>) et inclut les éléments définis par POSIX.2 (il peut y en avoir plus sous forme d'extension GNU) : 

typedef struct {
    size_t   gl_pathc;    /* Nombre de chemins correspondant  */
    char   **gl_pathv;    /* Liste des chemins correspondant  */
    size_t   gl_offs;     /* Entrées à réserver dans  gl_pathv.  */
} glob_t;

Les résultats sont sauvés dans une zone allouée dynamiquement.
Le paramètre flags est constitué d'un OU binaire « | » entre zéro ou plus des constantes symboliques suivantes, modifiant le comportement de glob() :
GLOB_ERR
Terminer dès qu'une erreur se produit (par exemple, un répertoire non lisible). Par défaut, glob() tente, malgré les erreurs, de lire tous les répertoires qu'il peut.
GLOB_MARK
Ajoute une barre oblique finale à chaque nom correspondant à un répertoire.
GLOB_NOSORT
Ne pas trier les chemins d'accès renvoyés. La seule raison pour faire cela est d'économiser du temps de traitement. Par défaut, les chemins d'accès renvoyés sont triés.
GLOB_DOOFFS
Réserve pglob->gl_offs points d'entrée au début de la liste de chaînes dans pglob->pathv. Les points d'entrée réservés contiennent des pointeurs NULL.
GLOB_NOCHECK
Si aucun motif ne correspond, renvoyer le motif original. Par défaut, glob() renvoie GLOB_NOMATCH s'il n'y a pas de correspondance.
GLOB_APPEND
Ajoute les résultats de cet appel au tableau de résultats renvoyé par un appel précédent à glob(). Ne pas indiquer cet attribut lors du premier appel de glob().
GLOB_NOESCAPE
Don't allow backslash ('\') to be used as an escape character. Normally, a backslash can be used to quote the following character, providing a mechanism to turn off the special meaning metacharacters.
flags peut également utiliser les constantes suivantes, qui sont des extensions GNU, non définies dans POSIX.2 :
GLOB_PERIOD
Permettre à un point en tête de chemin de correspondre à un méta-caractère. Par défaut, les méta-caractères ne peuvent pas correspondre à un point en tête de chemin.
GLOB_ALTDIRFUNC
Utiliser les fonctions alternatives pglob->gl_closedir, pglob->gl_readdir, pglob->gl_opendir, pglob->gl_lstat et pglob->gl_stat pour l'accès au système de fichiers au lieu des fonctions normales de bibliothèque.
GLOB_BRACE
Développer dans le style csh(1) les expressions de type {a,b}. Les expressions entre accolades peuvent être imbriquées. Ainsi, par exemple, spécifier le motif « {foo/{,cat,dog},bar} » retournera le même résultat que quatre appels à glob() séparés utilisant les chaînes : « foo/ », « foo/cat », « foo/dog », et « bar ».
GLOB_NOMAGIC
Si le motif renvoyé ne contient pas de méta-caractères, il sera retourné comme seul mot correspondant, même s'il n'existe pas de fichier avec ce nom.
GLOB_TILDE
Carry out tilde expansion. If a tilde ('~') is the only character in the pattern, or an initial tilde is followed immediately by a slash ('/'), then the home directory of the caller is substituted for the tilde. If an initial tilde is followed by a username (e.g., "~andrea/bin"), then the tilde and username are substituted by the home directory of that user. If the username is invalid, or the home directory cannot be determined, then no substitution is performed.
GLOB_TILDE_CHECK
Fournit un comportement similaire à celui de GLOB_TILDE. La différence est que si le nom d'utilisateur n'est pas valable ou si le répertoire personnel ne peut pas être déterminé, plutôt que d'utiliser le motif lui-même comme nom, glob() renvoie GLOB_NOMATCH pour indiquer l'erreur.
GLOB_ONLYDIR
C'est une indication pour glob() indiquant que l'appelant ne s'intéresse qu'aux répertoires correspondant au motif. Si l'implémentation peut facilement déterminer le type de fichier, les fichiers qui ne sont pas des répertoires ne sont pas renvoyés à l'appelant. Toutefois, l'appelant doit toujours vérifier que les fichiers renvoyés sont des répertoires (le but de cet attribut est simplement d'optimiser les performances lorsque l'appelant ne s'intéresse qu'aux répertoires).
Si errfunc n'est pas NULL, elle sera appelée en cas d'erreur, avec les arguments epath un pointeur sur le chemin qui a échoué, et eerrno la valeur de errno telle qu'elle a été renvoyée par un appel à opendir(3), readdir(3) ou stat(2). Si errfunc renvoie une valeur non nulle, ou si GLOB_ERR est positionné, glob() se terminera après l'appel de errfunc.
Si glob() réussit complètement, pglob->gl_pathc contient le nombre de chemins d'accès correspondants et pglob->gl_pathv contient un pointeur sur une liste des chemins. Le premier pointeur après le dernier chemin vaut NULL.
Il est possible d'appeler glob() plusieurs fois. Dans ce cas, l'attribut GLOB_APPEND doit être indiqué dans flags durant le second appel et les suivants.
En tant qu'extension GNU, le champ pglob->gl_flags contient les attributs indiqués liés par un OU avec GLOB_MAGCHAR si un méta-caractère a été trouvé.

VALEUR RENVOYÉE

S'il réussit complètement glob() renvoie zéro. Les autres valeurs renvoyées peuvent être :
GLOB_NOSPACE
pas assez de mémoire,
GLOB_ABORTED
erreur de lecture,
GLOB_NOMATCH
aucune correspondance trouvée.

ATTRIBUTS

Pour une explication des termes utilisés dans cette section, consulter attributes(7).
Interface Attribut Valeur
glob() Sécurité des threads MT-Unsafe race:utent env sig:ALRM timer locale
globfree() Sécurité des threads MT-Safe
 
In the above table, utent in race:utent signifies that if any of the functions setutent(3), getutent(3), or endutent(3) are used in parallel in different threads of a program, then data races could occur. glob() calls those functions, so we use race:utent to remind users.

STANDARDS

POSIX.1-2001, POSIX.1-2008, POSIX.2.

NOTES

Les éléments de la structure gl_pathc et gl_offs sont déclarés comme des size_t dans glibc 2.1, comme préconisé dans POSIX.2, mais sont déclarés sous forme de int dans glibc 2.0.

BOGUES

La fonction glob() peut échouer en cas d'erreur dans un appel de fonction sous-jacent, comme malloc(3) ou opendir(3). Le code d'erreur sera alors stocké dans errno.

EXEMPLES

L'exemple d'utilisation suivant simule la frappe de 

ls -l *.c ../*.c

dans un shell : 

glob_t globbuf;


globbuf.gl_offs = 2;
glob("*.c", GLOB_DOOFS, NULL, &globbuf);
glob("../*.c", GLOB_DOOFS | GLOB_APPEND, NULL, &globbuf);
globbuf.gl_pathv[0] = "ls";
globbuf.gl_pathv[1] = "-l";
execvp("ls", &globbuf.gl_pathv[0]);

VOIR AUSSI

ls(1), sh(1), stat(2), exec(3), fnmatch(3), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7)

TRADUCTION

La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <[email protected]>, Thierry Vignaud <[email protected]>, François Micaux, Alain Portal <[email protected]>, Jean-Philippe Guérard <[email protected]>, Jean-Luc Coulon (f5ibh) <[email protected]>, Julien Cristau <[email protected]>, Thomas Huriaux <[email protected]>, Nicolas François <[email protected]>, Florentin Duneau <[email protected]>, Simon Paillard <[email protected]>, Denis Barbier <[email protected]>, David Prévot <[email protected]> et Frédéric Hantrais <[email protected]>
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 à [email protected]