]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
3 | .\" This is free documentation; you can redistribute it and/or | |
4 | .\" modify it under the terms of the GNU General Public License as | |
5 | .\" published by the Free Software Foundation; either version 2 of | |
6 | .\" the License, or (at your option) any later version. | |
7 | .\" | |
8 | .\" The GNU General Public License's references to "object code" | |
9 | .\" and "executables" are to be interpreted as the output of any | |
10 | .\" document formatting or typesetting system, including | |
11 | .\" intermediate and printed output. | |
12 | .\" | |
13 | .\" This manual is distributed in the hope that it will be useful, | |
14 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
16 | .\" GNU General Public License for more details. | |
17 | .\" | |
18 | .\" You should have received a copy of the GNU General Public | |
19 | .\" License along with this manual; if not, write to the Free | |
20 | .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, | |
21 | .\" USA. | |
22 | .\" | |
23 | .\" | |
24 | .\" Earlier versions of this page influenced the present text. | |
25 | .\" It was derived from a Berkeley page with version | |
26 | .\" @(#)printf.3 6.14 (Berkeley) 7/30/91 | |
27 | .\" converted for Linux by faith@cs.unc.edu, updated by | |
28 | .\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible. | |
29 | .\" | |
30 | .\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99. | |
31 | .\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes | |
32 | .\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes | |
33 | .\" | |
2ccfac8b | 34 | .TH PRINTF 3 2007-11-26 "GNU" "Linux Programmer's Manual" |
fea681da MK |
35 | .SH NAME |
36 | printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf \- formatted output conversion | |
37 | .SH SYNOPSIS | |
38 | .B #include <stdio.h> | |
39 | .sp | |
40 | .BI "int printf(const char *" format ", ...);" | |
41 | .br | |
42 | .BI "int fprintf(FILE *" stream ", const char *" format ", ...);" | |
43 | .br | |
44 | .BI "int sprintf(char *" str ", const char *" format ", ...);" | |
45 | .br | |
46 | .BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);" | |
47 | .sp | |
48 | .B #include <stdarg.h> | |
49 | .sp | |
50 | .BI "int vprintf(const char *" format ", va_list " ap ); | |
51 | .br | |
52 | .BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap ); | |
53 | .br | |
54 | .BI "int vsprintf(char *" str ", const char *" format ", va_list " ap ); | |
55 | .br | |
56 | .BI "int vsnprintf(char *" str ", size_t " size ", const char *" format ", va_list " ap ); | |
cc4615cc MK |
57 | .ad |
58 | .sp | |
59 | .in -4n | |
60 | Feature Test Macro Requirements for glibc (see | |
61 | .BR feature_test_macros (7)): | |
62 | .in | |
63 | .sp | |
64 | .ad l | |
65 | .BR snprintf (), | |
66 | .BR vsnprintf (): | |
67 | _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE; or | |
68 | .I "cc -std=c99" | |
69 | .ad b | |
fea681da MK |
70 | .SH DESCRIPTION |
71 | The functions in the | |
e511ffb6 | 72 | .BR printf () |
fea681da MK |
73 | family produce output according to a |
74 | .I format | |
c13182ef MK |
75 | as described below. |
76 | The functions | |
e511ffb6 | 77 | .BR printf () |
fea681da | 78 | and |
e511ffb6 | 79 | .BR vprintf () |
fea681da MK |
80 | write output to |
81 | .IR stdout , | |
82 | the standard output stream; | |
e511ffb6 | 83 | .BR fprintf () |
fea681da | 84 | and |
e511ffb6 | 85 | .BR vfprintf () |
fea681da MK |
86 | write output to the given output |
87 | .IR stream ; | |
e511ffb6 | 88 | .BR sprintf (), |
c13182ef | 89 | .BR snprintf (), |
e511ffb6 | 90 | .BR vsprintf () |
fea681da | 91 | and |
e511ffb6 | 92 | .BR vsnprintf () |
fea681da MK |
93 | write to the character string |
94 | .IR str . | |
95 | .PP | |
96 | The functions | |
11050e19 MK |
97 | .BR snprintf () |
98 | and | |
99 | .BR vsnprintf () | |
100 | write at most | |
101 | .I size | |
102 | bytes (including the trailing null byte ('\e0')) to | |
103 | .IR str . | |
104 | .PP | |
105 | The functions | |
e511ffb6 MK |
106 | .BR vprintf (), |
107 | .BR vfprintf (), | |
108 | .BR vsprintf (), | |
109 | .BR vsnprintf () | |
fea681da | 110 | are equivalent to the functions |
e511ffb6 MK |
111 | .BR printf (), |
112 | .BR fprintf (), | |
113 | .BR sprintf (), | |
114 | .BR snprintf (), | |
f6b55d82 MK |
115 | respectively, except that they are called with a |
116 | .I va_list | |
117 | instead of a variable number of arguments. | |
c13182ef | 118 | These functions do not call the |
fea681da | 119 | .I va_end |
c13182ef | 120 | macro. |
f6b55d82 MK |
121 | Because they invoke the |
122 | .I va_arg | |
123 | macro, the value of | |
fea681da | 124 | .I ap |
c13182ef | 125 | is undefined after the call. |
f6b55d82 | 126 | See |
31b640cb | 127 | .BR stdarg (3). |
fea681da MK |
128 | .PP |
129 | These eight functions write the output under the control of a | |
130 | .I format | |
131 | string that specifies how subsequent arguments (or arguments accessed via | |
132 | the variable-length argument facilities of | |
133 | .BR stdarg (3)) | |
134 | are converted for output. | |
135 | .SS "Return value" | |
136 | Upon successful return, these functions return the number of characters | |
137 | printed (not including the trailing '\e0' used to end output to strings). | |
11050e19 | 138 | |
fea681da | 139 | The functions |
6e1ffb98 | 140 | .BR snprintf () |
c13182ef | 141 | and |
6e1ffb98 | 142 | .BR vsnprintf () |
fea681da MK |
143 | do not write more than |
144 | .I size | |
145 | bytes (including the trailing '\e0'). | |
146 | If the output was truncated due to this limit then the return value | |
147 | is the number of characters (not including the trailing '\e0') | |
148 | which would have been written to the final string if enough space | |
c13182ef MK |
149 | had been available. |
150 | Thus, a return value of | |
fea681da | 151 | .I size |
c13182ef MK |
152 | or more means that the output was truncated. |
153 | (See also below under NOTES.) | |
11050e19 | 154 | |
fea681da MK |
155 | If an output error is encountered, a negative value is returned. |
156 | .SS "Format of the format string" | |
157 | The format string is a character string, beginning and ending | |
158 | in its initial shift state, if any. | |
159 | The format string is composed of zero or more directives: ordinary | |
160 | characters (not | |
161 | .BR % ), | |
162 | which are copied unchanged to the output stream; | |
163 | and conversion specifications, each of which results in fetching zero or | |
c13182ef MK |
164 | more subsequent arguments. |
165 | Each conversion specification is introduced by | |
fea681da MK |
166 | the character |
167 | .BR % , | |
168 | and ends with a | |
169 | .IR "conversion specifier" . | |
170 | In between there may be (in this order) zero or more | |
171 | .IR flags , | |
172 | an optional minimum | |
173 | .IR "field width" , | |
174 | an optional | |
175 | .I precision | |
176 | and an optional | |
177 | .IR "length modifier" . | |
178 | ||
179 | The arguments must correspond properly (after type promotion) with the | |
c13182ef MK |
180 | conversion specifier. |
181 | By default, the arguments are used in the order | |
fea681da MK |
182 | given, where each `*' and each conversion specifier asks for the next |
183 | argument (and it is an error if insufficiently many arguments are given). | |
184 | One can also specify explicitly which argument is taken, | |
185 | at each place where an argument is required, by writing `%m$' instead | |
186 | of `%' and `*m$' instead of `*', where the decimal integer m denotes | |
187 | the position in the argument list of the desired argument, indexed starting | |
c13182ef MK |
188 | from 1. |
189 | Thus, | |
bd191423 | 190 | .in +4n |
fea681da | 191 | .nf |
7295b7ed | 192 | |
bd191423 | 193 | printf("%*d", width, num); |
7295b7ed | 194 | |
fea681da | 195 | .fi |
bd191423 | 196 | .in |
fea681da | 197 | and |
bd191423 | 198 | .in +4n |
fea681da | 199 | .nf |
7295b7ed | 200 | |
bd191423 | 201 | printf("%2$*1$d", width, num); |
7295b7ed | 202 | |
fea681da | 203 | .fi |
bd191423 | 204 | .in |
c13182ef MK |
205 | are equivalent. |
206 | The second style allows repeated references to the | |
207 | same argument. | |
208 | The C99 standard does not include the style using `$', | |
209 | which comes from the Single Unix Specification. | |
210 | If the style using | |
fea681da MK |
211 | `$' is used, it must be used throughout for all conversions taking an |
212 | argument and all width and precision arguments, but it may be mixed | |
c13182ef MK |
213 | with `%%' formats which do not consume an argument. |
214 | There may be no | |
fea681da MK |
215 | gaps in the numbers of arguments specified using `$'; for example, if |
216 | arguments 1 and 3 are specified, argument 2 must also be specified | |
217 | somewhere in the format string. | |
218 | ||
219 | For some numeric conversions a radix character (`decimal point') or | |
c13182ef MK |
220 | thousands' grouping character is used. |
221 | The actual character used | |
2f0af33b MK |
222 | depends on the |
223 | .B LC_NUMERIC | |
224 | part of the locale. | |
c13182ef | 225 | The POSIX locale |
fea681da MK |
226 | uses `.' as radix character, and does not have a grouping character. |
227 | Thus, | |
a6e2f128 | 228 | .in +4n |
fea681da | 229 | .nf |
7295b7ed | 230 | printf("%'.2f", 1234567.89); |
fea681da | 231 | .fi |
a6e2f128 | 232 | .in |
fea681da MK |
233 | results in `1234567.89' in the POSIX locale, in `1234567,89' in the |
234 | nl_NL locale, and in `1.234.567,89' in the da_DK locale. | |
235 | .SS "The flag characters" | |
236 | The character % is followed by zero or more of the following flags: | |
237 | .TP | |
238 | .B # | |
324633ae | 239 | The value should be converted to an "alternate form". |
fea681da | 240 | For |
0daa9e92 | 241 | .B o |
fea681da MK |
242 | conversions, the first character of the output string is made zero |
243 | (by prefixing a 0 if it was not zero already). | |
244 | For | |
245 | .B x | |
246 | and | |
247 | .B X | |
ca5ac066 | 248 | conversions, a non-zero result has the string `0x' (or `0X' for |
fea681da | 249 | .B X |
c13182ef MK |
250 | conversions) prepended to it. |
251 | For | |
fea681da MK |
252 | .BR a , |
253 | .BR A , | |
254 | .BR e , | |
255 | .BR E , | |
256 | .BR f , | |
257 | .BR F , | |
258 | .BR g , | |
259 | and | |
260 | .B G | |
261 | conversions, the result will always contain a decimal point, even if no | |
262 | digits follow it (normally, a decimal point appears in the results of those | |
c13182ef MK |
263 | conversions only if a digit follows). |
264 | For | |
fea681da MK |
265 | .B g |
266 | and | |
267 | .B G | |
268 | conversions, trailing zeros are not removed from the result as they would | |
269 | otherwise be. | |
270 | For other conversions, the result is undefined. | |
271 | .TP | |
272 | .B \&0 | |
c13182ef MK |
273 | The value should be zero padded. |
274 | For | |
fea681da MK |
275 | .BR d , |
276 | .BR i , | |
277 | .BR o , | |
278 | .BR u , | |
279 | .BR x , | |
280 | .BR X , | |
281 | .BR a , | |
282 | .BR A , | |
283 | .BR e , | |
284 | .BR E , | |
285 | .BR f , | |
286 | .BR F , | |
287 | .BR g , | |
288 | and | |
289 | .B G | |
290 | conversions, the converted value is padded on the left with zeros rather | |
291 | than blanks. | |
292 | If the | |
293 | .B \&0 | |
294 | and | |
295 | .B \- | |
296 | flags both appear, the | |
297 | .B \&0 | |
298 | flag is ignored. | |
299 | If a precision is given with a numeric conversion | |
b9d200ce | 300 | .RB ( d , |
fea681da MK |
301 | .BR i , |
302 | .BR o , | |
303 | .BR u , | |
304 | .BR x , | |
305 | and | |
306 | .BR X ), | |
307 | the | |
308 | .B \&0 | |
309 | flag is ignored. | |
310 | For other conversions, the behavior is undefined. | |
311 | .TP | |
312 | .B \- | |
313 | The converted value is to be left adjusted on the field boundary. | |
c13182ef MK |
314 | (The default is right justification.) |
315 | Except for | |
fea681da MK |
316 | .B n |
317 | conversions, the converted value is padded on the right with blanks, rather | |
c13182ef MK |
318 | than on the left with blanks or zeros. |
319 | A | |
fea681da MK |
320 | .B \- |
321 | overrides a | |
322 | .B \&0 | |
323 | if both are given. | |
324 | .TP | |
325 | .B ' ' | |
326 | (a space) A blank should be left before a positive number | |
327 | (or empty string) produced by a signed conversion. | |
328 | .TP | |
329 | .B + | |
4897420e | 330 | A sign (+ or \-) should always be placed before a number produced by a signed |
c13182ef MK |
331 | conversion. |
332 | By default a sign is used only for negative numbers. | |
333 | A | |
fea681da MK |
334 | .B + |
335 | overrides a space if both are used. | |
336 | .PP | |
337 | The five flag characters above are defined in the C standard. | |
338 | The SUSv2 specifies one further flag character. | |
c13182ef | 339 | .TP |
fea681da MK |
340 | .B ' |
341 | For decimal conversion | |
b9d200ce | 342 | .RB ( i , |
fea681da MK |
343 | .BR d , |
344 | .BR u , | |
345 | .BR f , | |
346 | .BR F , | |
347 | .BR g , | |
348 | .BR G ) | |
349 | the output is to be grouped with thousands' grouping characters | |
c13182ef MK |
350 | if the locale information indicates any. |
351 | Note that many versions of | |
8478ee02 | 352 | .BR gcc (1) |
c13182ef MK |
353 | cannot parse this option and will issue a warning. |
354 | SUSv2 does not | |
fea681da MK |
355 | include %'F. |
356 | .PP | |
357 | glibc 2.2 adds one further flag character. | |
358 | .TP | |
359 | .B I | |
360 | For decimal integer conversion | |
b9d200ce | 361 | .RB ( i , |
fea681da MK |
362 | .BR d , |
363 | .BR u ) | |
364 | the output uses the locale's alternative output digits, if any. | |
365 | For example, since glibc 2.2.3 this will give Arabic-Indic digits | |
366 | in the Persian (`fa_IR') locale. | |
367 | .\" outdigits keyword in locale file | |
368 | .SS "The field width" | |
f59a3f19 | 369 | An optional decimal digit string (with non-zero first digit) specifying |
c13182ef MK |
370 | a minimum field width. |
371 | If the converted value has fewer characters | |
fea681da MK |
372 | than the field width, it will be padded with spaces on the left |
373 | (or right, if the left-adjustment flag has been given). | |
374 | Instead of a decimal digit string one may write `*' or `*m$' | |
375 | (for some decimal integer m) to specify that the field width | |
376 | is given in the next argument, or in the m-th argument, respectively, | |
377 | which must be of type | |
378 | .IR int . | |
8c383102 | 379 | A negative field width is taken as a `\-' flag followed by a |
fea681da MK |
380 | positive field width. |
381 | In no case does a non-existent or small field width cause truncation of a | |
382 | field; if the result of a conversion is wider than the field width, the | |
383 | field is expanded to contain the conversion result. | |
384 | .SS "The precision" | |
385 | An optional precision, in the form of a period (`\&.') followed by an | |
386 | optional decimal digit string. | |
387 | Instead of a decimal digit string one may write `*' or `*m$' | |
388 | (for some decimal integer m) to specify that the precision | |
389 | is given in the next argument, or in the m-th argument, respectively, | |
390 | which must be of type | |
391 | .IR int . | |
392 | If the precision is given as just `.', or the precision is negative, | |
393 | the precision is taken to be zero. | |
394 | This gives the minimum number of digits to appear for | |
395 | .BR d , | |
396 | .BR i , | |
397 | .BR o , | |
398 | .BR u , | |
399 | .BR x , | |
400 | and | |
401 | .B X | |
402 | conversions, the number of digits to appear after the radix character for | |
403 | .BR a , | |
404 | .BR A , | |
405 | .BR e , | |
406 | .BR E , | |
407 | .BR f , | |
408 | and | |
409 | .B F | |
410 | conversions, the maximum number of significant digits for | |
411 | .B g | |
412 | and | |
413 | .B G | |
414 | conversions, or the maximum number of characters to be printed from a | |
415 | string for | |
416 | .B s | |
417 | and | |
418 | .B S | |
419 | conversions. | |
420 | .SS "The length modifier" | |
421 | Here, `integer conversion' stands for | |
422 | .BR d , | |
423 | .BR i , | |
424 | .BR o , | |
425 | .BR u , | |
426 | .BR x , | |
427 | or | |
0daa9e92 | 428 | .B X |
fea681da MK |
429 | conversion. |
430 | .TP | |
431 | .B hh | |
432 | A following integer conversion corresponds to a | |
433 | .I signed char | |
434 | or | |
435 | .I unsigned char | |
436 | argument, or a following | |
437 | .B n | |
438 | conversion corresponds to a pointer to a | |
439 | .I signed char | |
440 | argument. | |
441 | .TP | |
442 | .B h | |
443 | A following integer conversion corresponds to a | |
444 | .I short int | |
445 | or | |
446 | .I unsigned short int | |
447 | argument, or a following | |
448 | .B n | |
449 | conversion corresponds to a pointer to a | |
450 | .I short int | |
451 | argument. | |
452 | .TP | |
453 | .B l | |
454 | (ell) A following integer conversion corresponds to a | |
455 | .I long int | |
456 | or | |
457 | .I unsigned long int | |
458 | argument, or a following | |
459 | .B n | |
460 | conversion corresponds to a pointer to a | |
461 | .I long int | |
462 | argument, or a following | |
463 | .B c | |
464 | conversion corresponds to a | |
465 | .I wint_t | |
466 | argument, or a following | |
467 | .B s | |
468 | conversion corresponds to a pointer to | |
469 | .I wchar_t | |
470 | argument. | |
471 | .TP | |
472 | .B ll | |
473 | (ell-ell). | |
474 | A following integer conversion corresponds to a | |
475 | .I long long int | |
476 | or | |
477 | .I unsigned long long int | |
478 | argument, or a following | |
479 | .B n | |
480 | conversion corresponds to a pointer to a | |
481 | .I long long int | |
482 | argument. | |
483 | .TP | |
0daa9e92 | 484 | .B L |
fea681da MK |
485 | A following |
486 | .BR a , | |
487 | .BR A , | |
488 | .BR e , | |
489 | .BR E , | |
490 | .BR f , | |
491 | .BR F , | |
492 | .BR g , | |
493 | or | |
494 | .B G | |
495 | conversion corresponds to a | |
496 | .I long double | |
497 | argument. | |
498 | (C99 allows %LF, but SUSv2 does not.) | |
499 | .TP | |
500 | .B q | |
c13182ef MK |
501 | (`quad'. 4.4BSD and Linux libc5 only. |
502 | Don't use.) | |
fea681da MK |
503 | This is a synonym for |
504 | .BR ll . | |
505 | .TP | |
506 | .B j | |
507 | A following integer conversion corresponds to an | |
508 | .I intmax_t | |
509 | or | |
510 | .I uintmax_t | |
511 | argument. | |
512 | .TP | |
513 | .B z | |
514 | A following integer conversion corresponds to a | |
515 | .I size_t | |
516 | or | |
517 | .I ssize_t | |
c13182ef MK |
518 | argument. |
519 | (Linux libc5 has | |
fea681da | 520 | .B Z |
c13182ef MK |
521 | with this meaning. |
522 | Don't use it.) | |
fea681da MK |
523 | .TP |
524 | .B t | |
525 | A following integer conversion corresponds to a | |
526 | .I ptrdiff_t | |
527 | argument. | |
528 | .PP | |
529 | The SUSv2 only knows about the length modifiers | |
530 | .B h | |
531 | (in | |
532 | .BR hd , | |
533 | .BR hi , | |
534 | .BR ho , | |
535 | .BR hx , | |
536 | .BR hX , | |
537 | .BR hn ) | |
538 | and | |
539 | .B l | |
540 | (in | |
541 | .BR ld , | |
542 | .BR li , | |
543 | .BR lo , | |
544 | .BR lx , | |
545 | .BR lX , | |
546 | .BR ln , | |
547 | .BR lc , | |
548 | .BR ls ) | |
549 | and | |
550 | .B L | |
551 | (in | |
552 | .BR Le , | |
553 | .BR LE , | |
554 | .BR Lf , | |
555 | .BR Lg , | |
556 | .BR LG ). | |
fea681da MK |
557 | .SS "The conversion specifier" |
558 | A character that specifies the type of conversion to be applied. | |
559 | The conversion specifiers and their meanings are: | |
560 | .TP | |
561 | .BR d , i | |
562 | The | |
563 | .I int | |
564 | argument is converted to signed decimal notation. | |
565 | The precision, if any, gives the minimum number of digits | |
566 | that must appear; if the converted value requires fewer digits, it is | |
c13182ef MK |
567 | padded on the left with zeros. |
568 | The default precision is 1. | |
fea681da MK |
569 | When 0 is printed with an explicit precision 0, the output is empty. |
570 | .TP | |
571 | .BR o , u , x , X | |
572 | The | |
573 | .I "unsigned int" | |
574 | argument is converted to unsigned octal | |
b9d200ce | 575 | .RB ( o ), |
fea681da | 576 | unsigned decimal |
b9d200ce | 577 | .RB ( u ), |
fea681da | 578 | or unsigned hexadecimal |
b9d200ce | 579 | .RB ( x |
fea681da MK |
580 | and |
581 | .BR X ) | |
c13182ef MK |
582 | notation. |
583 | The letters | |
fea681da MK |
584 | .B abcdef |
585 | are used for | |
586 | .B x | |
587 | conversions; the letters | |
588 | .B ABCDEF | |
589 | are used for | |
590 | .B X | |
c13182ef MK |
591 | conversions. |
592 | The precision, if any, gives the minimum number of digits | |
fea681da | 593 | that must appear; if the converted value requires fewer digits, it is |
c13182ef MK |
594 | padded on the left with zeros. |
595 | The default precision is 1. | |
fea681da MK |
596 | When 0 is printed with an explicit precision 0, the output is empty. |
597 | .TP | |
598 | .BR e , E | |
599 | The | |
600 | .I double | |
601 | argument is rounded and converted in the style | |
602 | .if \w'\*(Pm'=0 .ds Pm \(+- | |
b9d200ce | 603 | .RB [\-]d \&. ddd e \\*(Pmdd |
ca5ac066 | 604 | where there is one digit before the decimal-point character and the number |
fea681da | 605 | of digits after it is equal to the precision; if the precision is missing, |
ca5ac066 | 606 | it is taken as 6; if the precision is zero, no decimal-point character |
c13182ef MK |
607 | appears. |
608 | An | |
fea681da MK |
609 | .B E |
610 | conversion uses the letter | |
611 | .B E | |
612 | (rather than | |
613 | .BR e ) | |
c13182ef MK |
614 | to introduce the exponent. |
615 | The exponent always contains at least two | |
fea681da MK |
616 | digits; if the value is zero, the exponent is 00. |
617 | .TP | |
618 | .BR f , F | |
619 | The | |
620 | .I double | |
621 | argument is rounded and converted to decimal notation in the style | |
b9d200ce | 622 | .RB [\-]ddd \&. ddd, |
ca5ac066 | 623 | where the number of digits after the decimal-point character is equal to |
c13182ef MK |
624 | the precision specification. |
625 | If the precision is missing, it is taken as | |
ca5ac066 | 626 | 6; if the precision is explicitly zero, no decimal-point character appears. |
fea681da MK |
627 | If a decimal point appears, at least one digit appears before it. |
628 | ||
629 | (The SUSv2 does not know about | |
630 | .B F | |
631 | and says that character string representations for infinity and NaN | |
c13182ef MK |
632 | may be made available. |
633 | The C99 standard specifies `[\-]inf' or `[\-]infinity' | |
fea681da MK |
634 | for infinity, and a string starting with `nan' for NaN, in the case of |
635 | .B f | |
8c383102 | 636 | conversion, and `[\-]INF' or `[\-]INFINITY' or `NAN*' in the case of |
fea681da MK |
637 | .B F |
638 | conversion.) | |
639 | .TP | |
640 | .BR g , G | |
641 | The | |
642 | .I double | |
643 | argument is converted in style | |
644 | .B f | |
645 | or | |
646 | .B e | |
647 | (or | |
648 | .B F | |
649 | or | |
650 | .B E | |
651 | for | |
652 | .B G | |
c13182ef MK |
653 | conversions). |
654 | The precision specifies the number of significant digits. | |
fea681da | 655 | If the precision is missing, 6 digits are given; if the precision is zero, |
c13182ef MK |
656 | it is treated as 1. |
657 | Style | |
fea681da MK |
658 | .B e |
659 | is used if the exponent from its conversion is less than \-4 or greater | |
c13182ef MK |
660 | than or equal to the precision. |
661 | Trailing zeros are removed from the | |
fea681da MK |
662 | fractional part of the result; a decimal point appears only if it is |
663 | followed by at least one digit. | |
664 | .TP | |
665 | .BR a , A | |
666 | (C99; not in SUSv2) For | |
667 | .B a | |
668 | conversion, the | |
669 | .I double | |
670 | argument is converted to hexadecimal notation (using the letters abcdef) | |
671 | in the style | |
b9d200ce | 672 | .RB [\-] 0x h \&. hhhh p \\*(Pmd; |
fea681da MK |
673 | for |
674 | .B A | |
675 | conversion the prefix | |
676 | .BR 0X , | |
677 | the letters ABCDEF, and the exponent separator | |
678 | .B P | |
679 | is used. | |
680 | There is one hexadecimal digit before the decimal point, | |
681 | and the number of digits after it is equal to the precision. | |
682 | The default precision suffices for an exact representation of the value | |
683 | if an exact representation in base 2 exists | |
684 | and otherwise is sufficiently large to distinguish values of type | |
685 | .IR double . | |
686 | The digit before the decimal point is unspecified for non-normalized | |
f59a3f19 | 687 | numbers, and non-zero but otherwise unspecified for normalized numbers. |
fea681da MK |
688 | .TP |
689 | .B c | |
690 | If no | |
691 | .B l | |
692 | modifier is present, the | |
693 | .I int | |
694 | argument is converted to an | |
695 | .IR "unsigned char" , | |
696 | and the resulting character is written. | |
697 | If an | |
698 | .B l | |
699 | modifier is present, the | |
700 | .I wint_t | |
701 | (wide character) argument is converted to a multibyte sequence by a call | |
702 | to the | |
fb186734 | 703 | .BR wcrtomb (3) |
fea681da MK |
704 | function, with a conversion state starting in the initial state, and the |
705 | resulting multibyte string is written. | |
706 | .TP | |
707 | .B s | |
708 | If no | |
709 | .B l | |
710 | modifier is present: The | |
711 | .I "const char *" | |
712 | argument is expected to be a pointer to an array of character type (pointer | |
c13182ef MK |
713 | to a string). |
714 | Characters from the array are written up to (but not | |
28d88c17 MK |
715 | including) a terminating null byte ('\\0'); |
716 | if a precision is specified, no more than the number specified | |
c13182ef MK |
717 | are written. |
718 | If a precision is given, no null byte need be present; | |
fea681da | 719 | if the precision is not specified, or is greater than the size of the |
28d88c17 | 720 | array, the array must contain a terminating null byte. |
fea681da MK |
721 | |
722 | If an | |
723 | .B l | |
724 | modifier is present: The | |
725 | .I "const wchar_t *" | |
726 | argument is expected to be a pointer to an array of wide characters. | |
727 | Wide characters from the array are converted to multibyte characters | |
728 | (each by a call to the | |
fb186734 | 729 | .BR wcrtomb (3) |
fea681da MK |
730 | function, with a conversion state starting in the initial state before |
731 | the first wide character), up to and including a terminating null | |
c13182ef MK |
732 | wide character. |
733 | The resulting multibyte characters are written up to | |
734 | (but not including) the terminating null byte. | |
735 | If a precision is | |
fea681da | 736 | specified, no more bytes than the number specified are written, but |
c13182ef MK |
737 | no partial multibyte characters are written. |
738 | Note that the precision | |
fea681da MK |
739 | determines the number of |
740 | .I bytes | |
741 | written, not the number of | |
742 | .I wide characters | |
743 | or | |
744 | .IR "screen positions" . | |
745 | The array must contain a terminating null wide character, unless a | |
746 | precision is given and it is so small that the number of bytes written | |
747 | exceeds it before the end of the array is reached. | |
748 | .TP | |
749 | .B C | |
750 | (Not in C99, but in SUSv2.) | |
751 | Synonym for | |
752 | .BR lc . | |
753 | Don't use. | |
754 | .TP | |
755 | .B S | |
756 | (Not in C99, but in SUSv2.) | |
757 | Synonym for | |
758 | .BR ls . | |
759 | Don't use. | |
760 | .TP | |
761 | .B p | |
762 | The | |
763 | .I "void *" | |
764 | pointer argument is printed in hexadecimal (as if by | |
765 | .B %#x | |
766 | or | |
767 | .BR %#lx ). | |
768 | .TP | |
769 | .B n | |
770 | The number of characters written so far is stored into the integer | |
771 | indicated by the | |
772 | .I "int *" | |
c13182ef MK |
773 | (or variant) pointer argument. |
774 | No argument is converted. | |
775 | .TP | |
c15f96dd | 776 | .B m |
c13182ef MK |
777 | (Glibc extension.) |
778 | Print output of | |
c15f96dd MK |
779 | .IR strerror(errno) . |
780 | No argument is required. | |
fea681da MK |
781 | .TP |
782 | .B % | |
c13182ef MK |
783 | A `%' is written. |
784 | No argument is converted. | |
785 | The complete conversion | |
fea681da | 786 | specification is `%%'. |
fea681da MK |
787 | .SH "CONFORMING TO" |
788 | The | |
e511ffb6 MK |
789 | .BR fprintf (), |
790 | .BR printf (), | |
791 | .BR sprintf (), | |
792 | .BR vprintf (), | |
793 | .BR vfprintf (), | |
fea681da | 794 | and |
e511ffb6 | 795 | .BR vsprintf () |
68e1685c | 796 | functions conform to C89 and C99. |
fea681da | 797 | The |
e511ffb6 | 798 | .BR snprintf () |
fea681da | 799 | and |
e511ffb6 | 800 | .BR vsnprintf () |
68e1685c | 801 | functions conform to C99. |
fea681da MK |
802 | .PP |
803 | Concerning the return value of | |
e511ffb6 | 804 | .BR snprintf (), |
68e1685c | 805 | SUSv2 and C99 contradict each other: when |
e511ffb6 | 806 | .BR snprintf () |
fea681da MK |
807 | is called with |
808 | .IR size =0 | |
809 | then SUSv2 stipulates an unspecified return value less than 1, | |
810 | while C99 allows | |
811 | .I str | |
812 | to be NULL in this case, and gives the return value (as always) | |
813 | as the number of characters that would have been written in case | |
814 | the output string has been large enough. | |
815 | .PP | |
816 | Linux libc4 knows about the five C standard flags. | |
817 | It knows about the length modifiers h,l,L, and the conversions | |
818 | cdeEfFgGinopsuxX, where F is a synonym for f. | |
819 | Additionally, it accepts D,O,U as synonyms for ld,lo,lu. | |
820 | (This is bad, and caused serious bugs later, when | |
c13182ef MK |
821 | support for %D disappeared.) |
822 | No locale-dependent radix character, | |
fea681da MK |
823 | no thousands' separator, no NaN or infinity, no %m$ and *m$. |
824 | .PP | |
825 | Linux libc5 knows about the five C standard flags and the ' flag, | |
826 | locale, %m$ and *m$. | |
827 | It knows about the length modifiers h,l,L,Z,q, but accepts L and q | |
e3e25559 | 828 | both for \fIlong double\fP and for \fIlong long int\fP (this is a bug). |
c15f96dd | 829 | It no longer recognizes FDOU, but adds the conversion character |
fea681da MK |
830 | .BR m , |
831 | which outputs | |
832 | .IR strerror(errno) . | |
833 | .PP | |
834 | glibc 2.0 adds conversion characters C and S. | |
835 | .PP | |
836 | glibc 2.1 adds length modifiers hh,j,t,z and conversion characters a,A. | |
837 | .PP | |
838 | glibc 2.2 adds the conversion character F with C99 semantics, and the | |
839 | flag character I. | |
2b2581ee MK |
840 | .SH NOTES |
841 | The glibc implementation of the functions | |
842 | .BR snprintf () | |
843 | and | |
844 | .BR vsnprintf () | |
75b94dc3 | 845 | conforms to the C99 standard, that is, behaves as described above, |
2b2581ee MK |
846 | since glibc version 2.1. |
847 | Until glibc 2.0.6 they would return \-1 | |
848 | when the output was truncated. | |
889829be MK |
849 | .\" .SH HISTORY |
850 | .\" Unix V7 defines the three routines | |
851 | .\" .BR printf (), | |
852 | .\" .BR fprintf (), | |
853 | .\" .BR sprintf (), | |
854 | .\" and has the flag \-, the width or precision *, the length modifier l, | |
855 | .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx. | |
856 | .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags | |
857 | .\" #, + and <space> and no longer mentions D,O,U,X. | |
858 | .\" 2.11BSD has | |
859 | .\" .BR vprintf (), | |
860 | .\" .BR vfprintf (), | |
861 | .\" .BR vsprintf (), | |
862 | .\" and warns not to use D,O,U,X. | |
863 | .\" 4.3BSD Reno has the flag 0, the length modifiers h and L, | |
864 | .\" and the conversions n, p, E, G, X (with current meaning) | |
865 | .\" and deprecates D,O,U. | |
866 | .\" 4.4BSD introduces the functions | |
867 | .\" .BR snprintf () | |
868 | .\" and | |
869 | .\" .BR vsnprintf (), | |
870 | .\" and the length modifier q. | |
871 | .\" FreeBSD also has functions | |
872 | .\" .BR asprintf () | |
873 | .\" and | |
874 | .\" .BR vasprintf (), | |
875 | .\" that allocate a buffer large enough for | |
876 | .\" .BR sprintf (). | |
877 | .\" In glibc there are functions | |
878 | .\" .BR dprintf () | |
879 | .\" and | |
880 | .\" .BR vdprintf () | |
881 | .\" that print to a file descriptor instead of a stream. | |
fea681da MK |
882 | .SH BUGS |
883 | Because | |
e511ffb6 | 884 | .BR sprintf () |
fea681da | 885 | and |
e511ffb6 | 886 | .BR vsprintf () |
fea681da | 887 | assume an arbitrarily long string, callers must be careful not to overflow |
c13182ef MK |
888 | the actual space; this is often impossible to assure. |
889 | Note that the length | |
fea681da MK |
890 | of the strings produced is locale-dependent and difficult to predict. |
891 | Use | |
e511ffb6 | 892 | .BR snprintf () |
fea681da | 893 | and |
e511ffb6 | 894 | .BR vsnprintf () |
fea681da | 895 | instead (or |
cc4615cc | 896 | .BR asprintf (3) |
fea681da | 897 | and |
74d32233 | 898 | .BR vasprintf (3)). |
fea681da MK |
899 | .PP |
900 | Linux libc4.[45] does not have a | |
e511ffb6 | 901 | .BR snprintf (), |
fea681da | 902 | but provides a libbsd that contains an |
e511ffb6 | 903 | .BR snprintf () |
fea681da | 904 | equivalent to |
e511ffb6 | 905 | .BR sprintf (), |
75b94dc3 | 906 | that is, one that ignores the |
fea681da MK |
907 | .I size |
908 | argument. | |
909 | Thus, the use of | |
e511ffb6 | 910 | .BR snprintf () |
fea681da MK |
911 | with early libc4 leads to serious security problems. |
912 | .PP | |
913 | Code such as | |
914 | .BI printf( foo ); | |
915 | often indicates a bug, since | |
916 | .I foo | |
c13182ef MK |
917 | may contain a % character. |
918 | If | |
fea681da MK |
919 | .I foo |
920 | comes from untrusted user input, it may contain %n, causing the | |
e511ffb6 | 921 | .BR printf () |
fea681da MK |
922 | call to write to memory and creating a security hole. |
923 | .\" .PP | |
924 | .\" Some floating point conversions under early libc4 | |
925 | .\" caused memory leaks. | |
2b2581ee MK |
926 | .SH EXAMPLE |
927 | .br | |
928 | .if \w'\*(Pi'=0 .ds Pi pi | |
929 | To print \*(Pi to five decimal places: | |
bd191423 | 930 | .in +4n |
2b2581ee MK |
931 | .nf |
932 | ||
933 | #include <math.h> | |
934 | #include <stdio.h> | |
935 | fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); | |
936 | .fi | |
bd191423 | 937 | .in |
2b2581ee MK |
938 | .PP |
939 | To print a date and time in the form `Sunday, July 3, 10:02', | |
940 | where | |
941 | .I weekday | |
942 | and | |
943 | .I month | |
944 | are pointers to strings: | |
bd191423 | 945 | .in +4n |
2b2581ee MK |
946 | .nf |
947 | ||
948 | #include <stdio.h> | |
949 | fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", | |
950 | weekday, month, day, hour, min); | |
951 | .fi | |
bd191423 | 952 | .in |
2b2581ee MK |
953 | .PP |
954 | Many countries use the day-month-year order. | |
955 | Hence, an internationalized version must be able to print | |
956 | the arguments in an order specified by the format: | |
bd191423 | 957 | .in +4n |
2b2581ee MK |
958 | .nf |
959 | ||
960 | #include <stdio.h> | |
961 | fprintf(stdout, format, | |
962 | weekday, month, day, hour, min); | |
963 | ||
964 | .fi | |
bd191423 | 965 | .in |
2b2581ee MK |
966 | where |
967 | .I format | |
968 | depends on locale, and may permute the arguments. | |
969 | With the value | |
bd191423 | 970 | .in +4n |
2b2581ee MK |
971 | .nf |
972 | "%1$s, %3$d. %2$s, %4$d:%5$.2d\en" | |
973 | .fi | |
bd191423 | 974 | .in |
2b2581ee MK |
975 | one might obtain `Sonntag, 3. Juli, 10:02'. |
976 | .PP | |
977 | To allocate a sufficiently large string and print into it | |
978 | (code correct for both glibc 2.0 and glibc 2.1): | |
2b2581ee MK |
979 | .nf |
980 | ||
981 | #include <stdio.h> | |
982 | #include <stdlib.h> | |
983 | #include <stdarg.h> | |
984 | ||
985 | char * | |
986 | make_message(const char *fmt, ...) | |
987 | { | |
988 | /* Guess we need no more than 100 bytes. */ | |
989 | int n, size = 100; | |
990 | char *p, *np; | |
991 | va_list ap; | |
992 | ||
993 | if ((p = malloc(size)) == NULL) | |
994 | return NULL; | |
995 | ||
996 | while (1) { | |
997 | /* Try to print in the allocated space. */ | |
998 | va_start(ap, fmt); | |
999 | n = vsnprintf(p, size, fmt, ap); | |
1000 | va_end(ap); | |
1001 | /* If that worked, return the string. */ | |
1002 | if (n > \-1 && n < size) | |
1003 | return p; | |
1004 | /* Else try again with more space. */ | |
1005 | if (n > \-1) /* glibc 2.1 */ | |
1006 | size = n+1; /* precisely what is needed */ | |
1007 | else /* glibc 2.0 */ | |
1008 | size *= 2; /* twice the old size */ | |
1009 | if ((np = realloc (p, size)) == NULL) { | |
1010 | free(p); | |
1011 | return NULL; | |
1012 | } else { | |
1013 | p = np; | |
1014 | } | |
1015 | } | |
1016 | } | |
1017 | .fi | |
fea681da MK |
1018 | .SH "SEE ALSO" |
1019 | .BR printf (1), | |
1020 | .BR asprintf (3), | |
1021 | .BR dprintf (3), | |
1022 | .BR scanf (3), | |
9fcfcba0 | 1023 | .BR setlocale (3), |
fea681da MK |
1024 | .BR wcrtomb (3), |
1025 | .BR wprintf (3), | |
1026 | .BR locale (5) |