| blob | 32d13ba29341d55d8e5a54f0ae78c0ea63a46347 |
1 .\"
2 .\" The contents of this file are subject to the terms of the
3 .\" Common Development and Distribution License (the "License").
4 .\" You may not use this file except in compliance with the License.
5 .\"
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
7 .\" or http://www.opensolaris.org/os/licensing.
8 .\" See the License for the specific language governing permissions
9 .\" and limitations under the License.
10 .\"
11 .\" When distributing Covered Code, include this CDDL HEADER in each
12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
13 .\" If applicable, add the following below this CDDL HEADER, with the
14 .\" fields enclosed by brackets "[]" replaced with your own identifying
15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
16 .\"
17 .\"
18 .\" Copyright 1989 AT&T
19 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
20 .\" Copyright 2016 Nexenta Systems, Inc.
21 .\"
22 .Dd Dec 1, 2016
23 .Dt SPRINTF 9F
24 .Os
25 .Sh NAME
26 .Nm sprintf ,
27 .Nm snprintf ,
28 .Nm vsprintf ,
29 .Nm vsnprintf
30 .Nd format characters in memory
31 .Sh SYNOPSIS
32 .In sys/cmn_err.h
33 .In sys/ddi.h
34 .In sys/sunddi.h
35 .Ft "char *"
36 .Fo sprintf
37 .Fa "char *s"
38 .Fa "const char *format"
39 .Fa ...
40 .Fc
41 .Ft size_t
42 .Fo snprintf
43 .Fa "char *s"
44 .Fa "size_t n"
45 .Fa "const char *format"
46 .Fa ...
47 .Fc
48 .In sys/varargs.h
49 .Ft "char *"
50 .Fo vsprintf
51 .Fa "char *s"
52 .Fa "const char *format"
53 .Fa "va_list ap"
54 .Fc
55 .Ft size_t
56 .Fo vsnprintf
57 .Fa "char *s"
58 .Fa "size_t n"
59 .Fa "const char *format"
60 .Fa "va_list ap"
61 .Fc
62 .Sh INTERFACE LEVEL
63 illumos DDI specific
64 .Sh PARAMETERS
65 .Bl -tag -width Ds
66 .It Fa s
67 Pointer to a character string.
68 .It Fa n
69 Size of the buffer pointed to by
70 .Fa s .
71 .It Fa format
72 Pointer to a character string.
73 .It Fa ap
74 Pointer to a variable argument list.
75 .El
76 .Sh DESCRIPTION
77 The
78 .Fn sprintf
79 function places output, followed by the null byte
80 .Pq \e0 ,
81 in consecutive bytes starting at
82 .Fa s ;
83 it is the user's responsibility to ensure that enough storage is available.
84 .Pp
85 The
86 .Fn snprintf
87 function is identical to
88 .Fn sprintf
89 with the addition of the argument
90 .Fa n ,
91 which specifies the size of the buffer referred to by
92 .Fa s .
93 If
94 .Fa n
95 is 0, nothing is written and
96 .Fa s
97 can be a null pointer.
98 Otherwise, output bytes beyond the
99 .Fa n Ns \-1st
100 are discarded instead of being written to the array and a null byte is written
101 at the end of the bytes actually written into the array.
102 .Pp
103 The
104 .Fn vsprintf
105 and
106 .Fn vsnprintf
107 functions are the same as
108 .Fn sprintf
109 and
110 .Fn snprintf ,
111 respectively, except that instead of being called with a variable number of
112 arguments, they are called with an argument list,
113 .Fa ap ,
114 used by the conversion specifications in
115 .Fa format .
116 .Fa ap
117 is a variable argument list and must be initialized by calling
118 .Xr va_start 9F .
119 .Xr va_end 9F
120 is used to clean up and must be called after each traversal of the list.
121 Multiple traversals of the argument list, each bracketed by
122 .Xr va_start 9F
123 and
124 .Xr va_end 9F ,
125 are possible.
126 .Pp
127 Each of these functions converts, formats, and prints its arguments under
128 control of the
129 .Fa format .
130 The
131 .Fa format
132 is composed of zero or more directives: ordinary characters, which are simply
133 copied to the output stream and conversion specifications, each of which results
134 in the fetching of zero or more arguments.
135 The results are undefined if there are insufficient arguments for the
136 .Fa format .
137 If the
138 .Fa format
139 is exhausted while arguments remain, the excess arguments are evaluated but are
140 otherwise ignored.
141 .Ss Conversion Specifications
142 Each conversion specification is introduced by the
143 .Qq Sy %
144 character after which the following appear in sequence:
145 .Bl -bullet
146 .It
147 Zero or more flags
148 .Pq in any order ,
149 which modify the meaning of the conversion specification.
150 .It
151 An optional minimum field width.
152 If the converted value has fewer bytes than the field width, it will be padded
153 with spaces by default on the left; it will be padded on the right, if the
154 left-adjustment flag
155 .Pq Qq Sy ‐ ,
156 described below, is given to the field width.
157 The field width takes the form of an asterisk
158 .Pq Qq Sy * ,
159 described below, or a decimal integer.
160 .It
161 An optional precision that gives the minimum number of digits to appear for the
162 .Sy d , D , o , O , x , X ,
163 or
164 .Sy u
165 conversions
166 .Pq the field is padded with leading zeros ;
167 or the maximum number of bytes to be printed from a string in s conversion.
168 The precision takes the form of a period
169 .Pq Qq Sy \&.
170 followed either by an asterisk
171 .Pq Qq Sy * ,
172 described below, or an optional decimal digit string, where a null digit string
173 is treated as 0.
174 If a precision appears with any other conversion specifier, the behavior is
175 undefined.
176 .It
177 An optional length modifier that specified the size of the argument.
178 .It
179 A conversion specifier that indicates the type of conversion to be applied.
180 .El
181 .Pp
182 A field width, or precision, or both can be indicated by an asterisk
183 .Pq Qq Sy * .
184 In this case, an argument of type int supplies the field width or precision.
185 Arguments specifying field width, or precision, or both must appear in that
186 order before the argument, if any, to be converted.
187 A negative field width is taken as a
188 .Qq Sy \-
189 flag followed by a positive field width.
190 A negative precision is taken as if the precision were omitted.
191 .Ss Flag Characters
192 The flag characters and their meanings are:
193 .Bl -tag -width Ds
194 .It Sy \-
195 The result of the conversion will be left-justified within the field.
196 The conversion will be right-justified if this flag is not specified.
197 .It Sy 0
198 For
199 .Sy d , D , o , O , x , X ,
200 or
201 .Sy u
202 conversions, leading zeros
203 .Pq following any indication of sign or base
204 are used to pad to the field width; no space padding is performed.
205 If the
206 .Sy 0
207 and
208 .Sy \-
209 flags both appear, the
210 .Sy 0
211 flag will be ignored.
212 If a precision is specified, the
213 .Sy 0
214 flag will be ignored.
215 For other conversions, the behavior is undefined.
216 .El
217 .Ss Length Modifiers
218 The length modifiers and their meanings are:
219 .Bl -tag -width Ds
220 .It Sy h
221 Specifies that a following
222 .Sy d , D , o , O , x , X ,
223 or
224 .Sy u
225 conversion specifier applies to a short or unsigned
226 short argument
227 .Po the argument will have been promoted according to the integer promotions,
228 but its value will be converted to short or unsigned short before printing
229 .Pc .
230 .It Sy hh
231 Specifies that a following
232 .Sy d , D , o , O , x , X ,
233 or
234 .Sy u
235 conversion specifier applies to a signed char or unsigned char argument
236 .Po the argument will have been promoted according to the integer promotions,
237 but its value will be converted to signed char or unsigned char before printing
238 .Pc .
239 .It Sy l
240 Specifies that a following
241 .Sy d , D , o , O , x , X ,
242 or
243 .Sy u
244 conversion specifier applies to a long or unsigned long argument.
245 .It Sy ll
246 Specifies that a following
247 .Sy d , D , o , O , x , X ,
248 or
249 .Sy u
250 conversion specifier applies to a long long or unsigned long long argument.
251 .El
252 .Ss Conversion Specifiers
253 Each conversion specifier results in fetching zero or more arguments.
254 The results are undefined if there are insufficient arguments for the
255 .Fa format .
256 If the
257 .Fa format
258 is exhausted while arguments remain, the excess arguments are ignored.
259 .Pp
260 The conversion specifiers and their meanings are:
261 .Bl -tag -width Ds
262 .It Sy d , D , o , O , x , X , u
263 The integer argument is converted to signed decimal
264 .Pq Sy d , D ,
265 unsigned octal
266 .Pq Sy o , O ,
267 unsigned hexadecimal
268 .Pq Sy x , X ,
269 or unsigned decimal
270 .Pq Sy u ,
271 respectively.
272 The letters
273 .Qq Sy abcdef
274 are used for
275 .Sy x
276 and letters
277 .Qq Sy ABCDEF
278 for
279 .Sy X
280 conversions.
281 .It Sy c
282 The character value of the argument is printed.
283 .It Sy b
284 The
285 .Sy %b
286 conversion specification allows bit values to be printed meaningfully.
287 Each
288 .Sy %b
289 takes an integer value and a format string from the argument list.
290 The first character of the format string should be the output base encoded as a
291 control character.
292 This base is used to print the integer argument.
293 The remaining groups of characters in the format string consist of a bit number
294 .Pq between 1 and 32, also encoded as a control character
295 and the next characters
296 .Pq up to the next control character or '\e0'
297 give the name of the bit field.
298 The string corresponding to the bit fields set in the integer argument is
299 printed after the numerical value.
300 .It Sy p
301 The argument is taken to be a pointer; the value of the pointer is printed in
302 unsigned hexadecimal.
303 The print format is equivalent to
304 .Sy %lx .
305 To avoid lint warnings, cast pointers to type
306 .Ft "void *"
307 when using the
308 .Sy %p
309 format specifier.
310 .It Sy s
311 The argument is taken to be a string
312 .Pq character pointer ,
313 and characters from the string are printed until a null character is ecountered.
314 If the character pointer is
315 .Sy NULL ,
316 the string
317 .Qq <null string>
318 is used in its place.
319 .It Sy %
320 Copy a
321 .Sy % ;
322 no argument is converted.
323 .El
324 .Sh CONTEXT
325 These functions can be called from user, kernel, interrupt, or
326 high-level interrupt context.
327 .Sh RETURN VALUES
328 .Fn sprintf
329 and
330 .Fn vsprintf
331 return
332 .Fa s .
333 .Pp
334 .Fn snprintf
335 and
336 .Fn vsnprintf
337 return the number of bytes that would have been written to
338 .Fa s
339 if
340 .Fa n
341 had been sufficiently large
342 .Pq excluding the terminating null byte .
343 .Sh SEE ALSO
344 .Xr cmn_err 9F ,
345 .Xr va_arg 9F ,
346 .Xr va_end 9F ,
347 .Xr va_start 9F