lib/libc/stdio/printf.3

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   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.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  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. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)printf.3    8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: head/lib/libc/stdio/printf.3 303524 2016-07-30 01:00:16Z bapt $
  34 .\"
  35 .Dd March 21, 2022
  36 .Dt PRINTF 3
  37 .Os
  38 .Sh NAME
  39 .Nm printf ,
  40 .Nm fprintf ,
  41 .Nm sprintf ,
  42 .Nm snprintf ,
  43 .Nm asprintf ,
  44 .Nm dprintf ,
  45 .Nm vprintf ,
  46 .Nm vfprintf ,
  47 .Nm vsprintf ,
  48 .Nm vsnprintf ,
  49 .Nm vasprintf ,
  50 .Nm vdprintf
  51 .Nd formatted output conversion
  52 .Sh LIBRARY
  53 .Lb libc
  54 .Sh SYNOPSIS
  55 .In stdio.h
  56 .Ft int
  57 .Fn printf "const char * restrict format" ...
  58 .Ft int
  59 .Fn fprintf "FILE * restrict stream" "const char * restrict format" ...
  60 .Ft int
  61 .Fn sprintf "char * restrict str" "const char * restrict format" ...
  62 .Ft int
  63 .Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ...
  64 .Ft int
  65 .Fn asprintf "char **ret" "const char *format" ...
  66 .Ft int
  67 .Fn dprintf "int" "const char * restrict format" ...
  68 .In stdarg.h
  69 .Ft int
  70 .Fn vprintf "const char * restrict format" "va_list ap"
  71 .Ft int
  72 .Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap"
  73 .Ft int
  74 .Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap"
  75 .Ft int
  76 .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
  77 .Ft int
  78 .Fn vasprintf "char **ret" "const char *format" "va_list ap"
  79 .Ft int
  80 .Fn vdprintf "int fd" "const char * restrict format" "va_list ap"
  81 .Sh DESCRIPTION
  82 The
  83 .Fn printf
  84 family of functions produces output according to a
  85 .Fa format
  86 as described below.
  87 The
  88 .Fn printf
  89 and
  90 .Fn vprintf
  91 functions
  92 write output to
  93 .Dv stdout ,
  94 the standard output stream;
  95 .Fn fprintf
  96 and
  97 .Fn vfprintf
  98 write output to the given output
  99 .Fa stream ;
 100 .Fn dprintf
 101 and
 102 .Fn vdprintf
 103 write output to the given file descriptor;
 104 .Fn sprintf ,
 105 .Fn snprintf ,
 106 .Fn vsprintf ,
 107 and
 108 .Fn vsnprintf
 109 write to the character string
 110 .Fa str ;
 111 and
 112 .Fn asprintf
 113 and
 114 .Fn vasprintf
 115 dynamically allocate a new string with
 116 .Xr malloc 3 .
 117 .Pp
 118 These functions write the output under the control of a
 119 .Fa format
 120 string that specifies how subsequent arguments
 121 (or arguments accessed via the variable-length argument facilities of
 122 .Xr stdarg 3 )
 123 are converted for output.
 124 .Pp
 125 The
 126 .Fn asprintf
 127 and
 128 .Fn vasprintf
 129 functions
 130 set
 131 .Fa *ret
 132 to be a pointer to a buffer sufficiently large to hold the formatted string.
 133 This pointer should be passed to
 134 .Xr free 3
 135 to release the allocated storage when it is no longer needed.
 136 If sufficient space cannot be allocated,
 137 .Fn asprintf
 138 and
 139 .Fn vasprintf
 140 will return \-1 and set
 141 .Fa ret
 142 to be a
 143 .Dv NULL
 144 pointer.
 145 .Pp
 146 The
 147 .Fn snprintf
 148 and
 149 .Fn vsnprintf
 150 functions
 151 will write at most
 152 .Fa size Ns \-1
 153 of the characters printed into the output string
 154 (the
 155 .Fa size Ns 'th
 156 character then gets the terminating
 157 .Ql \e0 ) ;
 158 if the return value is greater than or equal to the
 159 .Fa size
 160 argument, the string was too short
 161 and some of the printed characters were discarded.
 162 The output is always null-terminated, unless
 163 .Fa size
 164 is 0.
 165 .Pp
 166 The
 167 .Fn sprintf
 168 and
 169 .Fn vsprintf
 170 functions
 171 effectively assume a
 172 .Fa size
 173 of
 174 .Dv INT_MAX
 175 + 1.
 176 .Pp
 177 The format string is composed of zero or more directives:
 178 ordinary
 179 .\" multibyte
 180 characters (not
 181 .Cm % ) ,
 182 which are copied unchanged to the output stream;
 183 and conversion specifications, each of which results
 184 in fetching zero or more subsequent arguments.
 185 Each conversion specification is introduced by
 186 the
 187 .Cm %
 188 character.
 189 The arguments must correspond properly (after type promotion)
 190 with the conversion specifier.
 191 After the
 192 .Cm % ,
 193 the following appear in sequence:
 194 .Bl -bullet
 195 .It
 196 An optional field, consisting of a decimal digit string followed by a
 197 .Cm $ ,
 198 specifying the next argument to access.
 199 If this field is not provided, the argument following the last
 200 argument accessed will be used.
 201 Arguments are numbered starting at
 202 .Cm 1 .
 203 If unaccessed arguments in the format string are interspersed with ones that
 204 are accessed the results will be indeterminate.
 205 .It
 206 Zero or more of the following flags:
 207 .Bl -tag -width ".So \  Sc (space)"
 208 .It Sq Cm #
 209 The value should be converted to an
 210 .Dq alternate form .
 211 For
 212 .Cm c , d , i , n , p , s ,
 213 and
 214 .Cm u
 215 conversions, this option has no effect.
 216 For
 217 .Cm o
 218 conversions, the precision of the number is increased to force the first
 219 character of the output string to a zero.
 220 For
 221 .Cm x
 222 and
 223 .Cm X
 224 conversions, a non-zero result has the string
 225 .Ql 0x
 226 (or
 227 .Ql 0X
 228 for
 229 .Cm X
 230 conversions) prepended to it.
 231 For
 232 .Cm a , A , e , E , f , F , g ,
 233 and
 234 .Cm G
 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).
 238 For
 239 .Cm g
 240 and
 241 .Cm G
 242 conversions, trailing zeros are not removed from the result as they
 243 would otherwise be.
 244 .It So Cm 0 Sc (zero)
 245 Zero padding.
 246 For all conversions except
 247 .Cm n ,
 248 the converted value is padded on the left with zeros rather than blanks.
 249 If a precision is given with a numeric conversion
 250 .Cm ( d , i , o , u , i , x ,
 251 and
 252 .Cm X ) ,
 253 the
 254 .Cm 0
 255 flag is ignored.
 256 .It Sq Cm \-
 257 A negative field width flag;
 258 the converted value is to be left adjusted on the field boundary.
 259 Except for
 260 .Cm n
 261 conversions, the converted value is padded on the right with blanks,
 262 rather than on the left with blanks or zeros.
 263 A
 264 .Cm \-
 265 overrides a
 266 .Cm 0
 267 if both are given.
 268 .It So "\ " Sc (space)
 269 A blank should be left before a positive number
 270 produced by a signed conversion
 271 .Cm ( a , A , d , e , E , f , F , g , G ,
 272 or
 273 .Cm i ) .
 274 .It Sq Cm +
 275 A sign must always be placed before a
 276 number produced by a signed conversion.
 277 A
 278 .Cm +
 279 overrides a space if both are used.
 280 .It So "'" Sc (apostrophe)
 281 Decimal conversions
 282 .Cm ( d , u ,
 283 or
 284 .Cm i )
 285 or the integral portion of a floating point conversion
 286 .Cm ( f
 287 or
 288 .Cm F )
 289 should be grouped and separated by thousands using
 290 the non-monetary separator returned by
 291 .Xr localeconv 3 .
 292 .El
 293 .It
 294 An optional decimal digit string specifying a minimum field width.
 295 If the converted value has fewer characters than the field width, it will
 296 be padded with spaces on the left (or right, if the left-adjustment
 297 flag has been given) to fill out
 298 the field width.
 299 .It
 300 An optional precision, in the form of a period
 301 .Cm \&.
 302 followed by an
 303 optional digit string.
 304 If the digit string is omitted, the precision is taken as zero.
 305 This gives the minimum number of digits to appear for
 306 .Cm d , i , o , u , x ,
 307 and
 308 .Cm X
 309 conversions, the number of digits to appear after the decimal-point for
 310 .Cm a , A , e , E , f ,
 311 and
 312 .Cm F
 313 conversions, the maximum number of significant digits for
 314 .Cm g
 315 and
 316 .Cm G
 317 conversions, or the maximum number of characters to be printed from a
 318 string for
 319 .Cm s
 320 conversions.
 321 .It
 322 An optional length modifier, that specifies the size of the argument.
 323 The following length modifiers are valid for the
 324 .Cm d , i , n , o , u , x ,
 325 or
 326 .Cm X
 327 conversion:
 328 .Bl -column ".Cm q Em (non-standard)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
 329 .It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
 330 .It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
 331 .It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
 332 .It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
 333 .It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
 334 .It Cm L Em (non-standard) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
 335 .It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
 336 .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
 337 .It Cm z Ta (see note) Ta Vt size_t Ta (see note)
 338 .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
 339 .El
 340 .Pp
 341 Note:
 342 the
 343 .Cm t
 344 modifier, when applied to a
 345 .Cm o , u , x ,
 346 or
 347 .Cm X
 348 conversion, indicates that the argument is of an unsigned type
 349 equivalent in size to a
 350 .Vt ptrdiff_t .
 351 The
 352 .Cm z
 353 modifier, when applied to a
 354 .Cm d
 355 or
 356 .Cm i
 357 conversion, indicates that the argument is of a signed type equivalent in
 358 size to a
 359 .Vt size_t .
 360 Similarly, when applied to an
 361 .Cm n
 362 conversion, it indicates that the argument is a pointer to a signed type
 363 equivalent in size to a
 364 .Vt size_t .
 365 .Pp
 366 The following length modifier is valid for the
 367 .Cm a , A , e , E , f , F , g ,
 368 or
 369 .Cm G
 370 conversion:
 371 .Bl -column ".Cm ll Em (non-standard)" ".Cm a , A , e , E , f , F , g , G"
 372 .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
 373 .It Cm l No (ell) Ta Vt double
 374 (ignored, same behavior as without it)
 375 .It Cm L Ta Vt "long double"
 376 .It Cm ll Em (non-standard) Ta Vt "long double"
 377 .El
 378 .Pp
 379 The following length modifier is valid for the
 380 .Cm c
 381 or
 382 .Cm s
 383 conversion:
 384 .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
 385 .It Sy Modifier Ta Cm c Ta Cm s
 386 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
 387 .El
 388 .It
 389 A character that specifies the type of conversion to be applied.
 390 .El
 391 .Pp
 392 A field width or precision, or both, may be indicated by
 393 an asterisk
 394 .Ql *
 395 or an asterisk followed by one or more decimal digits and a
 396 .Ql $
 397 instead of a
 398 digit string.
 399 In this case, an
 400 .Vt int
 401 argument supplies the field width or precision.
 402 A negative field width is treated as a left adjustment flag followed by a
 403 positive field width; a negative precision is treated as though it were
 404 missing.
 405 If a single format directive mixes positional
 406 .Pq Li nn$
 407 and non-positional arguments, the results are undefined.
 408 .Pp
 409 The conversion specifiers and their meanings are:
 410 .Bl -tag -width ".Cm diouxX"
 411 .It Cm diouxX
 412 The
 413 .Vt int
 414 (or appropriate variant) argument is converted to signed decimal
 415 .Cm ( d
 416 and
 417 .Cm i ) ,
 418 unsigned octal
 419 .Pq Cm o ,
 420 unsigned decimal
 421 .Pq Cm u ,
 422 or unsigned hexadecimal
 423 .Cm ( x
 424 and
 425 .Cm X )
 426 notation.
 427 The letters
 428 .Dq Li abcdef
 429 are used for
 430 .Cm x
 431 conversions; the letters
 432 .Dq Li ABCDEF
 433 are used for
 434 .Cm X
 435 conversions.
 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
 438 the left with zeros.
 439 .It Cm DOU
 440 The
 441 .Vt "long int"
 442 argument is converted to signed decimal, unsigned octal, or unsigned
 443 decimal, as if the format had been
 444 .Cm ld , lo ,
 445 or
 446 .Cm lu
 447 respectively.
 448 These conversion characters are deprecated, and will eventually disappear.
 449 .It Cm eE
 450 The
 451 .Vt double
 452 argument is rounded and converted in the style
 453 .Sm off
 454 .Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd
 455 .Sm on
 456 where there is one digit before the
 457 decimal-point character
 458 and the number of digits after it is equal to the precision;
 459 if the precision is missing,
 460 it is taken as 6; if the precision is
 461 zero, no decimal-point character appears.
 462 An
 463 .Cm E
 464 conversion uses the letter
 465 .Ql E
 466 (rather than
 467 .Ql e )
 468 to introduce the exponent.
 469 The exponent always contains at least two digits; if the value is zero,
 470 the exponent is 00.
 471 .Pp
 472 For
 473 .Cm a , A , e , E , f , F , g ,
 474 and
 475 .Cm G
 476 conversions, positive and negative infinity are represented as
 477 .Li inf
 478 and
 479 .Li -inf
 480 respectively when using the lowercase conversion character, and
 481 .Li INF
 482 and
 483 .Li -INF
 484 respectively when using the uppercase conversion character.
 485 Similarly, NaN is represented as
 486 .Li nan
 487 when using the lowercase conversion, and
 488 .Li NAN
 489 when using the uppercase conversion.
 490 .It Cm fF
 491 The
 492 .Vt double
 493 argument is rounded and converted to decimal notation in the style
 494 .Sm off
 495 .Oo \- Oc Ar ddd Li \&. Ar ddd ,
 496 .Sm on
 497 where the number of digits after the decimal-point character
 498 is equal to the precision specification.
 499 If the precision is missing, it is taken as 6; if the precision is
 500 explicitly zero, no decimal-point character appears.
 501 If a decimal point appears, at least one digit appears before it.
 502 .It Cm gG
 503 The
 504 .Vt double
 505 argument is converted in style
 506 .Cm f
 507 or
 508 .Cm e
 509 (or
 510 .Cm F
 511 or
 512 .Cm E
 513 for
 514 .Cm G
 515 conversions).
 516 The precision specifies the number of significant digits.
 517 If the precision is missing, 6 digits are given; if the precision is zero,
 518 it is treated as 1.
 519 Style
 520 .Cm e
 521 is used if the exponent from its conversion is less than \-4 or greater than
 522 or equal to the precision.
 523 Trailing zeros are removed from the fractional part of the result; a
 524 decimal point appears only if it is followed by at least one digit.
 525 .It Cm aA
 526 The
 527 .Vt double
 528 argument is rounded and converted to hexadecimal notation in the style
 529 .Sm off
 530 .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d ,
 531 .Sm on
 532 where the number of digits after the hexadecimal-point character
 533 is equal to the precision specification.
 534 If the precision is missing, it is taken as enough to represent
 535 the floating-point number exactly, and no rounding occurs.
 536 If the precision is zero, no hexadecimal-point character appears.
 537 The
 538 .Cm p
 539 is a literal character
 540 .Ql p ,
 541 and the exponent consists of a positive or negative sign
 542 followed by a decimal number representing an exponent of 2.
 543 The
 544 .Cm A
 545 conversion uses the prefix
 546 .Dq Li 0X
 547 (rather than
 548 .Dq Li 0x ) ,
 549 the letters
 550 .Dq Li ABCDEF
 551 (rather than
 552 .Dq Li abcdef )
 553 to represent the hex digits, and the letter
 554 .Ql P
 555 (rather than
 556 .Ql p )
 557 to separate the mantissa and exponent.
 558 .Pp
 559 Note that there may be multiple valid ways to represent floating-point
 560 numbers in this hexadecimal format.
 561 For example,
 562 .Li 0x1.92p+1 , 0x3.24p+0 , 0x6.48p-1 ,
 563 and
 564 .Li 0xc.9p-2
 565 are all equivalent.
 566 .Fx 8.0
 567 and later always prints finite non-zero numbers using
 568 .Ql 1
 569 as the digit before the hexadecimal point.
 570 Zeroes are always represented with a mantissa of 0 (preceded by a
 571 .Ql -
 572 if appropriate) and an exponent of
 573 .Li +0 .
 574 .It Cm C
 575 Treated as
 576 .Cm c
 577 with the
 578 .Cm l
 579 (ell) modifier.
 580 .It Cm c
 581 The
 582 .Vt int
 583 argument is converted to an
 584 .Vt "unsigned char" ,
 585 and the resulting character is written.
 586 .Pp
 587 If the
 588 .Cm l
 589 (ell) modifier is used, the
 590 .Vt wint_t
 591 argument shall be converted to a
 592 .Vt wchar_t ,
 593 and the (potentially multi-byte) sequence representing the
 594 single wide character is written, including any shift sequences.
 595 If a shift sequence is used, the shift state is also restored
 596 to the original state after the character.
 597 .It Cm S
 598 Treated as
 599 .Cm s
 600 with the
 601 .Cm l
 602 (ell) modifier.
 603 .It Cm s
 604 The
 605 .Vt "char *"
 606 argument is expected to be a pointer to an array of character type (pointer
 607 to a string).
 608 Characters from the array are written up to (but not including)
 609 a terminating
 610 .Dv NUL
 611 character;
 612 if a precision is specified, no more than the number specified are
 613 written.
 614 If a precision is given, no null character
 615 need be present; if the precision is not specified, or is greater than
 616 the size of the array, the array must contain a terminating
 617 .Dv NUL
 618 character.
 619 .Pp
 620 If the
 621 .Cm l
 622 (ell) modifier is used, the
 623 .Vt "wchar_t *"
 624 argument is expected to be a pointer to an array of wide characters
 625 (pointer to a wide string).
 626 For each wide character in the string, the (potentially multi-byte)
 627 sequence representing the
 628 wide character is written, including any shift sequences.
 629 If any shift sequence is used, the shift state is also restored
 630 to the original state after the string.
 631 Wide characters from the array are written up to (but not including)
 632 a terminating wide
 633 .Dv NUL
 634 character;
 635 if a precision is specified, no more than the number of bytes specified are
 636 written (including shift sequences).
 637 Partial characters are never written.
 638 If a precision is given, no null character
 639 need be present; if the precision is not specified, or is greater than
 640 the number of bytes required to render the multibyte representation of
 641 the string, the array must contain a terminating wide
 642 .Dv NUL
 643 character.
 644 .It Cm p
 645 The
 646 .Vt "void *"
 647 pointer argument is printed in hexadecimal (as if by
 648 .Ql %#x
 649 or
 650 .Ql %#lx ) .
 651 .It Cm n
 652 The number of characters written so far is stored into the
 653 integer indicated by the
 654 .Vt "int *"
 655 (or variant) pointer argument.
 656 No argument is converted.
 657 .It Cm %
 658 A
 659 .Ql %
 660 is written.
 661 No argument is converted.
 662 The complete conversion specification
 663 is
 664 .Ql %% .
 665 .El
 666 .Pp
 667 The decimal point
 668 character is defined in the program's locale (category
 669 .Dv LC_NUMERIC ) .
 670 .Pp
 671 In no case does a non-existent or small field width cause truncation of
 672 a numeric field; if the result of a conversion is wider than the field
 673 width, the
 674 field is expanded to contain the conversion result.
 675 .Sh RETURN VALUES
 676 These functions return the number of characters printed
 677 (not including the trailing
 678 .Ql \e0
 679 used to end output to strings),
 680 except for
 681 .Fn snprintf
 682 and
 683 .Fn vsnprintf ,
 684 which return the number of characters that would have been printed if the
 685 .Fa size
 686 were unlimited
 687 (again, not including the final
 688 .Ql \e0 ) .
 689 These functions return a negative value if an error occurs.
 690 .Sh EXAMPLES
 691 To print a date and time in the form
 692 .Dq Li "Sunday, July 3, 10:02" ,
 693 where
 694 .Fa weekday
 695 and
 696 .Fa month
 697 are pointers to strings:
 698 .Bd -literal -offset indent
 699 #include <stdio.h>
 700 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
 701         weekday, month, day, hour, min);
 702 .Ed
 703 .Pp
 704 To print \*(Pi
 705 to five decimal places:
 706 .Bd -literal -offset indent
 707 #include <math.h>
 708 #include <stdio.h>
 709 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
 710 .Ed
 711 .Pp
 712 To allocate a 128 byte string and print into it:
 713 .Bd -literal -offset indent
 714 #include <stdio.h>
 715 #include <stdlib.h>
 716 #include <stdarg.h>
 717 char *newfmt(const char *fmt, ...)
 718 {
 719         char *p;
 720         va_list ap;
 721         if ((p = malloc(128)) == NULL)
 722                 return (NULL);
 723         va_start(ap, fmt);
 724         (void) vsnprintf(p, 128, fmt, ap);
 725         va_end(ap);
 726         return (p);
 727 }
 728 .Ed
 729 .Sh COMPATIBILITY
 730 The conversion formats
 731 .Cm \&%D , \&%O ,
 732 and
 733 .Cm \&%U
 734 are not standard and
 735 are provided only for backward compatibility.
 736 The effect of padding the
 737 .Cm %p
 738 format with zeros (either by the
 739 .Cm 0
 740 flag or by specifying a precision), and the benign effect (i.e., none)
 741 of the
 742 .Cm #
 743 flag on
 744 .Cm %n
 745 and
 746 .Cm %p
 747 conversions, as well as other
 748 nonsensical combinations such as
 749 .Cm %Ld ,
 750 are not standard; such combinations
 751 should be avoided.
 752 .Sh ERRORS
 753 In addition to the errors documented for the
 754 .Xr write 2
 755 system call, the
 756 .Fn printf
 757 family of functions may fail if:
 758 .Bl -tag -width Er
 759 .It Bq Er EILSEQ
 760 An invalid wide character code was encountered.
 761 .It Bq Er ENOMEM
 762 Insufficient storage space is available.
 763 .It Bq Er EOVERFLOW
 764 The
 765 .Fa size
 766 argument exceeds
 767 .Dv INT_MAX + 1 ,
 768 or the return value would be too large to be represented by an
 769 .Vt int .
 770 .El
 771 .Sh SEE ALSO
 772 .Xr printf 1 ,
 773 .Xr fmtcheck 3 ,
 774 .Xr scanf 3 ,
 775 .Xr setlocale 3 ,
 776 .Xr snprintb 3 ,
 777 .Xr wprintf 3
 778 .Sh STANDARDS
 779 Subject to the caveats noted in the
 780 .Sx BUGS
 781 section below, the
 782 .Fn fprintf ,
 783 .Fn printf ,
 784 .Fn sprintf ,
 785 .Fn vprintf ,
 786 .Fn vfprintf ,
 787 and
 788 .Fn vsprintf
 789 functions
 790 conform to
 791 .St -ansiC
 792 and
 793 .St -isoC-99 .
 794 With the same reservation, the
 795 .Fn snprintf
 796 and
 797 .Fn vsnprintf
 798 functions conform to
 799 .St -isoC-99 ,
 800 while
 801 .Fn dprintf
 802 and
 803 .Fn vdprintf
 804 conform to
 805 .St -p1003.1-2008 .
 806 .Pp
 807 As an extension,
 808 .Dx
 809 treats the length modifiers
 810 .Cm ll
 811 and
 812 .Cm L
 813 as synonyms, so that the non-standard
 814 .Cm %Ld
 815 is equivalent to
 816 .Cm %ld
 817 and the non-standard
 818 .Cm %llg
 819 is equivalent
 820 to
 821 .Cm %Lg .
 822 .Sh HISTORY
 823 The functions
 824 .Fn asprintf
 825 and
 826 .Fn vasprintf
 827 first appeared in the
 828 .Tn GNU C
 829 library.
 830 These were implemented by
 831 .An Peter Wemm Aq Mt peter@FreeBSD.org
 832 in
 833 .Fx 2.2 ,
 834 but were later replaced with a different implementation
 835 from
 836 .Ox 2.3
 837 by
 838 .An Todd C. Miller Aq Mt Todd.Miller@courtesan.com .
 839 The
 840 .Fn dprintf
 841 and
 842 .Fn vdprintf
 843 functions were added in
 844 .Fx 8.0 .
 845 .Sh BUGS
 846 The
 847 .Nm
 848 family of functions do not correctly handle multibyte characters in the
 849 .Fa format
 850 argument.
 851 .Sh SECURITY CONSIDERATIONS
 852 The
 853 .Fn sprintf
 854 and
 855 .Fn vsprintf
 856 functions are easily misused in a manner which enables malicious users
 857 to arbitrarily change a running program's functionality through
 858 a buffer overflow attack.
 859 Because
 860 .Fn sprintf
 861 and
 862 .Fn vsprintf
 863 assume an infinitely long string,
 864 callers must be careful not to overflow the actual space;
 865 this is often hard to assure.
 866 For safety, programmers should use the
 867 .Fn snprintf
 868 interface instead.
 869 For example:
 870 .Bd -literal
 871 void
 872 foo(const char *arbitrary_string, const char *and_another)
 873 {
 874         char onstack[8];
 875
 876 #ifdef BAD
 877         /*
 878          * This first sprintf is bad behavior.  Do not use sprintf!
 879          */
 880         sprintf(onstack, "%s, %s", arbitrary_string, and_another);
 881 #else
 882         /*
 883          * The following two lines demonstrate better use of
 884          * snprintf().
 885          */
 886         snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string,
 887             and_another);
 888 #endif
 889 }
 890 .Ed
 891 .Pp
 892 The
 893 .Fn printf
 894 and
 895 .Fn sprintf
 896 family of functions are also easily misused in a manner
 897 allowing malicious users to arbitrarily change a running program's
 898 functionality by either causing the program
 899 to print potentially sensitive data
 900 .Dq "left on the stack" ,
 901 or causing it to generate a memory fault or bus error
 902 by dereferencing an invalid pointer.
 903 .Pp
 904 .Cm %n
 905 can be used to write arbitrary data to potentially carefully-selected
 906 addresses.
 907 Programmers are therefore strongly advised to never pass untrusted strings
 908 as the
 909 .Fa format
 910 argument, as an attacker can put format specifiers in the string
 911 to mangle your stack,
 912 leading to a possible security hole.
 913 This holds true even if the string was built using a function like
 914 .Fn snprintf ,
 915 as the resulting string may still contain user-supplied conversion specifiers
 916 for later interpolation by
 917 .Fn printf .
 918 .Pp
 919 Always use the proper secure idiom:
 920 .Pp
 921 .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"