man3/printf.3

   1 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" Earlier versions of this page influenced the present text.
   4 .\" It was derived from a Berkeley page with version
   5 .\"       @(#)printf.3    6.14 (Berkeley) 7/30/91
   6 .\" converted for Linux by faith@cs.unc.edu, updated by
   7 .\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible.
   8 .\"
   9 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
  10 .\" This is free documentation; you can redistribute it and/or
  11 .\" modify it under the terms of the GNU General Public License as
  12 .\" published by the Free Software Foundation; either version 2 of
  13 .\" the License, or (at your option) any later version.
  14 .\"
  15 .\" The GNU General Public License's references to "object code"
  16 .\" and "executables" are to be interpreted as the output of any
  17 .\" document formatting or typesetting system, including
  18 .\" intermediate and printed output.
  19 .\"
  20 .\" This manual is distributed in the hope that it will be useful,
  21 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  22 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23 .\" GNU General Public License for more details.
  24 .\"
  25 .\" You should have received a copy of the GNU General Public
  26 .\" License along with this manual; if not, see
  27 .\" <http://www.gnu.org/licenses/>.
  28 .\" %%%LICENSE_END
  29 .\"
  30 .\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99.
  31 .\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes
  32 .\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes
  33 .\"
  34 .TH PRINTF 3  2016-12-12 "GNU" "Linux Programmer's Manual"
  35 .SH NAME
  36 printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf,
  37 vsprintf, vsnprintf \- formatted output conversion
  38 .SH SYNOPSIS
  39 .B #include <stdio.h>
  40 .PP
  41 .BI "int printf(const char *" format ", ...);"
  42 .br
  43 .BI "int fprintf(FILE *" stream ", const char *" format ", ...);"
  44 .br
  45 .BI "int dprintf(int " fd ", const char *" format ", ...);"
  46 .br
  47 .BI "int sprintf(char *" str ", const char *" format ", ...);"
  48 .br
  49 .BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);"
  50
  51 .B #include <stdarg.h>
  52 .PP
  53 .BI "int vprintf(const char *" format ", va_list " ap );
  54 .br
  55 .BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap );
  56 .br
  57 .BI "int vdprintf(int " fd ", const char *" format ", va_list " ap );
  58 .br
  59 .BI "int vsprintf(char *" str ", const char *" format ", va_list " ap );
  60 .br
  61 .BI "int vsnprintf(char *" str ", size_t " size ", const char *" format \
  62 ", va_list " ap );
  63 .PP
  64 .in -4n
  65 Feature Test Macro Requirements for glibc (see
  66 .BR feature_test_macros (7)):
  67 .in
  68 .PP
  69 .ad l
  70 .BR snprintf (),
  71 .BR vsnprintf ():
  72 .RS 4
  73 _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
  74     || /* Glibc versions <= 2.19: */ _BSD_SOURCE
  75 .RE
  76 .PP
  77 .BR dprintf (),
  78 .BR vdprintf ():
  79 .PD 0
  80 .RS 4
  81 .TP 4
  82 Since glibc 2.10:
  83 _POSIX_C_SOURCE\ >=\ 200809L
  84 .TP
  85 Before glibc 2.10:
  86 _GNU_SOURCE
  87 .RE
  88 .ad
  89 .PD
  90 .SH DESCRIPTION
  91 The functions in the
  92 .BR printf ()
  93 family produce output according to a
  94 .I format
  95 as described below.
  96 The functions
  97 .BR printf ()
  98 and
  99 .BR vprintf ()
 100 write output to
 101 .IR stdout ,
 102 the standard output stream;
 103 .BR fprintf ()
 104 and
 105 .BR vfprintf ()
 106 write output to the given output
 107 .IR stream ;
 108 .BR sprintf (),
 109 .BR snprintf (),
 110 .BR vsprintf ()
 111 and
 112 .BR vsnprintf ()
 113 write to the character string
 114 .IR str .
 115 .PP
 116 The function
 117 .BR dprintf ()
 118 is the same as
 119 .BR fprintf ()
 120 except that it outputs to a file descriptor,
 121 .IR fd ,
 122 instead of to a
 123 .I stdio
 124 stream.
 125 .PP
 126 The functions
 127 .BR snprintf ()
 128 and
 129 .BR vsnprintf ()
 130 write at most
 131 .I size
 132 bytes (including the terminating null byte (\(aq\e0\(aq)) to
 133 .IR str .
 134 .PP
 135 The functions
 136 .BR vprintf (),
 137 .BR vfprintf (),
 138 .BR vdprintf (),
 139 .BR vsprintf (),
 140 .BR vsnprintf ()
 141 are equivalent to the functions
 142 .BR printf (),
 143 .BR fprintf (),
 144 .BR dprintf (),
 145 .BR sprintf (),
 146 .BR snprintf (),
 147 respectively, except that they are called with a
 148 .I va_list
 149 instead of a variable number of arguments.
 150 These functions do not call the
 151 .I va_end
 152 macro.
 153 Because they invoke the
 154 .I va_arg
 155 macro, the value of
 156 .I ap
 157 is undefined after the call.
 158 See
 159 .BR stdarg (3).
 160 .PP
 161 All of these functions write the output under the control of a
 162 .I format
 163 string that specifies how subsequent arguments (or arguments accessed via
 164 the variable-length argument facilities of
 165 .BR stdarg (3))
 166 are converted for output.
 167 .PP
 168 C99 and POSIX.1-2001 specify that the results are undefined if a call to
 169 .BR sprintf (),
 170 .BR snprintf (),
 171 .BR vsprintf (),
 172 or
 173 .BR vsnprintf ()
 174 would cause copying to take place between objects that overlap
 175 (e.g., if the target string array and one of the supplied input arguments
 176 refer to the same buffer).
 177 See NOTES.
 178 .SS Format of the format string
 179 The format string is a character string, beginning and ending
 180 in its initial shift state, if any.
 181 The format string is composed of zero or more directives: ordinary
 182 characters (not
 183 .BR % ),
 184 which are copied unchanged to the output stream;
 185 and conversion specifications, each of which results in fetching zero or
 186 more subsequent arguments.
 187 Each conversion specification is introduced by
 188 the character
 189 .BR % ,
 190 and ends with a
 191 .IR "conversion specifier" .
 192 In between there may be (in this order) zero or more
 193 .IR flags ,
 194 an optional minimum
 195 .IR "field width" ,
 196 an optional
 197 .I precision
 198 and an optional
 199 .IR "length modifier" .
 200 .PP
 201 The arguments must correspond properly (after type promotion) with the
 202 conversion specifier.
 203 By default, the arguments are used in the order
 204 given, where each \(aq*\(aq (see
 205 .I "Field width"
 206 and
 207 .I Precision
 208 below) and each conversion specifier asks for the next
 209 argument (and it is an error if insufficiently many arguments are given).
 210 One can also specify explicitly which argument is taken,
 211 at each place where an argument is required, by writing "%m$" instead
 212 of \(aq%\(aq and "*m$" instead of \(aq*\(aq,
 213 where the decimal integer \fIm\fP denotes
 214 the position in the argument list of the desired argument, indexed starting
 215 from 1.
 216 Thus,
 217 .in +4n
 218 .nf
 219
 220 printf("%*d", width, num);
 221
 222 .fi
 223 .in
 224 and
 225 .in +4n
 226 .nf
 227
 228 printf("%2$*1$d", width, num);
 229
 230 .fi
 231 .in
 232 are equivalent.
 233 The second style allows repeated references to the
 234 same argument.
 235 The C99 standard does not include the style using \(aq$\(aq,
 236 which comes from the Single UNIX Specification.
 237 If the style using
 238 \(aq$\(aq is used, it must be used throughout for all conversions taking an
 239 argument and all width and precision arguments, but it may be mixed
 240 with "%%" formats, which do not consume an argument.
 241 There may be no
 242 gaps in the numbers of arguments specified using \(aq$\(aq; for example, if
 243 arguments 1 and 3 are specified, argument 2 must also be specified
 244 somewhere in the format string.
 245 .PP
 246 For some numeric conversions a radix character ("decimal point") or
 247 thousands' grouping character is used.
 248 The actual character used
 249 depends on the
 250 .B LC_NUMERIC
 251 part of the locale.
 252 (See
 253 .BR setlocale (3).)
 254 The POSIX locale
 255 uses \(aq.\(aq as radix character, and does not have a grouping character.
 256 Thus,
 257 .in +4n
 258 .nf
 259
 260     printf("%\(aq.2f", 1234567.89);
 261
 262 .fi
 263 .in
 264 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
 265 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
 266 .SS Flag characters
 267 The character % is followed by zero or more of the following flags:
 268 .TP
 269 .B #
 270 The value should be converted to an "alternate form".
 271 For
 272 .B o
 273 conversions, the first character of the output string is made zero
 274 (by prefixing a 0 if it was not zero already).
 275 For
 276 .B x
 277 and
 278 .B X
 279 conversions, a nonzero result has the string "0x" (or "0X" for
 280 .B X
 281 conversions) prepended to it.
 282 For
 283 .BR a ,
 284 .BR A ,
 285 .BR e ,
 286 .BR E ,
 287 .BR f ,
 288 .BR F ,
 289 .BR g ,
 290 and
 291 .B G
 292 conversions, the result will always contain a decimal point, even if no
 293 digits follow it (normally, a decimal point appears in the results of those
 294 conversions only if a digit follows).
 295 For
 296 .B g
 297 and
 298 .B G
 299 conversions, trailing zeros are not removed from the result as they would
 300 otherwise be.
 301 For other conversions, the result is undefined.
 302 .TP
 303 .B \&0
 304 The value should be zero padded.
 305 For
 306 .BR d ,
 307 .BR i ,
 308 .BR o ,
 309 .BR u ,
 310 .BR x ,
 311 .BR X ,
 312 .BR a ,
 313 .BR A ,
 314 .BR e ,
 315 .BR E ,
 316 .BR f ,
 317 .BR F ,
 318 .BR g ,
 319 and
 320 .B G
 321 conversions, the converted value is padded on the left with zeros rather
 322 than blanks.
 323 If the
 324 .B \&0
 325 and
 326 .B \-
 327 flags both appear, the
 328 .B \&0
 329 flag is ignored.
 330 If a precision is given with a numeric conversion
 331 .RB ( d ,
 332 .BR i ,
 333 .BR o ,
 334 .BR u ,
 335 .BR x ,
 336 and
 337 .BR X ),
 338 the
 339 .B \&0
 340 flag is ignored.
 341 For other conversions, the behavior is undefined.
 342 .TP
 343 .B \-
 344 The converted value is to be left adjusted on the field boundary.
 345 (The default is right justification.)
 346 The converted value is padded on the right with blanks, rather
 347 than on the left with blanks or zeros.
 348 A
 349 .B \-
 350 overrides a
 351 .B \&0
 352 if both are given.
 353 .TP
 354 .B \(aq \(aq
 355 (a space) A blank should be left before a positive number
 356 (or empty string) produced by a signed conversion.
 357 .TP
 358 .B +
 359 A sign (+ or \-) should always be placed before a number produced by a signed
 360 conversion.
 361 By default, a sign is used only for negative numbers.
 362 A
 363 .B +
 364 overrides a space if both are used.
 365 .PP
 366 The five flag characters above are defined in the C99 standard.
 367 The Single UNIX Specification specifies one further flag character.
 368 .TP
 369 .B \(aq
 370 For decimal conversion
 371 .RB ( i ,
 372 .BR d ,
 373 .BR u ,
 374 .BR f ,
 375 .BR F ,
 376 .BR g ,
 377 .BR G )
 378 the output is to be grouped with thousands' grouping characters
 379 if the locale information indicates any.
 380 (See
 381 .BR setlocale (3).)
 382 Note that many versions of
 383 .BR gcc (1)
 384 cannot parse this option and will issue a warning.
 385 (SUSv2 did not
 386 include \fI%\(aqF\fP, but SUSv3 added it.)
 387 .PP
 388 glibc 2.2 adds one further flag character.
 389 .TP
 390 .B I
 391 For decimal integer conversion
 392 .RB ( i ,
 393 .BR d ,
 394 .BR u )
 395 the output uses the locale's alternative output digits, if any.
 396 For example, since glibc 2.2.3 this will give Arabic-Indic digits
 397 in the Persian ("fa_IR") locale.
 398 .\" outdigits keyword in locale file
 399 .SS Field width
 400 An optional decimal digit string (with nonzero first digit) specifying
 401 a minimum field width.
 402 If the converted value has fewer characters
 403 than the field width, it will be padded with spaces on the left
 404 (or right, if the left-adjustment flag has been given).
 405 Instead of a decimal digit string one may write "*" or "*m$"
 406 (for some decimal integer \fIm\fP) to specify that the field width
 407 is given in the next argument, or in the \fIm\fP-th argument, respectively,
 408 which must be of type
 409 .IR int .
 410 A negative field width is taken as a \(aq\-\(aq flag followed by a
 411 positive field width.
 412 In no case does a nonexistent or small field width cause truncation of a
 413 field; if the result of a conversion is wider than the field width, the
 414 field is expanded to contain the conversion result.
 415 .SS Precision
 416 An optional precision, in the form of a period (\(aq.\(aq)  followed by an
 417 optional decimal digit string.
 418 Instead of a decimal digit string one may write "*" or "*m$"
 419 (for some decimal integer \fIm\fP) to specify that the precision
 420 is given in the next argument, or in the \fIm\fP-th argument, respectively,
 421 which must be of type
 422 .IR int .
 423 If the precision is given as just \(aq.\(aq, the precision is taken to
 424 be zero.
 425 A negative precision is taken as if the precision were omitted.
 426 This gives the minimum number of digits to appear for
 427 .BR d ,
 428 .BR i ,
 429 .BR o ,
 430 .BR u ,
 431 .BR x ,
 432 and
 433 .B X
 434 conversions, the number of digits to appear after the radix character for
 435 .BR a ,
 436 .BR A ,
 437 .BR e ,
 438 .BR E ,
 439 .BR f ,
 440 and
 441 .B F
 442 conversions, the maximum number of significant digits for
 443 .B g
 444 and
 445 .B G
 446 conversions, or the maximum number of characters to be printed from a
 447 string for
 448 .B s
 449 and
 450 .B S
 451 conversions.
 452 .SS Length modifier
 453 Here, "integer conversion" stands for
 454 .BR d ,
 455 .BR i ,
 456 .BR o ,
 457 .BR u ,
 458 .BR x ,
 459 or
 460 .B X
 461 conversion.
 462 .TP
 463 .B hh
 464 A following integer conversion corresponds to a
 465 .I signed char
 466 or
 467 .I unsigned char
 468 argument, or a following
 469 .B n
 470 conversion corresponds to a pointer to a
 471 .I signed char
 472 argument.
 473 .TP
 474 .B h
 475 A following integer conversion corresponds to a
 476 .I short int
 477 or
 478 .I unsigned short int
 479 argument, or a following
 480 .B n
 481 conversion corresponds to a pointer to a
 482 .I short int
 483 argument.
 484 .TP
 485 .B l
 486 (ell) A following integer conversion corresponds to a
 487 .I long int
 488 or
 489 .I unsigned long int
 490 argument, or a following
 491 .B n
 492 conversion corresponds to a pointer to a
 493 .I long int
 494 argument, or a following
 495 .B c
 496 conversion corresponds to a
 497 .I wint_t
 498 argument, or a following
 499 .B s
 500 conversion corresponds to a pointer to
 501 .I wchar_t
 502 argument.
 503 .TP
 504 .B ll
 505 (ell-ell).
 506 A following integer conversion corresponds to a
 507 .I long long int
 508 or
 509 .I unsigned long long int
 510 argument, or a following
 511 .B n
 512 conversion corresponds to a pointer to a
 513 .I long long int
 514 argument.
 515 .TP
 516 .B q
 517 A synonym for
 518 .BR ll .
 519 This is a nonstandard extension, derived from BSD;
 520 avoid its use in new code.
 521 .TP
 522 .B L
 523 A following
 524 .BR a ,
 525 .BR A ,
 526 .BR e ,
 527 .BR E ,
 528 .BR f ,
 529 .BR F ,
 530 .BR g ,
 531 or
 532 .B G
 533 conversion corresponds to a
 534 .I long double
 535 argument.
 536 (C99 allows %LF, but SUSv2 does not.)
 537 .TP
 538 .B j
 539 A following integer conversion corresponds to an
 540 .I intmax_t
 541 or
 542 .I uintmax_t
 543 argument, or a following
 544 .B n
 545 conversion corresponds to a pointer to an
 546 .I intmax_t
 547 argument.
 548 .TP
 549 .B z
 550 A following integer conversion corresponds to a
 551 .I size_t
 552 or
 553 .I ssize_t
 554 argument, or a following
 555 .B n
 556 conversion corresponds to a pointer to a
 557 .I size_t
 558 argument.
 559 .TP
 560 .B Z
 561 A nonstandard synonym for
 562 .BR z
 563 that predates the appearance of
 564 .BR z .
 565 Do not use in new code.
 566 .TP
 567 .B t
 568 A following integer conversion corresponds to a
 569 .I ptrdiff_t
 570 argument, or a following
 571 .B n
 572 conversion corresponds to a pointer to a
 573 .I ptrdiff_t
 574 argument.
 575 .PP
 576 SUSv3 specifies all of the above,
 577 except for those modifiers explicitly noted as being nonstandard extensions.
 578 SUSv2 specified only the length modifiers
 579 .B h
 580 (in
 581 .BR hd ,
 582 .BR hi ,
 583 .BR ho ,
 584 .BR hx ,
 585 .BR hX ,
 586 .BR hn )
 587 and
 588 .B l
 589 (in
 590 .BR ld ,
 591 .BR li ,
 592 .BR lo ,
 593 .BR lx ,
 594 .BR lX ,
 595 .BR ln ,
 596 .BR lc ,
 597 .BR ls )
 598 and
 599 .B L
 600 (in
 601 .BR Le ,
 602 .BR LE ,
 603 .BR Lf ,
 604 .BR Lg ,
 605 .BR LG ).
 606 .PP
 607 As a nonstandard extension, the GNU implementations treats
 608 .B ll
 609 and
 610 .B L
 611 as synonyms, so that one can, for example, write
 612 .BR llg
 613 (as a synonym for the standards-compliant
 614 .RB Lg )
 615 and
 616 .BR Ld
 617 (as a synonym for the standards compliant
 618 .BR lld ).
 619 Such usage is nonportable.
 620 .\"
 621 .SS Conversion specifiers
 622 A character that specifies the type of conversion to be applied.
 623 The conversion specifiers and their meanings are:
 624 .TP
 625 .BR d ", " i
 626 The
 627 .I int
 628 argument is converted to signed decimal notation.
 629 The precision, if any, gives the minimum number of digits
 630 that must appear; if the converted value requires fewer digits, it is
 631 padded on the left with zeros.
 632 The default precision is 1.
 633 When 0 is printed with an explicit precision 0, the output is empty.
 634 .TP
 635 .BR o ", " u ", " x ", " X
 636 The
 637 .I "unsigned int"
 638 argument is converted to unsigned octal
 639 .RB ( o ),
 640 unsigned decimal
 641 .RB ( u ),
 642 or unsigned hexadecimal
 643 .RB ( x
 644 and
 645 .BR X )
 646 notation.
 647 The letters
 648 .B abcdef
 649 are used for
 650 .B x
 651 conversions; the letters
 652 .B ABCDEF
 653 are used for
 654 .B X
 655 conversions.
 656 The precision, if any, gives the minimum number of digits
 657 that must appear; if the converted value requires fewer digits, it is
 658 padded on the left with zeros.
 659 The default precision is 1.
 660 When 0 is printed with an explicit precision 0, the output is empty.
 661 .TP
 662 .BR e ", " E
 663 The
 664 .I double
 665 argument is rounded and converted in the style
 666 .RB [\-]d \&. ddd e \(+-dd
 667 where there is one digit before the decimal-point character and the number
 668 of digits after it is equal to the precision; if the precision is missing,
 669 it is taken as 6; if the precision is zero, no decimal-point character
 670 appears.
 671 An
 672 .B E
 673 conversion uses the letter
 674 .B E
 675 (rather than
 676 .BR e )
 677 to introduce the exponent.
 678 The exponent always contains at least two
 679 digits; if the value is zero, the exponent is 00.
 680 .TP
 681 .BR f ", " F
 682 The
 683 .I double
 684 argument is rounded and converted to decimal notation in the style
 685 .RB [\-]ddd \&. ddd,
 686 where the number of digits after the decimal-point character is equal to
 687 the precision specification.
 688 If the precision is missing, it is taken as
 689 6; if the precision is explicitly zero, no decimal-point character appears.
 690 If a decimal point appears, at least one digit appears before it.
 691 .IP
 692 (SUSv2 does not know about
 693 .B F
 694 and says that character string representations for infinity and NaN
 695 may be made available.
 696 SUSv3 adds a specification for
 697 .BR F .
 698 The C99 standard specifies "[\-]inf" or "[\-]infinity"
 699 for infinity, and a string starting with "nan" for NaN, in the case of
 700 .B f
 701 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of
 702 .B F
 703 conversion.)
 704 .TP
 705 .BR g ", " G
 706 The
 707 .I double
 708 argument is converted in style
 709 .B f
 710 or
 711 .B e
 712 (or
 713 .B F
 714 or
 715 .B E
 716 for
 717 .B G
 718 conversions).
 719 The precision specifies the number of significant digits.
 720 If the precision is missing, 6 digits are given; if the precision is zero,
 721 it is treated as 1.
 722 Style
 723 .B e
 724 is used if the exponent from its conversion is less than \-4 or greater
 725 than or equal to the precision.
 726 Trailing zeros are removed from the
 727 fractional part of the result; a decimal point appears only if it is
 728 followed by at least one digit.
 729 .TP
 730 .BR a ", " A
 731 (C99; not in SUSv2, but added in SUSv3)
 732 For
 733 .B a
 734 conversion, the
 735 .I double
 736 argument is converted to hexadecimal notation (using the letters abcdef)
 737 in the style
 738 .RB [\-] 0x h \&. hhhh p \(+-;
 739 for
 740 .B A
 741 conversion the prefix
 742 .BR 0X ,
 743 the letters ABCDEF, and the exponent separator
 744 .B P
 745 is used.
 746 There is one hexadecimal digit before the decimal point,
 747 and the number of digits after it is equal to the precision.
 748 The default precision suffices for an exact representation of the value
 749 if an exact representation in base 2 exists
 750 and otherwise is sufficiently large to distinguish values of type
 751 .IR double .
 752 The digit before the decimal point is unspecified for nonnormalized
 753 numbers, and nonzero but otherwise unspecified for normalized numbers.
 754 .TP
 755 .B c
 756 If no
 757 .B l
 758 modifier is present, the
 759 .I int
 760 argument is converted to an
 761 .IR "unsigned char" ,
 762 and the resulting character is written.
 763 If an
 764 .B l
 765 modifier is present, the
 766 .I wint_t
 767 (wide character) argument is converted to a multibyte sequence by a call
 768 to the
 769 .BR wcrtomb (3)
 770 function, with a conversion state starting in the initial state, and the
 771 resulting multibyte string is written.
 772 .TP
 773 .B s
 774 If no
 775 .B l
 776 modifier is present: the
 777 .I "const char\ *"
 778 argument is expected to be a pointer to an array of character type (pointer
 779 to a string).
 780 Characters from the array are written up to (but not
 781 including) a terminating null byte (\(aq\\0\(aq);
 782 if a precision is specified, no more than the number specified
 783 are written.
 784 If a precision is given, no null byte need be present;
 785 if the precision is not specified, or is greater than the size of the
 786 array, the array must contain a terminating null byte.
 787 .IP
 788 If an
 789 .B l
 790 modifier is present: the
 791 .I "const wchar_t\ *"
 792 argument is expected to be a pointer to an array of wide characters.
 793 Wide characters from the array are converted to multibyte characters
 794 (each by a call to the
 795 .BR wcrtomb (3)
 796 function, with a conversion state starting in the initial state before
 797 the first wide character), up to and including a terminating null
 798 wide character.
 799 The resulting multibyte characters are written up to
 800 (but not including) the terminating null byte.
 801 If a precision is
 802 specified, no more bytes than the number specified are written, but
 803 no partial multibyte characters are written.
 804 Note that the precision
 805 determines the number of
 806 .I bytes
 807 written, not the number of
 808 .I wide characters
 809 or
 810 .IR "screen positions" .
 811 The array must contain a terminating null wide character, unless a
 812 precision is given and it is so small that the number of bytes written
 813 exceeds it before the end of the array is reached.
 814 .TP
 815 .B C
 816 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
 817 Synonym for
 818 .BR lc .
 819 Don't use.
 820 .TP
 821 .B S
 822 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
 823 Synonym for
 824 .BR ls .
 825 Don't use.
 826 .TP
 827 .B p
 828 The
 829 .I "void\ *"
 830 pointer argument is printed in hexadecimal (as if by
 831 .B %#x
 832 or
 833 .BR %#lx ).
 834 .TP
 835 .B n
 836 The number of characters written so far is stored into the integer
 837 pointed to by the corresponding argument.
 838 That argument shall be an
 839 .IR "int\ *" ,
 840 or variant whose size matches the (optionally)
 841 supplied integer length modifier.
 842 No argument is converted.
 843 (This specifier is not supported by the bionic C library.)
 844 The behavior is undefined if the conversion specification includes
 845 any flags, a field width, or a precision.
 846 .TP
 847 .B m
 848 (Glibc extension; supported by uClibc and musl.)
 849 Print output of
 850 .IR strerror(errno) .
 851 No argument is required.
 852 .TP
 853 .B %
 854 A \(aq%\(aq is written.
 855 No argument is converted.
 856 The complete conversion
 857 specification is \(aq%%\(aq.
 858 .SH RETURN VALUE
 859 Upon successful return, these functions return the number of characters
 860 printed (excluding the null byte used to end output to strings).
 861 .PP
 862 The functions
 863 .BR snprintf ()
 864 and
 865 .BR vsnprintf ()
 866 do not write more than
 867 .I size
 868 bytes (including the terminating null byte (\(aq\e0\(aq)).
 869 If the output was truncated due to this limit, then the return value
 870 is the number of characters (excluding the terminating null byte)
 871 which would have been written to the final string if enough space
 872 had been available.
 873 Thus, a return value of
 874 .I size
 875 or more means that the output was truncated.
 876 (See also below under NOTES.)
 877 .PP
 878 If an output error is encountered, a negative value is returned.
 879 .SH ATTRIBUTES
 880 For an explanation of the terms used in this section, see
 881 .BR attributes (7).
 882 .TS
 883 allbox;
 884 lbw23 lb lb
 885 l l l.
 886 Interface       Attribute       Value
 887 T{
 888 .BR printf (),
 889 .BR fprintf (),
 890 .br
 891 .BR sprintf (),
 892 .BR snprintf (),
 893 .br
 894 .BR vprintf (),
 895 .BR vfprintf (),
 896 .br
 897 .BR vsprintf (),
 898 .BR vsnprintf ()
 899 T}      Thread safety   MT-Safe locale
 900 .TE
 901 .sp 1
 902 .SH CONFORMING TO
 903 .BR fprintf (),
 904 .BR printf (),
 905 .BR sprintf (),
 906 .BR vprintf (),
 907 .BR vfprintf (),
 908 .BR vsprintf ():
 909 POSIX.1-2001, POSIX.1-2008, C89, C99.
 910 .PP
 911 .BR snprintf (),
 912 .BR vsnprintf ():
 913 POSIX.1-2001, POSIX.1-2008, C99.
 914 .PP
 915 The
 916 .BR dprintf ()
 917 and
 918 .BR vdprintf ()
 919 functions were originally GNU extensions that were later standardized
 920 in POSIX.1-2008.
 921 .PP
 922 Concerning the return value of
 923 .BR snprintf (),
 924 SUSv2 and C99 contradict each other: when
 925 .BR snprintf ()
 926 is called with
 927 .IR size =0
 928 then SUSv2 stipulates an unspecified return value less than 1,
 929 while C99 allows
 930 .I str
 931 to be NULL in this case, and gives the return value (as always)
 932 as the number of characters that would have been written in case
 933 the output string has been large enough.
 934 POSIX.1-2001 and later align their specification of
 935 .BR snprintf ()
 936 with C99.
 937 .\" .PP
 938 .\" Linux libc4 knows about the five C standard flags.
 939 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
 940 .\" and the conversions
 941 .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
 942 .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
 943 .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
 944 .\" where \fBF\fP is a synonym for \fBf\fP.
 945 .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
 946 .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
 947 .\" (This is bad, and caused serious bugs later, when
 948 .\" support for \fB%D\fP disappeared.)
 949 .\" No locale-dependent radix character,
 950 .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
 951 .\" .PP
 952 .\" Linux libc5 knows about the five C standard flags and the \(aq flag,
 953 .\" locale, "%m$" and "*m$".
 954 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
 955 .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
 956 .\" both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
 957 .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
 958 .\" but adds the conversion character
 959 .\" .BR m ,
 960 .\" which outputs
 961 .\" .IR strerror(errno) .
 962 .\" .PP
 963 .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
 964 .PP
 965 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
 966 and conversion characters \fBa\fP and \fBA\fP.
 967 .PP
 968 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
 969 and the flag character \fBI\fP.
 970 .SH NOTES
 971 Some programs imprudently rely on code such as the following
 972 .PP
 973     sprintf(buf, "%s some further text", buf);
 974 .PP
 975 to append text to
 976 .IR buf .
 977 However, the standards explicitly note that the results are undefined
 978 if source and destination buffers overlap when calling
 979 .BR sprintf (),
 980 .BR snprintf (),
 981 .BR vsprintf (),
 982 and
 983 .BR vsnprintf ().
 984 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
 985 Depending on the version of
 986 .BR gcc (1)
 987 used, and the compiler options employed, calls such as the above will
 988 .B not
 989 produce the expected results.
 990 .PP
 991 The glibc implementation of the functions
 992 .BR snprintf ()
 993 and
 994 .BR vsnprintf ()
 995 conforms to the C99 standard, that is, behaves as described above,
 996 since glibc version 2.1.
 997 Until glibc 2.0.6, they would return \-1
 998 when the output was truncated.
 999 .\" .SH HISTORY
1000 .\" UNIX V7 defines the three routines
1001 .\" .BR printf (),
1002 .\" .BR fprintf (),
1003 .\" .BR sprintf (),
1004 .\" and has the flag \-, the width or precision *, the length modifier l,
1005 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
1006 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
1007 .\" #, + and <space> and no longer mentions D,O,U,X.
1008 .\" 2.11BSD has
1009 .\" .BR vprintf (),
1010 .\" .BR vfprintf (),
1011 .\" .BR vsprintf (),
1012 .\" and warns not to use D,O,U,X.
1013 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
1014 .\" and the conversions n, p, E, G, X (with current meaning)
1015 .\" and deprecates D,O,U.
1016 .\" 4.4BSD introduces the functions
1017 .\" .BR snprintf ()
1018 .\" and
1019 .\" .BR vsnprintf (),
1020 .\" and the length modifier q.
1021 .\" FreeBSD also has functions
1022 .\" .BR asprintf ()
1023 .\" and
1024 .\" .BR vasprintf (),
1025 .\" that allocate a buffer large enough for
1026 .\" .BR sprintf ().
1027 .\" In glibc there are functions
1028 .\" .BR dprintf ()
1029 .\" and
1030 .\" .BR vdprintf ()
1031 .\" that print to a file descriptor instead of a stream.
1032 .SH BUGS
1033 Because
1034 .BR sprintf ()
1035 and
1036 .BR vsprintf ()
1037 assume an arbitrarily long string, callers must be careful not to overflow
1038 the actual space; this is often impossible to assure.
1039 Note that the length
1040 of the strings produced is locale-dependent and difficult to predict.
1041 Use
1042 .BR snprintf ()
1043 and
1044 .BR vsnprintf ()
1045 instead (or
1046 .BR asprintf (3)
1047 and
1048 .BR vasprintf (3)).
1049 .\" .PP
1050 .\" Linux libc4.[45] does not have a
1051 .\" .BR snprintf (),
1052 .\" but provides a libbsd that contains an
1053 .\" .BR snprintf ()
1054 .\" equivalent to
1055 .\" .BR sprintf (),
1056 .\" that is, one that ignores the
1057 .\" .I size
1058 .\" argument.
1059 .\" Thus, the use of
1060 .\" .BR snprintf ()
1061 .\" with early libc4 leads to serious security problems.
1062 .PP
1063 Code such as
1064 .BI printf( foo );
1065 often indicates a bug, since
1066 .I foo
1067 may contain a % character.
1068 If
1069 .I foo
1070 comes from untrusted user input, it may contain \fB%n\fP, causing the
1071 .BR printf ()
1072 call to write to memory and creating a security hole.
1073 .\" .PP
1074 .\" Some floating-point conversions under early libc4
1075 .\" caused memory leaks.
1076 .SH EXAMPLE
1077 To print
1078 .I Pi
1079 to five decimal places:
1080 .in +4n
1081 .nf
1082
1083 #include <math.h>
1084 #include <stdio.h>
1085 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
1086 .fi
1087 .in
1088 .PP
1089 To print a date and time in the form "Sunday, July 3, 10:02",
1090 where
1091 .I weekday
1092 and
1093 .I month
1094 are pointers to strings:
1095 .in +4n
1096 .nf
1097
1098 #include <stdio.h>
1099 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
1100         weekday, month, day, hour, min);
1101 .fi
1102 .in
1103 .PP
1104 Many countries use the day-month-year order.
1105 Hence, an internationalized version must be able to print
1106 the arguments in an order specified by the format:
1107 .in +4n
1108 .nf
1109
1110 #include <stdio.h>
1111 fprintf(stdout, format,
1112         weekday, month, day, hour, min);
1113
1114 .fi
1115 .in
1116 where
1117 .I format
1118 depends on locale, and may permute the arguments.
1119 With the value:
1120 .in +4n
1121 .nf
1122
1123 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
1124
1125 .fi
1126 .in
1127 one might obtain "Sonntag, 3. Juli, 10:02".
1128 .PP
1129 To allocate a sufficiently large string and print into it
1130 (code correct for both glibc 2.0 and glibc 2.1):
1131 .nf
1132
1133 #include <stdio.h>
1134 #include <stdlib.h>
1135 #include <stdarg.h>
1136
1137 char *
1138 make_message(const char *fmt, ...)
1139 {
1140     int size = 0;
1141     char *p = NULL;
1142     va_list ap;
1143
1144     /* Determine required size */
1145
1146     va_start(ap, fmt);
1147     size = vsnprintf(p, size, fmt, ap);
1148     va_end(ap);
1149
1150     if (size < 0)
1151         return NULL;
1152
1153     size++;             /* For '\\0' */
1154     p = malloc(size);
1155     if (p == NULL)
1156         return NULL;
1157
1158     va_start(ap, fmt);
1159     size = vsnprintf(p, size, fmt, ap);
1160     va_end(ap);
1161
1162     if (size < 0) {
1163         free(p);
1164         return NULL;
1165     }
1166
1167     return p;
1168 }
1169 .fi
1170 .PP
1171 If truncation occurs in glibc versions prior to 2.0.6, this is treated as an
1172 error instead of being handled gracefully.
1173 .SH SEE ALSO
1174 .BR printf (1),
1175 .BR asprintf (3),
1176 .BR puts (3),
1177 .BR scanf (3),
1178 .BR setlocale (3),
1179 .BR strfromd (3),
1180 .BR wcrtomb (3),
1181 .BR wprintf (3),
1182 .BR locale (5)