Provided by: manpages-fr-dev_3.57d1p1-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 ê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 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 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 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 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()
À 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 possibles, à condition que chacune soit encadrée par va_start() et
va_end(). va_end() peut être une macro ou une fonction.
va_copy()
La macro va_copy() copie la liste d'arguments variables (précédemment initialisés) src
vers dest. Le comportement serait similaire si va_start() était appliqué à dest avec le
même argument last, suivi du même nombre d'invocations de va_arg() qui ont été utilisées
pour atteindre l'état actuel de src.
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é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 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);
À 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.
ATTRIBUTS
Multithreading (voir pthreads(7)) Les macros va_start(), va_arg(), va_end() et va_copy() sont sûres dans un contexte multithread.
CONFORMITÉ
Les macros va_start(), va_arg() et va_end() sont conformes à C89. C99 définit la macro
va_copy().
NOTES
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>.
La mise en œuvre 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 problème 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).
EXEMPLE
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);
}
COLOPHON
Cette page fait partie de la publication 3.57 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
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a
<http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet
perkamon <http://perkamon.alioth.debian.org/>.
Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain Portal
<http://manpagesfr.free.fr/> (2003-2006). Nicolas François et l'équipe francophone de
traduction de Debian (2006-2009).
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> ».
10 décembre 2013 STDARG(3)