Provided by:
manpages-fr_1.67.0-1_all 
NOM
stdarg, va_start, va_arg, va_copy, va_end - Liste variable d’arguments.
SYNOPSIS
#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);
DESCRIPTION
Une fonction peut être appelée avec un nombre variable d’arguments,
eux-mêmes de types variables. Une telle fonction est dite "variadique".
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
d’argument variable, 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 registre, 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 modifie ap pour
que l’appel suivant renvoie l’argument 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 renvient
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
produiront.
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
A chaque invocation de va_start doit correspondre une invocation de
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 possible, à
condition que chacune soit encadrée par va_start et va_end. va_end
peut être une macro ou ue fonction.
va_copy
Une implémentation évidente est de représenter va_list par un pointeur
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é 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 situations,
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);
A chaque invocation de va_copy doit correspondre une invocation de
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.
EXEMPLES
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, *p, *s;
va_start (ap, fmt);
while (*fmt)
switch (*fmt ++) {
case ’s’: /* chaîne */
s = va_arg (ap, char *);
printf ("chaine %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);
}
CONFORMITÉ
Les macros va_start, va_arg, et va_end sont conformes à ANSI
X3.159-1989 ("C89"). C99 définit la macro va_copy.
COMPATIBILITÉ
Ces macros ne sont PAS compatibles avec les anciennes macros qu’elles
remplacent. Une compatibilité de version peut être obtenue en incluant
le fichier d’en-tête varargs.h.
COMPARAISON
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.
BOGUES
Contrairement aux macros varargs, les macros stdarg ne permettent pas
aux programmeurs de coder une fonction sans aucun argument fixe. Ce
probleme se pose principalement en convertissant directement du code
utilisant varargs en code utilisant stdarg, mais il se pose également
pour les fonctions qui désirent passer tous leurs arguments à une
fonction utilisant un argument va_list comme vfprintf(3).
TRADUCTION
Christophe Blaess, 1996-2003.