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