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