stdarg(3) Library Functions Manual stdarg(3) NOM stdarg, va_start, va_arg, va_end, va_copy - Liste variable d'arguments BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include 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 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 dernier 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 dernier. 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 du prochain argument effectif, 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() La macro va_copy() copie la liste d'arguments variables (precedemment initialises) src vers dest. Le comportement serait similaire si va_start() etait applique a dest avec le meme argument dernier, suivi du meme nombre d'invocations de va_arg() qui seraient utilisees pour atteindre l'etat actuel de src. 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. ATTRIBUTS Pour une explication des termes utilises dans cette section, consulter attributes(7). +-------------------------+--------------------------+-----------------+ |Interface | Attribut | Valeur | +-------------------------+--------------------------+-----------------+ |va_start(), va_end(), | Securite des threads | MT-Safe | |va_copy() | | | +-------------------------+--------------------------+-----------------+ |va_arg() | Securite des threads | MT-Safe race:ap | +-------------------------+--------------------------+-----------------+ STANDARDS C11, POSIX.1-2008. HISTORIQUE va_start() va_arg() va_end() C89, POSIX.1-2001. va_copy() C99, POSIX.1-2001. CAVEATS Contrairement aux macros varargs() historiques, 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 telle que vfprintf(3). EXEMPLES 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 #include void foo(char *fmt, ...) /* '...' is C syntax for a variadic function */ { va_list ap; int d; char c; char *s; va_start(ap, fmt); while (*fmt) switch (*fmt++) { case 's': /* string */ s = va_arg(ap, char *); printf("string %s\n", s); break; case 'd': /* int */ d = va_arg(ap, int); printf("int %d\n", d); break; case 'c': /* char */ /* need a cast here since va_arg only takes fully promoted types */ c = (char) va_arg(ap, int); printf("char %c\n", c); break; } va_end(ap); } VOIR AUSSI vprintf(3), vscanf(3), vsyslog(3) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot , Cedric Boutillier , Frederic Hantrais et Gregoire Scano Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 stdarg(3)