1.\" $NetBSD: printf.3,v 1.21 2001/10/17 13:27:15 kleink 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. 452.It 453A character that specifies the type of conversion to be applied. 454.El 455.Pp 456A field width or precision, or both, may be indicated by 457an asterisk 458.Ql * 459instead of a 460digit string. 461In this case, an 462.Em int 463argument supplies the field width or precision. 464A negative field width is treated as a left adjustment flag followed by a 465positive field width; a negative precision is treated as though it were 466missing. 467.Pp 468The conversion specifiers and their meanings are: 469.Bl -tag -width "diouxX" 470.It Cm diouxX 471The 472.Em int 473(or appropriate variant) argument is converted to signed decimal 474.Pf ( Cm d 475and 476.Cm i ) , 477unsigned octal 478.Pq Cm o , 479unsigned decimal 480.Pq Cm u , 481or unsigned hexadecimal 482.Pf ( Cm x 483and 484.Cm X ) 485notation. The letters 486.Cm abcdef 487are used for 488.Cm x 489conversions; the letters 490.Cm ABCDEF 491are used for 492.Cm X 493conversions. 494The precision, if any, gives the minimum number of digits that must 495appear; if the converted value requires fewer digits, it is padded on 496the left with zeros. 497.It Cm DOU 498The 499.Em long int 500argument is converted to signed decimal, unsigned octal, or unsigned 501decimal, as if the format had been 502.Cm ld , 503.Cm lo , 504or 505.Cm lu 506respectively. 507These conversion characters are deprecated, and will eventually disappear. 508.It Cm eE 509The 510.Em double 511argument is rounded and converted in the style 512.Sm off 513.Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd 514.Sm on 515where there is one digit before the 516decimal-point character 517and the number of digits after it is equal to the precision; 518if the precision is missing, 519it is taken as 6; if the precision is 520zero, no decimal-point character appears. 521An 522.Cm E 523conversion uses the letter 524.Cm E 525(rather than 526.Cm e ) 527to introduce the exponent. 528The exponent always contains at least two digits; if the value is zero, 529the exponent is 00. 530.It Cm f 531The 532.Em double 533argument is rounded and converted to decimal notation in the style 534.Sm off 535.Pf [-]ddd Cm \&. No ddd , 536.Sm on 537where the number of digits after the decimal-point character 538is equal to the precision specification. 539If the precision is missing, it is taken as 6; if the precision is 540explicitly zero, no decimal-point character appears. 541If a decimal point appears, at least one digit appears before it. 542.It Cm g 543The 544.Em double 545argument is converted in style 546.Cm f 547or 548.Cm e 549(or 550.Cm E 551for 552.Cm G 553conversions). 554The precision specifies the number of significant digits. 555If the precision is missing, 6 digits are given; if the precision is zero, 556it is treated as 1. 557Style 558.Cm e 559is used if the exponent from its conversion is less than -4 or greater than 560or equal to the precision. 561Trailing zeros are removed from the fractional part of the result; a 562decimal point appears only if it is followed by at least one digit. 563.It Cm c 564The 565.Em int 566argument is converted to an 567.Em unsigned char , 568and the resulting character is written. 569.It Cm s 570The 571.Dq Em char * 572argument is expected to be a pointer to an array of character type (pointer 573to a string). 574Characters from the array are written up to (but not including) 575a terminating 576.Dv NUL 577character; 578if a precision is specified, no more than the number specified are 579written. 580If a precision is given, no null character 581need be present; if the precision is not specified, or is greater than 582the size of the array, the array must contain a terminating 583.Dv NUL 584character. 585.It Cm p 586The 587.Dq Em void * 588pointer argument is printed in hexadecimal (as if by 589.Ql %#x 590or 591.Ql %#lx ) . 592.It Cm n 593The number of characters written so far is stored into the 594integer indicated by the 595.Dq Em int * 596(or variant) pointer argument. 597No argument is converted. 598.It Cm % 599A 600.Ql % 601is written. No argument is converted. The complete conversion specification 602is 603.Ql %% . 604.El 605.Pp 606In no case does a non-existent or small field width cause truncation of 607a field; if the result of a conversion is wider than the field width, the 608field is expanded to contain the conversion result. 609.Sh EXAMPLES 610.br 611To print a date and time in the form `Sunday, July 3, 10:02', 612where 613.Em weekday 614and 615.Em month 616are pointers to strings: 617.Bd -literal -offset indent 618#include <stdio.h> 619fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", 620 weekday, month, day, hour, min); 621.Ed 622.Pp 623To print \*(Pi 624to five decimal places: 625.Bd -literal -offset indent 626#include <math.h> 627#include <stdio.h> 628fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); 629.Ed 630.Pp 631To allocate a 128 byte string and print into it: 632.Bd -literal -offset indent 633#include <stdio.h> 634#include <stdlib.h> 635#include <stdarg.h> 636char *newfmt(const char *fmt, ...) 637{ 638 char *p; 639 va_list ap; 640 if ((p = malloc(128)) == NULL) 641 return (NULL); 642 va_start(ap, fmt); 643 (void) vsnprintf(p, 128, fmt, ap); 644 va_end(ap); 645 return (p); 646} 647.Ed 648.Sh SEE ALSO 649.Xr printf 1 , 650.Xr scanf 3 , 651.Xr printf 9 652.Sh STANDARDS 653The 654.Fn fprintf , 655.Fn printf , 656.Fn sprintf , 657.Fn vprintf , 658.Fn vfprintf , 659and 660.Fn vsprintf 661functions 662conform to 663.St -isoC90 . 664The conversion format modifiers 665.Cm %j , 666.Cm %t 667and 668.Cm %z 669conform to 670.St -isoC99 . 671The 672.Fn snprintf 673and 674.Fn vsnprintf 675functions 676conform to 677.St -isoC99 . 678.Sh HISTORY 679The functions 680.Fn snprintf 681and 682.Fn vsnprintf 683first appeared in 684.Bx 4.4 . 685The functions 686.Fn asprintf 687and 688.Fn vasprintf 689are modeled on the ones that first appeared in the GNU C library. 690.Sh BUGS 691The conversion formats 692.Cm \&%D , 693.Cm \&%O , 694and 695.Cm %U 696are not standard and are provided only for backward compatibility. 697The effect of padding the 698.Cm %p 699format with zeros (either by the 700.Sq Cm 0 701flag or by specifying a precision), and the benign effect (i.e. none) 702of the 703.Sq Cm # 704flag on 705.Cm %n 706and 707.Cm %p 708conversions, as well as other nonsensical combinations such as 709.Cm %Ld , 710are not standard; such combinations should be avoided. 711.Sh SECURITY CONSIDERATIONS 712Because 713.Fn sprintf 714and 715.Fn vsprintf 716assume an infinitely long string, callers must be careful not to 717overflow the actual space; this is often impossible to assure. 718For safety, programmers should use the 719.Fn snprintf 720and 721.Fn asprintf 722family of interfaces instead. 723Unfortunately, the 724.Fn snprintf 725interfaces are not available on older 726systems and the 727.Fn asprintf 728interfaces are not yet portable. 729