NAME

vprintf, vfprintf, vsprintf − print formatted output of a variable argument list

SYNOPSIS

#include <stdio.h>
#include <stdarg.h>

int vprintf(const char ∗format, va_list ap);

int vfprintf(FILE ∗stream, const char ∗format, va_list ap);

int vsprintf(char ∗s, const char ∗format, va_list ap);

MT-LEVEL

See the NOTES section of this page. 

DESCRIPTION

vprintf, vfprintf, vsprintf − vprintf(), vfprintf(), and vsprintf() are the same as printf(), fprintf(), and sprintf() respectively, except that instead of being called with a variable number of arguments, they are called with an argument list as defined by the <stdarg.h> header. 

The <stdarg.h> header defines the type va_list and a set of macros for advancing through a list of arguments whose number and types may vary.  The argument ap to the vprint family of routines is of type va_list.  This argument is used with the <stdarg.h> header file macros va_start(), va_arg(), and va_end() (see stdarg(5)).  The EXAMPLE section below shows their use with vprintf(). 

The macro va_alist is used as the parameter list in a function definition, as in the function called error() in the example below.  The macro va_start(ap, parmN), where ap is of type va_list, and parmN is the rightmost parameter (just before ...), must be called before any attempt to traverse and access unnamed arguments is made. Calls to va_arg(ap, atype) traverse the argument list.  Each execution of va_arg() expands to an expression with the value and type of the next argument in the list ap, which is the same object initialized by va_start.  The argument atype is the type that the returned argument is expected to be.  The va_end(ap) macro must be invoked when all desired arguments have been accessed.  (The argument list in ap can be traversed again if va_start() is called again after va_end().)  In the example below, va_arg() is executed first to return the function_name passed to error().  The remaining error() arguments, arg1, arg2, ..., are given to vfprintf() in the argument ap.

RETURN VALUES

vprintf() and vfprintf() return the number of characters transmitted, or return −1 if an error was encountered. 

EXAMPLE

The following demonstrates how vfprintf() could be used to write an error routine:

#include <stdio.h>
#include <stdarg.h>
. . .
/∗
 ∗   error should be called like
 ∗         error(function_name, format, arg1, ...);
 ∗/
void error(char ∗function_name, char ∗format, ...)
{
    va_list ap;
    va_start(ap, );
    /∗ print out name of function causing error ∗/
    (void) fprintf(stderr, "ERR in %s: ", function_name);
    /∗ print out remainder of message ∗/
    (void) vfprintf(stderr, format, ap);
    va_end(ap);
    (void) abort;
}

SEE ALSO

printf(3S), stdarg(5)

NOTES

vprintf() and vfprintf() are Async-Safe in mutli-thread applications.  vsprintf() is MT-Safe in multi-thread applications. 

SunOS 5.2  —  Last change: 22 Jan 1993