]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright (c) 1990, 1991, 1993 | |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
4 | .\" This code is derived from software contributed to Berkeley by | |
5 | .\" Chris Torek and the American National Standards Committee X3, | |
6 | .\" on Information Processing Systems. | |
7 | .\" | |
8 | .\" Redistribution and use in source and binary forms, with or without | |
9 | .\" modification, are permitted provided that the following conditions | |
10 | .\" are met: | |
11 | .\" 1. Redistributions of source code must retain the above copyright | |
12 | .\" notice, this list of conditions and the following disclaimer. | |
13 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
14 | .\" notice, this list of conditions and the following disclaimer in the | |
15 | .\" documentation and/or other materials provided with the distribution. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)printf.3 8.1 (Berkeley) 6/4/93 | |
33 | .\" $FreeBSD$ | |
34 | .\" | |
35 | .Dd December 2, 2009 | |
36 | .Dt PRINTF 3 | |
37 | .Os | |
38 | .Sh NAME | |
39 | .Nm printf , fprintf , sprintf , snprintf , asprintf , dprintf , | |
40 | .Nm vprintf , vfprintf, vsprintf , vsnprintf , vasprintf, vdprintf | |
41 | .Nd formatted output conversion | |
42 | .Sh LIBRARY | |
43 | .Lb libc | |
44 | .Sh SYNOPSIS | |
45 | .In stdio.h | |
46 | .Ft int | |
47 | .Fn printf "const char * restrict format" ... | |
48 | .Ft int | |
49 | .Fn fprintf "FILE * restrict stream" "const char * restrict format" ... | |
50 | .Ft int | |
51 | .Fn sprintf "char * restrict str" "const char * restrict format" ... | |
52 | .Ft int | |
53 | .Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ... | |
54 | .Ft int | |
55 | .Fn asprintf "char **ret" "const char *format" ... | |
56 | .Ft int | |
57 | .Fn dprintf "int fd" "const char * restrict format" ... | |
58 | .In stdarg.h | |
59 | .Ft int | |
60 | .Fn vprintf "const char * restrict format" "va_list ap" | |
61 | .Ft int | |
62 | .Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap" | |
63 | .Ft int | |
64 | .Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap" | |
65 | .Ft int | |
66 | .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap" | |
67 | .Ft int | |
68 | .Fn vasprintf "char **ret" "const char *format" "va_list ap" | |
69 | .Ft int | |
70 | .Fn vdprintf "int fd" "const char * restrict format" "va_list ap" | |
71 | .Sh DESCRIPTION | |
72 | The | |
73 | .Fn printf | |
74 | family of functions produces output according to a | |
75 | .Fa format | |
76 | as described below. | |
77 | The | |
78 | .Fn printf | |
79 | and | |
80 | .Fn vprintf | |
81 | functions | |
82 | write output to | |
83 | .Dv stdout , | |
84 | the standard output stream; | |
85 | .Fn fprintf | |
86 | and | |
87 | .Fn vfprintf | |
88 | write output to the given output | |
89 | .Fa stream ; | |
90 | .Fn dprintf | |
91 | and | |
92 | .Fn vdprintf | |
93 | write output to the given file descriptor; | |
94 | .Fn sprintf , | |
95 | .Fn snprintf , | |
96 | .Fn vsprintf , | |
97 | and | |
98 | .Fn vsnprintf | |
99 | write to the character string | |
100 | .Fa str ; | |
101 | and | |
102 | .Fn asprintf | |
103 | and | |
104 | .Fn vasprintf | |
105 | dynamically allocate a new string with | |
106 | .Xr malloc 3 . | |
107 | .Pp | |
108 | Extended locale versions of these functions are documented in | |
109 | .Xr printf_l 3 . | |
110 | See | |
111 | .Xr xlocale 3 | |
112 | for more information. | |
113 | .Pp | |
114 | These functions write the output under the control of a | |
115 | .Fa format | |
116 | string that specifies how subsequent arguments | |
117 | (or arguments accessed via the variable-length argument facilities of | |
118 | .Xr stdarg 3 ) | |
119 | are converted for output. | |
120 | .Pp | |
121 | The | |
122 | .Fn asprintf | |
123 | and | |
124 | .Fn vasprintf | |
125 | functions | |
126 | set | |
127 | .Fa *ret | |
128 | to be a pointer to a buffer sufficiently large to hold the formatted string. | |
129 | This pointer should be passed to | |
130 | .Xr free 3 | |
131 | to release the allocated storage when it is no longer needed. | |
132 | If sufficient space cannot be allocated, | |
133 | .Fn asprintf | |
134 | and | |
135 | .Fn vasprintf | |
136 | will return \-1 and set | |
137 | .Fa ret | |
138 | to be a | |
139 | .Dv NULL | |
140 | pointer. | |
141 | .Pp | |
142 | The | |
143 | .Fn snprintf | |
144 | and | |
145 | .Fn vsnprintf | |
146 | functions | |
147 | will write at most | |
148 | .Fa size Ns \-1 | |
149 | of the characters printed into the output string | |
150 | (the | |
151 | .Fa size Ns 'th | |
152 | character then gets the terminating | |
153 | .Ql \e0 ) ; | |
154 | if the return value is greater than or equal to the | |
155 | .Fa size | |
156 | argument, the string was too short | |
157 | and some of the printed characters were discarded. | |
158 | The output is always null-terminated, unless | |
159 | .Fa size | |
160 | is 0. | |
161 | .Pp | |
162 | The | |
163 | .Fn sprintf | |
164 | and | |
165 | .Fn vsprintf | |
166 | functions | |
167 | effectively assume a | |
168 | .Fa size | |
169 | of | |
170 | .Dv INT_MAX + 1. | |
171 | .Pp | |
172 | For those routines that write to a user-provided character string, | |
173 | that string and the format strings should not overlap, as the | |
174 | behavior is undefined. | |
175 | .Pp | |
176 | The format string is composed of zero or more directives: | |
177 | ordinary | |
178 | .\" multibyte | |
179 | characters (not | |
180 | .Cm % ) , | |
181 | which are copied unchanged to the output stream; | |
182 | and conversion specifications, each of which results | |
183 | in fetching zero or more subsequent arguments. | |
184 | Each conversion specification is introduced by | |
185 | the | |
186 | .Cm % | |
187 | character. | |
188 | The arguments must correspond properly (after type promotion) | |
189 | with the conversion specifier. | |
190 | After the | |
191 | .Cm % , | |
192 | the following appear in sequence: | |
193 | .Bl -bullet | |
194 | .It | |
195 | An optional field, consisting of a decimal digit string followed by a | |
196 | .Cm $ , | |
197 | specifying the next argument to access. | |
198 | If this field is not provided, the argument following the last | |
199 | argument accessed will be used. | |
200 | Arguments are numbered starting at | |
201 | .Cm 1 . | |
202 | If unaccessed arguments in the format string are interspersed with ones that | |
203 | are accessed the results will be indeterminate. | |
204 | .It | |
205 | Zero or more of the following flags: | |
206 | .Bl -tag -width ".So \ Sc (space)" | |
207 | .It Sq Cm # | |
208 | The value should be converted to an | |
209 | .Dq alternate form . | |
210 | For | |
211 | .Cm c , d , i , n , p , s , | |
212 | and | |
213 | .Cm u | |
214 | conversions, this option has no effect. | |
215 | For | |
216 | .Cm o | |
217 | conversions, the precision of the number is increased to force the first | |
218 | character of the output string to a zero. | |
219 | For | |
220 | .Cm x | |
221 | and | |
222 | .Cm X | |
223 | conversions, a non-zero result has the string | |
224 | .Ql 0x | |
225 | (or | |
226 | .Ql 0X | |
227 | for | |
228 | .Cm X | |
229 | conversions) prepended to it. | |
230 | For | |
231 | .Cm a , A , e , E , f , F , g , | |
232 | and | |
233 | .Cm G | |
234 | conversions, the result will always contain a decimal point, even if no | |
235 | digits follow it (normally, a decimal point appears in the results of | |
236 | those conversions only if a digit follows). | |
237 | For | |
238 | .Cm g | |
239 | and | |
240 | .Cm G | |
241 | conversions, trailing zeros are not removed from the result as they | |
242 | would otherwise be. | |
243 | .It So Cm 0 Sc (zero) | |
244 | Zero padding. | |
245 | For all conversions except | |
246 | .Cm n , | |
247 | the converted value is padded on the left with zeros rather than blanks. | |
248 | If a precision is given with a numeric conversion | |
249 | .Cm ( d , i , o , u , i , x , | |
250 | and | |
251 | .Cm X ) , | |
252 | the | |
253 | .Cm 0 | |
254 | flag is ignored. | |
255 | .It Sq Cm \- | |
256 | A negative field width flag; | |
257 | the converted value is to be left adjusted on the field boundary. | |
258 | Except for | |
259 | .Cm n | |
260 | conversions, the converted value is padded on the right with blanks, | |
261 | rather than on the left with blanks or zeros. | |
262 | A | |
263 | .Cm \- | |
264 | overrides a | |
265 | .Cm 0 | |
266 | if both are given. | |
267 | .It So "\ " Sc (space) | |
268 | A blank should be left before a positive number | |
269 | produced by a signed conversion | |
270 | .Cm ( a , A , d , e , E , f , F , g , G , | |
271 | or | |
272 | .Cm i ) . | |
273 | .It Sq Cm + | |
274 | A sign must always be placed before a | |
275 | number produced by a signed conversion. | |
276 | A | |
277 | .Cm + | |
278 | overrides a space if both are used. | |
279 | .It So "'" Sc (apostrophe) | |
280 | Decimal conversions | |
281 | .Cm ( d , u , | |
282 | or | |
283 | .Cm i ) | |
284 | or the integral portion of a floating point conversion | |
285 | .Cm ( f | |
286 | or | |
287 | .Cm F ) | |
288 | should be grouped and separated by thousands using | |
289 | the non-monetary separator returned by | |
290 | .Xr localeconv 3 . | |
291 | .El | |
292 | .It | |
293 | An optional separator character ( | |
294 | .Cm \ , | \; | \ : | _ | |
295 | ) used for separating multiple values when printing an AltiVec or SSE vector, | |
296 | or other multi-value unit. | |
297 | .Pp | |
298 | NOTE: This is an extension to the | |
299 | .Fn printf | |
300 | specification. | |
301 | Behaviour of these values for | |
302 | .Fn printf | |
303 | is only defined for operating systems conforming to the | |
304 | AltiVec Technology Programming Interface Manual. | |
305 | (At time of writing this includes only Mac OS X 10.2 and later.) | |
306 | .It | |
307 | An optional decimal digit string specifying a minimum field width. | |
308 | If the converted value has fewer characters than the field width, it will | |
309 | be padded with spaces on the left (or right, if the left-adjustment | |
310 | flag has been given) to fill out | |
311 | the field width. | |
312 | .It | |
313 | An optional precision, in the form of a period | |
314 | .Cm \&. | |
315 | followed by an | |
316 | optional digit string. | |
317 | If the digit string is omitted, the precision is taken as zero. | |
318 | This gives the minimum number of digits to appear for | |
319 | .Cm d , i , o , u , x , | |
320 | and | |
321 | .Cm X | |
322 | conversions, the number of digits to appear after the decimal-point for | |
323 | .Cm a , A , e , E , f , | |
324 | and | |
325 | .Cm F | |
326 | conversions, the maximum number of significant digits for | |
327 | .Cm g | |
328 | and | |
329 | .Cm G | |
330 | conversions, or the maximum number of characters to be printed from a | |
331 | string for | |
332 | .Cm s | |
333 | conversions. | |
334 | .It | |
335 | An optional length modifier, that specifies the size of the argument. | |
336 | The following length modifiers are valid for the | |
337 | .Cm d , i , n , o , u , x , | |
338 | or | |
339 | .Cm X | |
340 | conversion: | |
341 | .Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *" | |
342 | .It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n | |
343 | .It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *" | |
344 | .It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *" | |
345 | .It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *" | |
346 | .It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *" | |
347 | .It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *" | |
348 | .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *" | |
349 | .It Cm z Ta (see note) Ta Vt size_t Ta (see note) | |
350 | .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *" | |
351 | .El | |
352 | .Pp | |
353 | Note: | |
354 | the | |
355 | .Cm t | |
356 | modifier, when applied to a | |
357 | .Cm o , u , x , | |
358 | or | |
359 | .Cm X | |
360 | conversion, indicates that the argument is of an unsigned type | |
361 | equivalent in size to a | |
362 | .Vt ptrdiff_t . | |
363 | The | |
364 | .Cm z | |
365 | modifier, when applied to a | |
366 | .Cm d | |
367 | or | |
368 | .Cm i | |
369 | conversion, indicates that the argument is of a signed type equivalent in | |
370 | size to a | |
371 | .Vt size_t . | |
372 | Similarly, when applied to an | |
373 | .Cm n | |
374 | conversion, it indicates that the argument is a pointer to a signed type | |
375 | equivalent in size to a | |
376 | .Vt size_t . | |
377 | .Pp | |
378 | The following length modifier is valid for the | |
379 | .Cm a , A , e , E , f , F , g , | |
380 | or | |
381 | .Cm G | |
382 | conversion: | |
383 | .Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G" | |
384 | .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G | |
385 | .It Cm l No (ell) Ta Vt double | |
386 | (ignored, same behavior as without it) | |
387 | .It Cm L Ta Vt "long double" | |
388 | .El | |
389 | .Pp | |
390 | The following length modifier is valid for the | |
391 | .Cm c | |
392 | or | |
393 | .Cm s | |
394 | conversion: | |
395 | .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *" | |
396 | .It Sy Modifier Ta Cm c Ta Cm s | |
397 | .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *" | |
398 | .El | |
399 | .Pp | |
400 | The AltiVec Technology Programming Interface Manual also defines five additional length modifiers | |
401 | which can be used (in place of the conventional length modifiers) for the printing of AltiVec or SSE vectors: | |
402 | .Bl -tag -compact | |
403 | .It Cm v | |
404 | Treat the argument as a vector value, unit length will be determined by the conversion | |
405 | specifier (default = 16 8-bit units for all integer conversions, | |
406 | 4 32-bit units for floating point conversions). | |
407 | .It Cm vh, hv | |
408 | Treat the argument as a vector of 8 16-bit units. | |
409 | .It Cm vl, lv | |
410 | Treat the argument as a vector of 4 32-bit units. | |
411 | .El | |
412 | .Pp | |
413 | NOTE: The vector length specifiers are extensions to the | |
414 | .Fn printf | |
415 | specification. | |
416 | Behaviour of these values for | |
417 | .Fn printf | |
418 | is only defined for operating systems conforming to the | |
419 | AltiVec Technology Programming Interface Manual. | |
420 | (At time of writing this includes only Mac OS X 10.2 and later.) | |
421 | .Pp | |
422 | As a further extension, for SSE2 64-bit units: | |
423 | .Bl -tag -compact | |
424 | .It Cm vll, llv | |
425 | Treat the argument as a vector of 2 64-bit units. | |
426 | .El | |
427 | .It | |
428 | A character that specifies the type of conversion to be applied. | |
429 | .El | |
430 | .Pp | |
431 | A field width or precision, or both, may be indicated by | |
432 | an asterisk | |
433 | .Ql * | |
434 | or an asterisk followed by one or more decimal digits and a | |
435 | .Ql $ | |
436 | instead of a | |
437 | digit string. | |
438 | In this case, an | |
439 | .Vt int | |
440 | argument supplies the field width or precision. | |
441 | A negative field width is treated as a left adjustment flag followed by a | |
442 | positive field width; a negative precision is treated as though it were | |
443 | missing. | |
444 | If a single format directive mixes positional | |
445 | .Pq Li nn$ | |
446 | and non-positional arguments, the results are undefined. | |
447 | .Pp | |
448 | The conversion specifiers and their meanings are: | |
449 | .Bl -tag -width ".Cm diouxX" | |
450 | .It Cm diouxX | |
451 | The | |
452 | .Vt int | |
453 | (or appropriate variant) argument is converted to signed decimal | |
454 | .Cm ( d | |
455 | and | |
456 | .Cm i ) , | |
457 | unsigned octal | |
458 | .Pq Cm o , | |
459 | unsigned decimal | |
460 | .Pq Cm u , | |
461 | or unsigned hexadecimal | |
462 | .Cm ( x | |
463 | and | |
464 | .Cm X ) | |
465 | notation. | |
466 | The letters | |
467 | .Dq Li abcdef | |
468 | are used for | |
469 | .Cm x | |
470 | conversions; the letters | |
471 | .Dq Li ABCDEF | |
472 | are used for | |
473 | .Cm X | |
474 | conversions. | |
475 | The precision, if any, gives the minimum number of digits that must | |
476 | appear; if the converted value requires fewer digits, it is padded on | |
477 | the left with zeros. | |
478 | .It Cm DOU | |
479 | The | |
480 | .Vt "long int" | |
481 | argument is converted to signed decimal, unsigned octal, or unsigned | |
482 | decimal, as if the format had been | |
483 | .Cm ld , lo , | |
484 | or | |
485 | .Cm lu | |
486 | respectively. | |
487 | These conversion characters are deprecated, and will eventually disappear. | |
488 | .It Cm eE | |
489 | The | |
490 | .Vt double | |
491 | argument is rounded and converted in the style | |
492 | .Sm off | |
493 | .Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd | |
494 | .Sm on | |
495 | where there is one digit before the | |
496 | decimal-point character | |
497 | and the number of digits after it is equal to the precision; | |
498 | if the precision is missing, | |
499 | it is taken as 6; if the precision is | |
500 | zero, no decimal-point character appears. | |
501 | An | |
502 | .Cm E | |
503 | conversion uses the letter | |
504 | .Ql E | |
505 | (rather than | |
506 | .Ql e ) | |
507 | to introduce the exponent. | |
508 | The exponent always contains at least two digits; if the value is zero, | |
509 | the exponent is 00. | |
510 | .Pp | |
511 | For | |
512 | .Cm a , A , e , E , f , F , g , | |
513 | and | |
514 | .Cm G | |
515 | conversions, positive and negative infinity are represented as | |
516 | .Li inf | |
517 | and | |
518 | .Li -inf | |
519 | respectively when using the lowercase conversion character, and | |
520 | .Li INF | |
521 | and | |
522 | .Li -INF | |
523 | respectively when using the uppercase conversion character. | |
524 | Similarly, NaN is represented as | |
525 | .Li nan | |
526 | when using the lowercase conversion, and | |
527 | .Li NAN | |
528 | when using the uppercase conversion. | |
529 | .It Cm fF | |
530 | The | |
531 | .Vt double | |
532 | argument is rounded and converted to decimal notation in the style | |
533 | .Sm off | |
534 | .Oo \- Oc Ar ddd Li \&. Ar ddd , | |
535 | .Sm on | |
536 | where the number of digits after the decimal-point character | |
537 | is equal to the precision specification. | |
538 | If the precision is missing, it is taken as 6; if the precision is | |
539 | explicitly zero, no decimal-point character appears. | |
540 | If a decimal point appears, at least one digit appears before it. | |
541 | .It Cm gG | |
542 | The | |
543 | .Vt double | |
544 | argument is converted in style | |
545 | .Cm f | |
546 | or | |
547 | .Cm e | |
548 | (or | |
549 | .Cm F | |
550 | or | |
551 | .Cm E | |
552 | for | |
553 | .Cm G | |
554 | conversions). | |
555 | The precision specifies the number of significant digits. | |
556 | If the precision is missing, 6 digits are given; if the precision is zero, | |
557 | it is treated as 1. | |
558 | Style | |
559 | .Cm e | |
560 | is used if the exponent from its conversion is less than \-4 or greater than | |
561 | or equal to the precision. | |
562 | Trailing zeros are removed from the fractional part of the result; a | |
563 | decimal point appears only if it is followed by at least one digit. | |
564 | .It Cm aA | |
565 | The | |
566 | .Vt double | |
567 | argument is rounded and converted to hexadecimal notation in the style | |
568 | .Sm off | |
569 | .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d , | |
570 | .Sm on | |
571 | where the number of digits after the hexadecimal-point character | |
572 | is equal to the precision specification. | |
573 | If the precision is missing, it is taken as enough to represent | |
574 | the floating-point number exactly, and no rounding occurs. | |
575 | If the precision is zero, no hexadecimal-point character appears. | |
576 | The | |
577 | .Cm p | |
578 | is a literal character | |
579 | .Ql p , | |
580 | and the exponent consists of a positive or negative sign | |
581 | followed by a decimal number representing an exponent of 2. | |
582 | The | |
583 | .Cm A | |
584 | conversion uses the prefix | |
585 | .Dq Li 0X | |
586 | (rather than | |
587 | .Dq Li 0x ) , | |
588 | the letters | |
589 | .Dq Li ABCDEF | |
590 | (rather than | |
591 | .Dq Li abcdef ) | |
592 | to represent the hex digits, and the letter | |
593 | .Ql P | |
594 | (rather than | |
595 | .Ql p ) | |
596 | to separate the mantissa and exponent. | |
597 | .Pp | |
598 | Note that there may be multiple valid ways to represent floating-point | |
599 | numbers in this hexadecimal format. | |
600 | For example, | |
601 | .Li 0x1.92p+1 , 0x3.24p+0 , 0x6.48p-1 , | |
602 | and | |
603 | .Li 0xc.9p-2 | |
604 | are all equivalent. | |
605 | The format chosen depends on the internal representation of the | |
606 | number, but the implementation guarantees that the length of the | |
607 | mantissa will be minimized. | |
608 | Zeroes are always represented with a mantissa of 0 (preceded by a | |
609 | .Ql - | |
610 | if appropriate) and an exponent of | |
611 | .Li +0 . | |
612 | .It Cm C | |
613 | Treated as | |
614 | .Cm c | |
615 | with the | |
616 | .Cm l | |
617 | (ell) modifier. | |
618 | .It Cm c | |
619 | The | |
620 | .Vt int | |
621 | argument is converted to an | |
622 | .Vt "unsigned char" , | |
623 | and the resulting character is written. | |
624 | .Pp | |
625 | If the | |
626 | .Cm l | |
627 | (ell) modifier is used, the | |
628 | .Vt wint_t | |
629 | argument shall be converted to a | |
630 | .Vt wchar_t , | |
631 | and the (potentially multi-byte) sequence representing the | |
632 | single wide character is written, including any shift sequences. | |
633 | If a shift sequence is used, the shift state is also restored | |
634 | to the original state after the character. | |
635 | .It Cm S | |
636 | Treated as | |
637 | .Cm s | |
638 | with the | |
639 | .Cm l | |
640 | (ell) modifier. | |
641 | .It Cm s | |
642 | The | |
643 | .Vt "char *" | |
644 | argument is expected to be a pointer to an array of character type (pointer | |
645 | to a string). | |
646 | Characters from the array are written up to (but not including) | |
647 | a terminating | |
648 | .Dv NUL | |
649 | character; | |
650 | if a precision is specified, no more than the number specified are | |
651 | written. | |
652 | If a precision is given, no null character | |
653 | need be present; if the precision is not specified, or is greater than | |
654 | the size of the array, the array must contain a terminating | |
655 | .Dv NUL | |
656 | character. | |
657 | .Pp | |
658 | If the | |
659 | .Cm l | |
660 | (ell) modifier is used, the | |
661 | .Vt "wchar_t *" | |
662 | argument is expected to be a pointer to an array of wide characters | |
663 | (pointer to a wide string). | |
664 | For each wide character in the string, the (potentially multi-byte) | |
665 | sequence representing the | |
666 | wide character is written, including any shift sequences. | |
667 | If any shift sequence is used, the shift state is also restored | |
668 | to the original state after the string. | |
669 | Wide characters from the array are written up to (but not including) | |
670 | a terminating wide | |
671 | .Dv NUL | |
672 | character; | |
673 | if a precision is specified, no more than the number of bytes specified are | |
674 | written (including shift sequences). | |
675 | Partial characters are never written. | |
676 | If a precision is given, no null character | |
677 | need be present; if the precision is not specified, or is greater than | |
678 | the number of bytes required to render the multibyte representation of | |
679 | the string, the array must contain a terminating wide | |
680 | .Dv NUL | |
681 | character. | |
682 | .It Cm p | |
683 | The | |
684 | .Vt "void *" | |
685 | pointer argument is printed in hexadecimal (as if by | |
686 | .Ql %#x | |
687 | or | |
688 | .Ql %#lx ) . | |
689 | .It Cm n | |
690 | The number of characters written so far is stored into the | |
691 | integer indicated by the | |
692 | .Vt "int *" | |
693 | (or variant) pointer argument. | |
694 | No argument is converted. | |
695 | .It Cm % | |
696 | A | |
697 | .Ql % | |
698 | is written. | |
699 | No argument is converted. | |
700 | The complete conversion specification | |
701 | is | |
702 | .Ql %% . | |
703 | .El | |
704 | .Pp | |
705 | The decimal point | |
706 | character is defined in the program's locale (category | |
707 | .Dv LC_NUMERIC ) . | |
708 | .Pp | |
709 | In no case does a non-existent or small field width cause truncation of | |
710 | a numeric field; if the result of a conversion is wider than the field | |
711 | width, the | |
712 | field is expanded to contain the conversion result. | |
713 | .Sh RETURN VALUES | |
714 | These functions return the number of characters printed | |
715 | (not including the trailing | |
716 | .Ql \e0 | |
717 | used to end output to strings), | |
718 | except for | |
719 | .Fn snprintf | |
720 | and | |
721 | .Fn vsnprintf , | |
722 | which return the number of characters that would have been printed if the | |
723 | .Fa size | |
724 | were unlimited | |
725 | (again, not including the final | |
726 | .Ql \e0 ) . | |
727 | These functions return a negative value if an error occurs. | |
728 | .Sh EXAMPLES | |
729 | To print a date and time in the form | |
730 | .Dq Li "Sunday, July 3, 10:02" , | |
731 | where | |
732 | .Fa weekday | |
733 | and | |
734 | .Fa month | |
735 | are pointers to strings: | |
736 | .Bd -literal -offset indent | |
737 | #include <stdio.h> | |
738 | fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", | |
739 | weekday, month, day, hour, min); | |
740 | .Ed | |
741 | .Pp | |
742 | To print \*(Pi | |
743 | to five decimal places: | |
744 | .Bd -literal -offset indent | |
745 | #include <math.h> | |
746 | #include <stdio.h> | |
747 | fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); | |
748 | .Ed | |
749 | .Pp | |
750 | To allocate a 128 byte string and print into it: | |
751 | .Bd -literal -offset indent | |
752 | #include <stdio.h> | |
753 | #include <stdlib.h> | |
754 | #include <stdarg.h> | |
755 | char *newfmt(const char *fmt, ...) | |
756 | { | |
757 | char *p; | |
758 | va_list ap; | |
759 | if ((p = malloc(128)) == NULL) | |
760 | return (NULL); | |
761 | va_start(ap, fmt); | |
762 | (void) vsnprintf(p, 128, fmt, ap); | |
763 | va_end(ap); | |
764 | return (p); | |
765 | } | |
766 | .Ed | |
767 | .Sh COMPATIBILITY | |
768 | The conversion formats | |
769 | .Cm \&%D , \&%O , | |
770 | and | |
771 | .Cm \&%U | |
772 | are not standard and | |
773 | are provided only for backward compatibility. | |
774 | The effect of padding the | |
775 | .Cm %p | |
776 | format with zeros (either by the | |
777 | .Cm 0 | |
778 | flag or by specifying a precision), and the benign effect (i.e., none) | |
779 | of the | |
780 | .Cm # | |
781 | flag on | |
782 | .Cm %n | |
783 | and | |
784 | .Cm %p | |
785 | conversions, as well as other | |
786 | nonsensical combinations such as | |
787 | .Cm %Ld , | |
788 | are not standard; such combinations | |
789 | should be avoided. | |
790 | .Sh ERRORS | |
791 | In addition to the errors documented for the | |
792 | .Xr write 2 | |
793 | system call, the | |
794 | .Fn printf | |
795 | family of functions may fail if: | |
796 | .Bl -tag -width Er | |
797 | .It Bq Er EILSEQ | |
798 | An invalid wide character code was encountered. | |
799 | .It Bq Er ENOMEM | |
800 | Insufficient storage space is available. | |
801 | .El | |
802 | .Sh SEE ALSO | |
803 | .Xr printf 1 , | |
804 | .Xr printf_l 3 , | |
805 | .Xr fmtcheck 3 , | |
806 | .Xr scanf 3 , | |
807 | .Xr setlocale 3 , | |
808 | .Xr stdarg 3 , | |
809 | .Xr wprintf 3 | |
810 | .Sh STANDARDS | |
811 | Subject to the caveats noted in the | |
812 | .Sx BUGS | |
813 | section below, the | |
814 | .Fn fprintf , | |
815 | .Fn printf , | |
816 | .Fn sprintf , | |
817 | .Fn vprintf , | |
818 | .Fn vfprintf , | |
819 | and | |
820 | .Fn vsprintf | |
821 | functions | |
822 | conform to | |
823 | .St -ansiC | |
824 | and | |
825 | .St -isoC-99 . | |
826 | With the same reservation, the | |
827 | .Fn snprintf | |
828 | and | |
829 | .Fn vsnprintf | |
830 | functions conform to | |
831 | .St -isoC-99 , | |
832 | while | |
833 | .Fn dprintf | |
834 | and | |
835 | .Fn vdprintf | |
836 | conform to | |
837 | .St -p1003.1-2008 . | |
838 | .Sh HISTORY | |
839 | The functions | |
840 | .Fn asprintf | |
841 | and | |
842 | .Fn vasprintf | |
843 | first appeared in the | |
844 | .Tn GNU C | |
845 | library. | |
846 | These were implemented by | |
847 | .An Peter Wemm Aq Mt peter@FreeBSD.org | |
848 | in | |
849 | .Fx 2.2 , | |
850 | but were later replaced with a different implementation | |
851 | from | |
852 | .Ox 2.3 | |
853 | by | |
854 | .An Todd C. Miller Aq Mt Todd.Miller@courtesan.com . | |
855 | The | |
856 | .Fn dprintf | |
857 | and | |
858 | .Fn vdprintf | |
859 | functions were added in | |
860 | .Fx 8.0 . | |
861 | .Sh BUGS | |
862 | The | |
863 | .Nm | |
864 | family of functions do not correctly handle multibyte characters in the | |
865 | .Fa format | |
866 | argument. | |
867 | .Sh SECURITY CONSIDERATIONS | |
868 | The | |
869 | .Fn sprintf | |
870 | and | |
871 | .Fn vsprintf | |
872 | functions are easily misused in a manner which enables malicious users | |
873 | to arbitrarily change a running program's functionality through | |
874 | a buffer overflow attack. | |
875 | Because | |
876 | .Fn sprintf | |
877 | and | |
878 | .Fn vsprintf | |
879 | assume an infinitely long string, | |
880 | callers must be careful not to overflow the actual space; | |
881 | this is often hard to assure. | |
882 | For safety, programmers should use the | |
883 | .Fn snprintf | |
884 | interface instead. | |
885 | For example: | |
886 | .Bd -literal | |
887 | void | |
888 | foo(const char *arbitrary_string, const char *and_another) | |
889 | { | |
890 | char onstack[8]; | |
891 | ||
892 | #ifdef BAD | |
893 | /* | |
894 | * This first sprintf is bad behavior. Do not use sprintf! | |
895 | */ | |
896 | sprintf(onstack, "%s, %s", arbitrary_string, and_another); | |
897 | #else | |
898 | /* | |
899 | * The following two lines demonstrate better use of | |
900 | * snprintf(). | |
901 | */ | |
902 | snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string, | |
903 | and_another); | |
904 | #endif | |
905 | } | |
906 | .Ed | |
907 | .Pp | |
908 | The | |
909 | .Fn printf | |
910 | and | |
911 | .Fn sprintf | |
912 | family of functions are also easily misused in a manner | |
913 | allowing malicious users to arbitrarily change a running program's | |
914 | functionality by either causing the program | |
915 | to print potentially sensitive data | |
916 | .Dq "left on the stack" , | |
917 | or causing it to generate a memory fault or bus error | |
918 | by dereferencing an invalid pointer. | |
919 | .Pp | |
920 | .Cm %n | |
921 | can be used to write arbitrary data to potentially carefully-selected | |
922 | addresses. | |
923 | Programmers are therefore strongly advised to never pass untrusted strings | |
924 | as the | |
925 | .Fa format | |
926 | argument, as an attacker can put format specifiers in the string | |
927 | to mangle your stack, | |
928 | leading to a possible security hole. | |
929 | This holds true even if the string was built using a function like | |
930 | .Fn snprintf , | |
931 | as the resulting string may still contain user-supplied conversion specifiers | |
932 | for later interpolation by | |
933 | .Fn printf . | |
934 | .Pp | |
935 | Always use the proper secure idiom: | |
936 | .Pp | |
937 | .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);" |