vsnprintf(3C)

NAME

     vprintf, vfprintf, vsprintf,  vsnprintf  -  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);

     int vsnprintf(char *s, size_t n, const char *format, va_list
     ap);

DESCRIPTION

     The vprintf(), vfprintf(), vsprintf() and vsnprintf()  func-
     tions  are  the  same as printf(), fprintf(), sprintf(), and
     snprintf(),  respectively,  except  that  instead  of  being
     called  with a variable number of arguments, they are called
     with an argument list as defined in the  <stdarg.h>  header.
     See printf(3C) and stdarg(3HEAD).

     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  functions  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(3HEAD)). The  EXAMPLES
     section  below  demonstrates  the  use  of  va_start()   and
     va_end() 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.  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, the error() arguments (arg1,  arg2, ...) are
     passed to vfprintf() in the argument ap.

RETURN VALUES

     The vprintf(), vfprintf(), and vsprintf()  functions  return
     the  number  of  characters transmitted (not including \0 in
     the case of vsprintf()). The  vsnprintf()  function  returns
     the  number  of characters formatted, that is, the number of
     characters that would have been written to the buffer if  it
     were large enough. Each function returns a negative value if
     an output error was encountered.

ERRORS

     The vprintf() and vfprintf() functions will fail  if  either
     the stream is unbuffered or the stream's buffer needed to be
     flushed and:

     EFBIG The file is a regular file and an attempt was made  to
           write at or beyond the offset maximum.

EXAMPLES

     Example 1: Using vprintf() to write an error routine.

     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, format);
             /* 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;
     }

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO

     printf(3C), attributes(5), stdarg(3HEAD)