1.\" Copyright (c) 1990, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Chris Torek and the American National Standards Committee X3, 6.\" on Information Processing Systems. 7.\" 8.\" %sccs.include.redist.man% 9.\" 10.\" @(#)printf.3 8.1 (Berkeley) 06/04/93 11.\" 12.Dd 13.Dt PRINTF 3 14.Os 15.Sh NAME 16.Nm printf , 17.Nm fprintf , 18.Nm sprintf , 19.Nm snprintf , 20.Nm vprintf , 21.Nm vfprintf, 22.Nm vsprintf , 23.Nm vsnprintf 24.Nd formatted output conversion 25.Sh SYNOPSIS 26.Fd #include <stdio.h> 27.Ft int 28.Fn printf "const char *format" ... 29.Ft int 30.Fn fprintf "FILE *stream" "const char *format" ... 31.Ft int 32.Fn sprintf "char *str" "const char *format" ... 33.Ft int 34.Fn snprintf "char *str" "size_t size" "const char *format" ... 35.\" .Ft int 36.\" .Fn smprintf "const char *format" ... 37.Fd #include <stdarg.h> 38.Ft int 39.Fn vprintf "const char *format" "va_list ap" 40.Ft int 41.Fn vfprintf "FILE *stream" "const char *format" "va_list ap" 42.Ft int 43.Fn vsprintf "char *str" "char *format" "va_list ap" 44.Ft int 45.Fn vsnprintf "char *str" "size_t size" "const char *format" "va_list ap" 46.\" .Ft int 47.\" .Fn vsmprintf "const char *format" "va_list ap" 48.Sh DESCRIPTION 49The 50.Fn printf 51family of functions produces output according to a 52.Fa format 53as described below. 54.Fn Printf 55and 56.Fn vprintf 57write output to 58.Em stdout, 59the standard output stream; 60.Fn fprintf 61and 62.Fn vfprintf 63write output to the given output 64.Fa stream ; 65.Fn sprintf , 66.Fn snprintf , 67.Fn vsprintf , 68and 69.Fn vsnprintf 70write to the character string 71.Fa str . 72.\" .IR str ; 73.\" and 74.\" .I smprintf 75.\" and 76.\" .I vsmprintf 77.\" dynamically allocate a new string with 78.\" .IR malloc . 79These functions write the output under the control of a 80.Fa format 81string that specifies how subsequent arguments 82(or arguments accessed via the variable-length argument facilities of 83.Xr stdarg 3 ) 84are converted for output. 85.\" Except for 86.\" .I smprintf 87.\" and 88.\" .IR vsmprintf , 89.\" all of these functions return 90These functions return 91the number of characters printed 92(not including the trailing 93.Ql \e0 94used to end output to strings). 95.\" .I Smprintf 96.\" and 97.\" .I vsmprintf 98.\" return a pointer to a string of an appropriate length; 99.\" this pointer should be passed to 100.\" .I free 101.\" to release the associated storage 102.\" when it is no longer needed. 103.\" If sufficient space is not avaliable, 104.\" .I smprintf 105.\" and 106.\" .I vsmprintf 107.\" will return 108.\" .SM 109.\" .BR 110.Fn Snprintf 111and 112.Fn vsnprintf 113will write at most 114.Fa size Ns \-1 115of the characters printed into the output string 116(the 117.Fa size Ns 'th 118character then gets the terminating 119.Ql \e0 ) ; 120if the return value is greater than or equal to the 121.Fa size 122argument, the string was too short 123and some of the printed characters were discarded. 124.Fn Sprintf 125and 126.Fn vsprintf 127effectively assume an infinite 128.Fa size . 129.Pp 130The format string is composed of zero or more directives: 131ordinary 132.\" multibyte 133characters (not 134.Cm % ) , 135which are copied unchanged to the output stream; 136and conversion specifications, each of which results 137in fetching zero or more subsequent arguments. 138Each conversion specification is introduced by 139the character 140.Cm % . 141The arguments must correspond properly (after type promotion) 142with the conversion specifier. 143After the 144.Cm % , 145the following appear in sequence: 146.Bl -bullet 147.It 148Zero or more of the following flags: 149.Bl -hyphen 150.It 151A 152.Cm # 153character 154specifying that the value should be converted to an ``alternate form''. 155For 156.Cm c , 157.Cm d , 158.Cm i , 159.Cm n , 160.Cm p , 161.Cm s , 162and 163.Cm u , 164conversions, this option has no effect. 165For 166.Cm o 167conversions, the precision of the number is increased to force the first 168character of the output string to a zero (except if a zero value is printed 169with an explicit precision of zero). 170For 171.Cm x 172and 173.Cm X 174conversions, a non-zero result has the string 175.Ql 0x 176(or 177.Ql 0X 178for 179.Cm X 180conversions) prepended to it. 181For 182.Cm e , 183.Cm E , 184.Cm f , 185.Cm g , 186and 187.Cm G , 188conversions, the result will always contain a decimal point, even if no 189digits follow it (normally, a decimal point appears in the results of 190those conversions only if a digit follows). 191For 192.Cm g 193and 194.Cm G 195conversions, trailing zeros are not removed from the result as they 196would otherwise be. 197.It 198A zero 199.Sq Cm \&0 200character specifying zero padding. 201For all conversions except 202.Cm n , 203the converted value is padded on the left with zeros rather than blanks. 204If a precision is given with a numeric conversion 205.Pf ( Mc d , 206.Cm i , 207.Cm o , 208.Cm u , 209.Cm i , 210.Cm x , 211and 212.Cm X ) , 213the 214.Sq Cm \&0 215flag is ignored. 216.It 217A negative field width flag 218.Sq Cm \- 219indicates the converted value is to be left adjusted on the field boundary. 220Except for 221.Cm n 222conversions, the converted value is padded on the right with blanks, 223rather than on the left with blanks or zeros. 224A 225.Sq Cm \- 226overrides a 227.Sq Cm \&0 228if both are given. 229.It 230A space, specifying that a blank should be left before a positive number 231produced by a signed conversion 232.Pf ( Cm d , 233.Cm e , 234.Cm E , 235.Cm f , 236.Cm g , 237.Cm G , 238or 239.Cm i ) . 240.It 241A 242.Sq Cm + 243character specifying that a sign always be placed before a 244number produced by a signed conversion. 245A 246.Sq Cm + 247overrides a space if both are used. 248.El 249.It 250An optional decimal digit string specifying a minimum field width. 251If the converted value has fewer characters than the field width, it will 252be padded with spaces on the left (or right, if the left-adjustment 253flag has been given) to fill out 254the field width. 255.It 256An optional precision, in the form of a period 257.Sq Cm \&. 258followed by an 259optional digit string. If the digit string is omitted, the precision 260is taken as zero. This gives the minimum number of digits to appear for 261.Cm d , 262.Cm i , 263.Cm o , 264.Cm u , 265.Cm x , 266and 267.Cm X 268conversions, the number of digits to appear after the decimal-point for 269.Cm e , 270.Cm E , 271and 272.Cm f 273conversions, the maximum number of significant digits for 274.Cm g 275and 276.Cm G 277conversions, or the maximum number of characters to be printed from a 278string for 279.Cm s 280conversions. 281.It 282The optional character 283.Cm h , 284specifying that a following 285.Cm d , 286.Cm i , 287.Cm o , 288.Cm u , 289.Cm x , 290or 291.Cm X 292conversion corresponds to a 293.Em short int 294or 295.Em unsigned short int 296argument, or that a following 297.Cm n 298conversion corresponds to a pointer to a 299.Em short int 300argument. 301.It 302The optional character 303.Cm l 304(ell) specifying that a following 305.Cm d , 306.Cm i , 307.Cm o , 308.Cm u , 309.Cm x , 310or 311.Cm X 312conversion applies to a pointer to a 313.Em long int 314or 315.Em unsigned long int 316argument, or that a following 317.Cm n 318conversion corresponds to a pointer to a 319.Em long int 320argument. 321.It 322The optional character 323.Cm q , 324specifying that a following 325.Cm d , 326.Cm i , 327.Cm o , 328.Cm u , 329.Cm x , 330or 331.Cm X 332conversion corresponds to a 333.Em quad int 334or 335.Em unsigned quad int 336argument, or that a following 337.Cm n 338conversion corresponds to a pointer to a 339.Em quad int 340argument. 341.It 342The character 343.Cm L 344specifying that a following 345.Cm e , 346.Cm E , 347.Cm f , 348.Cm g , 349or 350.Cm G 351conversion corresponds to a 352.Em long double 353argument (but note that long double values are not currently supported 354by the 355.Tn VAX 356and 357.Tn Tahoe 358compilers). 359.It 360A character that specifies the type of conversion to be applied. 361.El 362.Pp 363A field width or precision, or both, may be indicated by 364an asterisk 365.Ql * 366instead of a 367digit string. 368In this case, an 369.Em int 370argument supplies the field width or precision. 371A negative field width is treated as a left adjustment flag followed by a 372positive field width; a negative precision is treated as though it were 373missing. 374.Pp 375The conversion specifiers and their meanings are: 376.Bl -tag -width "diouxX" 377.It Cm diouxX 378The 379.Em int 380(or appropriate variant) argument is converted to signed decimal 381.Pf ( Cm d 382and 383.Cm i ) , 384unsigned octal 385.Pq Cm o , 386unsigned decimal 387.Pq Cm u , 388or unsigned hexadecimal 389.Pf ( Cm x 390and 391.Cm X ) 392notation. The letters 393.Cm abcdef 394are used for 395.Cm x 396conversions; the letters 397.Cm ABCDEF 398are used for 399.m X 400conversions. 401The precision, if any, gives the minimum number of digits that must 402appear; if the converted value requires fewer digits, it is padded on 403the left with zeros. 404.It Cm DOU 405The 406.Em long int 407argument is converted to signed decimal, unsigned octal, or unsigned 408decimal, as if the format had been 409.Cm ld , 410.Cm lo , 411or 412.Cm lu 413respectively. 414These conversion characters are deprecated, and will eventually disappear. 415.It Cm eE 416The 417.Em double 418argument is rounded and converted in the style 419.Sm off 420.Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd 421.Sm on 422where there is one digit before the 423decimal-point character 424and the number of digits after it is equal to the precision; 425if the precision is missing, 426it is taken as 6; if the precision is 427zero, no decimal-point character appears. 428An 429.Cm E 430conversion uses the letter 431.Cm E 432(rather than 433.Cm e ) 434to introduce the exponent. 435The exponent always contains at least two digits; if the value is zero, 436the exponent is 00. 437.It Cm f 438The 439.Em double 440argument is rounded and converted to decimal notation in the style 441.Sm off 442.Pf [-]ddd Cm \&. No ddd , 443.Sm on 444where the number of digits after the decimal-point character 445is equal to the precision specification. 446If the precision is missing, it is taken as 6; if the precision is 447explicitly zero, no decimal-point character appears. 448If a decimal point appears, at least one digit appears before it. 449.It Cm g 450The 451.Em double 452argument is converted in style 453.Cm f 454or 455.Cm e 456(or 457.Cm E 458for 459.Cm G 460conversions). 461The precision specifies the number of significant digits. 462If the precision is missing, 6 digits are given; if the precision is zero, 463it is treated as 1. 464Style 465.Cm e 466is used if the exponent from its conversion is less than -4 or greater than 467or equal to the precision. 468Trailing zeros are removed from the fractional part of the result; a 469decimal point appears only if it is followed by at least one digit. 470.It Cm c 471The 472.Em int 473argument is converted to an 474.Em unsigned char , 475and the resulting character is written. 476.It Cm s 477The 478.Dq Em char * 479argument is expected to be a pointer to an array of character type (pointer 480to a string). 481Characters from the array are written up to (but not including) 482a terminating 483.Dv NUL 484character; 485if a precision is specified, no more than the number specified are 486written. 487If a precision is given, no null character 488need be present; if the precision is not specified, or is greater than 489the size of the array, the array must contain a terminating 490.Dv NUL 491character. 492.It Cm p 493The 494.Dq Em void * 495pointer argument is printed in hexadecimal (as if by 496.Ql %#x 497or 498.Ql %#lx ) . 499.It Cm n 500The number of characters written so far is stored into the 501integer indicated by the 502.Dq Em int * 503(or variant) pointer argument. 504No argument is converted. 505.It Cm % 506A 507.Ql % 508is written. No argument is converted. The complete conversion specification 509is 510.Ql %% . 511.El 512.Pp 513In no case does a non-existent or small field width cause truncation of 514a field; if the result of a conversion is wider than the field width, the 515field is expanded to contain the conversion result. 516.Pp 517.Sh EXAMPLES 518.br 519To print a date and time in the form `Sunday, July 3, 10:02', 520where 521.Em weekday 522and 523.Em month 524are pointers to strings: 525.Bd -literal -offset indent 526#include <stdio.h> 527fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", 528 weekday, month, day, hour, min); 529.Ed 530.Pp 531To print \*(Pi 532to five decimal places: 533.Bd -literal -offset indent 534#include <math.h> 535#include <stdio.h> 536fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); 537.Ed 538.Pp 539To allocate a 128 byte string and print into it: 540.Bd -literal -offset indent 541#include <stdio.h> 542#include <stdlib.h> 543#include <stdarg.h> 544char *newfmt(const char *fmt, ...) 545{ 546 char *p; 547 va_list ap; 548 if ((p = malloc(128)) == NULL) 549 return (NULL); 550 va_start(ap, fmt); 551 (void) vsnprintf(p, 128, fmt, ap); 552 va_end(ap); 553 return (p); 554} 555.Ed 556.Sh SEE ALSO 557.Xr printf 1 , 558.Xr scanf 3 559.Sh STANDARDS 560The 561.Fn fprintf , 562.Fn printf , 563.Fn sprintf , 564.Fn vprintf , 565.Fn vfprintf , 566and 567.Fn vsprintf 568functions 569conform to 570.St -ansiC . 571.Sh HISTORY 572The functions 573.Fn snprintf 574and 575.Fn vsnprintf 576are new to this release. 577.Sh BUGS 578The conversion formats 579.Cm \&%D , 580.Cm \&%O , 581and 582.Cm %U 583are not standard and 584are provided only for backward compatibility. 585The effect of padding the 586.Cm %p 587format with zeros (either by the 588.Sq Cm 0 589flag or by specifying a precision), and the benign effect (i.e., none) 590of the 591.Sq Cm # 592flag on 593.Cm %n 594and 595.Cm %p 596conversions, as well as other 597nonsensical combinations such as 598.Cm %Ld , 599are not standard; such combinations 600should be avoided. 601.Pp 602Because 603.Fn sprintf 604and 605.Fn vsprintf 606assume an infinitely long string, 607callers must be careful not to overflow the actual space; 608this is often impossible to assure. 609For safety, programmers should use the 610.Fn snprintf 611interface instead. 612Unfortunately, this interface is not portable. 613