NOM
wordexp, wordfree - Effectuer l’expansion de mots à la manière d’un
shell POSIX
SYNOPSIS
#include <wordexp.h>
int wordexp(const char *s, wordexp_t *p, int flags);
void wordfree(wordexp_t *p);
Exigences de macros de test de fonctionnalités pour la glibc (voir
feature_test_macros(7)) :
wordexp(), wordfree() : _XOPEN_SOURCE
La fonction wordexp() effectue une expansion de type shell de la chaîne
s et retourne le résultat dans la structure pointée par p. Le type de
données wordexp_t est une structure qui possède au moins les membres
we_wordc, we_wordv, et we_offs. Le membre we_wordc est de type size_t
et donne le nombre de mots dans l’expansion de s. Le membre we_wordv
est de type char ** et pointe sur le tableau des mots trouvés. Le
membre we_offs de type size_t est quelquefois (suivant flags, voir plus
loin) utilisé pour indiquer le nombre d’éléments du tableau we_wordv
qui devraient être remplis initialement avec le caractère NULL.
La fonction wordfree() libère la mémoire nouvellement allouée. Plus
précisément, elle ne libère pas son argument mais libère le tableau
we_wordv ainsi que les chaînes vers lesquelles il pointe.
L’argument chaîne
Puisque l’expansion est effectuée de la même manière que le shell (voir
sh(1)) sur les paramètres d’une commande, la chaîne s ne doit pas
contenir de caractères qui seraient illégaux dans les paramètres d’une
commande shell. En particulier, il ne doit pas y avoir de caractères
nouvelle ligne ou |, &, ;, <, >, (, ), {, } non protégés en dehors d’un
contexte de substitution de commande ou de paramètre.
Si l’argument s contient un mot qui débute par un caractère de
commentaires « # » hors de tous guillemets, il n’est pas spécifié si ce
mot et les suivants sont ignorés, ou si le # est considéré comme un
caractère normal.
L’expansion
L’expansion effectuée consiste en les étapes suivantes : expansion du
caractère tilde (remplacement de ~utilisateur par le répertoire
personnel de l’utilisateur), substitution de variable (remplacement de
$FOO par la valeur de la variable d’environnement FOO), substitution de
commande (remplacement de $(commande) ou `commande` par la sortie de la
commande), expansion arithmétique, découpage de champs, expansion des
caractères de remplacement (wildcard), suppression des caractères de
citation (quotes).
Le résultat de l’expansion de caractères spéciaux ($@, $*, $#, $?, $-,
$$, $!, $0) n’est pas spécifié.
Le découpage des champs est effectué en utilisant la variable
d’environnement $IFS. Si elle n’est pas positionnée, les séparateurs de
champs sont l’espace, la tabulation et le caractère nouvelle ligne.
Le tableau de sortie
Le tableau we_wordv contient les mots trouvés, suivi par le caractère
NULL.
L’argument flags
L’argument flag est un OU inclusif bit à bit des valeurs suivantes :
WRDE_APPEND
Ajouter les mots trouvés au tableau résultant d’un précédent
appel.
WRDE_DOOFFS
Insérer we_offs caractères initiaux NULL dans le tableau
we_wordv (ils ne seront pas comptés dans le membre we_wordc
retourné).
WRDE_NOCMD
Ne pas effectuer la substitution de commande.
WRDE_REUSE
Le paramètre p résulte d’un précédent appel à wordexp(), et
wordfree() n’a pas été appelé. Réutiliser l’espace de stockage
alloué.
WRDE_SHOWERR
Normalement, lors d’une substitution de commande, stderr est
redirigée vers /dev/null. Ce drapeau spécifie que stderr ne sera
pas redirigé.
WRDE_UNDEF
Considérer comme une erreur le fait qu’une variable shell non
définie soit développée.
VALEUR RENVOYÉE
Si elle réussit, la fonction renvoie 0. Si elle échoue, elle renvoie
l’une des cinq valeurs suivantes :
WRDE_BADCHAR
Occurrence illégale d’un caractère nouvelle ligne ou d’un
caractère parmi |, &, ;, <, >, (, ), {, }.
WRDE_BADVAL
Il y a une référence à une variable shell non définie, et le
drapeau WRDE_UNDEF nous demande de considérer que c’est une
erreur.
WRDE_CMDSUB
Une substitution de commande est apparue, et le drapeau
WRDE_NOCMD nous demande de considérer que c’est une erreur.
WRDE_NOSPACE
Plus de mémoire disponible.
WRDE_SYNTAX
Erreur de syntaxe shell, comme des parenthèses ou des guillemets
non appariés.
VERSIONS
wordexp() et wordfree() sont fournies par la glibc depuis la
version 2.1.
CONFORMITÉ
POSIX.1-2001.
EXEMPLE
La sortie du programme d’exemple suivant est approximativement celle de
«ls [a-c]*.c ».
#include <stdio.h>
#include <stdlib.h>
#include <wordexp.h>
int
main(int argc, char **argv)
{
wordexp_t p;
char **w;
int i;
wordexp("[a-c]*.c", &p, 0);
w = p.we_wordv;
for (i = 0; i < p.we_wordc; i++)
printf("%s\n", w[i]);
wordfree(&p);
exit(EXIT_SUCCESS);
}
VOIR AUSSI
fnmatch(3), glob(3)
COLOPHON
Cette page fait partie de la publication 3.23 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/.
TRADUCTION
Cette page de manuel a été traduite et mise à jour par Alain Portal
<aportal AT univ-montp2 DOT fr> entre 2004 et 2006, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Nicolas François
<nicolas.francois@centraliens.net> et l’équipe francophone de
traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document
en utilisant la commande « man -L C <section> <page_de_man> ».
14 juillet 2008 WORDEXP(3)