vsprintf(9F)

NAME

     vsprintf - format characters in memory

SYNOPSIS

     #include <sys/varargs.h>
      #include <sys/ddi.h>
      #include <sys/sunddi.h>

     char *vsprintf(char *buf, const char *fmt, va_list ap);

INTERFACE LEVEL

     Solaris DDI specific (Solaris DDI).

PARAMETERS

      buf  Pointer to a character string.

     fmt   Pointer to a character string.

     ap    Pointer to a variable argument list.

DESCRIPTION

     vsprintf() builds a string in buf under the control  of  the
     format  fmt.  The  format  is a character string with either
     plain characters, which  are  simply  copied  into  buf,  or
     conversion  specifications,  each  of which converts zero or
     more arguments, again copied  into  buf.   The  results  are
     unpredictable  if  there  are insufficient arguments for the
     format;  excess arguments are  simply  ignored.  It  is  the
     user's  responsibility  to  ensure  that  enough  storage is
     available for buf.

     ap contains the list of arguments  used  by  the  conversion
     specifications  in  fmt.  ap is a variable argument list and
     must be initialized by calling  va_start(9F). va_end(9F)  is
     used  to clean up and must be called after each traversal of
     the list. Multiple traversals of  the  argument  list,  each
     bracketed by  va_start(9F) and  va_end(9F), are possible.

     Each conversion specification is introduced by the % charac-
     ter, after which the following appear in sequence:

     An optional decimal digit specifying a minimum  field  width
     for  numeric  conversion. The converted value will be right-
     justified and padded with leading zeroes  if  it  has  fewer
     characters than the minimum.

     An optional l (ll) specifying that a following d, D,  o,  O,
     x,  X,  or  u  conversion  character applies to a long (long
     long) integer argument. An l (ll) before any  other  conver-
     sion character is ignored.

     A character indicating the type of conversion to be applied:

     d, D,o,O,x, X,u
           The integer argument is converted  to  signed  decimal
           (d,  D),  unsigned  octal (o, O), unsigned hexadecimal
           (x, X) or  unsigned  decimal  (u),  respectively,  and
           copied.  The letters abcdef are used for x conversion.
           The letters ABCDEF are used for X conversion.

     c     The character value of the argument is copied.

     b     This conversion uses  two  additional  arguments.  The
           first is an integer, and is converted according to the
           base specified in  the  second  argument.  The  second
           argument   is   a   character   string   in  the  form
           <base>[<arg>...]. The  base  supplies  the  conversion
           base  for  the  first argument as a binary value;  \10
           gives octal, \20 gives  hexadecimal.  Each  subsequent
           <arg>  is a sequence of characters, the first of which
           is the bit number to be tested, and subsequent charac-
           ters,  up  to the next bit number or terminating null,
           supply the name of the bit.

           A bit number is a binary-valued character in the range
           1-32.  For  each  bit  set  in the first argument, and
           named in  the  second  argument,  the  bit  names  are
           copied, separated by commas, and bracketed by < and >.
           Thus,  the  following  function  call  would  generate
           reg=3<BitTwo,BitOne>\n in buf.

           vsprintf(buf, "reg=%b\n", 3, "\10\2BitTwo\1BitOne")

     s     The argument  is  taken  to  be  a  string  (character
           pointer),  and  characters  from the string are copied
           until a null character is encountered.  If the charac-
           ter  pointer is NULL on SPARC, the string <nullstring>
           is used in its place; on x86, it is undefined.

     %     Copy a %; no argument is converted.

RETURN VALUES

     vsprintf() returns its first parameter, buf.

CONTEXT

     vsprintf() can be called from  user,  kernel,  or  interrupt
     context.

EXAMPLES

     Example 1: Using vsprintf()

     In  this  example,  xxerror()  accepts  a   pointer   to   a
     dev_info_t  structure  dip,  an  error level level, a format
     fmt, and a variable number of arguments.  The  routine  uses
     vsprintf()  to  format  the error message in  buf. Note that
     va_start(9F) and va_end(9F) bracket the call to  vsprintf().
     instance,   level,   name,  and   buf  are  then  passed  to
     cmn_err(9F).

     #include <sys/varargs.h>
     #include <sys/ddi.h>
     #include <sys/sunddi.h>
     #define MAX_MSG 256

     void
     xxerror(dev_info_t *dip, int level, const char *fmt, ...)
     {
          va_list        ap;
          int       instance;
          char      buf[MAX_MSG],
                    *name;

          instance = ddi_get_instance(dip);
          name = ddi_binding_name(dip);

          /* format buf using fmt and arguments contained in ap */
          va_start(ap, fmt);
          vsprintf(buf, fmt, ap);
          va_end(ap);

          /* pass formatted string to cmn_err(9F) */
          cmn_err(level, "%s%d: %s", name, instance, buf);
     }

SEE ALSO

     cmn_err(9F),   ddi_binding_name(9F),   ddi_get_instance(9F),
     va_arg(9F)

     Writing Device Drivers