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