STDARG(3)

NOME
stdarg - listas variáveis de argumentos

SINÓPSE
#include <stdarg.h>

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

DESCRIÇÃO
Uma função pode ser chamada com um número variado de argumentos de tipos variados. O arquivo include stdarg.h declara um tipo va_list e define três macros para caminhar através de uma lista de argumentos cujo número e tipo são desconhecidos pela função chamada.

A função chamada deve declarar um objeto do tipo va_list o qual é usado pelas macros va_start, va_arg, e va_end.

A macro va_start inicializa ap para uso subsequente por va_arg e va_end, e deve ser chamada primeiro.

O parâmetro last é o nome do último parâmetro antes da lista de argumentos variável, i.e., o último parâmetro do qual a função chamada conhece o tipo.

Por causa do endereço desse parâmetro, é usada na macro va_start, ela não deve ser declarada como uma variável de registro ou como um tipo de função ou matriz.

A macro va_start não retorna valor algum.

A macro va_arg expande para uma expressão que possui o tipo e valor do próximo argumento na chamada. O parâmetro ap é va_list ap inicializado po va_start. Cada chamada a va_arg modifica ap de modo que a chamada seguinte retorna o argumento seguinte. O parâmetro type é um nome de tipo especificado de maneira que o tipo de ponteiro para um objeto que possui o tipo especificado possa ser obtido simplesmente adicionando-se um * a type.

Se não houver um argumento seguinte ou se type não é compatível com o tipo do argumento seguinte real (promovido de acordo com as promoções padrão de argumentos), erros aleatórios ocorrerão.

O primeiro uso da macro va_arg após o da macro va_start retorna o argumento após last. Invocações sucessivas retornam os valores dos argumentos restantes.

A macro va_end manipula um retorno normal da função cuja lista variável de argumentos foi inicializada por va_start.

A macro va_end não retorna valor algum.

EXEMPLOS
A função foo pega uma cadeia de formato caracteres e imprime o argumento associado com cada caracter de formato baseada no tipo.
    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 */
    		        /* 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);
    }

DE ACORDO COM
A macros va_start, va_arg, e va_end estão em conformidade com ANSI X3.159-1989 ('ANSI C').

COMPATIBILIDADE
Estas macros não são compatíveis com as macros históricas que elas substituem. Uma versão para compatibilidade anterior porde ser encontrada no arquivo 'include' varargs.h.

PROBLEMAS
Diferentemente das macros varargs, as macros stdarg não permitem que os programadores codifiquem uma função sem argumentos fixados. Este problema dá trabalho principalmente quando se converte código varargs para código stdarg, mas isto também cria dificuldades para funções 'variadic' que desejam passar seus argumentos para uma função que aceita um argumento va_list, tal como vfprintf(3).

TRADUZIDO POR LDP-BR EM 05/07/2001.

  Tradução:
Valter Ferraz Sanches <vfs@ezlinux.cjb.net>

  Revisão.:
André Luiz Fassone <lonely_wolf@ig.com.br>