Fonctions
des bibliothèques (section 3) stdarg
Nom
stdarg - 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);
Description
Une fonction peut être appelée avec un nombre variable d'arguments, eux-mêmes de types variables. 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.Le fonction appelée doit déclarer un objet de type va_list utilisé par les macros va_start, va_arg, et va_end.
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.
La macro va_start ne renvoie pas de valeur.
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.
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.
La première utilisation de la macro va_arg après va_start renvoie l'argument suivant last. Les invoquations successives renvoient les valeurs des arguments restants.
La macro va_end déclenche un retour normal de la fonction dont la liste variable d'arguments a été initalisée par va_start.
La macro va_end ne renvoie pas de valeur.
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é.
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 (``ANSI C'').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.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, 1997.