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