1 .\" Copyright (c) 1990, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
5 .\" Chris Torek and the American National Standards Committee X3,
6 .\" on Information Processing Systems.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed by the University of
19 .\" California, Berkeley and its contributors.
20 .\" 4. Neither the name of the University nor the names of its contributors
21 .\" may be used to endorse or promote products derived from this software
22 .\" without specific prior written permission.
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .\" @(#)printf.3 8.1 (Berkeley) 6/4/93
37 .\" $FreeBSD: src/lib/libc/stdio/printf.3,v 1.17.2.11 2003/03/02 07:29:33 tjr Exp $
38 .\" $DragonFly: src/lib/libc/stdio/printf.3,v 1.2 2003/06/17 04:26:46 dillon Exp $
44 .Nm printf , fprintf , sprintf , snprintf , asprintf ,
45 .Nm vprintf , vfprintf, vsprintf , vsnprintf , vasprintf
46 .Nd formatted output conversion
52 .Fn printf "const char *format" ...
54 .Fn fprintf "FILE *stream" "const char *format" ...
56 .Fn sprintf "char *str" "const char *format" ...
58 .Fn snprintf "char *str" "size_t size" "const char *format" ...
60 .Fn asprintf "char **ret" "const char *format" ...
63 .Fn vprintf "const char *format" "va_list ap"
65 .Fn vfprintf "FILE *stream" "const char *format" "va_list ap"
67 .Fn vsprintf "char *str" "const char *format" "va_list ap"
69 .Fn vsnprintf "char *str" "size_t size" "const char *format" "va_list ap"
71 .Fn vasprintf "char **ret" "const char *format" "va_list ap"
75 family of functions produces output according to a
83 the standard output stream;
87 write output to the given output
94 write to the character string
100 dynamically allocate a new string with
103 These functions write the output under the control of a
105 string that specifies how subsequent arguments
106 (or arguments accessed via the variable-length argument facilities of
108 are converted for output.
110 These functions return the number of characters printed
111 (not including the trailing
113 used to end output to strings) or a negative value if an output error occurs,
118 which return the number of characters that would have been printed if the
121 (again, not including the final
129 to be a pointer to a buffer sufficiently large to hold the formatted string.
130 This pointer should be passed to
132 to release the allocated storage when it is no longer needed.
133 If sufficient space cannot be allocated,
137 will return -1 and set
148 of the characters printed into the output string
151 character then gets the terminating
153 if the return value is greater than or equal to the
155 argument, the string was too short
156 and some of the printed characters were discarded.
161 effectively assume an infinite
164 The format string is composed of zero or more directives:
169 which are copied unchanged to the output stream;
170 and conversion specifications, each of which results
171 in fetching zero or more subsequent arguments.
172 Each conversion specification is introduced by
176 The arguments must correspond properly (after type promotion)
177 with the conversion specifier.
180 the following appear in sequence:
183 An optional field, consisting of a decimal digit string followed by a
185 specifying the next argument to access.
186 If this field is not provided, the argument following the last
187 argument accessed will be used.
188 Arguments are numbered starting at
190 If unaccessed arguments in the format string are interspersed with ones that
191 are accessed the results will be indeterminate.
193 Zero or more of the following flags:
199 specifying that the value should be converted to an
202 .Cm c , d , i , n , p , s ,
205 conversions, this option has no effect.
208 conversions, the precision of the number is increased to force the first
209 character of the output string to a zero (except if a zero value is printed
210 with an explicit precision of zero).
215 conversions, a non-zero result has the string
221 conversions) prepended to it.
226 conversions, the result will always contain a decimal point, even if no
227 digits follow it (normally, a decimal point appears in the results of
228 those conversions only if a digit follows).
233 conversions, trailing zeros are not removed from the result as they
239 character specifying zero padding.
240 For all conversions except
242 the converted value is padded on the left with zeros rather than blanks.
243 If a precision is given with a numeric conversion
244 .Cm ( d , i , o , u , i , x ,
251 A negative field width flag
253 indicates the converted value is to be left adjusted on the field boundary.
256 conversions, the converted value is padded on the right with blanks,
257 rather than on the left with blanks or zeros.
264 A space, specifying that a blank should be left before a positive number
265 produced by a signed conversion
266 .Cm ( d , e , E , f , g , G ,
272 character specifying that a sign always be placed before a
273 number produced by a signed conversion.
276 overrides a space if both are used.
279 An optional decimal digit string specifying a minimum field width.
280 If the converted value has fewer characters than the field width, it will
281 be padded with spaces on the left (or right, if the left-adjustment
282 flag has been given) to fill out
285 An optional precision, in the form of a period
288 optional digit string.
289 If the digit string is omitted, the precision is taken as zero.
290 This gives the minimum number of digits to appear for
291 .Cm d , i , o , u , x ,
294 conversions, the number of digits to appear after the decimal-point for
298 conversions, the maximum number of significant digits for
302 conversions, or the maximum number of characters to be printed from a
307 The optional character
309 specifying that a following
310 .Cm d , i , o , u , x ,
313 conversion corresponds to a
316 .Vt unsigned short int
317 argument, or that a following
319 conversion corresponds to a pointer to a
323 The optional character
325 (ell) specifying that a following
326 .Cm d , i , o , u , x ,
329 conversion applies to a pointer to a
332 .Vt unsigned long int
333 argument, or that a following
335 conversion corresponds to a pointer to a
339 The optional characters
341 (ell ell) specifying that a following
342 .Cm d , i , o , u , x ,
345 conversion applies to a pointer to a
348 .Vt unsigned long long int
349 argument, or that a following
351 conversion corresponds to a pointer to a
355 The optional character
357 specifying that a following
358 .Cm d , i , o , u , x ,
361 conversion corresponds to a
364 .Vt unsigned quad int
365 argument, or that a following
367 conversion corresponds to a pointer to a
373 specifying that a following
377 conversion corresponds to a
381 A character that specifies the type of conversion to be applied.
384 A field width or precision, or both, may be indicated by
387 or an asterisk followed by one or more decimal digits and a
393 argument supplies the field width or precision.
394 A negative field width is treated as a left adjustment flag followed by a
395 positive field width; a negative precision is treated as though it were
397 If a single format directive mixes positional (nn$)
398 and non-positional arguments, the results are undefined.
400 The conversion specifiers and their meanings are:
401 .Bl -tag -width "diouxX"
405 (or appropriate variant) argument is converted to signed decimal
413 or unsigned hexadecimal
422 conversions; the letters
427 The precision, if any, gives the minimum number of digits that must
428 appear; if the converted value requires fewer digits, it is padded on
433 argument is converted to signed decimal, unsigned octal, or unsigned
434 decimal, as if the format had been
439 These conversion characters are deprecated, and will eventually disappear.
443 argument is rounded and converted in the style
444 .Oo \- Oc Ns d Ns Cm \&. Ns ddd Ns Cm e Ns \\*[Pm]dd
445 where there is one digit before the
446 decimal-point character
447 and the number of digits after it is equal to the precision;
448 if the precision is missing,
449 it is taken as 6; if the precision is
450 zero, no decimal-point character appears.
453 conversion uses the letter
457 to introduce the exponent.
458 The exponent always contains at least two digits; if the value is zero,
463 argument is rounded and converted to decimal notation in the style
464 .Oo \- Oc Ns ddd Ns Cm \&. Ns ddd ,
465 where the number of digits after the decimal-point character
466 is equal to the precision specification.
467 If the precision is missing, it is taken as 6; if the precision is
468 explicitly zero, no decimal-point character appears.
469 If a decimal point appears, at least one digit appears before it.
473 argument is converted in style
482 The precision specifies the number of significant digits.
483 If the precision is missing, 6 digits are given; if the precision is zero,
487 is used if the exponent from its conversion is less than -4 or greater than
488 or equal to the precision.
489 Trailing zeros are removed from the fractional part of the result; a
490 decimal point appears only if it is followed by at least one digit.
494 argument is converted to an
496 and the resulting character is written.
500 argument is expected to be a pointer to an array of character type (pointer
502 Characters from the array are written up to (but not including)
506 if a precision is specified, no more than the number specified are
508 If a precision is given, no null character
509 need be present; if the precision is not specified, or is greater than
510 the size of the array, the array must contain a terminating
516 pointer argument is printed in hexadecimal (as if by
521 The number of characters written so far is stored into the
522 integer indicated by the
524 (or variant) pointer argument.
525 No argument is converted.
530 No argument is converted.
531 The complete conversion specification
536 In no case does a non-existent or small field width cause truncation of
537 a field; if the result of a conversion is wider than the field width, the
538 field is expanded to contain the conversion result.
540 To print a date and time in the form
541 .Dq Li "Sunday, July 3, 10:02" ,
546 are pointers to strings:
547 .Bd -literal -offset indent
549 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
550 weekday, month, day, hour, min);
554 to five decimal places:
555 .Bd -literal -offset indent
558 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
561 To allocate a 128 byte string and print into it:
562 .Bd -literal -offset indent
566 char *newfmt(const char *fmt, ...)
570 if ((p = malloc(128)) == NULL)
573 (void) vsnprintf(p, 128, fmt, ap);
579 In addition to the errors documented for the
583 family of functions may fail if:
586 Insufficient storage space is available.
608 first appeared in the
611 These were implemented by
612 .An Peter Wemm Aq peter@FreeBSD.org
615 but were later replaced with a different implementation
617 .An Todd C. Miller Aq Todd.Miller@courtesan.com
621 The conversion formats
626 are provided only for backward compatibility.
627 The effect of padding the
629 format with zeros (either by the
631 flag or by specifying a precision), and the benign effect (i.e., none)
638 conversions, as well as other
639 nonsensical combinations such as
641 are not standard; such combinations
648 assume an infinitely long string,
649 callers must be careful not to overflow the actual space;
650 this is often hard to assure.
651 For safety, programmers should use the
654 Unfortunately, this interface is not portable.