Provided by:
manpages-fr-dev_3.27fr1.4-1_all 
NOM
stdarg, va_start, va_arg, va_end, va_copy - 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 etre appelee avec un nombre variable d'arguments,
eux-memes de types variables. Une telle fonction est dite
<< variadique >>. Le fichier d'en-tete <stdarg.h> declare un type
va_list et definit trois macros permettant de parcourir la liste
d'arguments dont le nombre et les types ne sont pas connus par la
fonction appelee.
La fonction appelee doit declarer un objet de type va_list utilise par
les macros va_start(), va_arg() et va_end().
va_start()
La macro va_start() initialise ap pour les utilisations ulterieures de
va_arg() et va_end(), et doit donc etre appelee en premier.
Le parametre last est le nom du dernier parametre avant la liste
variable de parametres, c'est-a-dire le dernier parametre dont la
fonction connaisse le type.
Comme l'adresse de ce parametre est utilisee dans la macro va_start(),
il ne doit pas etre declare comme une variable en registre, ni comme un
type fonction ou tableau.
va_arg()
La macro va_arg() se developpe en une expression qui a le type et la
valeur de l'argument suivant de l'appel. Le parametre ap est la va_list
ap initialisee par va_start(). Chaque appel de va_arg() modifie ap pour
que l'appel suivant renvoie le parametre suivant. Le parametre type est
le nom du type, indique de telle maniere qu'un pointeur sur un objet de
ce type puisse etre declare simplement en ajoutant un asterisque a
type.
La premiere utilisation de la macro va_arg() apres 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 reel du prochain argument, des erreurs imprevisibles se
produiront.
Si ap est passe a une fonction qui utilise va_arg(ap,type) alors la
valeur de ap est indefinie apres le retour de cette fonction.
va_end()
A chaque invocation de va_start() doit correspondre une invocation de
va_end() dans la meme fonction. Apres l'appel va_end(ap) la variable ap
est indefinie. Plusieurs traversees de la liste sont possibles, a
condition que chacune soit encadree par va_start() et va_end().
va_end() peut etre une macro ou une fonction.
va_copy()
Une implementation evidente est de representer 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 a une affectation
va_list aq = ap;
Malheureusement, il y a aussi des systemes qui creent une table de
pointeurs (de longueur 1), et on devrait ecrire
va_list aq;
*aq = *ap;
De plus, sur les systemes ou les parametres sont passes dans des
registres, il peut etre necessaire pour va_start() d'allouer de la
memoire, d'y enregistrer les parametres ainsi que l'indication du
parametre suivant, afin que va_arg() puisse balayer la liste. Ainsi
va_end() pourra liberer la memoire allouee. Pour gerer ces situations,
C99 ajoute une macro va_copy(), afin que les affectations ci-dessus
soient remplacees 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 meme fonction. Certains systemes qui ne disposent pas
de va_copy() ont une macro __va_copy() a la place, puisque c'etait le
nom propose auparavant.
CONFORMIT'E
Les macros va_start(), va_arg() et va_end() sont conformes a C89. C99
definit la macro va_copy().
NOTES
Ces macros ne sont pas compatibles avec les anciennes macros qu'elles
remplacent. Une compatibilite de version peut etre obtenue en incluant
le fichier d'en-tete <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 systemes, va_end() contient une accolade fermante << } >>
correspondant a l'accolade ouvrante << { >> dans va_start(), ainsi les
deux macros doivent se trouver dans la meme fonction, placees d'une
maniere 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
egalement pour les fonctions qui desirent passer tous leurs arguments a
une fonction utilisant un argument va_list comme vfprintf(3).
EXEMPLE
La fonction foo() prend une chaine de caracteres de mise en forme, et
affiche les arguments associes avec chaque format correspondant au type
indique.
#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': /* chaine */
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': /* caractere */
c = va_arg (ap, char);
printf("char %c\n", c);
break;
}
va_end(ap);
}
COLOPHON
Cette page fait partie de la publication 3.27 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent etre trouvees a l'adresse
<URL:http://www.kernel.org/doc/man-pages/>.
TRADUCTION
Depuis 2010, cette traduction est maintenue a l'aide de l'outil po4a
<URL:http://po4a.alioth.debian.org/> par l'equipe de traduction
francophone au sein du projet perkamon
<URL:http://perkamon.alioth.debian.org/>.
Christophe Blaess <URL:http://www.blaess.fr/christophe/> (1996-2003),
Alain Portal <URL:http://manpagesfr.free.fr/> (2003-2006). Nicolas
Francois et l'equipe francophone de traduction de Debian (2006-2009).
Veuillez signaler toute erreur de traduction en ecrivant a
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir acces a la version anglaise de ce document
en utilisant la commande << man -L C <section> <page_de_man> >>.
14 octobre 2001 STDARG(3)