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