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