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.3 2005/01/04 00:00:52 cpressey 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 Upon success, these functions return the number of characters printed
111 (not including the trailing
113 used to end output to strings),
118 the number of characters that would have been printed if the
121 (again, not including the final
123 All of these function return a negative value if an output error occurs.
130 to be a pointer to a buffer sufficiently large to hold the formatted string.
131 This pointer should be passed to
133 to release the allocated storage when it is no longer needed.
134 If sufficient space cannot be allocated,
138 will return -1 and set
149 of the characters printed into the output string
152 character then gets the terminating
154 if the return value is greater than or equal to the
156 argument, the string was too short
157 and some of the printed characters were discarded.
162 effectively assume an infinite
165 The format string is composed of zero or more directives:
170 which are copied unchanged to the output stream;
171 and conversion specifications, each of which results
172 in fetching zero or more subsequent arguments.
173 Each conversion specification is introduced by
177 The arguments must correspond properly (after type promotion)
178 with the conversion specifier.
181 the following appear in sequence:
184 An optional field, consisting of a decimal digit string followed by a
186 specifying the next argument to access.
187 If this field is not provided, the argument following the last
188 argument accessed will be used.
189 Arguments are numbered starting at
191 If unaccessed arguments in the format string are interspersed with ones that
192 are accessed the results will be indeterminate.
194 Zero or more of the following flags:
200 specifying that the value should be converted to an
203 .Cm c , d , i , n , p , s ,
206 conversions, this option has no effect.
209 conversions, the precision of the number is increased to force the first
210 character of the output string to a zero (except if a zero value is printed
211 with an explicit precision of zero).
216 conversions, a non-zero result has the string
222 conversions) prepended to it.
227 conversions, the result will always contain a decimal point, even if no
228 digits follow it (normally, a decimal point appears in the results of
229 those conversions only if a digit follows).
234 conversions, trailing zeros are not removed from the result as they
240 character specifying zero padding.
241 For all conversions except
243 the converted value is padded on the left with zeros rather than blanks.
244 If a precision is given with a numeric conversion
245 .Cm ( d , i , o , u , i , x ,
252 A negative field width flag
254 indicates the converted value is to be left adjusted on the field boundary.
257 conversions, the converted value is padded on the right with blanks,
258 rather than on the left with blanks or zeros.
265 A space, specifying that a blank should be left before a positive number
266 produced by a signed conversion
267 .Cm ( d , e , E , f , g , G ,
273 character specifying that a sign always be placed before a
274 number produced by a signed conversion.
277 overrides a space if both are used.
280 An optional decimal digit string specifying a minimum field width.
281 If the converted value has fewer characters than the field width, it will
282 be padded with spaces on the left (or right, if the left-adjustment
283 flag has been given) to fill out
286 An optional precision, in the form of a period
289 optional digit string.
290 If the digit string is omitted, the precision is taken as zero.
291 This gives the minimum number of digits to appear for
292 .Cm d , i , o , u , x ,
295 conversions, the number of digits to appear after the decimal-point for
299 conversions, the maximum number of significant digits for
303 conversions, or the maximum number of characters to be printed from a
308 The optional character
310 specifying that a following
311 .Cm d , i , o , u , x ,
314 conversion corresponds to a
317 .Vt unsigned short int
318 argument, or that a following
320 conversion corresponds to a pointer to a
324 The optional character
326 (ell) specifying that a following
327 .Cm d , i , o , u , x ,
330 conversion applies to a pointer to a
333 .Vt unsigned long int
334 argument, or that a following
336 conversion corresponds to a pointer to a
340 The optional characters
342 (ell ell) specifying that a following
343 .Cm d , i , o , u , x ,
346 conversion applies to a pointer to a
349 .Vt unsigned long long int
350 argument, or that a following
352 conversion corresponds to a pointer to a
356 The optional character
358 specifying that a following
359 .Cm d , i , o , u , x ,
362 conversion corresponds to a
365 .Vt unsigned quad int
366 argument, or that a following
368 conversion corresponds to a pointer to a
374 specifying that a following
378 conversion corresponds to a
382 A character that specifies the type of conversion to be applied.
385 A field width or precision, or both, may be indicated by
388 or an asterisk followed by one or more decimal digits and a
394 argument supplies the field width or precision.
395 A negative field width is treated as a left adjustment flag followed by a
396 positive field width; a negative precision is treated as though it were
398 If a single format directive mixes positional (nn$)
399 and non-positional arguments, the results are undefined.
401 The conversion specifiers and their meanings are:
402 .Bl -tag -width "diouxX"
406 (or appropriate variant) argument is converted to signed decimal
414 or unsigned hexadecimal
423 conversions; the letters
428 The precision, if any, gives the minimum number of digits that must
429 appear; if the converted value requires fewer digits, it is padded on
434 argument is converted to signed decimal, unsigned octal, or unsigned
435 decimal, as if the format had been
440 These conversion characters are deprecated, and will eventually disappear.
444 argument is rounded and converted in the style
445 .Oo \- Oc Ns d Ns Cm \&. Ns ddd Ns Cm e Ns \\*[Pm]dd
446 where there is one digit before the
447 decimal-point character
448 and the number of digits after it is equal to the precision;
449 if the precision is missing,
450 it is taken as 6; if the precision is
451 zero, no decimal-point character appears.
454 conversion uses the letter
458 to introduce the exponent.
459 The exponent always contains at least two digits; if the value is zero,
464 argument is rounded and converted to decimal notation in the style
465 .Oo \- Oc Ns ddd Ns Cm \&. Ns ddd ,
466 where the number of digits after the decimal-point character
467 is equal to the precision specification.
468 If the precision is missing, it is taken as 6; if the precision is
469 explicitly zero, no decimal-point character appears.
470 If a decimal point appears, at least one digit appears before it.
474 argument is converted in style
483 The precision specifies the number of significant digits.
484 If the precision is missing, 6 digits are given; if the precision is zero,
488 is used if the exponent from its conversion is less than -4 or greater than
489 or equal to the precision.
490 Trailing zeros are removed from the fractional part of the result; a
491 decimal point appears only if it is followed by at least one digit.
495 argument is converted to an
497 and the resulting character is written.
501 argument is expected to be a pointer to an array of character type (pointer
503 Characters from the array are written up to (but not including)
507 if a precision is specified, no more than the number specified are
509 If a precision is given, no null character
510 need be present; if the precision is not specified, or is greater than
511 the size of the array, the array must contain a terminating
517 pointer argument is printed in hexadecimal (as if by
522 The number of characters written so far is stored into the
523 integer indicated by the
525 (or variant) pointer argument.
526 No argument is converted.
531 No argument is converted.
532 The complete conversion specification
537 In no case does a non-existent or small field width cause truncation of
538 a field; if the result of a conversion is wider than the field width, the
539 field is expanded to contain the conversion result.
541 To print a date and time in the form
542 .Dq Li "Sunday, July 3, 10:02" ,
547 are pointers to strings:
548 .Bd -literal -offset indent
550 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
551 weekday, month, day, hour, min);
555 to five decimal places:
556 .Bd -literal -offset indent
559 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
562 To allocate a 128 byte string and print into it:
563 .Bd -literal -offset indent
567 char *newfmt(const char *fmt, ...)
571 if ((p = malloc(128)) == NULL)
574 (void) vsnprintf(p, 128, fmt, ap);
580 In addition to the errors documented for the
584 family of functions may fail if:
587 Insufficient storage space is available.
609 first appeared in the
612 These were implemented by
613 .An Peter Wemm Aq peter@FreeBSD.org
616 but were later replaced with a different implementation
618 .An Todd C. Miller Aq Todd.Miller@courtesan.com
622 The conversion formats
627 are provided only for backward compatibility.
628 The effect of padding the
630 format with zeros (either by the
632 flag or by specifying a precision), and the benign effect (i.e., none)
639 conversions, as well as other
640 nonsensical combinations such as
642 are not standard; such combinations
649 assume an infinitely long string,
650 callers must be careful not to overflow the actual space;
651 this is often hard to assure.
652 For safety, programmers should use the
655 Unfortunately, this interface is not portable.