varargs(5) varargs(5)
NAME [Toc] [Back]
varargs - handle variable argument list
SYNOPSIS [Toc] [Back]
#include <varargs.h>
va_alist
va_dcl
void va_start(pvar)
va_list pvar;
type va_arg(pvar, type)
va_list pvar;
void va_end(pvar)
va_list pvar;
DESCRIPTION [Toc] [Back]
This set of macros enables programmers to write portable procedures
that accept variable argument lists. Routines that have variable
argument lists (such as printf()) but do not use varargs are
inherently nonportable, because different machines use different
argument-passing conventions (see printf(3S)).
va_alist is used as the parameter list in a function header.
va_dcl is a declaration for va_alist. No semicolon should follow
va_dcl.
va_list is a type defined for the variable used to traverse the list.
va_start is called to initialize pvar to the beginning of the list.
The type of argN should be the same as the argument to the function
just before the variable portion of the argument list.
va_arg returns the next argument in the list pointed to by pvar. type
is the type the argument is expected to be. Different types can be
mixed, but it is up to the routine to know what type of argument is
expected, because it cannot be determined at runtime.
va_end is used to clean up.
Multiple traversals, each bracketed by va_start ... va_end, are
possible.
NOTE: The <varargs.h> header file is provided for compatibility with
pre-ANSI compilers and earlier releases of HP C/HP-UX. It is
superceded by <stdarg.h> which includes all of the varargs macros.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
varargs(5) varargs(5)
EXAMPLE [Toc] [Back]
The following example shows a possible implementation of execl() (see
exec(2)):
#include <varargs.h>
#define MAXARGS 100
/* execl is called by
execl(file, arg1, arg2, ..., (char *)0);
*/
execl(va_alist)
va_dcl
{
va_list ap;
char *file;
char *args[MAXARGS];
int argno = 0;
va_start(ap);
file = va_arg(ap, char *);
while ((args[argno++] = va_arg(ap, char *)) != (char *)0);
va_end(ap);
return execv(file, args);
}
The next example illustrates how a function that receives variable
arguments can pass these arguments down to other functions. To
accomplish this, the first routine (log_errors() in this example)
which receives the variable argument list must pass the address
pointer resulting from a call to va_start() on to any subsequent calls
that need to access this same variable argument list. All routines
that receive this address pointer (v_print_log() in this example) need
only to use va_arg() to access the original variable argument list
just as if they were the original routine to be passed the variable
arguments.
In this example, one can imagine that there are a series of other
routines (such as a log_warning() and log_message()) that also call
the v_print_log() function.
#include <stdio.h>
#include <varargs.h>
#include <unistd.h>
int error_count;
/* VARARGS4 -- for lint */
int
log_errors(log_fp, func_name, err_num, msg_fmt, va_alist)
FILE *log_fp;
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
varargs(5) varargs(5)
char *func_name;
int err_num;
char *msg_fmt;
va_dcl
{
va_list ap;
/* Print error header information */
(void) fprintf(log_fp, "\nERROR in process %d\n", getpid());
(void) fprintf(log_fp, " function \"%s\": ", func_name);
switch(err_num)
{
case ILLEGAL_OPTION:
(void) fprintf(log_fp, "illegal option\n");
break;
case CANNOT_PARSE:
(void) fprintf(log_fp, "cannot parse input file\n");
break;
...
}
/*
* Get pointer to first variable argument so that we can
* pass it on to v_print_log(). We do this so that
* v_print_log() can access the variable arguments passed
* to this routine.
*/
va_start(ap);
v_print_log(log_fp, msg_fmt, ap);
va_end(ap);
}
/* VARARGS2 -- for lint */
int
v_print_log(log_fp, fmt, ap)
FILE *log_fp;
char *fmt;
va_list ap;
{
/*
* If "%Y" is the first two characters in the format string,
* a second file pointer has been passed in to print general
* message information to. The rest of the format string is
* a standard printf(3S) format string.
*/
if ((*fmt == '%') && (*(fmt + 1) == 'Y'))
{
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
varargs(5) varargs(5)
FILE *other_fp;
fmt += 2;
other_fp = (FILE *) va_arg(ap, char *);
if (other_fp != (FILE *) NULL)
{
/*
* Print general message information to additional stream.
*/
(void) vfprintf(other_fp, fmt, ap);
(void) fflush(other_fp);
}
}
/*
* Now print it to the log file.
*/
(void) vfprintf(log_fp, fmt, ap);
}
WARNINGS [Toc] [Back]
It is up to the calling routine to specify how many arguments there
are, because it is not always possible to determine this from the
stack frame. For example, execl() is passed a zero pointer to signal
the end of the list. printf() can determine how many arguments are
present by the format.
It is non-portable to specify a second argument of char, short, or
float to va_arg, because arguments seen by the called function are not
char, short, or float. C converts char and short arguments to int,
and converts float arguments to double, before passing them to a
function.
SEE ALSO [Toc] [Back]
exec(2), vprintf(3S), stdarg(5).
STANDARDS CONFORMANCE [Toc] [Back]
va_alist: AES, SVID2, SVID3, XPG2, XPG3, XPG4
va_arg: SVID2, SVID3, XPG2, XPG3, XPG4
va_dcl: SVID2, SVID3, XPG2, XPG3, XPG4
va_end: SVID2, SVID3, XPG2, XPG3, XPG4
va_list: SVID2, SVID3, XPG2, XPG3, XPG4
va_start: SVID2, SVID3, XPG2, XPG3, XPG4
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
varargs(5) varargs(5)
<varargs.h>: AES, SVID3, XPG2, XPG3, XPG4
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003 [ Back ] |
