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