man3/printf.3

   1 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .\"
  24 .\" Earlier versions of this page influenced the present text.
  25 .\" It was derived from a Berkeley page with version
  26 .\"       @(#)printf.3    6.14 (Berkeley) 7/30/91
  27 .\" converted for Linux by faith@cs.unc.edu, updated by
  28 .\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible.
  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  2000-10-16 "Linux Manpage" "Linux Programmer's Manual"
  35 .SH NAME
  36 printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf \- formatted output conversion
  37 .SH SYNOPSIS
  38 .B #include <stdio.h>
  39 .sp
  40 .BI "int printf(const char *" format ", ...);"
  41 .br
  42 .BI "int fprintf(FILE *" stream ", const char *" format ", ...);"
  43 .br
  44 .BI "int sprintf(char *" str ", const char *" format ", ...);"
  45 .br
  46 .BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);"
  47 .sp
  48 .B #include <stdarg.h>
  49 .sp
  50 .BI "int vprintf(const char *" format ", va_list " ap );
  51 .br
  52 .BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap );
  53 .br
  54 .BI "int vsprintf(char *" str ", const char *" format ", va_list " ap );
  55 .br
  56 .BI "int vsnprintf(char *" str ", size_t " size ", const char *" format ", va_list " ap );
  57 .SH DESCRIPTION
  58 The functions in the
  59 .B printf
  60 family produce output according to a
  61 .I format
  62 as described below. The functions
  63 .B printf
  64 and
  65 .B vprintf
  66 write output to
  67 .IR stdout ,
  68 the standard output stream;
  69 .B fprintf
  70 and
  71 .B vfprintf
  72 write output to the given output
  73 .IR stream ;
  74 .BR sprintf ,
  75 .BR snprintf ,
  76 .B vsprintf
  77 and
  78 .B vsnprintf
  79 write to the character string
  80 .IR  str .
  81 .PP
  82 The functions
  83 .BR vprintf ,
  84 .BR vfprintf ,
  85 .BR vsprintf ,
  86 .B vsnprintf
  87 are equivalent to the functions
  88 .BR printf ,
  89 .BR fprintf ,
  90 .BR sprintf ,
  91 .BR snprintf ,
  92 respectively, except that they are called with a va_list instead
  93 of a variable number of arguments. These functions do not call the
  94 .I va_end
  95 macro. Consequently, the value of
  96 .I ap
  97 is undefined after the call. The application should call
  98 .I va_end(ap)
  99 itself afterwards.
 100 .PP
 101 These eight functions write the output under the control of a
 102 .I format
 103 string that specifies how subsequent arguments (or arguments accessed via
 104 the variable-length argument facilities of
 105 .BR stdarg (3))
 106 are converted for output.
 107 .SS "Return value"
 108 Upon successful return, these functions return the number of characters
 109 printed (not including the trailing '\e0' used to end output to strings).
 110 The functions
 111 .BR snprintf " and " vsnprintf
 112 do not write more than
 113 .I size
 114 bytes (including the trailing '\e0').
 115 If the output was truncated due to this limit then the return value
 116 is the number of characters (not including the trailing '\e0')
 117 which would have been written to the final string if enough space
 118 had been available. Thus, a return value of
 119 .I size
 120 or more means that the output was truncated. (See also below
 121 under NOTES.)
 122 If an output error is encountered, a negative value is returned.
 123 .SS "Format of the format string"
 124 The format string is a character string, beginning and ending
 125 in its initial shift state, if any.
 126 The format string is composed of zero or more directives: ordinary
 127 characters (not
 128 .BR % ),
 129 which are copied unchanged to the output stream;
 130 and conversion specifications, each of which results in fetching zero or
 131 more subsequent arguments.  Each conversion specification is introduced by
 132 the character
 133 .BR % ,
 134 and ends with a
 135 .IR "conversion specifier" .
 136 In between there may be (in this order) zero or more
 137 .IR flags ,
 138 an optional minimum
 139 .IR "field width" ,
 140 an optional
 141 .I precision
 142 and an optional
 143 .IR "length modifier" .
 144
 145 The arguments must correspond properly (after type promotion) with the
 146 conversion specifier. By default, the arguments are used in the order
 147 given, where each `*' and each conversion specifier asks for the next
 148 argument (and it is an error if insufficiently many arguments are given).
 149 One can also specify explicitly which argument is taken,
 150 at each place where an argument is required, by writing `%m$' instead
 151 of `%' and `*m$' instead of `*', where the decimal integer m denotes
 152 the position in the argument list of the desired argument, indexed starting
 153 from 1. Thus,
 154 .RS
 155 .nf
 156         printf("%*d", width, num);
 157 .fi
 158 .RE
 159 and
 160 .RS
 161 .nf
 162         printf("%2$*1$d", width, num);
 163 .fi
 164 .RE
 165 are equivalent. The second style allows repeated references to the
 166 same argument. The C99 standard does not include the style using `$',
 167 which comes from the Single Unix Specification.  If the style using
 168 `$' is used, it must be used throughout for all conversions taking an
 169 argument and all width and precision arguments, but it may be mixed
 170 with `%%' formats which do not consume an argument.  There may be no
 171 gaps in the numbers of arguments specified using `$'; for example, if
 172 arguments 1 and 3 are specified, argument 2 must also be specified
 173 somewhere in the format string.
 174
 175 For some numeric conversions a radix character (`decimal point') or
 176 thousands' grouping character is used. The actual character used
 177 depends on the LC_NUMERIC part of the locale. The POSIX locale
 178 uses `.' as radix character, and does not have a grouping character.
 179 Thus,
 180 .RS
 181 .nf
 182         printf("%'.2f", 1234567.89);
 183 .fi
 184 .RE
 185 results in `1234567.89' in the POSIX locale, in `1234567,89' in the
 186 nl_NL locale, and in `1.234.567,89' in the da_DK locale.
 187 .SS "The flag characters"
 188 The character % is followed by zero or more of the following flags:
 189 .TP
 190 .B #
 191 The value should be converted to an ``alternate form''.
 192 For
 193 .BR o
 194 conversions, the first character of the output string is made zero
 195 (by prefixing a 0 if it was not zero already).
 196 For
 197 .B x
 198 and
 199 .B X
 200 conversions, a non\-zero result has the string `0x' (or `0X' for
 201 .B X
 202 conversions) prepended to it.  For
 203 .BR a ,
 204 .BR A ,
 205 .BR e ,
 206 .BR E ,
 207 .BR f ,
 208 .BR F ,
 209 .BR g ,
 210 and
 211 .B G
 212 conversions, the result will always contain a decimal point, even if no
 213 digits follow it (normally, a decimal point appears in the results of those
 214 conversions only if a digit follows).  For
 215 .B g
 216 and
 217 .B G
 218 conversions, trailing zeros are not removed from the result as they would
 219 otherwise be.
 220 For other conversions, the result is undefined.
 221 .TP
 222 .B \&0
 223 The value should be zero padded.  For
 224 .BR d ,
 225 .BR i ,
 226 .BR o ,
 227 .BR u ,
 228 .BR x ,
 229 .BR X ,
 230 .BR a ,
 231 .BR A ,
 232 .BR e ,
 233 .BR E ,
 234 .BR f ,
 235 .BR F ,
 236 .BR g ,
 237 and
 238 .B G
 239 conversions, the converted value is padded on the left with zeros rather
 240 than blanks.
 241 If the
 242 .B \&0
 243 and
 244 .B \-
 245 flags both appear, the
 246 .B \&0
 247 flag is ignored.
 248 If a precision is given with a numeric conversion
 249 .BR "" ( d ,
 250 .BR i ,
 251 .BR o ,
 252 .BR u ,
 253 .BR x ,
 254 and
 255 .BR X ),
 256 the
 257 .B \&0
 258 flag is ignored.
 259 For other conversions, the behavior is undefined.
 260 .TP
 261 .B \-
 262 The converted value is to be left adjusted on the field boundary.
 263 (The default is right justification.) Except for
 264 .B n
 265 conversions, the converted value is padded on the right with blanks, rather
 266 than on the left with blanks or zeros.  A
 267 .B \-
 268 overrides a
 269 .B \&0
 270 if both are given.
 271 .TP
 272 .B ' '
 273 (a space) A blank should be left before a positive number
 274 (or empty string) produced by a signed conversion.
 275 .TP
 276 .B +
 277 A sign (+ or -) always be placed before a number produced by a signed
 278 conversion.  By default a sign is used only for negative numbers. A
 279 .B +
 280 overrides a space if both are used.
 281 .PP
 282 The five flag characters above are defined in the C standard.
 283 The SUSv2 specifies one further flag character.
 284 .TP
 285 .B '
 286 For decimal conversion
 287 .BR "" ( i ,
 288 .BR d ,
 289 .BR u ,
 290 .BR f ,
 291 .BR F ,
 292 .BR g ,
 293 .BR G )
 294 the output is to be grouped with thousands' grouping characters
 295 if the locale information indicates any.  Note that many versions of
 296 .B gcc
 297 cannot parse this option and will issue a warning.  SUSv2 does not
 298 include %'F.
 299 .PP
 300 glibc 2.2 adds one further flag character.
 301 .TP
 302 .B I
 303 For decimal integer conversion
 304 .BR "" ( i ,
 305 .BR d ,
 306 .BR u )
 307 the output uses the locale's alternative output digits, if any.
 308 For example, since glibc 2.2.3 this will give Arabic-Indic digits
 309 in the Persian (`fa_IR') locale.
 310 .\" outdigits keyword in locale file
 311 .SS "The field width"
 312 An optional decimal digit string (with non-zero first digit) specifying
 313 a minimum field width.  If the converted value has fewer characters
 314 than the field width, it will be padded with spaces on the left
 315 (or right, if the left-adjustment flag has been given).
 316 Instead of a decimal digit string one may write `*' or `*m$'
 317 (for some decimal integer m) to specify that the field width
 318 is given in the next argument, or in the m-th argument, respectively,
 319 which must be of type
 320 .IR int .
 321 A negative field width is taken as a `-' flag followed by a
 322 positive field width.
 323 In no case does a non-existent or small field width cause truncation of a
 324 field; if the result of a conversion is wider than the field width, the
 325 field is expanded to contain the conversion result.
 326 .SS "The precision"
 327 An optional precision, in the form of a period (`\&.')  followed by an
 328 optional decimal digit string.
 329 Instead of a decimal digit string one may write `*' or `*m$'
 330 (for some decimal integer m) to specify that the precision
 331 is given in the next argument, or in the m-th argument, respectively,
 332 which must be of type
 333 .IR int .
 334 If the precision is given as just `.', or the precision is negative,
 335 the precision is taken to be zero.
 336 This gives the minimum number of digits to appear for
 337 .BR d ,
 338 .BR i ,
 339 .BR o ,
 340 .BR u ,
 341 .BR x ,
 342 and
 343 .B X
 344 conversions, the number of digits to appear after the radix character for
 345 .BR a ,
 346 .BR A ,
 347 .BR e ,
 348 .BR E ,
 349 .BR f ,
 350 and
 351 .B F
 352 conversions, the maximum number of significant digits for
 353 .B g
 354 and
 355 .B G
 356 conversions, or the maximum number of characters to be printed from a
 357 string for
 358 .B s
 359 and
 360 .B S
 361 conversions.
 362 .SS "The length modifier"
 363 Here, `integer conversion' stands for
 364 .BR d ,
 365 .BR i ,
 366 .BR o ,
 367 .BR u ,
 368 .BR x ,
 369 or
 370 .BR X
 371 conversion.
 372 .TP
 373 .B hh
 374 A following integer conversion corresponds to a
 375 .I signed char
 376 or
 377 .I unsigned char
 378 argument, or a following
 379 .B n
 380 conversion corresponds to a pointer to a
 381 .I signed char
 382 argument.
 383 .TP
 384 .B h
 385 A following integer conversion corresponds to a
 386 .I short int
 387 or
 388 .I unsigned short int
 389 argument, or a following
 390 .B n
 391 conversion corresponds to a pointer to a
 392 .I short int
 393 argument.
 394 .TP
 395 .B l
 396 (ell) A following integer conversion corresponds to a
 397 .I long int
 398 or
 399 .I unsigned long int
 400 argument, or a following
 401 .B n
 402 conversion corresponds to a pointer to a
 403 .I long int
 404 argument, or a following
 405 .B c
 406 conversion corresponds to a
 407 .I wint_t
 408 argument, or a following
 409 .B s
 410 conversion corresponds to a pointer to
 411 .I wchar_t
 412 argument.
 413 .TP
 414 .B ll
 415 (ell-ell).
 416 A following integer conversion corresponds to a
 417 .I long long int
 418 or
 419 .I unsigned long long int
 420 argument, or a following
 421 .B n
 422 conversion corresponds to a pointer to a
 423 .I long long int
 424 argument.
 425 .TP
 426 .BR L
 427 A following
 428 .BR a ,
 429 .BR A ,
 430 .BR e ,
 431 .BR E ,
 432 .BR f ,
 433 .BR F ,
 434 .BR g ,
 435 or
 436 .B G
 437 conversion corresponds to a
 438 .I long double
 439 argument.
 440 (C99 allows %LF, but SUSv2 does not.)
 441 .TP
 442 .B q
 443 (`quad'. BSD 4.4 and Linux libc5 only. Don't use.)
 444 This is a synonym for
 445 .BR ll .
 446 .TP
 447 .B j
 448 A following integer conversion corresponds to an
 449 .I intmax_t
 450 or
 451 .I uintmax_t
 452 argument.
 453 .TP
 454 .B z
 455 A following integer conversion corresponds to a
 456 .I size_t
 457 or
 458 .I ssize_t
 459 argument. (Linux libc5 has
 460 .B Z
 461 with this meaning. Don't use it.)
 462 .TP
 463 .B t
 464 A following integer conversion corresponds to a
 465 .I ptrdiff_t
 466 argument.
 467 .PP
 468 The SUSv2 only knows about the length modifiers
 469 .B h
 470 (in
 471 .BR hd ,
 472 .BR hi ,
 473 .BR ho ,
 474 .BR hx ,
 475 .BR hX ,
 476 .BR hn )
 477 and
 478 .B l
 479 (in
 480 .BR ld ,
 481 .BR li ,
 482 .BR lo ,
 483 .BR lx ,
 484 .BR lX ,
 485 .BR ln ,
 486 .BR lc ,
 487 .BR ls )
 488 and
 489 .B L
 490 (in
 491 .BR Le ,
 492 .BR LE ,
 493 .BR Lf ,
 494 .BR Lg ,
 495 .BR LG ).
 496
 497 .SS "The conversion specifier"
 498 A character that specifies the type of conversion to be applied.
 499 The conversion specifiers and their meanings are:
 500 .TP
 501 .BR d , i
 502 The
 503 .I int
 504 argument is converted to signed decimal notation.
 505 The precision, if any, gives the minimum number of digits
 506 that must appear; if the converted value requires fewer digits, it is
 507 padded on the left with zeros. The default precision is 1.
 508 When 0 is printed with an explicit precision 0, the output is empty.
 509 .TP
 510 .BR o , u , x , X
 511 The
 512 .I "unsigned int"
 513 argument is converted to unsigned octal
 514 .BR "" ( o ),
 515 unsigned decimal
 516 .BR "" ( u ),
 517 or unsigned hexadecimal
 518 .BR "" ( x
 519 and
 520 .BR X )
 521 notation.  The letters
 522 .B abcdef
 523 are used for
 524 .B x
 525 conversions; the letters
 526 .B ABCDEF
 527 are used for
 528 .B X
 529 conversions.  The precision, if any, gives the minimum number of digits
 530 that must appear; if the converted value requires fewer digits, it is
 531 padded on the left with zeros. The default precision is 1.
 532 When 0 is printed with an explicit precision 0, the output is empty.
 533 .TP
 534 .BR e , E
 535 The
 536 .I double
 537 argument is rounded and converted in the style
 538 .if \w'\*(Pm'=0 .ds Pm \(+-
 539 .BR "" [\-]d \&. ddd e \\*(Pmdd
 540 where there is one digit before the decimal\-point character and the number
 541 of digits after it is equal to the precision; if the precision is missing,
 542 it is taken as 6; if the precision is zero, no decimal\-point character
 543 appears.  An
 544 .B E
 545 conversion uses the letter
 546 .B E
 547 (rather than
 548 .BR e )
 549 to introduce the exponent.  The exponent always contains at least two
 550 digits; if the value is zero, the exponent is 00.
 551 .TP
 552 .BR f , F
 553 The
 554 .I double
 555 argument is rounded and converted to decimal notation in the style
 556 .BR "" [\-]ddd \&. ddd,
 557 where the number of digits after the decimal\-point character is equal to
 558 the precision specification.  If the precision is missing, it is taken as
 559 6; if the precision is explicitly zero, no decimal\-point character appears.
 560 If a decimal point appears, at least one digit appears before it.
 561
 562 (The SUSv2 does not know about
 563 .B F
 564 and says that character string representations for infinity and NaN
 565 may be made available. The C99 standard specifies `[-]inf' or `[-]infinity'
 566 for infinity, and a string starting with `nan' for NaN, in the case of
 567 .B f
 568 conversion, and `[-]INF' or `[-]INFINITY' or `NAN*' in the case of
 569 .B F
 570 conversion.)
 571 .TP
 572 .BR g , G
 573 The
 574 .I double
 575 argument is converted in style
 576 .B f
 577 or
 578 .B e
 579 (or
 580 .B F
 581 or
 582 .B E
 583 for
 584 .B G
 585 conversions).  The precision specifies the number of significant digits.
 586 If the precision is missing, 6 digits are given; if the precision is zero,
 587 it is treated as 1.  Style
 588 .B e
 589 is used if the exponent from its conversion is less than \-4 or greater
 590 than or equal to the precision.  Trailing zeros are removed from the
 591 fractional part of the result; a decimal point appears only if it is
 592 followed by at least one digit.
 593 .TP
 594 .BR a , A
 595 (C99; not in SUSv2) For
 596 .B a
 597 conversion, the
 598 .I double
 599 argument is converted to hexadecimal notation (using the letters abcdef)
 600 in the style
 601 .BR "" [-] 0x h \&. hhhh p \\*(Pmd;
 602 for
 603 .B A
 604 conversion the prefix
 605 .BR 0X ,
 606 the letters ABCDEF, and the exponent separator
 607 .B P
 608 is used.
 609 There is one hexadecimal digit before the decimal point,
 610 and the number of digits after it is equal to the precision.
 611 The default precision suffices for an exact representation of the value
 612 if an exact representation in base 2 exists
 613 and otherwise is sufficiently large to distinguish values of type
 614 .IR double .
 615 The digit before the decimal point is unspecified for non-normalized
 616 numbers, and non-zero but otherwise unspecified for normalized numbers.
 617 .TP
 618 .B c
 619 If no
 620 .B l
 621 modifier is present, the
 622 .I int
 623 argument is converted to an
 624 .IR "unsigned char" ,
 625 and the resulting character is written.
 626 If an
 627 .B l
 628 modifier is present, the
 629 .I wint_t
 630 (wide character) argument is converted to a multibyte sequence by a call
 631 to the
 632 .B wcrtomb
 633 function, with a conversion state starting in the initial state, and the
 634 resulting multibyte string is written.
 635 .TP
 636 .B s
 637 If no
 638 .B l
 639 modifier is present: The
 640 .I "const char *"
 641 argument is expected to be a pointer to an array of character type (pointer
 642 to a string).  Characters from the array are written up to (but not
 643 including) a terminating
 644 .B NUL
 645 character; if a precision is specified, no more than the number specified
 646 are written.  If a precision is given, no null character need be present;
 647 if the precision is not specified, or is greater than the size of the
 648 array, the array must contain a terminating
 649 .B NUL
 650 character.
 651
 652 If an
 653 .B l
 654 modifier is present: The
 655 .I "const wchar_t *"
 656 argument is expected to be a pointer to an array of wide characters.
 657 Wide characters from the array are converted to multibyte characters
 658 (each by a call to the
 659 .B wcrtomb
 660 function, with a conversion state starting in the initial state before
 661 the first wide character), up to and including a terminating null
 662 wide character. The resulting multibyte characters are written up to
 663 (but not including) the terminating null byte. If a precision is
 664 specified, no more bytes than the number specified are written, but
 665 no partial multibyte characters are written. Note that the precision
 666 determines the number of
 667 .I bytes
 668 written, not the number of
 669 .I wide characters
 670 or
 671 .IR "screen positions" .
 672 The array must contain a terminating null wide character, unless a
 673 precision is given and it is so small that the number of bytes written
 674 exceeds it before the end of the array is reached.
 675 .TP
 676 .B C
 677 (Not in C99, but in SUSv2.)
 678 Synonym for
 679 .BR lc .
 680 Don't use.
 681 .TP
 682 .B S
 683 (Not in C99, but in SUSv2.)
 684 Synonym for
 685 .BR ls .
 686 Don't use.
 687 .TP
 688 .B p
 689 The
 690 .I "void *"
 691 pointer argument is printed in hexadecimal (as if by
 692 .B %#x
 693 or
 694 .BR  %#lx ).
 695 .TP
 696 .B n
 697 The number of characters written so far is stored into the integer
 698 indicated by the
 699 .I "int *"
 700 (or variant) pointer argument.  No argument is converted.
 701 .TP
 702 .B %
 703 A `%' is written. No argument is converted. The complete conversion
 704 specification is `%%'.
 705 .PP
 706 .SH EXAMPLES
 707 .br
 708 .if \w'\*(Pi'=0 .ds Pi pi
 709 To print \*(Pi to five decimal places:
 710 .RS
 711 .nf
 712 #include <math.h>
 713 #include <stdio.h>
 714 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
 715 .fi
 716 .RE
 717 .PP
 718 To print a date and time in the form `Sunday, July 3, 10:02',
 719 where
 720 .I weekday
 721 and
 722 .I month
 723 are pointers to strings:
 724 .RS
 725 .nf
 726 #include <stdio.h>
 727 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
 728         weekday, month, day, hour, min);
 729 .fi
 730 .RE
 731 .PP
 732 Many countries use the day-month-year order.
 733 Hence, an internationalized version must be able to print
 734 the arguments in an order specified by the format:
 735 .RS
 736 .nf
 737 #include <stdio.h>
 738 fprintf(stdout, format,
 739         weekday, month, day, hour, min);
 740 .fi
 741 .RE
 742 where
 743 .I format
 744 depends on locale, and may permute the arguments. With the value
 745 .RS
 746 .nf
 747 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
 748 .fi
 749 .RE
 750 one might obtain `Sonntag, 3. Juli, 10:02'.
 751 .PP
 752 To allocate a sufficiently large string and print into it
 753 (code correct for both glibc 2.0 and glibc 2.1):
 754 .RS
 755 .nf
 756 #include <stdio.h>
 757 #include <stdlib.h>
 758 #include <stdarg.h>
 759
 760 char *
 761 make_message(const char *fmt, ...) {
 762    /* Guess we need no more than 100 bytes. */
 763    int n, size = 100;
 764    char *p, *np;
 765    va_list ap;
 766
 767    if ((p = malloc (size)) == NULL)
 768       return NULL;
 769
 770    while (1) {
 771       /* Try to print in the allocated space. */
 772       va_start(ap, fmt);
 773       n = vsnprintf (p, size, fmt, ap);
 774       va_end(ap);
 775       /* If that worked, return the string. */
 776       if (n > -1 && n < size)
 777          return p;
 778       /* Else try again with more space. */
 779       if (n > -1)    /* glibc 2.1 */
 780          size = n+1; /* precisely what is needed */
 781       else           /* glibc 2.0 */
 782          size *= 2;  /* twice the old size */
 783       if ((np = realloc (p, size)) == NULL) {
 784          free(p);
 785          return NULL;
 786       } else {
 787          p = np;
 788       }
 789    }
 790 }
 791 .fi
 792 .RE
 793
 794 .SH NOTES
 795 The glibc implementation of the functions
 796 .B snprintf
 797 and
 798 .B vsnprintf
 799 conforms to the C99 standard, i.e., behaves as described above,
 800 since glibc version 2.1. Until glibc 2.0.6 they would return \-1
 801 when the output was truncated.
 802 .SH "CONFORMING TO"
 803 The
 804 .BR fprintf ,
 805 .BR printf ,
 806 .BR sprintf ,
 807 .BR vprintf ,
 808 .BR vfprintf ,
 809 and
 810 .B vsprintf
 811 functions conform to ANSI X3.159-1989 (``ANSI C'') and ISO/IEC 9899:1999
 812 (``ISO C99'').
 813 The
 814 .B snprintf
 815 and
 816 .B vsnprintf
 817 functions conform to ISO/IEC 9899:1999.
 818 .PP
 819 Concerning the return value of
 820 .BR snprintf ,
 821 the SUSv2 and the C99 standard contradict each other: when
 822 .B snprintf
 823 is called with
 824 .IR size =0
 825 then SUSv2 stipulates an unspecified return value less than 1,
 826 while C99 allows
 827 .I str
 828 to be NULL in this case, and gives the return value (as always)
 829 as the number of characters that would have been written in case
 830 the output string has been large enough.
 831 .PP
 832 Linux libc4 knows about the five C standard flags.
 833 It knows about the length modifiers h,l,L, and the conversions
 834 cdeEfFgGinopsuxX, where F is a synonym for f.
 835 Additionally, it accepts D,O,U as synonyms for ld,lo,lu.
 836 (This is bad, and caused serious bugs later, when
 837 support for %D disappeared.) No locale-dependent radix character,
 838 no thousands' separator, no NaN or infinity, no %m$ and *m$.
 839 .PP
 840 Linux libc5 knows about the five C standard flags and the ' flag,
 841 locale, %m$ and *m$.
 842 It knows about the length modifiers h,l,L,Z,q, but accepts L and q
 843 both for long doubles and for long long integers (this is a bug).
 844 It no longer recognizes FDOU, but adds a new conversion character
 845 .BR m ,
 846 which outputs
 847 .IR strerror(errno) .
 848 .PP
 849 glibc 2.0 adds conversion characters C and S.
 850 .PP
 851 glibc 2.1 adds length modifiers hh,j,t,z and conversion characters a,A.
 852 .PP
 853 glibc 2.2 adds the conversion character F with C99 semantics, and the
 854 flag character I.
 855 .SH HISTORY
 856 Unix V7 defines the three routines
 857 .BR printf ,
 858 .BR fprintf ,
 859 .BR sprintf ,
 860 and has the flag -, the width or precision *, the length modifier l,
 861 and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
 862 This is still true for BSD 2.9.1, but BSD 2.10 has the flags
 863 #, + and <space> and no longer mentions D,O,U,X.
 864 BSD 2.11 has
 865 .BR vprintf ,
 866 .BR vfprintf ,
 867 .BR vsprintf ,
 868 and warns not to use D,O,U,X.
 869 BSD 4.3 Reno has the flag 0, the length modifiers h and L,
 870 and the conversions n, p, E, G, X (with current meaning)
 871 and deprecates D,O,U.
 872 BSD 4.4 introduces the functions
 873 .B snprintf
 874 and
 875 .BR vsnprintf ,
 876 and the length modifier q.
 877 FreeBSD also has functions
 878 .I asprintf
 879 and
 880 .IR vasprintf ,
 881 that allocate a buffer large enough for
 882 .BR sprintf .
 883 In glibc there are functions
 884 .I dprintf
 885 and
 886 .I vdprintf
 887 that print to a file descriptor instead of a stream.
 888 .SH BUGS
 889 Because
 890 .B sprintf
 891 and
 892 .B vsprintf
 893 assume an arbitrarily long string, callers must be careful not to overflow
 894 the actual space; this is often impossible to assure. Note that the length
 895 of the strings produced is locale-dependent and difficult to predict.
 896 Use
 897 .B snprintf
 898 and
 899 .B vsnprintf
 900 instead (or
 901 .B asprintf
 902 and
 903 .BR vasprintf ).
 904 .PP
 905 Linux libc4.[45] does not have a
 906 .BR snprintf ,
 907 but provides a libbsd that contains an
 908 .B snprintf
 909 equivalent to
 910 .BR sprintf ,
 911 i.e., one that ignores the
 912 .I size
 913 argument.
 914 Thus, the use of
 915 .B snprintf
 916 with early libc4 leads to serious security problems.
 917 .PP
 918 Code such as
 919 .BI printf( foo );
 920 often indicates a bug, since
 921 .I foo
 922 may contain a % character.  If
 923 .I foo
 924 comes from untrusted user input, it may contain %n, causing the
 925 .B printf
 926 call to write to memory and creating a security hole.
 927 .\" .PP
 928 .\" Some floating point conversions under early libc4
 929 .\" caused memory leaks.
 930
 931 .SH "SEE ALSO"
 932 .BR printf (1),
 933 .BR asprintf (3),
 934 .BR dprintf (3),
 935 .BR scanf (3),
 936 .BR wcrtomb (3),
 937 .BR wprintf (3),
 938 .BR locale (5)