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