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