1.\" $NetBSD: printf.3,v 1.25 2002/02/07 07:00:26 ross Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Chris Torek and the American National Standards Committee X3, 8.\" on Information Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.\" @(#)printf.3 8.1 (Berkeley) 6/4/93 39.\" 40.Dd December 2, 2001 41.Dt PRINTF 3 42.Os 43.Sh NAME 44.Nm printf , 45.Nm fprintf , 46.Nm sprintf , 47.Nm snprintf , 48.Nm asprintf , 49.Nm vprintf , 50.Nm vfprintf , 51.Nm vsprintf , 52.Nm vsnprintf , 53.Nm vasprintf 54.Nd formatted output conversion 55.Sh LIBRARY 56.Lb libc 57.Sh SYNOPSIS 58.Fd #include \*[Lt]stdio.h\*[Gt] 59.Ft int 60.Fn printf "const char * restrict format" ... 61.Ft int 62.Fn fprintf "FILE * restrict stream" "const char * restrict format" ... 63.Ft int 64.Fn sprintf "char * restrict str" "const char * restrict format" ... 65.Ft int 66.Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ... 67.Ft int 68.Fn asprintf "char ** restrict ret" "const char * restrict format" ... 69.Fd #include \*[Lt]stdarg.h\*[Gt] 70.Ft int 71.Fn vprintf "const char * restrict format" "va_list ap" 72.Ft int 73.Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap" 74.Ft int 75.Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap" 76.Ft int 77.Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap" 78.Ft int 79.Fn vasprintf "char ** restrict ret" "const char * restrict format" "va_list ap" 80.Sh DESCRIPTION 81The 82.Fn printf 83family of functions produces output according to a 84.Fa format 85as described below. 86.Fn printf 87and 88.Fn vprintf 89write output to 90.Em stdout , 91the standard output stream; 92.Fn fprintf 93and 94.Fn vfprintf 95write output to the given output 96.Fa stream ; 97.Fn sprintf , 98.Fn snprintf , 99.Fn vsprintf , 100and 101.Fn vsnprintf 102write to the character string 103.Fa str ; 104.Fn asprintf 105and 106.Fn vasprintf 107write to a dynamically allocated string that is stored in 108.Fa ret . 109.Pp 110These functions write the output under the control of a 111.Fa format 112string that specifies how subsequent arguments 113(or arguments accessed via the variable-length argument facilities of 114.Xr stdarg 3 ) 115are converted for output. 116.Pp 117These functions return 118the number of characters printed 119(not including the trailing 120.Ql \e0 121used to end output to strings). 122.Pp 123.Fn asprintf 124and 125.Fn vasprintf 126return a pointer to a buffer sufficiently large to hold the 127string in the 128.Fa ret 129argument. 130This pointer should be passed to 131.Xr free 3 132to release the allocated storage when it is no longer needed. 133If sufficient space cannot be allocated, these functions 134will return -1 and set 135.Fa ret 136to be a NULL pointer. 137.Pp 138.Fn snprintf 139and 140.Fn vsnprintf 141will write at most 142.Fa size Ns \-1 143of the characters printed into the output string 144(the 145.Fa size Ns 'th 146character then gets the terminating 147.Ql \e0 ) ; 148if the return value is greater than or equal to the 149.Fa size 150argument, the string was too short 151and some of the printed characters were discarded. 152If 153.Fa size 154is zero, nothing is written and 155.Fa str 156may be a NULL pointer. 157.Pp 158.Fn sprintf 159and 160.Fn vsprintf 161effectively assume an infinite 162.Fa size . 163.Pp 164The format string is composed of zero or more directives: 165ordinary 166.\" multibyte 167characters (not 168.Cm % ) , 169which are copied unchanged to the output stream; 170and conversion specifications, each of which results 171in fetching zero or more subsequent arguments. 172Each conversion specification is introduced by 173the character 174.Cm % . 175The arguments must correspond properly (after type promotion) 176with the conversion specifier. 177After the 178.Cm % , 179the following appear in sequence: 180.Bl -bullet 181.It 182Zero or more of the following flags: 183.Bl -hyphen 184.It 185A 186.Cm # 187character 188specifying that the value should be converted to an ``alternative form''. 189For 190.Cm c , 191.Cm d , 192.Cm i , 193.Cm n , 194.Cm p , 195.Cm s , 196and 197.Cm u , 198conversions, this option has no effect. 199For 200.Cm o 201conversions, the precision of the number is increased to force the first 202character of the output string to a zero (except if a zero value is printed 203with an explicit precision of zero). 204For 205.Cm x 206and 207.Cm X 208conversions, a non-zero result has the string 209.Ql 0x 210(or 211.Ql 0X 212for 213.Cm X 214conversions) prepended to it. 215For 216.Cm e , 217.Cm E , 218.Cm f , 219.Cm F , 220.Cm g , 221and 222.Cm G , 223conversions, the result will always contain a decimal point, even if no 224digits follow it (normally, a decimal point appears in the results of 225those conversions only if a digit follows). 226For 227.Cm g 228and 229.Cm G 230conversions, trailing zeros are not removed from the result as they 231would otherwise be. 232.It 233A zero 234.Sq Cm \&0 235character specifying zero padding. 236For all conversions except 237.Cm n , 238the converted value is padded on the left with zeros rather than blanks. 239If a precision is given with a numeric conversion 240.Pf ( Cm d , 241.Cm i , 242.Cm o , 243.Cm u , 244.Cm i , 245.Cm x , 246and 247.Cm X ) , 248the 249.Sq Cm \&0 250flag is ignored. 251.It 252A negative field width flag 253.Sq Cm \- 254indicates the converted value is to be left adjusted on the field boundary. 255Except for 256.Cm n 257conversions, the converted value is padded on the right with blanks, 258rather than on the left with blanks or zeros. 259A 260.Sq Cm \- 261overrides a 262.Sq Cm \&0 263if both are given. 264.It 265A space, specifying that a blank should be left before a positive number 266produced by a signed conversion 267.Pf ( Cm d , 268.Cm e , 269.Cm E , 270.Cm f , 271.Cm F , 272.Cm g , 273.Cm G , 274or 275.Cm i ) . 276.It 277A 278.Sq Cm + 279character specifying that a sign always be placed before a 280number produced by a signed conversion. 281A 282.Sq Cm + 283overrides a space if both are used. 284.El 285.It 286An optional decimal digit string specifying a minimum field width. 287If the converted value has fewer characters than the field width, it will 288be padded with spaces on the left (or right, if the left-adjustment 289flag has been given) to fill out 290the field width. 291.It 292An optional precision, in the form of a period 293.Sq Cm \&. 294followed by an 295optional digit string. If the digit string is omitted, the precision 296is taken as zero. This gives the minimum number of digits to appear for 297.Cm d , 298.Cm i , 299.Cm o , 300.Cm u , 301.Cm x , 302and 303.Cm X 304conversions, the number of digits to appear after the decimal-point for 305.Cm e , 306.Cm E , 307.Cm f , 308and 309.Cm F 310conversions, the maximum number of significant digits for 311.Cm g 312and 313.Cm G 314conversions, or the maximum number of characters to be printed from a 315string for 316.Cm s 317conversions. 318.It 319The optional character 320.Cm h , 321specifying that a following 322.Cm d , 323.Cm i , 324.Cm o , 325.Cm u , 326.Cm x , 327or 328.Cm X 329conversion corresponds to a 330.Em short int 331or 332.Em unsigned short int 333argument, or that a following 334.Cm n 335conversion corresponds to a pointer to a 336.Em short int 337argument. 338.It 339The optional character 340.Cm j , 341specifying that a following 342.Cm d , 343.Cm i , 344.Cm o , 345.Cm u , 346.Cm x , 347or 348.Cm X 349conversion corresponds to an 350.Em intmax_t 351or 352.Em uintmax_t 353argument, or that a following 354.Cm n 355conversion corresponds to a pointer to a 356.Em intmax_t 357argument. 358.It 359The optional character 360.Cm l 361(ell) specifying that a following 362.Cm d , 363.Cm i , 364.Cm o , 365.Cm u , 366.Cm x , 367or 368.Cm X 369conversion corresponds to a 370.Em long int 371or 372.Em unsigned long int 373argument, or that a following 374.Cm n 375conversion corresponds to a pointer to a 376.Em long int 377argument. 378.It 379The optional character 380.Cm q , 381or alternatively two consecutive 382.Cm l 383(ell) characters, 384specifying that a following 385.Cm d , 386.Cm i , 387.Cm o , 388.Cm u , 389.Cm x , 390or 391.Cm X 392conversion corresponds to a 393.Em quad_t 394or 395.Em u_quad_t 396argument, or that a following 397.Cm n 398conversion corresponds to a pointer to a 399.Em quad_t 400argument. 401.It 402The optional character 403.Cm t , 404specifying that a following 405.Cm d , 406.Cm i , 407.Cm o , 408.Cm u , 409.Cm x , 410or 411.Cm X 412conversion corresponds to a 413.Em ptrdiff_t 414or 415the corresponding unsigned integer type 416argument, or that a following 417.Cm n 418conversion corresponds to a pointer to a 419.Em ptrdiff_t 420argument. 421.It 422The optional character 423.Cm z , 424specifying that a following 425.Cm d , 426.Cm i , 427.Cm o , 428.Cm u , 429.Cm x , 430or 431.Cm X 432conversion corresponds to a 433.Em size_t 434or 435the corresponding signed integer type 436argument, or that a following 437.Cm n 438conversion corresponds to a pointer to a 439signed integer type corresponding to 440.Em size_t 441argument. 442.It 443The character 444.Cm L 445specifying that a following 446.Cm e , 447.Cm E , 448.Cm f , 449.Cm F , 450.Cm g , 451or 452.Cm G 453conversion corresponds to a 454.Em long double 455argument. 456.It 457A character that specifies the type of conversion to be applied. 458.El 459.Pp 460A field width or precision, or both, may be indicated by 461an asterisk 462.Ql * 463instead of a 464digit string. 465In this case, an 466.Em int 467argument supplies the field width or precision. 468A negative field width is treated as a left adjustment flag followed by a 469positive field width; a negative precision is treated as though it were 470missing. 471.Pp 472The conversion specifiers and their meanings are: 473.Bl -tag -width "diouxX" 474.It Cm diouxX 475The 476.Em int 477(or appropriate variant) argument is converted to signed decimal 478.Pf ( Cm d 479and 480.Cm i ) , 481unsigned octal 482.Pq Cm o , 483unsigned decimal 484.Pq Cm u , 485or unsigned hexadecimal 486.Pf ( Cm x 487and 488.Cm X ) 489notation. The letters 490.Cm abcdef 491are used for 492.Cm x 493conversions; the letters 494.Cm ABCDEF 495are used for 496.Cm X 497conversions. 498The precision, if any, gives the minimum number of digits that must 499appear; if the converted value requires fewer digits, it is padded on 500the left with zeros. 501.It Cm DOU 502The 503.Em long int 504argument is converted to signed decimal, unsigned octal, or unsigned 505decimal, as if the format had been 506.Cm ld , 507.Cm lo , 508or 509.Cm lu 510respectively. 511These conversion characters are deprecated, and will eventually disappear. 512.It Cm fF 513The 514.Em double 515argument is rounded and converted to decimal notation in the style 516.Sm off 517.Pf [-]ddd Cm \&. No ddd , 518.Sm on 519where the number of digits after the decimal-point character 520is equal to the precision specification. 521If the precision is missing, it is taken as 6; if the precision is 522explicitly zero, no decimal-point character appears. 523If a decimal point appears, at least one digit appears before it. 524.Pp 525If the double argument repesents an infinity it is converted 526in the style 527.Pf [-] Cm inf . 528If the double argument represents a NaN it is converted 529in the style 530.Pf [-] Cm nan . 531An 532.Cm F 533conversion produces 534.Pf [-] Cm INF 535and 536.Pf [-] Cm NAN , 537respectively. 538.It Cm eE 539The 540.Em double 541argument is rounded and converted in the style 542.Sm off 543.Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd 544.Sm on 545where there is one digit before the 546decimal-point character 547and the number of digits after it is equal to the precision; 548if the precision is missing, 549it is taken as 6; if the precision is 550zero, no decimal-point character appears. 551An 552.Cm E 553conversion uses the letter 554.Cm E 555(rather than 556.Cm e ) 557to introduce the exponent. 558The exponent always contains at least two digits; if the value is zero, 559the exponent is 00. 560.Pp 561Double arguments representing infinities or NaNs are converted in the 562same styles as in the 563.Cm f 564and 565.Cm F 566conversions. 567.It Cm gG 568The 569.Em double 570argument is converted in style 571.Cm f 572or 573.Cm e 574(or in style 575.Cm F 576or 577.Cm E 578for 579.Cm G 580conversions). 581The precision specifies the number of significant digits. 582If the precision is missing, 6 digits are given; if the precision is zero, 583it is treated as 1. 584Style 585.Cm e 586is used if the exponent from its conversion is less than -4 or greater than 587or equal to the precision. 588Trailing zeros are removed from the fractional part of the result; a 589decimal point appears only if it is followed by at least one digit. 590.Pp 591Double arguments representing infinities or NaNs are converted in the 592same styles as in the 593.Cm f 594and 595.Cm F 596conversions. 597.It Cm c 598The 599.Em int 600argument is converted to an 601.Em unsigned char , 602and the resulting character is written. 603.It Cm s 604The 605.Dq Em char * 606argument is expected to be a pointer to an array of character type (pointer 607to a string). 608Characters from the array are written up to (but not including) 609a terminating 610.Dv NUL 611character; 612if a precision is specified, no more than the number specified are 613written. 614If a precision is given, no null character 615need be present; if the precision is not specified, or is greater than 616the size of the array, the array must contain a terminating 617.Dv NUL 618character. 619.It Cm p 620The 621.Dq Em void * 622pointer argument is printed in hexadecimal (as if by 623.Ql %#x 624or 625.Ql %#lx ) . 626.It Cm n 627The number of characters written so far is stored into the 628integer indicated by the 629.Dq Em int * 630(or variant) pointer argument. 631No argument is converted. 632.It Cm % 633A 634.Ql % 635is written. No argument is converted. The complete conversion specification 636is 637.Ql %% . 638.El 639.Pp 640In no case does a non-existent or small field width cause truncation of 641a field; if the result of a conversion is wider than the field width, the 642field is expanded to contain the conversion result. 643.Sh EXAMPLES 644.br 645To print a date and time in the form `Sunday, July 3, 10:02', 646where 647.Em weekday 648and 649.Em month 650are pointers to strings: 651.Bd -literal -offset indent 652#include \*[Lt]stdio.h\*[Gt] 653fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", 654 weekday, month, day, hour, min); 655.Ed 656.Pp 657To print \*(Pi 658to five decimal places: 659.Bd -literal -offset indent 660#include \*[Lt]math.h\*[Gt] 661#include \*[Lt]stdio.h\*[Gt] 662fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); 663.Ed 664.Pp 665To allocate a 128 byte string and print into it: 666.Bd -literal -offset indent 667#include \*[Lt]stdio.h\*[Gt] 668#include \*[Lt]stdlib.h\*[Gt] 669#include \*[Lt]stdarg.h\*[Gt] 670char *newfmt(const char *fmt, ...) 671{ 672 char *p; 673 va_list ap; 674 if ((p = malloc(128)) == NULL) 675 return (NULL); 676 va_start(ap, fmt); 677 (void) vsnprintf(p, 128, fmt, ap); 678 va_end(ap); 679 return (p); 680} 681.Ed 682.Sh SEE ALSO 683.Xr printf 1 , 684.Xr scanf 3 , 685.Xr printf 9 686.Sh STANDARDS 687The 688.Fn fprintf , 689.Fn printf , 690.Fn sprintf , 691.Fn vprintf , 692.Fn vfprintf , 693and 694.Fn vsprintf 695functions 696conform to 697.St -isoC90 . 698The conversion format modifiers 699.Cm %j , 700.Cm %t 701and 702.Cm %z 703conform to 704.St -isoC99 . 705The 706.Fn snprintf 707and 708.Fn vsnprintf 709functions 710conform to 711.St -isoC99 . 712.Sh HISTORY 713The functions 714.Fn snprintf 715and 716.Fn vsnprintf 717first appeared in 718.Bx 4.4 . 719The functions 720.Fn asprintf 721and 722.Fn vasprintf 723are modeled on the ones that first appeared in the GNU C library. 724.Sh BUGS 725The conversion formats 726.Cm \&%D , 727.Cm \&%O , 728and 729.Cm %U 730are not standard and are provided only for backward compatibility. 731The effect of padding the 732.Cm %p 733format with zeros (either by the 734.Sq Cm 0 735flag or by specifying a precision), and the benign effect (i.e. none) 736of the 737.Sq Cm # 738flag on 739.Cm %n 740and 741.Cm %p 742conversions, as well as other nonsensical combinations such as 743.Cm %Ld , 744are not standard; such combinations should be avoided. 745.Sh SECURITY CONSIDERATIONS 746Because 747.Fn sprintf 748and 749.Fn vsprintf 750assume an infinitely long string, callers must be careful not to 751overflow the actual space; this is often impossible to assure. 752For safety, programmers should use the 753.Fn snprintf 754and 755.Fn asprintf 756family of interfaces instead. 757Unfortunately, the 758.Fn snprintf 759interfaces are not available on older 760systems and the 761.Fn asprintf 762interfaces are not yet portable. 763