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.
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.
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]
18 .\" Copyright 1989 AT&T
19 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
20 .\" Copyright 2016 Nexenta Systems, Inc.
26 .Nm sprintf, snprintf, vsprintf, vsnprintf
27 .Nd format characters in memory
35 .Fa "const char *format"
42 .Fa "const char *format"
49 .Fa "const char *format"
56 .Fa "const char *format"
64 Pointer to a character string.
66 Size of the buffer pointed to by
69 Pointer to a character string.
71 Pointer to a variable argument list.
76 function places output, followed by the null byte
78 in consecutive bytes starting at
80 it is the user's responsibility to ensure that enough storage is available.
84 function is identical to
86 with the addition of the argument
88 which specifies the size of the buffer referred to by
92 is 0, nothing is written and
94 can be a null pointer.
95 Otherwise, output bytes beyond the
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.
104 functions are the same as
108 respectively, except that instead of being called with a variable number of
109 arguments, they are called with an argument list,
111 used by the conversion specifications in
114 is a variable argument list and must be initialized by calling
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
124 Each of these functions converts, formats, and prints its arguments under
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
136 is exhausted while arguments remain, the excess arguments are evaluated but are
138 .Ss Conversion Specifications
139 Each conversion specification is introduced by the
141 character after which the following appear in sequence:
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
153 described below, is given to the field width.
154 The field width takes the form of an asterisk
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 ,
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
167 followed either by an asterisk
169 described below, or an optional decimal digit string, where a null digit string
171 If a precision appears with any other conversion specifier, the behavior is
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
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
186 flag followed by a positive field width.
187 A negative precision is taken as if the precision were omitted.
189 The flag characters and their meanings are:
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.
196 .Sy d , D , o , O , x , X ,
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.
206 flags both appear, the
208 flag will be ignored.
209 If a precision is specified, the
211 flag will be ignored.
212 For other conversions, the behavior is undefined.
215 The length modifiers and their meanings are:
218 Specifies that a following
219 .Sy d , D , o , O , x , X ,
222 conversion specifier applies to a short or unsigned
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
228 Specifies that a following
229 .Sy d , D , o , O , x , X ,
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
237 Specifies that a following
238 .Sy d , D , o , O , x , X ,
241 conversion specifier applies to a long or unsigned long argument.
243 Specifies that a following
244 .Sy d , D , o , O , x , X ,
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
255 is exhausted while arguments remain, the excess arguments are ignored.
257 The conversion specifiers and their meanings are:
259 .It Sy d , D , o , O , x , X , u
260 The integer argument is converted to signed decimal
279 The character value of the argument is printed.
283 conversion specification allows bit values to be printed meaningfully.
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
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.
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
302 To avoid lint warnings, cast pointers to type
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
315 is used in its place.
319 no argument is converted.
322 These functions can be called from user, kernel, interrupt, or
323 high-level interrupt context.
334 return the number of bytes that would have been written to
338 had been sufficiently large
339 .Pq excluding the terminating null byte .