Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > V

varargs(5)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

varargs — handle variable argument list

SYNOPSIS

#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

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.

EXAMPLE

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; 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')) { 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

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.

STANDARDS CONFORMANCE

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

<varargs.h>: AES, SVID3, XPG2, XPG3, XPG4

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.