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.5 2005/08/05 23:22:23 swildner Exp $
54 .Nd formatted output conversion
60 .Fn printf "const char *format" ...
62 .Fn fprintf "FILE *stream" "const char *format" ...
64 .Fn sprintf "char *str" "const char *format" ...
66 .Fn snprintf "char *str" "size_t size" "const char *format" ...
68 .Fn asprintf "char **ret" "const char *format" ...
71 .Fn vprintf "const char *format" "va_list ap"
73 .Fn vfprintf "FILE *stream" "const char *format" "va_list ap"
75 .Fn vsprintf "char *str" "const char *format" "va_list ap"
77 .Fn vsnprintf "char *str" "size_t size" "const char *format" "va_list ap"
79 .Fn vasprintf "char **ret" "const char *format" "va_list ap"
83 family of functions produces output according to a
91 the standard output stream;
95 write output to the given output
102 write to the character string
108 dynamically allocate a new string with
111 These functions write the output under the control of a
113 string that specifies how subsequent arguments
114 (or arguments accessed via the variable-length argument facilities of
116 are converted for output.
118 Upon success, these functions return the number of characters printed
119 (not including the trailing
121 used to end output to strings),
126 the number of characters that would have been printed if the
129 (again, not including the final
131 All of these function return a negative value if an output error occurs.
138 to be a pointer to a buffer sufficiently large to hold the formatted string.
139 This pointer should be passed to
141 to release the allocated storage when it is no longer needed.
142 If sufficient space cannot be allocated,
146 will return -1 and set
157 of the characters printed into the output string
160 character then gets the terminating
162 if the return value is greater than or equal to the
164 argument, the string was too short
165 and some of the printed characters were discarded.
170 effectively assume an infinite
173 The format string is composed of zero or more directives:
178 which are copied unchanged to the output stream;
179 and conversion specifications, each of which results
180 in fetching zero or more subsequent arguments.
181 Each conversion specification is introduced by
185 The arguments must correspond properly (after type promotion)
186 with the conversion specifier.
189 the following appear in sequence:
192 An optional field, consisting of a decimal digit string followed by a
194 specifying the next argument to access.
195 If this field is not provided, the argument following the last
196 argument accessed will be used.
197 Arguments are numbered starting at
199 If unaccessed arguments in the format string are interspersed with ones that
200 are accessed the results will be indeterminate.
202 Zero or more of the following flags:
208 specifying that the value should be converted to an
211 .Cm c , d , i , n , p , s ,
214 conversions, this option has no effect.
217 conversions, the precision of the number is increased to force the first
218 character of the output string to a zero (except if a zero value is printed
219 with an explicit precision of zero).
224 conversions, a non-zero result has the string
230 conversions) prepended to it.
235 conversions, the result will always contain a decimal point, even if no
236 digits follow it (normally, a decimal point appears in the results of
237 those conversions only if a digit follows).
242 conversions, trailing zeros are not removed from the result as they
248 character specifying zero padding.
249 For all conversions except
251 the converted value is padded on the left with zeros rather than blanks.
252 If a precision is given with a numeric conversion
253 .Cm ( d , i , o , u , i , x ,
260 A negative field width flag
262 indicates the converted value is to be left adjusted on the field boundary.
265 conversions, the converted value is padded on the right with blanks,
266 rather than on the left with blanks or zeros.
273 A space, specifying that a blank should be left before a positive number
274 produced by a signed conversion
275 .Cm ( d , e , E , f , g , G ,
281 character specifying that a sign always be placed before a
282 number produced by a signed conversion.
285 overrides a space if both are used.
288 An optional decimal digit string specifying a minimum field width.
289 If the converted value has fewer characters than the field width, it will
290 be padded with spaces on the left (or right, if the left-adjustment
291 flag has been given) to fill out
294 An optional precision, in the form of a period
297 optional digit string.
298 If the digit string is omitted, the precision is taken as zero.
299 This gives the minimum number of digits to appear for
300 .Cm d , i , o , u , x ,
303 conversions, the number of digits to appear after the decimal-point for
307 conversions, the maximum number of significant digits for
311 conversions, or the maximum number of characters to be printed from a
316 The optional character
318 specifying that a following
319 .Cm d , i , o , u , x ,
322 conversion corresponds to a
325 .Vt unsigned short int
326 argument, or that a following
328 conversion corresponds to a pointer to a
332 The optional character
334 (ell) specifying that a following
335 .Cm d , i , o , u , x ,
338 conversion applies to a pointer to a
341 .Vt unsigned long int
342 argument, or that a following
344 conversion corresponds to a pointer to a
348 The optional characters
350 (ell ell) specifying that a following
351 .Cm d , i , o , u , x ,
354 conversion applies to a pointer to a
357 .Vt unsigned long long int
358 argument, or that a following
360 conversion corresponds to a pointer to a
364 The optional character
366 specifying that a following
367 .Cm d , i , o , u , x ,
370 conversion corresponds to a
373 .Vt unsigned quad int
374 argument, or that a following
376 conversion corresponds to a pointer to a
382 specifying that a following
386 conversion corresponds to a
390 A character that specifies the type of conversion to be applied.
393 A field width or precision, or both, may be indicated by
396 or an asterisk followed by one or more decimal digits and a
402 argument supplies the field width or precision.
403 A negative field width is treated as a left adjustment flag followed by a
404 positive field width; a negative precision is treated as though it were
406 If a single format directive mixes positional (nn$)
407 and non-positional arguments, the results are undefined.
409 The conversion specifiers and their meanings are:
410 .Bl -tag -width "diouxX"
414 (or appropriate variant) argument is converted to signed decimal
422 or unsigned hexadecimal
431 conversions; the letters
436 The precision, if any, gives the minimum number of digits that must
437 appear; if the converted value requires fewer digits, it is padded on
442 argument is converted to signed decimal, unsigned octal, or unsigned
443 decimal, as if the format had been
448 These conversion characters are deprecated, and will eventually disappear.
452 argument is rounded and converted in the style
453 .Oo \- Oc Ns d Ns Cm \&. Ns ddd Ns Cm e Ns \\*[Pm]dd
454 where there is one digit before the
455 decimal-point character
456 and the number of digits after it is equal to the precision;
457 if the precision is missing,
458 it is taken as 6; if the precision is
459 zero, no decimal-point character appears.
462 conversion uses the letter
466 to introduce the exponent.
467 The exponent always contains at least two digits; if the value is zero,
472 argument is rounded and converted to decimal notation in the style
473 .Oo \- Oc Ns ddd Ns Cm \&. Ns ddd ,
474 where the number of digits after the decimal-point character
475 is equal to the precision specification.
476 If the precision is missing, it is taken as 6; if the precision is
477 explicitly zero, no decimal-point character appears.
478 If a decimal point appears, at least one digit appears before it.
482 argument is converted in style
491 The precision specifies the number of significant digits.
492 If the precision is missing, 6 digits are given; if the precision is zero,
496 is used if the exponent from its conversion is less than -4 or greater than
497 or equal to the precision.
498 Trailing zeros are removed from the fractional part of the result; a
499 decimal point appears only if it is followed by at least one digit.
503 argument is converted to an
505 and the resulting character is written.
509 argument is expected to be a pointer to an array of character type (pointer
511 Characters from the array are written up to (but not including)
515 if a precision is specified, no more than the number specified are
517 If a precision is given, no null character
518 need be present; if the precision is not specified, or is greater than
519 the size of the array, the array must contain a terminating
525 pointer argument is printed in hexadecimal (as if by
530 The number of characters written so far is stored into the
531 integer indicated by the
533 (or variant) pointer argument.
534 No argument is converted.
539 No argument is converted.
540 The complete conversion specification
545 In no case does a non-existent or small field width cause truncation of
546 a field; if the result of a conversion is wider than the field width, the
547 field is expanded to contain the conversion result.
549 To print a date and time in the form
550 .Dq Li "Sunday, July 3, 10:02" ,
555 are pointers to strings:
556 .Bd -literal -offset indent
558 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
559 weekday, month, day, hour, min);
563 to five decimal places:
564 .Bd -literal -offset indent
567 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
570 To allocate a 128 byte string and print into it:
571 .Bd -literal -offset indent
575 char *newfmt(const char *fmt, ...)
579 if ((p = malloc(128)) == NULL)
582 (void) vsnprintf(p, 128, fmt, ap);
588 In addition to the errors documented for the
592 family of functions may fail if:
595 Insufficient storage space is available.
617 first appeared in the
620 These were implemented by
621 .An Peter Wemm Aq peter@FreeBSD.org
624 but were later replaced with a different implementation
626 .An Todd C. Miller Aq Todd.Miller@courtesan.com
630 The conversion formats
635 are provided only for backward compatibility.
636 The effect of padding the
638 format with zeros (either by the
640 flag or by specifying a precision), and the benign effect (i.e., none)
647 conversions, as well as other
648 nonsensical combinations such as
650 are not standard; such combinations
657 assume an infinitely long string,
658 callers must be careful not to overflow the actual space;
659 this is often hard to assure.
660 For safety, programmers should use the
663 Unfortunately, this interface is not portable.