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