Penguin
Recent Changes
Annotated edit history of printf(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 PRINTF
2 !!!PRINTF
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 EXAMPLES
7 SEE ALSO
8 CONFORMING TO
9 HISTORY
10 BUGS
11 ----
12 !!NAME
13
14
15 printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf - formatted output conversion
16 !!SYNOPSIS
17
18
19 __#include __
20
21
22 __int printf(const char *__''format''__, ...);
23 int fprintf(FILE *__''stream''__, const char
24 *__''format''__, ...);
25 int sprintf(char *__''str''__, const char
26 *__''format''__, ...);
27 int snprintf(char *__''str''__, size_t__
28 ''size''__, const char *__''format''__, ...);
29 int asprintf(char **__''strp''__, const char
30 *__''format''__, ...);
31 int dprintf(int__ ''d''__, const char
32 *__''format''__, ...);__
33
34
35 __#include __
36
37
38 __int vprintf(const char *__''format''__, va_list__
39 ''ap''__);
40 int vfprintf(FILE *__''stream''__, const char
41 *__''format''__, va_list__ ''ap''__);
42 int vsprintf(char *__''str''__, const char
43 *__''format''__, va_list__ ''ap''__);
44 int vsnprintf(char *__''str''__, size_t__
45 ''size''__, const char *__''format''__,
46 va_list__ ''ap''__);
47 int vasprintf(char **__''strp''__, const char
48 *__''format''__, va_list__ ''ap''__);
49 int vdprintf(int__ ''d''__, const char
50 *__''format''__, va_list__
51 ''ap''__);__
52 !!DESCRIPTION
53
54
55 The functions in the __printf__ family produce output
56 according to a ''format'' as described below. The
57 functions __printf__ and __vprintf__ write output to
58 ''stdout'', the standard output stream; __fprintf__
59 and __vfprintf__ write output to the given output
60 ''stream''; __sprintf__, __snprintf__,
61 __vsprintf__ and __vsnprintf__ write to the character
62 string ''str''.
63
64
65 The functions __vprintf__, __vfprintf__,
66 __vsprintf__, __vsnprintf__ are equivalent to the
67 functions __printf__, __fprintf__, __sprintf__,
68 __snprintf__, respectively, except that they are called
69 with a va_list instead of a variable number of arguments.
70 These functions do not call the ''va_end'' macro.
71 Consequently, the value of ''ap'' is undefined after the
72 call. The application should call ''va_end(ap)'' itself
73 afterwards.
74
75
76 These eight functions write the output under the control of
77 a ''format'' string that specifies how subsequent
78 arguments (or arguments accessed via the variable-length
79 argument facilities of stdarg(3)) are converted for
80 output.
81
82
83 __Return value__
84
85
86 These functions return the number of characters printed (not
87 including the trailing `0' used to end output to strings).
88 __snprintf__ and __vsnprintf__ do not write more than
89 ''size'' bytes (including the trailing '0'), and return
90 -1 if the output was truncated due to this limit. (Thus
91 until glibc 2.0.6. Since glibc 2.1 these functions follow
92 the C99 standard and return the number of characters
93 (excluding the trailing '0') which would have been written
94 to the final string if enough space had been
95 available.)
96
97
98 __Format of the format string__
99
100
101 The format string is a character string, beginning and
102 ending in its initial shift state, if any. The format string
103 is composed of zero or more directives: ordinary characters
104 (not __%__), which are copied unchanged to the output
105 stream; and conversion specifications, each of which results
106 in fetching zero or more subsequent arguments. Each
107 conversion specification is introduced by the character
108 __%__, and ends with a ''conversion specifier''. In
109 between there may be (in this order) zero or more
110 ''flags'', an optional minimum ''field width'', an
111 optional ''precision'' and an optional ''length
112 modifier''.
113
114
115 The arguments must correspond properly (after type
116 promotion) with the conversion specifier. By default, the
117 arguments are used in the order given, where each `*' and
118 each conversion specifier asks for the next argument (and it
119 is an error if insufficiently many arguments are given). One
120 can also specify explicitly which argument is taken, at each
121 place where an argument is required, by writing `%m$'
122 instead of `%' and `*m$' instead of `*', where the decimal
123 integer m denotes the position in the argument list of the
124 desired argument, indexed starting from 1.
125 Thus,
126
127
128 printf(
129
130
131 and
132
133
134 printf(
135
136
137 are equivalent. The second style allows repeated references
138 to the same argument. The C99 standard does not include the
139 style using `$', which comes from the Single Unix
140 Specification. If the style using `$' is used, it must be
141 used throughout for all conversions taking an argument and
142 all width and precision arguments, but it may be mixed with
143 `%%' formats which do not consume an argument. There may be
144 no gaps in the numbers of arguments specified using `$'; for
145 example, if arguments 1 and 3 are specified, argument 2 must
146 also be specified somewhere in the format
147 string.
148
149
150 For some numeric conversions a radix character (`decimal
151 point') or thousands' grouping character is used. The actual
152 character used depends on the LC_NUMERIC part of the locale.
153 The POSIX locale uses `.' as radix character, and does not
154 have a grouping character. Thus,
155
156
157 printf(
158
159
160 results in `1234567.89' in the POSIX locale, in `1234567,89'
161 in the nl_NL locale, and in `1.234.567,89' in the da_DK
162 locale.
163
164
165 __The flag characters__
166
167
168 The character % is followed by zero or more of the following
169 flags:
170
171
172 __#__
173
174
175 The value should be converted to an ``alternate form''. For
176 __o__ conversions, the first character of the output
177 string is made zero (by prefixing a 0 if it was not zero
178 already). For __x__ and __X__ conversions, a non-zero
179 result has the string `0x' (or `0X' for __X__
180 conversions) prepended to it. For __a__, __A__,
181 __e__, __E__, __f__, __F__, __g__, and
182 __G__ conversions, the result will always contain a
183 decimal point, even if no digits follow it (normally, a
184 decimal point appears in the results of those conversions
185 only if a digit follows). For __g__ and __G__
186 conversions, trailing zeros are not removed from the result
187 as they would otherwise be. For other conversions, the
188 result is undefined.
189
190
191 __0__
192
193
194 The value should be zero padded. For __d__, __i__,
195 __o__, __u__, __x__, __X__, __a__, __A__,
196 __e__, __E__, __f__, __F__, __g__, and
197 __G__ conversions, the converted value is padded on the
198 left with zeros rather than blanks. If the __0__ and
199 __-__ flags both appear, the __0__ flag is ignored. If
200 a precision is given with a numeric conversion (__d__,
201 __i__, __o__, __u__, __x__, and __X__), the
202 __0__ flag is ignored. For other conversions, the
203 behavior is undefined.
204
205
206 __-__
207
208
209 The converted value is to be left adjusted on the field
210 boundary. (The default is right justification.) Except for
211 __n__ conversions, the converted value is padded on the
212 right with blanks, rather than on the left with blanks or
213 zeros. A __-__ overrides a __0__ if both are
214 given.
215
216
217 __' '__
218
219
220 (a space) A blank should be left before a positive number
221 (or empty string) produced by a signed
222 conversion.
223
224
225 __+__
226
227
228 A sign (+ or -) always be placed before a number produced by
229 a signed conversion. By default a sign is used only for
230 negative numbers. A __+__ overrides a space if both are
231 used.
232
233
234 The five flag characters above are defined in the C
235 standard. The SUSv2 specifies one further flag
236 character.
237
238
239 __'__
240
241
242 For decimal conversion (__i__, __d__, __u__,
243 __f__, __F__, __g__, __G__) the output is to be
244 grouped with thousands' grouping characters if the locale
245 information indicates any. Note that many versions of
246 __gcc__ cannot parse this option and will issue a
247 warning. SUSv2 does not include %'F.
248
249
250 glibc 2.2 adds one further flag character.
251
252
253 __I__
254
255
256 For decimal integer conversion (__i__, __d__,
257 __u__) the output uses the locale's alternative output
258 digits, if any (for example, Arabic digits). However, it
259 does not include any locale definitions with such
260 __outdigits__ defined.
261
262
263 __The field width__
264
265
266 An optional decimal digit string (with nonzero first digit)
267 specifying a minimum field width. If the converted value has
268 fewer characters than the field width, it will be padded
269 with spaces on the left (or right, if the left-adjustment
270 flag has been given). Instead of a decimal digit string one
271 may write `*' or `*m$' (for some decimal integer m) to
272 specify that the field width is given in the next argument,
273 or in the m-th argument, respectively, which must be of type
274 ''int''. A negative field width is taken as a `-' flag
275 followed by a positive field width. In no case does a
276 non-existent or small field width cause truncation of a
277 field; if the result of a conversion is wider than the field
278 width, the field is expanded to contain the conversion
279 result.
280
281
282 __The precision__
283
284
285 An optional precision, in the form of a period (`.')
286 followed by an optional decimal digit string. Instead of a
287 decimal digit string one may write `*' or `*m$' (for some
288 decimal integer m) to specify that the precision is given in
289 the next argument, or in the m-th argument, respectively,
290 which must be of type ''int''. If the precision is given
291 as just `.', or the precision is negative, the precision is
292 taken to be zero. This gives the minimum number of digits to
293 appear for __d__, __i__, __o__, __u__, __x__,
294 and __X__ conversions, the number of digits to appear
295 after the radix character for __a__, __A__, __e__,
296 __E__, __f__, and __F__ conversions, the maximum
297 number of significant digits for __g__ and __G__
298 conversions, or the maximum number of characters to be
299 printed from a string for __s__ and __S__
300 conversions.
301
302
303 __The length modifier__
304
305
306 Here, `integer conversion' stands for __d__, __i__,
307 __o__, __u__, __x__, or __X__
308 conversion.
309
310
311 __hh__
312
313
314 A following integer conversion corresponds to a ''signed
315 char'' or ''unsigned char'' argument, or a following
316 __n__ conversion corresponds to a pointer to a ''signed
317 char'' argument.
318
319
320 __h__
321
322
323 A following integer conversion corresponds to a ''short
324 int'' or ''unsigned short int'' argument, or a
325 following __n__ conversion corresponds to a pointer to a
326 ''short int'' argument.
327
328
329 __l__
330
331
332 (ell) A following integer conversion corresponds to a
333 ''long int'' or ''unsigned long int'' argument, or a
334 following __n__ conversion corresponds to a pointer to a
335 ''long int'' argument, or a following __c__ conversion
336 corresponds to a ''wint_t'' argument, or a following
337 __s__ conversion corresponds to a pointer to
338 ''wchar_t'' argument.
339
340
341 __ll__
342
343
344 (ell-ell). A following integer conversion corresponds to a
345 ''long long int'' or ''unsigned long long int''
346 argument, or a following __n__ conversion corresponds to
347 a pointer to a ''long long int'' argument.
348
349
350 __L__
351
352
353 A following __a__, __A__, __e__, __E__,
354 __f__, __F__, __g__, or __G__ conversion
355 corresponds to a ''long double'' argument. (C99 allows
356 %LF, but SUSv2 does not.)
357
358
359 __q__
360
361
362 (`quad'. BSD 4.4 and Linux libc5 only. Don't use.) This is a
363 synonym for __ll__.
364
365
366 __j__
367
368
369 A following integer conversion corresponds to an
370 ''intmax_t'' or ''uintmax_t'' argument.
371
372
373 __z__
374
375
376 A following integer conversion corresponds to a
377 ''size_t'' or ''ssize_t'' argument. (Linux libc5 has
378 __Z__ with this meaning. Don't use it.)
379
380
381 __t__
382
383
384 A following integer conversion corresponds to a
385 ''ptrdiff_t'' argument.
386
387
388 The SUSv2 only knows about the length modifiers __h__ (in
389 __hd__, __hi__, __ho__, __hx__, __hX__,
390 __hn__) and __l__ (in __ld__, __li__, __lo__,
391 __lx__, __lX__, __ln__, __lc__, __ls__) and
392 __L__ (in __Le__, __LE__, __Lf__, __Lg__,
393 __LG__).
394
395
396 __The conversion specifier__
397
398
399 A character that specifies the type of conversion to be
400 applied. The conversion specifiers and their meanings
401 are:
402
403
404 __d__,__i__
405
406
407 The ''int'' argument is converted to signed decimal
408 notation. The precision, if any, gives the minimum number of
409 digits that must appear; if the converted value requires
410 fewer digits, it is padded on the left with zeros. The
411 default precision is 1. When 0 is printed with an explicit
412 precision 0, the output is empty.
413
414
415 __o__,__u__,__x__,__X__
416
417
418 The ''unsigned int'' argument is converted to unsigned
419 octal (__o__), unsigned decimal (__u__), or unsigned
420 hexadecimal (__x__ and __X__) notation. The letters
421 __abcdef__ are used for __x__ conversions; the letters
422 __ABCDEF__ are used for __X__ conversions. The
423 precision, if any, gives the minimum number of digits that
424 must appear; if the converted value requires fewer digits,
425 it is padded on the left with zeros. The default precision
426 is 1. When 0 is printed with an explicit precision 0, the
427 output is empty.
428
429
430 __e__,__E__
431
432
433 The ''double'' argument is rounded and converted in the
434 style [[-]d__.__ddd__e__
435 __E__ conversion uses
436 the letter __E__ (rather than __e__) to introduce the
437 exponent. The exponent always contains at least two digits;
438 if the value is zero, the exponent is 00.
439
440
441 __f__,__F__
442
443
444 The ''double'' argument is rounded and converted to
445 decimal notation in the style [[-]ddd__.__ddd, where the
446 number of digits after the decimal-point character is equal
447 to the precision specification. If the precision is missing,
448 it is taken as 6; if the precision is explicitly zero, no
449 decimal-point character appears. If a decimal point appears,
450 at least one digit appears before it.
451
452
453 (The SUSv2 does not know about __F__ and says that
454 character string representations for infinity and NaN may be
455 made available. The C99 standard specifies `[[-]inf' or
456 `[[-]infinity' for infinity, and a string starting with `nan'
457 for NaN, in the case of __f__ conversion, and `[[-]INF' or
458 `[[-]INFINITY' or `NAN*' in the case of __F__
459 conversion.)
460
461
462 __g__,__G__
463
464
465 The ''double'' argument is converted in style __f__ or
466 __e__ (or __F__ or __E__ for __G__ conversions).
467 The precision specifies the number of significant digits. If
468 the precision is missing, 6 digits are given; if the
469 precision is zero, it is treated as 1. Style __e__ is
470 used if the exponent from its conversion is less than -4 or
471 greater than or equal to the precision. Trailing zeros are
472 removed from the fractional part of the result; a decimal
473 point appears only if it is followed by at least one
474 digit.
475
476
477 __a__,__A__
478
479
480 (C99; not in SUSv2) For __a__ conversion, the
481 ''double'' argument is converted to hexadecimal notation
482 (using the letters abcdef) in the style
483 [[-]__0x__h__.__hhhh__p____A__
484 conversion the prefix __0X__, the letters ABCDEF, and the
485 exponent separator __P__ is used. There is one
486 hexadecimal digit before the decimal point, and the number
487 of digits after it is equal to the precision. The default
488 precision suffices for an exact representation of the value
489 if an exact representation in base 2 exists and otherwise is
490 sufficiently large to distinguish values of type
491 ''double''. The digit before the decimal point is
492 unspecified for non-normalized numbers, and nonzero but
493 otherwise unspecified for normalized numbers.
494
495
496 __c__
497
498
499 If no __l__ modifier is present, the ''int'' argument
500 is converted to an ''unsigned char'', and the resulting
501 character is written. If an __l__ modifier is present,
502 the ''wint_t'' (wide character) argument is converted to
503 a multibyte sequence by a call to the __wcrtomb__
504 function, with a conversion state starting in the initial
505 state, and the resulting multibyte string is
506 written.
507
508
509 __s__
510
511
512 If no __l__ modifier is present: The ''const char *''
513 argument is expected to be a pointer to an array of
514 character type (pointer to a string). Characters from the
515 array are written up to (but not including) a terminating
516 __NUL__ character; if a precision is specified, no more
517 than the number specified are written. If a precision is
518 given, no null character need be present; if the precision
519 is not specified, or is greater than the size of the array,
520 the array must contain a terminating __NUL__
521 character.
522
523
524 If an __l__ modifier is present: The ''const wchar_t
525 *'' argument is expected to be a pointer to an array of
526 wide characters. Wide characters from the array are
527 converted to multibyte characters (each by a call to the
528 __wcrtomb__ function, with a conversion state starting in
529 the initial state before the first wide character), up to
530 and including a terminating null wide character. The
531 resulting multibyte characters are written up to (but not
532 including) the terminating null byte. If a precision is
533 specified, no more bytes than the number specified are
534 written, but no partial multibyte characters are written.
535 Note that the precision determines the number of
536 ''bytes'' written, not the number of ''wide
537 characters'' or ''screen positions''. The array must
538 contain a terminating null wide character, unless a
539 precision is given and it is so small that the number of
540 bytes written exceeds it before the end of the array is
541 reached.
542
543
544 __C__
545
546
547 (Not in C99, but in SUSv2.) Synonym for __lc__. Don't
548 use.
549
550
551 __S__
552
553
554 (Not in C99, but in SUSv2.) Synonym for __ls__. Don't
555 use.
556
557
558 __p__
559
560
561 The ''void *'' pointer argument is printed in hexadecimal
562 (as if by __%#x__ or __%#lx__).
563
564
565 __n__
566
567
568 The number of characters written so far is stored into the
569 integer indicated by the ''int *'' (or variant) pointer
570 argument. No argument is converted.
571
572
573 __%__
574
575
576 A `%' is written. No argument is converted. The complete
577 conversion specification is `%%'.
578 !!EXAMPLES
579
580
581 To print pi to five decimal places:
582
583
584 #include
585
586
587 To print a date and time in the form `Sunday, July 3,
588 10:02', where ''weekday'' and ''month'' are pointers
589 to strings:
590
591
592 #include
593
594
595 Many countries use the day-month-year order. Hence, an
596 internationalized version must be able to print the
597 arguments in an order specified by the format:
598
599
600 #include
601
602
603 where ''format'' depends on locale, and may permute the
604 arguments. With the value
605
606
607
608
609 one might obtain `Sonntag, 3. Juli, 10:02'.
610
611
612 To allocate a sufficiently large string and print into it
613 (code correct for both glibc 2.0 and glibc
614 2.1):
615
616
617 #include
618 !!SEE ALSO
619
620
621 printf(1), wcrtomb(3), wprintf(3),
622 scanf(3), locale(5)
623 !!CONFORMING TO
624
625
626 The __fprintf__, __printf__, __sprintf__,
627 __vprintf__, __vfprintf__, and __vsprintf__
628 functions conform to ANSI X3.159-1989 (``ANSI C'') and
629 ISO/IEC 9899:1999 (``ISO C99''). The __snprintf__ and
630 __vsnprintf__ functions conform to ISO/IEC
631 9899:1999.
632
633
634 Concerning the return value of __snprintf__, the SUSv2
635 and the C99 standard contradict each other: when
636 __snprintf__ is called with ''size''=0 then SUSv2
637 stipulates an unspecified return value less than 1, while
638 C99 allows ''str'' to be NULL in this case, and gives the
639 return value (as always) as the number of characters that
640 would have been written in case the output string has been
641 large enough.
642
643
644 Linux libc5 knows about the five C standard flags and the '
645 flag, locale, %m$ and *m$. It knows about the length
646 modifiers h,l,L,Z,q, but accepts L and q both for long
647 doubles and for long long integers (this is a bug). It no
648 longer recognizes FDOU, but adds a new conversion character
649 __m__, which outputs ''strerror(errno)''.
650
651
652 glibc 2.0 adds conversion characters C and S.
653
654
655 glibc 2.1 adds length modifiers hh,j,t,z and conversion
656 characters a,A.
657
658
659 glibc 2.2 adds the conversion character F with C99
660 semantics, and the flag character I.
661 !!HISTORY
662
663
664 Unix V7 defines the three routines __printf__,
665 __fprintf__, __sprintf__, and has the flag -, the
666 width or precision *, the length modifier l, and the
667 conversions doxfegcsu, and also D,O,U,X as synonyms for
668 ld,lo,lu,lx. This is still true for BSD 2.9.1, but BSD 2.10
669 has the flags #, + and
670 __vprintf__, __vfprintf__,
671 __vsprintf__, and warns not to use D,O,U,X. BSD 4.3 Reno
672 has the flag 0, the length modifiers h and L, and the
673 conversions n, p, E, G, X (with current meaning) and
674 deprecates D,O,U. BSD 4.4 introduces the functions
675 __snprintf__ and __vsnprintf__, and the length
676 modifier q. FreeBSD also has functions ''asprintf'' and
677 ''vasprintf'', that allocate a buffer large enough for
678 __sprintf__.
679 !!BUGS
680
681
682 Because __sprintf__ and __vsprintf__ assume an
683 arbitrarily long string, callers must be careful not to
684 overflow the actual space; this is often impossible to
685 assure. Note that the length of the strings produced is
686 locale-dependent and difficult to predict. Use
687 __snprintf__ and __vsnprintf__ instead (or
688 __asprintf__ and __vasprintf__).
689
690
691 Code such as __printf(__''foo''__);__ often
692 indicates a bug, since ''foo'' may contain a % character.
693 If ''foo'' comes from untrusted user input, it may
694 contain %n, causing the __printf__ call to write to
695 memory and creating a security hole.
696 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.