1.\" $NetBSD: printf.3,v 1.20 2001/09/16 02:17:16 wiz 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 April 30, 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 <stdio.h> 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 <stdarg.h> 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 g , 220and 221.Cm G , 222conversions, the result will always contain a decimal point, even if no 223digits follow it (normally, a decimal point appears in the results of 224those conversions only if a digit follows). 225For 226.Cm g 227and 228.Cm G 229conversions, trailing zeros are not removed from the result as they 230would otherwise be. 231.It 232A zero 233.Sq Cm \&0 234character specifying zero padding. 235For all conversions except 236.Cm n , 237the converted value is padded on the left with zeros rather than blanks. 238If a precision is given with a numeric conversion 239.Pf ( Cm d , 240.Cm i , 241.Cm o , 242.Cm u , 243.Cm i , 244.Cm x , 245and 246.Cm X ) , 247the 248.Sq Cm \&0 249flag is ignored. 250.It 251A negative field width flag 252.Sq Cm \- 253indicates the converted value is to be left adjusted on the field boundary. 254Except for 255.Cm n 256conversions, the converted value is padded on the right with blanks, 257rather than on the left with blanks or zeros. 258A 259.Sq Cm \- 260overrides a 261.Sq Cm \&0 262if both are given. 263.It 264A space, specifying that a blank should be left before a positive number 265produced by a signed conversion 266.Pf ( Cm d , 267.Cm e , 268.Cm E , 269.Cm f , 270.Cm g , 271.Cm G , 272or 273.Cm i ) . 274.It 275A 276.Sq Cm + 277character specifying that a sign always be placed before a 278number produced by a signed conversion. 279A 280.Sq Cm + 281overrides a space if both are used. 282.El 283.It 284An optional decimal digit string specifying a minimum field width. 285If the converted value has fewer characters than the field width, it will 286be padded with spaces on the left (or right, if the left-adjustment 287flag has been given) to fill out 288the field width. 289.It 290An optional precision, in the form of a period 291.Sq Cm \&. 292followed by an 293optional digit string. If the digit string is omitted, the precision 294is taken as zero. This gives the minimum number of digits to appear for 295.Cm d , 296.Cm i , 297.Cm o , 298.Cm u , 299.Cm x , 300and 301.Cm X 302conversions, the number of digits to appear after the decimal-point for 303.Cm e , 304.Cm E , 305and 306.Cm f 307conversions, the maximum number of significant digits for 308.Cm g 309and 310.Cm G 311conversions, or the maximum number of characters to be printed from a 312string for 313.Cm s 314conversions. 315.It 316The optional character 317.Cm h , 318specifying that a following 319.Cm d , 320.Cm i , 321.Cm o , 322.Cm u , 323.Cm x , 324or 325.Cm X 326conversion corresponds to a 327.Em short int 328or 329.Em unsigned short int 330argument, or that a following 331.Cm n 332conversion corresponds to a pointer to a 333.Em short int 334argument. 335.It 336The optional character 337.Cm j , 338specifying that a following 339.Cm d , 340.Cm i , 341.Cm o , 342.Cm u , 343.Cm x , 344or 345.Cm X 346conversion corresponds to an 347.Em intmax_t 348or 349.Em uintmax_t 350argument, or that a following 351.Cm n 352conversion corresponds to a pointer to a 353.Em intmax_t 354argument. 355.It 356The optional character 357.Cm l 358(ell) specifying that a following 359.Cm d , 360.Cm i , 361.Cm o , 362.Cm u , 363.Cm x , 364or 365.Cm X 366conversion corresponds to a 367.Em long int 368or 369.Em unsigned long int 370argument, or that a following 371.Cm n 372conversion corresponds to a pointer to a 373.Em long int 374argument. 375.It 376The optional character 377.Cm q , 378or alternatively two consecutive 379.Cm l 380(ell) characters, 381specifying that a following 382.Cm d , 383.Cm i , 384.Cm o , 385.Cm u , 386.Cm x , 387or 388.Cm X 389conversion corresponds to a 390.Em quad_t 391or 392.Em u_quad_t 393argument, or that a following 394.Cm n 395conversion corresponds to a pointer to a 396.Em quad_t 397argument. 398.It 399The optional character 400.Cm t , 401specifying that a following 402.Cm d , 403.Cm i , 404.Cm o , 405.Cm u , 406.Cm x , 407or 408.Cm X 409conversion corresponds to a 410.Em ptrdiff_t 411or 412the corresponding unsigned integer type 413argument, or that a following 414.Cm n 415conversion corresponds to a pointer to a 416.Em ptrdiff_t 417argument. 418.It 419The optional character 420.Cm z , 421specifying that a following 422.Cm d , 423.Cm i , 424.Cm o , 425.Cm u , 426.Cm x , 427or 428.Cm X 429conversion corresponds to a 430.Em size_t 431or 432the corresponding signed integer type 433argument, or that a following 434.Cm n 435conversion corresponds to a pointer to a 436signed integer type correspoinding to 437.Em ptrdiff_t 438argument. 439.It 440The character 441.Cm L 442specifying that a following 443.Cm e , 444.Cm E , 445.Cm f , 446.Cm g , 447or 448.Cm G 449conversion corresponds to a 450.Em long double 451argument (but note that long double values are not currently supported 452by the 453.Tn VAX 454and 455.Tn Tahoe 456compilers). 457.It 458A character that specifies the type of conversion to be applied. 459.El 460.Pp 461A field width or precision, or both, may be indicated by 462an asterisk 463.Ql * 464instead of a 465digit string. 466In this case, an 467.Em int 468argument supplies the field width or precision. 469A negative field width is treated as a left adjustment flag followed by a 470positive field width; a negative precision is treated as though it were 471missing. 472.Pp 473The conversion specifiers and their meanings are: 474.Bl -tag -width "diouxX" 475.It Cm diouxX 476The 477.Em int 478(or appropriate variant) argument is converted to signed decimal 479.Pf ( Cm d 480and 481.Cm i ) , 482unsigned octal 483.Pq Cm o , 484unsigned decimal 485.Pq Cm u , 486or unsigned hexadecimal 487.Pf ( Cm x 488and 489.Cm X ) 490notation. The letters 491.Cm abcdef 492are used for 493.Cm x 494conversions; the letters 495.Cm ABCDEF 496are used for 497.Cm X 498conversions. 499The precision, if any, gives the minimum number of digits that must 500appear; if the converted value requires fewer digits, it is padded on 501the left with zeros. 502.It Cm DOU 503The 504.Em long int 505argument is converted to signed decimal, unsigned octal, or unsigned 506decimal, as if the format had been 507.Cm ld , 508.Cm lo , 509or 510.Cm lu 511respectively. 512These conversion characters are deprecated, and will eventually disappear. 513.It Cm eE 514The 515.Em double 516argument is rounded and converted in the style 517.Sm off 518.Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd 519.Sm on 520where there is one digit before the 521decimal-point character 522and the number of digits after it is equal to the precision; 523if the precision is missing, 524it is taken as 6; if the precision is 525zero, no decimal-point character appears. 526An 527.Cm E 528conversion uses the letter 529.Cm E 530(rather than 531.Cm e ) 532to introduce the exponent. 533The exponent always contains at least two digits; if the value is zero, 534the exponent is 00. 535.It Cm f 536The 537.Em double 538argument is rounded and converted to decimal notation in the style 539.Sm off 540.Pf [-]ddd Cm \&. No ddd , 541.Sm on 542where the number of digits after the decimal-point character 543is equal to the precision specification. 544If the precision is missing, it is taken as 6; if the precision is 545explicitly zero, no decimal-point character appears. 546If a decimal point appears, at least one digit appears before it. 547.It Cm g 548The 549.Em double 550argument is converted in style 551.Cm f 552or 553.Cm e 554(or 555.Cm E 556for 557.Cm G 558conversions). 559The precision specifies the number of significant digits. 560If the precision is missing, 6 digits are given; if the precision is zero, 561it is treated as 1. 562Style 563.Cm e 564is used if the exponent from its conversion is less than -4 or greater than 565or equal to the precision. 566Trailing zeros are removed from the fractional part of the result; a 567decimal point appears only if it is followed by at least one digit. 568.It Cm c 569The 570.Em int 571argument is converted to an 572.Em unsigned char , 573and the resulting character is written. 574.It Cm s 575The 576.Dq Em char * 577argument is expected to be a pointer to an array of character type (pointer 578to a string). 579Characters from the array are written up to (but not including) 580a terminating 581.Dv NUL 582character; 583if a precision is specified, no more than the number specified are 584written. 585If a precision is given, no null character 586need be present; if the precision is not specified, or is greater than 587the size of the array, the array must contain a terminating 588.Dv NUL 589character. 590.It Cm p 591The 592.Dq Em void * 593pointer argument is printed in hexadecimal (as if by 594.Ql %#x 595or 596.Ql %#lx ) . 597.It Cm n 598The number of characters written so far is stored into the 599integer indicated by the 600.Dq Em int * 601(or variant) pointer argument. 602No argument is converted. 603.It Cm % 604A 605.Ql % 606is written. No argument is converted. The complete conversion specification 607is 608.Ql %% . 609.El 610.Pp 611In no case does a non-existent or small field width cause truncation of 612a field; if the result of a conversion is wider than the field width, the 613field is expanded to contain the conversion result. 614.Sh EXAMPLES 615.br 616To print a date and time in the form `Sunday, July 3, 10:02', 617where 618.Em weekday 619and 620.Em month 621are pointers to strings: 622.Bd -literal -offset indent 623#include <stdio.h> 624fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", 625 weekday, month, day, hour, min); 626.Ed 627.Pp 628To print \*(Pi 629to five decimal places: 630.Bd -literal -offset indent 631#include <math.h> 632#include <stdio.h> 633fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); 634.Ed 635.Pp 636To allocate a 128 byte string and print into it: 637.Bd -literal -offset indent 638#include <stdio.h> 639#include <stdlib.h> 640#include <stdarg.h> 641char *newfmt(const char *fmt, ...) 642{ 643 char *p; 644 va_list ap; 645 if ((p = malloc(128)) == NULL) 646 return (NULL); 647 va_start(ap, fmt); 648 (void) vsnprintf(p, 128, fmt, ap); 649 va_end(ap); 650 return (p); 651} 652.Ed 653.Sh SEE ALSO 654.Xr printf 1 , 655.Xr scanf 3 , 656.Xr printf 9 657.Sh STANDARDS 658The 659.Fn fprintf , 660.Fn printf , 661.Fn sprintf , 662.Fn vprintf , 663.Fn vfprintf , 664and 665.Fn vsprintf 666functions 667conform to 668.St -isoC90 . 669The conversion format modifiers 670.Cm %j , 671.Cm %t 672and 673.Cm %z 674conform to 675.St -isoC99 . 676The 677.Fn snprintf 678and 679.Fn vsnprintf 680functions 681conform to 682.St -isoC99 . 683.Sh HISTORY 684The functions 685.Fn snprintf 686and 687.Fn vsnprintf 688first appeared in 689.Bx 4.4 . 690The functions 691.Fn asprintf 692and 693.Fn vasprintf 694are modeled on the ones that first appeared in the GNU C library. 695.Sh BUGS 696The conversion formats 697.Cm \&%D , 698.Cm \&%O , 699and 700.Cm %U 701are not standard and are provided only for backward compatibility. 702The effect of padding the 703.Cm %p 704format with zeros (either by the 705.Sq Cm 0 706flag or by specifying a precision), and the benign effect (i.e. none) 707of the 708.Sq Cm # 709flag on 710.Cm %n 711and 712.Cm %p 713conversions, as well as other nonsensical combinations such as 714.Cm %Ld , 715are not standard; such combinations should be avoided. 716.Sh SECURITY CONSIDERATIONS 717Because 718.Fn sprintf 719and 720.Fn vsprintf 721assume an infinitely long string, callers must be careful not to 722overflow the actual space; this is often impossible to assure. 723For safety, programmers should use the 724.Fn snprintf 725and 726.Fn asprintf 727family of interfaces instead. 728Unfortunately, the 729.Fn snprintf 730interfaces are not available on older 731systems and the 732.Fn asprintf 733interfaces are not yet portable. 734