1 VPRINTF(3C)              Standard C Library Functions              VPRINTF(3C)
   2 
   3 NAME
   4      vprintf, vfprintf, vsprintf, vsnprintf, vasprintf - print formatted
   5      output of a variable argument list
   6 
   7 LIBRARY
   8      Standard C Library (libc, -lc)
   9 
  10 SYNOPSIS
  11      #include <stdarg.h>
  12      #include <stdio.h>
  13 
  14      int
  15      vprintf(const char *format, va_list);
  16 
  17      int
  18      vfprintf(FILE *stream, const char *format, va_list ap);
  19 
  20      int
  21      vsprintf(char *s, const char *format, va_list ap);
  22 
  23      int
  24      vsnprintf(char *s, size_t n, const char *format, va_list ap);
  25 
  26      int
  27      vasprintf(char **ret, const char *format, va_list ap);
  28 
  29 DESCRIPTION
  30      The vprintf(), vfprintf(), vsprintf(), vsnprintf(), and vasprintf()
  31      functions are the same as printf(), fprintf(), sprintf(), snprintf(), and
  32      asprintf(), respectively, except that instead of being called with a
  33      variable number of arguments, they are called with an argument list as
  34      defined in the <stdarg.h> header.    See printf(3C).
  35 
  36      The <stdarg.h> header defines the type va_list and   a set of macros for
  37      advancing through a list of arguments whose number and types may vary.
  38      The argument ap to the vprint family of functions is of type va_list.
  39      This argument is used with the <stdarg.h> header file macros va_start(),
  40      va_arg(), and va_end() (see stdarg(3EXT)).  The EXAMPLES section below
  41      demonstrates the use of va_start() and va_end() with vprintf().
  42 
  43      The macro va_alist() is used as the parameter list in a function
  44      definition, as in the function called error() in the example below.  The
  45      macro `va_start(ap, name)', where ap is of type va_list and name is the
  46      rightmost parameter (just before ...), must be called before any attempt
  47      to traverse and access unnamed arguments is made.  The `va_end(ap)' macro
  48      must be invoked when all desired arguments have been accessed.  The
  49      argument list in ap can be traversed again if va_start() is called again
  50      after va_end().  In the example below, the error() arguments (arg1, arg2,
  51      ...) are passed to vfprintf() in the argument ap.
  52 
  53 RETURN VALUES
  54      Refer to printf(3C).
  55 
  56 EXAMPLES
  57      Example 1 Using vprintf() to write an error routine.
  58 
  59      The following demonstrates how vfprintf() could be used to write an error
  60      routine:
  61 
  62      #include <stdarg.h>
  63      #include <stdio.h>
  64 
  65      /*
  66       * error should be called like
  67       *      error(function_name, format, arg1, ...);
  68       */
  69      void
  70      error(char *function_name, char *format, ...)
  71      {
  72              va_list ap;
  73 
  74              va_start(ap, format);
  75 
  76              /* Print out name of function causing error */
  77              (void) fprintf(stderr, "ERR in %s: ", function_name);
  78 
  79              /* Print out remainder of message */
  80              (void) vfprintf(stderr, format, ap);
  81 
  82              va_end(ap);
  83 
  84              (void) abort();
  85      }
  86 
  87 ERRORS
  88      The vfprintf() function will fail if either the stream is unbuffered or
  89      the stream's buffer needed to be flushed and:
  90 
  91      EFBIG              The file is a regular file and an attempt was made to
  92                         write at or beyond the offset maximum.
  93 
  94 INTERFACE STABILITY
  95      Committed
  96 
  97 MT-LEVEL
  98      All of these functions can be used safely in multithreaded applications,
  99      as long as setlocale(3C) is not being called to change the locale.
 100 
 101 SEE ALSO
 102      printf(3C), stdarg(3EXT), attributes(5), standards(5)
 103 
 104 STANDARDS
 105      See standards(5) for the standards conformance of vprintf(), vfprintf(),
 106      vsprintf(), and vsnprintf().  The vasprintf() function is modeled on the
 107      one that appears in the FreeBSD, NetBSD, and GNU C libraries.
 108 
 109 NOTES
 110      The vsnprintf() return value when n is 0 was changed in the Solaris 10
 111      release.  The change was based on the SUSv3 specification.  The previous
 112      behavior was based on the initial SUSv2 specification, where vsnprintf()
 113      when n is 0 returns an unspecified value less than 1.
 114 
 115 illumos                          July 10, 2020                         illumos