wordexp, wordfree - Effectuer l'expansion de mots à la manière
d'un shell POSIX
Bibliothèque C standard (
libc,
-lc)
#include <wordexp.h>
int wordexp(const char *restrict s, wordexp_t *restrict p, int flags);
void wordfree(wordexp_t *p);
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.
Puisque l'expansion est effectuée de la même manière que le
shell (consultez
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 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
we_wordv contient les mots trouvés, suivis par le
caractère NULL.
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. Cet attribut
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.
En cas de succès,
wordexp() renvoie
0. En cas
d'échec,
wordexp() une des valeurs suivantes différentes
de zéro :
- 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 l'attribut WRDE_UNDEF nous demande de
considérer que c'est une erreur.
- WRDE_CMDSUB
- Une substitution de commande est requise, lais l'attribut
WRDE_NOCMD nous demande de considérer que c'est une
erreur.
- WRDE_NOSPACE
- Plus assez de mémoire.
- WRDE_SYNTAX
- Erreur de syntaxe shell, comme des parenthèses ou
des guillemets non appariés.
wordexp() et
wordfree() sont fournies depuis la glibc 2.1.
Pour une explication des termes utilisés dans cette section, consulter
attributes(7).
| Interface |
Attribut |
Valeur |
|
wordexp() |
Sécurité des threads |
MT-Unsafe race:utent const:env env sig:ALRM timer locale |
|
wordfree() |
Sécurité des threads |
MT-Safe |
Dans le tableau ci-dessus,
utent dans
race:utent signifie que si
unedes fonctions
setutent(3),
getutent(3) ou
endutent(3)
est utilisée en parallèle dans différents threads d'un
programme, des conditions de compétition de données peuvent
survenir.
wordexp() appelle ces fonctions, aussi race:utent est
utilisé pour le rappeler aux utilisateurs.
POSIX.1-2001, POSIX.1-2008.
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(void)
{
wordexp_t p;
char **w;
wordexp("[a-c]*.c", &p, 0);
w = p.we_wordv;
for (size_t i = 0; i < p.we_wordc; i++)
printf("%s\n", w[i]);
wordfree(&p);
exit(EXIT_SUCCESS);
}
fnmatch(3),
glob(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
<
[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]>,
Frédéric Hantrais <
[email protected]> et Jean-Pierre
Giraud <
[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]