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

#include <glob.h>

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

La fonction glob() recherche tous les chemins d'accès correspondants au motif pattern en utilisant les règles du shell (voir glob(7)). Aucun remplacement de tilde ou substitution de paramètre n'est effectué. Si vous avez besoin de ces fonctionnalités, voyez 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, qui est du type glob_t défini dans <glob.h> en incluant les éléments définis par POSIX.2 (il peut y en avoir plus sous forme d'extension GNU) :

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

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

demande à glob() de se terminer dès qu'une erreur se produit (par exemple un répertoire non lisible).

GLOB_MARK

Ajouter un slash final à chaque nom aboutissant à un répertoire.

GLOB_NOSORT

Ne pas trier les chemins d'accès renvoyés (ils le sont par défaut).

GLOB_DOOFFS

signifie que pglob->gl_offs points d'entrée seront réservés au début de la liste de chaînes dans pglob->pathv.

GLOB_NOCHECK

demande à glob() de renvoyer le motif original si aucune correspondance n'est possible.

GLOB_APPEND

ajoute les résultats à ceux d'un appel précédent. Ne pas indiquer cet attribut lors du premier appel de glob().

GLOB_NOESCAPE

Les méta-caractères ne peuvent pas être désactivés par un backslash.

On peut également utiliser les constantes suivantes, qui sont des extensions GNU, non définies dans POSIX.2 :

GLOB_PERIOD

Un point en tête de chemin peut correspondre à un méta-caractère.

GLOB_ALTDIRFUNC

On utilisera comme alternatives aux fonctions normales de bibliothèque les fonctions pglob->gl_closedir, pglob->gl_readdir, pglob->gl_opendir, pglob->gl_lstat, et pglob->gl_stat.

GLOB_BRACE

Les expressions de type {a,b} sont développées avec le style csh(1).

GLOB_NOMAGIC

Le motif est renvoyé s'il ne contient pas de méta-caractères.

GLOB_TILDE

L'expansion du tilde est prise en charge.

GLOB_ONLYDIR

Seuls les répertoires sont mis en correspondance.

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(), readdir(), ou stat(). 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 est 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é.

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.

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_DOOFFS, NULL, &globbuf); glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf); globbuf.gl_pathv[0] = "ls"; globbuf.gl_pathv[1] = "-l"; execvp("ls", &globbuf.gl_pathv[0]);

POSIX.2

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

Les membres gl_pathc et gl_offs de la structure glob_t sont des size_t dans GlibC 2.1, comme indiqué dans POSIX.2, mais sont déclarés sous forme de int dans LibC 4, LibC 5 et GlibC 2.0.

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

Christophe Blaess, 1996-2003.