STDARG(3) Manuel du programmeur Linux STDARG(3)
stdarg, va_start, va_arg, va_end, va_copy - Liste variable d’arguments.
#include <stdarg.h>
void va_start(va_list ap, last);
type va_arg(va_list ap, type);
void va_end(va_list ap);
void va_copy(va_list dest, va_list src);
Une fonction peut être appelée avec un nombre variable d’arguments,
eux-mêmes de types variables. Une telle fonction est dite « vari‐
adique». Le fichier d’en-tête <stdarg.h> déclare un type va_list et
définit trois macros permettant de parcourir la liste d’arguments dont
le nombre et les types ne sont pas connus par la fonction appelée.
La fonction appelée doit déclarer un objet de type va_list utilisé
par les macros va_start(), va_arg() et va_end().
va_start()
La macro va_start() initialise ap pour les utilisations ultérieures de
va_arg() et va_end(), et doit donc être appelée en premier.
Le paramètre last est le nom du dernier paramètre avant la liste
variable de paramètres, c’est-Ã-dire le dernier paramètre dont la
fonction connaisse le type.
Comme l’adresse de ce paramètre est utilisée dans la macro
va_start(), il ne doit pas être déclaré comme une variable en reg‐
istre, ni comme un type fonction ou tableau.
va_arg()
La macro va_arg() se développe en une expression qui a le type et la
valeur de l’argument suivant de l’appel. Le paramètre ap est la
va_list ap initialisée par va_start(). Chaque appel de va_arg() modi‐
fie ap pour que l’appel suivant renvoie le paramètre suivant. Le
paramètre type est le nom du type, indiqué de telle manière qu’un
pointeur sur un objet de ce type puisse être déclaré simplement en
ajoutant un astérisque à type.
La première utilisation de la macro va_arg() après celle de
va_start() renvoie l’argument suivant last. Les invocations successives
renvoient les valeurs des arguments restants.
S’il n’y a pas d’argument suivant, ou si type n’est pas compatible avec
le type réel du prochain argument, des erreurs imprévisibles se pro‐
duiront.
Si ap est passé à une fonction qui utilise va_arg(ap,type) alors la
valeur de ap est indéfinie après le retour de cette fonction.
va_end()
haque invo ation de va_start() doit orrespondre une invo
Ãva_end() dans la même fonction. Après l’appel va_end(ap) la variable
ap est indéfinie. Plusieurs traversées de la liste sont possibles, Ã
condition que chacune soit encadrée par va_start() et va_end().
va_end() peut être une macro ou une fonction.
va_copy()
Une implémentation évidente est de représenter va_list par un poin‐
teur dans la pile de la fonction variadique. Dans une telle situation
(de loin la plus courante), rien ne semble s’opposer à une affectation
va_list aq = ap;
Malheureusement, il y a aussi des systèmes qui créent une table de
pointeurs (de longueur 1), et on devrait écrire
va_list aq;
*aq = *ap;
De plus, sur les systèmes où les paramètres sont passés dans des
registres, il peut être nécessaire pour va_start() d’allouer de la
mémoire, d’y enregistrer les paramètres ainsi que l’indication du
paramètre suivant, afin que va_arg() puisse balayer la liste. Ainsi
va_end() pourra libérer la mémoire allouée. Pour gérer ces situa‐
tions, C99 ajoute une macro va_copy(), afin que les affectations
ci-dessus soient remplacées par
va_list aq;
va_copy(aq, ap);
...
va_end(aq);
haque invo ation de va_ opy() doit
Ãva_end() dans la même fonction. Certains systèmes qui ne disposent
pas de va_copy() ont une macro __va_copy() à la place, puisque c’était
le nom proposé auparavant.
Les macros va_start(), va_arg() et va_end() sont conformes à C89. C99
définit la macro va_copy().
Ces macros ne sont pas compatibles avec les anciennes macros qu’elles
remplacent. Une compatibilité de version peut être obtenue en inclu‐
ant le fichier d’en-tête <varargs.h>.
La mise en oeuvre historique est :
#include <varargs.h>
void
foo(va_alist)
va_dcl
{
va_list ap;
va_start(ap);
while (...) {
...
x = va_arg(ap, type);
...
}
va_end(ap);
}
Sur certains systèmes, va_end() contient une accolade fermante « } »
correspondant à l’accolade ouvrante « { » dans va_start(), ainsi les
deux macros doivent se trouver dans la même fonction, placées d’une
manière qui permette ceci.
Contrairement aux macros varargs(), les macros stdarg() ne permettent
pas aux programmeurs de coder une fonction sans aucun argument fixe. Ce
problème se pose principalement en convertissant directement du code
utilisant varargs() en code utilisant stdarg(), mais il se pose égale‐
ment pour les fonctions qui désirent passer tous leurs arguments à une
fonction utilisant un argument va_list comme vfprintf(3).
La fonction foo() prend une chaîne de caractères de mise en forme, et
affiche les arguments associés avec chaque format correspondant au
type indiqué.
#include <stdio.h>
#include <stdarg.h>
void
foo(char *fmt, ...)
{
va_list ap;
int d;
char c, *s;
va_start(ap, fmt);
while (*fmt)
switch (*fmt ++) {
case 's': /* chaîne */
s = va_arg (ap, char *);
printf("chaîne %s\n", s);
break;
case 'd': /* entier */
d = va_arg (ap, int);
printf("int %d\n", d);
break;
case 'c': /* caractère */
c = va_arg (ap, char);
printf("char %c\n", c);
break;
}
va_end(ap);
}
Cette page fait partie de la publication 3.07 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse http://www.ker‐
nel.org/doc/man-pages/.
Cette page de manuel a été traduite et mise à jour par Christophe
Blaess <http://www.blaess.fr/christophe/>; entre 1996 et 2003, puis par
Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 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@cen‐
traliens.net> et l’équipe francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant Ã
<debian-l10n-french [AT] lists.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 octobre 2001 STDARG(3)