vsprintf(9f)

1vsprintf(9F)             Kernel Functions for Drivers             vsprintf(9F)
2
3
4

NAME

6       vsprintf - format characters in memory
7

SYNOPSIS

9       #include <sys/varargs.h>
10        #include <sys/ddi.h>
11        #include <sys/sunddi.h>
12
13
14
15       char *vsprintf(char *buf, const char *fmt, va_list ap);
16
17

INTERFACE LEVEL

19       Solaris DDI specific (Solaris DDI).
20

PARAMETERS

22       buf     Pointer to a character string.
23
24
25       fmt     Pointer to a character string.
26
27
28       ap      Pointer to a variable argument list.
29
30

DESCRIPTION

32       vsprintf()  builds a string in buf under the control of the format fmt.
33       The format is a character string with either  plain  characters,  which
34       are simply copied into buf, or conversion specifications, each of which
35       converts zero or more arguments, again copied into buf. The results are
36       unpredictable  if  there  are  insufficient  arguments  for the format;
37       excess arguments are simply ignored. It is the user's responsibility to
38       ensure that enough storage is available for buf.
39
40
41       ap contains the list of arguments used by the conversion specifications
42       in fmt. ap is a variable argument list and must be initialized by call‐
43       ing   va_start(9F).  va_end(9F)  is used to clean up and must be called
44       after each traversal of the list. Multiple traversals of  the  argument
45       list, each bracketed by  va_start(9F) and  va_end(9F), are possible.
46
47
48       Each  conversion  specification is introduced by the % character, after
49       which the following appear in sequence:
50
51
52       An optional decimal digit specifying a minimum field width for  numeric
53       conversion. The converted value will be right-justified and padded with
54       leading zeroes if it has fewer characters than the minimum.
55
56
57       An optional l (ll) specifying that a following d, D, o, O, x, X,  or  u
58       conversion character applies to a long (long long) integer argument. An
59       l (ll) before any other conversion character is ignored.
60
61
62       A character indicating the type of conversion to be applied:
63
64       d,D,o,O,x,X,u    The integer argument is converted  to  signed  decimal
65                        (d,  D),  unsigned  octal (o, O), unsigned hexadecimal
66                        (x, X) or  unsigned  decimal  (u),  respectively,  and
67                        copied.  The letters abcdef are used for x conversion.
68                        The letters ABCDEF are used for X conversion.
69
70
71       c                The character value of the argument is copied.
72
73
74       b                This conversion uses  two  additional  arguments.  The
75                        first is an integer, and is converted according to the
76                        base specified in  the  second  argument.  The  second
77                        argument   is   a   character   string   in  the  form
78                        <base>[<arg>...]. The  base  supplies  the  conversion
79                        base  for  the  first argument as a binary value;  \10
80                        gives octal, \20 gives  hexadecimal.  Each  subsequent
81                        <arg>  is a sequence of characters, the first of which
82                        is the bit number to be tested, and subsequent charac‐
83                        ters,  up  to the next bit number or terminating null,
84                        supply the name of the bit.
85
86
87                        A bit number is a binary-valued character in the range
88                        1-32.  For  each  bit  set  in the first argument, and
89                        named in  the  second  argument,  the  bit  names  are
90                        copied, separated by commas, and bracketed by < and >.
91                        Thus,  the  following  function  call  would  generate
92                        reg=3<BitTwo,BitOne>\n in buf.
93
94
95                        vsprintf(buf, "reg=%b\n", 3, "\10\2BitTwo\1BitOne")
96
97
98       s                The  argument  is  taken  to  be  a  string (character
99                        pointer), and characters from the  string  are  copied
100                        until a null character is encountered.  If the charac‐
101                        ter pointer is NULL on SPARC, the string  <nullstring>
102                        is used in its place; on x86, it is undefined.
103
104
105       %                Copy a %; no argument is converted.
106
107

RETURN VALUES

109       vsprintf() returns its first parameter, buf.
110

CONTEXT

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

EXAMPLES

115       Example 1 Using vsprintf()
116
117
118       In this example, xxerror() accepts a pointer to a  dev_info_t structure
119       dip, an error level level, a format  fmt,  and  a  variable  number  of
120       arguments.   The routine uses vsprintf() to format the error message in
121       buf. Note  that   va_start(9F)  and  va_end(9F)  bracket  the  call  to
122       vsprintf().  instance,  level,  name,  and   buf  are  then  passed  to
123       cmn_err(9F).
124
125
126         #include <sys/varargs.h>
127         #include <sys/ddi.h>
128         #include <sys/sunddi.h>
129         #define MAX_MSG 256
130
131         void
132         xxerror(dev_info_t *dip, int level, const char *fmt, ...)
133         {
134              va_list        ap;
135              int       instance;
136              char      buf[MAX_MSG],
137                        *name;
138
139              instance = ddi_get_instance(dip);
140              name = ddi_binding_name(dip);
141
142              /* format buf using fmt and arguments contained in ap */
143              va_start(ap, fmt);
144              vsprintf(buf, fmt, ap);
145              va_end(ap);
146
147              /* pass formatted string to cmn_err(9F) */
148              cmn_err(level, "%s%d: %s", name, instance, buf);
149         }
150
151