STDARG(3)

BEZEICHNUNG
stdarg - variable Argument-Listen

ÜBERSICHT
#include <stdarg.h>

void va_start( va_list ap, last);
type va_arg( va_list ap, type);
void va_end( va_list ap);

BESCHREIBUNG
Eine Funktion darf mit einer veränderlchen Anzahl von Argumenten veränderlichen Typs aufgerufen werden. Die Include-Datei stdarg.h deklariert einen Typ va_list und definiert drei Makros, um eine Liste vor Argumenten durchzugehen, deren Anzahl und Typen der aufgerufenen Funktion unbekannt sind.

Die aufgerufene Funktion muss ein Objekt des Typs va_list deklarieren, welches von den Makros va_start, va_arg, und va_end benutzt wird.

Das Makro va_start initialisiert ap für spätere Benutzung durch va_arg und va_end, und muss zuerst aufgerufen werden.

Der Parameter last ist der Name des letzten Parameters vor der Liste der veränderlichen Argumente, d.h. der letzte Parameter, dessen Typ die aufrufende Funktion kennt.

Da die Adresse dieses Parameters in dem Makro va_start benutzt wird sollte er nicht als eine Registervariable, als Funktion oder Array-Typ deklariert sein.

Das Makro va_start liefert keinen Wert zurück.

Das Makro va_arg expandiert zu einem Ausdruck, der den Typ und Wert des nächsten aufzurufenden Argumentes hat. Der Parameter ap ist va_list ap initialisiert durch va_start. Jeder Aufruf von va_arg verändert ap so dass der nächste Aufruf das nächste Argument zurückliefert. Der Parameter type ist ein Typenname, der so angegeben ist, dass der Typ eines Pointers auf ein Objekt, das den angegebenen Typ hat, durch Hinzufügen eines * zu type erhalten werden kann.

Wenn es kein weiteres Argument gibt, oder wenn type nicht kompatibel mit dem Typ des nächsten Argumentes ist, erscheinen zufällige Fehler.

Die erste Benutzung des Makros va_arg nach va_start liefert das Argument nach last zurück. Folgende Aufrufe geben die Werte der verbleibenden Argumente zurück.

Das Makro va_end ermöglicht eine normale Rückkehr aus der Funktion dessen variable Argumentliste durch va_start initialisiert wurde.

Das Makro va_end liefert keinen Wert zurück.

BEISPIELE
Die Funktion foo nimmt einem String von Format-Zeichen und gibt das Argument aus, das mit jedem Format-Zeichen in Zusammenhang gebracht wird, basierend auf dem Typ.
    void foo(char *fmt, ...)
    {
    	va_list ap;
    	int d;
    	char c, *p, *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 */
    			c = va_arg(ap, char);
    			printf("char %c\n", c);
    			break;
    		}
    	va_end(ap);
    }

STANDARDS
Die Makros va_start, va_arg, und va_end sind konform zu ANSI C3.159-1989 (``ANSI C'').

KOMPATIBILITÄT
Diese Makros sind not kompatibel mit den historischen Makros, die sie ersetzen. Eine abwärtskompatible Version kann in der Includedatei varargs.h gefunden werden.

BUGS
Im Gegensatz zu den Makros varargs erlauben die Makros stdarg dem Programmierer nicht, eine Funktion ohne feste Argumente zu implementieren. Dieses Problem macht hauptsächlich Arbeit wenn man Code mit varargs nach stdarg konvertiert, aber es erzeugt auch Schwierigkeiten bei veränderlichen Funktionen die wünschen, ihre Argumente an eine Funktion weiterzugeben, die ein Argument va_list nimmt, wie vfprintf(3).