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 .\" 4. 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$
  34 .\"
  35 .Dd December 2, 2009
  36 .Dt PRINTF 3
  37 .Os
  38 .Sh NAME
  39 .Nm printf , fprintf , sprintf , snprintf , asprintf , dprintf ,
  40 .Nm vprintf , vfprintf, vsprintf , vsnprintf , vasprintf, vdprintf
  41 .Nd formatted output conversion
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .Fd "#define _WITH_DPRINTF"
  46 .In stdio.h
  47 .Ft int
  48 .Fn printf "const char * restrict format" ...
  49 .Ft int
  50 .Fn fprintf "FILE * restrict stream" "const char * restrict format" ...
  51 .Ft int
  52 .Fn sprintf "char * restrict str" "const char * restrict format" ...
  53 .Ft int
  54 .Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ...
  55 .Ft int
  56 .Fn asprintf "char **ret" "const char *format" ...
  57 .Ft int
  58 .Fn dprintf "int fd" "const char * restrict format" ...
  59 .In stdarg.h
  60 .Ft int
  61 .Fn vprintf "const char * restrict format" "va_list ap"
  62 .Ft int
  63 .Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap"
  64 .Ft int
  65 .Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap"
  66 .Ft int
  67 .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
  68 .Ft int
  69 .Fn vasprintf "char **ret" "const char *format" "va_list ap"
  70 .Ft int
  71 .Fn vdprintf "int fd" "const char * restrict format" "va_list ap"
  72 .Sh DESCRIPTION
  73 The
  74 .Fn printf
  75 family of functions produces output according to a
  76 .Fa format
  77 as described below.
  78 The
  79 .Fn printf
  80 and
  81 .Fn vprintf
  82 functions
  83 write output to
  84 .Dv stdout ,
  85 the standard output stream;
  86 .Fn fprintf
  87 and
  88 .Fn vfprintf
  89 write output to the given output
  90 .Fa stream ;
  91 .Fn dprintf
  92 and
  93 .Fn vdprintf
  94 write output to the given file descriptor;
  95 .Fn sprintf ,
  96 .Fn snprintf ,
  97 .Fn vsprintf ,
  98 and
  99 .Fn vsnprintf
 100 write to the character string
 101 .Fa str ;
 102 and
 103 .Fn asprintf
 104 and
 105 .Fn vasprintf
 106 dynamically allocate a new string with
 107 .Xr malloc 3 .
 108 .Pp
 109 These functions write the output under the control of a
 110 .Fa format
 111 string that specifies how subsequent arguments
 112 (or arguments accessed via the variable-length argument facilities of
 113 .Xr stdarg 3 )
 114 are converted for output.
 115 .Pp
 116 These functions return the number of characters printed
 117 (not including the trailing
 118 .Ql \e0
 119 used to end output to strings) or a negative value if an output error occurs,
 120 except for
 121 .Fn snprintf
 122 and
 123 .Fn vsnprintf ,
 124 which return the number of characters that would have been printed if the
 125 .Fa size
 126 were unlimited
 127 (again, not including the final
 128 .Ql \e0 ) .
 129 .Pp
 130 The
 131 .Fn asprintf
 132 and
 133 .Fn vasprintf
 134 functions
 135 set
 136 .Fa *ret
 137 to be a pointer to a buffer sufficiently large to hold the formatted string.
 138 This pointer should be passed to
 139 .Xr free 3
 140 to release the allocated storage when it is no longer needed.
 141 If sufficient space cannot be allocated,
 142 .Fn asprintf
 143 and
 144 .Fn vasprintf
 145 will return \-1 and set
 146 .Fa ret
 147 to be a
 148 .Dv NULL
 149 pointer.
 150 .Pp
 151 The
 152 .Fn snprintf
 153 and
 154 .Fn vsnprintf
 155 functions
 156 will write at most
 157 .Fa size Ns \-1
 158 of the characters printed into the output string
 159 (the
 160 .Fa size Ns 'th
 161 character then gets the terminating
 162 .Ql \e0 ) ;
 163 if the return value is greater than or equal to the
 164 .Fa size
 165 argument, the string was too short
 166 and some of the printed characters were discarded.
 167 The output is always null-terminated.
 168 .Pp
 169 The
 170 .Fn sprintf
 171 and
 172 .Fn vsprintf
 173 functions
 174 effectively assume an infinite
 175 .Fa size .
 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 (deprecated)" ".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 j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
 335 .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
 336 .It Cm z Ta (see note) Ta Vt size_t Ta (see note)
 337 .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
 338 .El
 339 .Pp
 340 Note:
 341 the
 342 .Cm t
 343 modifier, when applied to a
 344 .Cm o , u , x ,
 345 or
 346 .Cm X
 347 conversion, indicates that the argument is of an unsigned type
 348 equivalent in size to a
 349 .Vt ptrdiff_t .
 350 The
 351 .Cm z
 352 modifier, when applied to a
 353 .Cm d
 354 or
 355 .Cm i
 356 conversion, indicates that the argument is of a signed type equivalent in
 357 size to a
 358 .Vt size_t .
 359 Similarly, when applied to an
 360 .Cm n
 361 conversion, it indicates that the argument is a pointer to a signed type
 362 equivalent in size to a
 363 .Vt size_t .
 364 .Pp
 365 The following length modifier is valid for the
 366 .Cm a , A , e , E , f , F , g ,
 367 or
 368 .Cm G
 369 conversion:
 370 .Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
 371 .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
 372 .It Cm l No (ell) Ta Vt double
 373 (ignored, same behavior as without it)
 374 .It Cm L Ta Vt "long double"
 375 .El
 376 .Pp
 377 The following length modifier is valid for the
 378 .Cm c
 379 or
 380 .Cm s
 381 conversion:
 382 .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
 383 .It Sy Modifier Ta Cm c Ta Cm s
 384 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
 385 .El
 386 .It
 387 A character that specifies the type of conversion to be applied.
 388 .El
 389 .Pp
 390 A field width or precision, or both, may be indicated by
 391 an asterisk
 392 .Ql *
 393 or an asterisk followed by one or more decimal digits and a
 394 .Ql $
 395 instead of a
 396 digit string.
 397 In this case, an
 398 .Vt int
 399 argument supplies the field width or precision.
 400 A negative field width is treated as a left adjustment flag followed by a
 401 positive field width; a negative precision is treated as though it were
 402 missing.
 403 If a single format directive mixes positional
 404 .Pq Li nn$
 405 and non-positional arguments, the results are undefined.
 406 .Pp
 407 The conversion specifiers and their meanings are:
 408 .Bl -tag -width ".Cm diouxX"
 409 .It Cm diouxX
 410 The
 411 .Vt int
 412 (or appropriate variant) argument is converted to signed decimal
 413 .Cm ( d
 414 and
 415 .Cm i ) ,
 416 unsigned octal
 417 .Pq Cm o ,
 418 unsigned decimal
 419 .Pq Cm u ,
 420 or unsigned hexadecimal
 421 .Cm ( x
 422 and
 423 .Cm X )
 424 notation.
 425 The letters
 426 .Dq Li abcdef
 427 are used for
 428 .Cm x
 429 conversions; the letters
 430 .Dq Li ABCDEF
 431 are used for
 432 .Cm X
 433 conversions.
 434 The precision, if any, gives the minimum number of digits that must
 435 appear; if the converted value requires fewer digits, it is padded on
 436 the left with zeros.
 437 .It Cm DOU
 438 The
 439 .Vt "long int"
 440 argument is converted to signed decimal, unsigned octal, or unsigned
 441 decimal, as if the format had been
 442 .Cm ld , lo ,
 443 or
 444 .Cm lu
 445 respectively.
 446 These conversion characters are deprecated, and will eventually disappear.
 447 .It Cm eE
 448 The
 449 .Vt double
 450 argument is rounded and converted in the style
 451 .Sm off
 452 .Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd
 453 .Sm on
 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.
 460 An
 461 .Cm E
 462 conversion uses the letter
 463 .Ql E
 464 (rather than
 465 .Ql e )
 466 to introduce the exponent.
 467 The exponent always contains at least two digits; if the value is zero,
 468 the exponent is 00.
 469 .Pp
 470 For
 471 .Cm a , A , e , E , f , F , g ,
 472 and
 473 .Cm G
 474 conversions, positive and negative infinity are represented as
 475 .Li inf
 476 and
 477 .Li -inf
 478 respectively when using the lowercase conversion character, and
 479 .Li INF
 480 and
 481 .Li -INF
 482 respectively when using the uppercase conversion character.
 483 Similarly, NaN is represented as
 484 .Li nan
 485 when using the lowercase conversion, and
 486 .Li NAN
 487 when using the uppercase conversion.
 488 .It Cm fF
 489 The
 490 .Vt double
 491 argument is rounded and converted to decimal notation in the style
 492 .Sm off
 493 .Oo \- Oc Ar ddd Li \&. Ar ddd ,
 494 .Sm on
 495 where the number of digits after the decimal-point character
 496 is equal to the precision specification.
 497 If the precision is missing, it is taken as 6; if the precision is
 498 explicitly zero, no decimal-point character appears.
 499 If a decimal point appears, at least one digit appears before it.
 500 .It Cm gG
 501 The
 502 .Vt double
 503 argument is converted in style
 504 .Cm f
 505 or
 506 .Cm e
 507 (or
 508 .Cm F
 509 or
 510 .Cm E
 511 for
 512 .Cm G
 513 conversions).
 514 The precision specifies the number of significant digits.
 515 If the precision is missing, 6 digits are given; if the precision is zero,
 516 it is treated as 1.
 517 Style
 518 .Cm e
 519 is used if the exponent from its conversion is less than \-4 or greater than
 520 or equal to the precision.
 521 Trailing zeros are removed from the fractional part of the result; a
 522 decimal point appears only if it is followed by at least one digit.
 523 .It Cm aA
 524 The
 525 .Vt double
 526 argument is rounded and converted to hexadecimal notation in the style
 527 .Sm off
 528 .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d ,
 529 .Sm on
 530 where the number of digits after the hexadecimal-point character
 531 is equal to the precision specification.
 532 If the precision is missing, it is taken as enough to represent
 533 the floating-point number exactly, and no rounding occurs.
 534 If the precision is zero, no hexadecimal-point character appears.
 535 The
 536 .Cm p
 537 is a literal character
 538 .Ql p ,
 539 and the exponent consists of a positive or negative sign
 540 followed by a decimal number representing an exponent of 2.
 541 The
 542 .Cm A
 543 conversion uses the prefix
 544 .Dq Li 0X
 545 (rather than
 546 .Dq Li 0x ) ,
 547 the letters
 548 .Dq Li ABCDEF
 549 (rather than
 550 .Dq Li abcdef )
 551 to represent the hex digits, and the letter
 552 .Ql P
 553 (rather than
 554 .Ql p )
 555 to separate the mantissa and exponent.
 556 .Pp
 557 Note that there may be multiple valid ways to represent floating-point
 558 numbers in this hexadecimal format.
 559 For example,
 560 .Li 0x1.92p+1 , 0x3.24p+0 , 0x6.48p-1 ,
 561 and
 562 .Li 0xc.9p-2
 563 are all equivalent.
 564 .Fx 8.0
 565 and later always prints finite non-zero numbers using
 566 .Ql 1
 567 as the digit before the hexadecimal point.
 568 Zeroes are always represented with a mantissa of 0 (preceded by a
 569 .Ql -
 570 if appropriate) and an exponent of
 571 .Li +0 .
 572 .It Cm C
 573 Treated as
 574 .Cm c
 575 with the
 576 .Cm l
 577 (ell) modifier.
 578 .It Cm c
 579 The
 580 .Vt int
 581 argument is converted to an
 582 .Vt "unsigned char" ,
 583 and the resulting character is written.
 584 .Pp
 585 If the
 586 .Cm l
 587 (ell) modifier is used, the
 588 .Vt wint_t
 589 argument shall be converted to a
 590 .Vt wchar_t ,
 591 and the (potentially multi-byte) sequence representing the
 592 single wide character is written, including any shift sequences.
 593 If a shift sequence is used, the shift state is also restored
 594 to the original state after the character.
 595 .It Cm S
 596 Treated as
 597 .Cm s
 598 with the
 599 .Cm l
 600 (ell) modifier.
 601 .It Cm s
 602 The
 603 .Vt "char *"
 604 argument is expected to be a pointer to an array of character type (pointer
 605 to a string).
 606 Characters from the array are written up to (but not including)
 607 a terminating
 608 .Dv NUL
 609 character;
 610 if a precision is specified, no more than the number specified are
 611 written.
 612 If a precision is given, no null character
 613 need be present; if the precision is not specified, or is greater than
 614 the size of the array, the array must contain a terminating
 615 .Dv NUL
 616 character.
 617 .Pp
 618 If the
 619 .Cm l
 620 (ell) modifier is used, the
 621 .Vt "wchar_t *"
 622 argument is expected to be a pointer to an array of wide characters
 623 (pointer to a wide string).
 624 For each wide character in the string, the (potentially multi-byte)
 625 sequence representing the
 626 wide character is written, including any shift sequences.
 627 If any shift sequence is used, the shift state is also restored
 628 to the original state after the string.
 629 Wide characters from the array are written up to (but not including)
 630 a terminating wide
 631 .Dv NUL
 632 character;
 633 if a precision is specified, no more than the number of bytes specified are
 634 written (including shift sequences).
 635 Partial characters are never written.
 636 If a precision is given, no null character
 637 need be present; if the precision is not specified, or is greater than
 638 the number of bytes required to render the multibyte representation of
 639 the string, the array must contain a terminating wide
 640 .Dv NUL
 641 character.
 642 .It Cm p
 643 The
 644 .Vt "void *"
 645 pointer argument is printed in hexadecimal (as if by
 646 .Ql %#x
 647 or
 648 .Ql %#lx ) .
 649 .It Cm n
 650 The number of characters written so far is stored into the
 651 integer indicated by the
 652 .Vt "int *"
 653 (or variant) pointer argument.
 654 No argument is converted.
 655 .It Cm %
 656 A
 657 .Ql %
 658 is written.
 659 No argument is converted.
 660 The complete conversion specification
 661 is
 662 .Ql %% .
 663 .El
 664 .Pp
 665 The decimal point
 666 character is defined in the program's locale (category
 667 .Dv LC_NUMERIC ) .
 668 .Pp
 669 In no case does a non-existent or small field width cause truncation of
 670 a numeric field; if the result of a conversion is wider than the field
 671 width, the
 672 field is expanded to contain the conversion result.
 673 .Sh EXAMPLES
 674 To print a date and time in the form
 675 .Dq Li "Sunday, July 3, 10:02" ,
 676 where
 677 .Fa weekday
 678 and
 679 .Fa month
 680 are pointers to strings:
 681 .Bd -literal -offset indent
 682 #include <stdio.h>
 683 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
 684         weekday, month, day, hour, min);
 685 .Ed
 686 .Pp
 687 To print \*(Pi
 688 to five decimal places:
 689 .Bd -literal -offset indent
 690 #include <math.h>
 691 #include <stdio.h>
 692 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
 693 .Ed
 694 .Pp
 695 To allocate a 128 byte string and print into it:
 696 .Bd -literal -offset indent
 697 #include <stdio.h>
 698 #include <stdlib.h>
 699 #include <stdarg.h>
 700 char *newfmt(const char *fmt, ...)
 701 {
 702         char *p;
 703         va_list ap;
 704         if ((p = malloc(128)) == NULL)
 705                 return (NULL);
 706         va_start(ap, fmt);
 707         (void) vsnprintf(p, 128, fmt, ap);
 708         va_end(ap);
 709         return (p);
 710 }
 711 .Ed
 712 .Sh COMPATIBILITY
 713 Many application writers used the name
 714 .Va dprintf
 715 before the
 716 .Fn dprintf
 717 function was introduced in
 718 .St -p1003.1 ,
 719 so a prototype is not provided by default in order to avoid
 720 compatibility problems.
 721 Applications that wish to use the
 722 .Fn dprintf
 723 function described herein should either request a strict
 724 .St -p1003.1-2008
 725 environment by defining the macro
 726 .Dv _POSIX_C_SOURCE
 727 to the value 200809 or greater, or by defining the macro
 728 .Dv _WITH_DPRINTF ,
 729 prior to the inclusion of
 730 .In stdio.h .
 731 For compatibility with GNU libc, defining either
 732 .Dv _BSD_SOURCE
 733 or
 734 .Dv _GNU_SOURCE
 735 prior to the inclusion of
 736 .In stdio.h
 737 will also make
 738 .Fn dprintf
 739 available.
 740 .Pp
 741 The conversion formats
 742 .Cm \&%D , \&%O ,
 743 and
 744 .Cm \&%U
 745 are not standard and
 746 are provided only for backward compatibility.
 747 The effect of padding the
 748 .Cm %p
 749 format with zeros (either by the
 750 .Cm 0
 751 flag or by specifying a precision), and the benign effect (i.e., none)
 752 of the
 753 .Cm #
 754 flag on
 755 .Cm %n
 756 and
 757 .Cm %p
 758 conversions, as well as other
 759 nonsensical combinations such as
 760 .Cm %Ld ,
 761 are not standard; such combinations
 762 should be avoided.
 763 .Sh ERRORS
 764 In addition to the errors documented for the
 765 .Xr write 2
 766 system call, the
 767 .Fn printf
 768 family of functions may fail if:
 769 .Bl -tag -width Er
 770 .It Bq Er EILSEQ
 771 An invalid wide character code was encountered.
 772 .It Bq Er ENOMEM
 773 Insufficient storage space is available.
 774 .El
 775 .Sh SEE ALSO
 776 .Xr printf 1 ,
 777 .Xr fmtcheck 3 ,
 778 .Xr scanf 3 ,
 779 .Xr setlocale 3 ,
 780 .Xr wprintf 3
 781 .Sh STANDARDS
 782 Subject to the caveats noted in the
 783 .Sx BUGS
 784 section below, the
 785 .Fn fprintf ,
 786 .Fn printf ,
 787 .Fn sprintf ,
 788 .Fn vprintf ,
 789 .Fn vfprintf ,
 790 and
 791 .Fn vsprintf
 792 functions
 793 conform to
 794 .St -ansiC
 795 and
 796 .St -isoC-99 .
 797 With the same reservation, the
 798 .Fn snprintf
 799 and
 800 .Fn vsnprintf
 801 functions conform to
 802 .St -isoC-99 ,
 803 while
 804 .Fn dprintf
 805 and
 806 .Fn vdprintf
 807 conform to
 808 .St -p1003.1-2008 .
 809 .Sh HISTORY
 810 The functions
 811 .Fn asprintf
 812 and
 813 .Fn vasprintf
 814 first appeared in the
 815 .Tn GNU C
 816 library.
 817 These were implemented by
 818 .An Peter Wemm Aq peter@FreeBSD.org
 819 in
 820 .Fx 2.2 ,
 821 but were later replaced with a different implementation
 822 from
 823 .Ox 2.3
 824 by
 825 .An Todd C. Miller Aq Todd.Miller@courtesan.com .
 826 The
 827 .Fn dprintf
 828 and
 829 .Fn vdprintf
 830 functions were added in
 831 .Fx 8.0 .
 832 .Sh BUGS
 833 The
 834 .Nm
 835 family of functions do not correctly handle multibyte characters in the
 836 .Fa format
 837 argument.
 838 .Sh SECURITY CONSIDERATIONS
 839 The
 840 .Fn sprintf
 841 and
 842 .Fn vsprintf
 843 functions are easily misused in a manner which enables malicious users
 844 to arbitrarily change a running program's functionality through
 845 a buffer overflow attack.
 846 Because
 847 .Fn sprintf
 848 and
 849 .Fn vsprintf
 850 assume an infinitely long string,
 851 callers must be careful not to overflow the actual space;
 852 this is often hard to assure.
 853 For safety, programmers should use the
 854 .Fn snprintf
 855 interface instead.
 856 For example:
 857 .Bd -literal
 858 void
 859 foo(const char *arbitrary_string, const char *and_another)
 860 {
 861         char onstack[8];
 862
 863 #ifdef BAD
 864         /*
 865          * This first sprintf is bad behavior.  Do not use sprintf!
 866          */
 867         sprintf(onstack, "%s, %s", arbitrary_string, and_another);
 868 #else
 869         /*
 870          * The following two lines demonstrate better use of
 871          * snprintf().
 872          */
 873         snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string,
 874             and_another);
 875 #endif
 876 }
 877 .Ed
 878 .Pp
 879 The
 880 .Fn printf
 881 and
 882 .Fn sprintf
 883 family of functions are also easily misused in a manner
 884 allowing malicious users to arbitrarily change a running program's
 885 functionality by either causing the program
 886 to print potentially sensitive data
 887 .Dq "left on the stack" ,
 888 or causing it to generate a memory fault or bus error
 889 by dereferencing an invalid pointer.
 890 .Pp
 891 .Cm %n
 892 can be used to write arbitrary data to potentially carefully-selected
 893 addresses.
 894 Programmers are therefore strongly advised to never pass untrusted strings
 895 as the
 896 .Fa format
 897 argument, as an attacker can put format specifiers in the string
 898 to mangle your stack,
 899 leading to a possible security hole.
 900 This holds true even if the string was built using a function like
 901 .Fn snprintf ,
 902 as the resulting string may still contain user-supplied conversion specifiers
 903 for later interpolation by
 904 .Fn printf .
 905 .Pp
 906 Always use the proper secure idiom:
 907 .Pp
 908 .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"