stdarg(3) Library Functions Manual stdarg(3)
NOM
stdarg, va_start, va_arg, va_end, va_copy - Liste variable d'arguments
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
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 « varia-
dique ». 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 dernier est le nom du dernier paramètre avant la liste va-
riable de paramètres, c'est-à-dire le dernier paramètre dont la fonc-
tion 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 dernier. Les invocations successives ren-
voient 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 imprévisibles se
produiront.
Si ap est passé à une fonction qui utilise va_arg(ap,type) alors la va-
leur 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 dernier, suivi
du même nombre d'invocations de va_arg() qui seraient 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 re-
gistres, 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 pa-
ramè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
Pour une explication des termes utilisés dans cette section, consulter
attributes(7).
┌─────────────────────────────┬──────────────────────┬─────────────────┐
│Interface │ Attribut │ Valeur │
├─────────────────────────────┼──────────────────────┼─────────────────┤
│va_start(), va_end(), │ Sécurité des threads │ MT-Safe │
│va_copy() │ │ │
├─────────────────────────────┼──────────────────────┼─────────────────┤
│va_arg() │ Sécurité des threads │ MT-Safe race:ap │
└─────────────────────────────┴──────────────────────┴─────────────────┘
STANDARDS
C99.
BOGUES
Contrairement aux macros varargs() historiques, les macros stdarg() ne
permettent pas aux programmeurs de coder une fonction sans aucun argu-
ment fixe. Ce problème se pose principalement en convertissant directe-
ment du code utilisant varargs() en code utilisant stdarg(), mais il se
pose également pour les fonctions qui désirent passer tous leurs argu-
ments à une fonction utilisant un argument va_list telle que vf-
printf(3).
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, ...) /* '...' 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 française de cette page de manuel a été créée par Chris-
tophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <ste-
phan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, Fran-
çois Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Gué-
rard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.cou-
lon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centra-
liens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <si-
mon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@de-
bian.org>, David Prévot <david@tilapin.org>, Cédric Boutillier <ce-
dric.boutillier@gmail.com>, Frédéric Hantrais <fhantrais@gmail.com> et
Grégoire Scano <gregoire.scano@malloc.fr>
Cette traduction est une documentation libre ; veuillez vous reporter à
la GNU General Public License version 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ concernant les conditions
de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel,
veuillez envoyer un message à ⟨debian-l10n-french@lists.debian.org⟩.
Pages du manuel de Linux 6.03 5 février 2023 stdarg(3)
Generated by dwww version 1.15 on Sat Jun 29 00:27:33 CEST 2024.