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.59 2005/09/05 09:49:33 tjr Exp $ 38.\" $DragonFly: src/lib/libc/stdio/printf.3,v 1.6 2006/08/26 10:27:55 swildner Exp $ 39.\" 40.Dd August 26, 2006 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. 86The 87.Fn printf 88and 89.Fn vprintf 90functions 91write output to 92.Dv stdout , 93the standard output stream; 94.Fn fprintf 95and 96.Fn vfprintf 97write output to the given output 98.Fa stream ; 99.Fn sprintf , 100.Fn snprintf , 101.Fn vsprintf , 102and 103.Fn vsnprintf 104write to the character string 105.Fa str ; 106and 107.Fn asprintf 108and 109.Fn vasprintf 110dynamically allocate a new string with 111.Xr malloc 3 . 112.Pp 113These functions write the output under the control of a 114.Fa format 115string that specifies how subsequent arguments 116(or arguments accessed via the variable-length argument facilities of 117.Xr stdarg 3 ) 118are converted for output. 119.Pp 120These functions return the number of characters printed 121(not including the trailing 122.Ql \e0 123used to end output to strings) or a negative value if an output error occurs, 124except for 125.Fn snprintf 126and 127.Fn vsnprintf , 128which return the number of characters that would have been printed if the 129.Fa size 130were unlimited 131(again, not including the final 132.Ql \e0 ) . 133.Pp 134The 135.Fn asprintf 136and 137.Fn vasprintf 138functions 139set 140.Fa *ret 141to be a pointer to a buffer sufficiently large to hold the formatted string. 142This pointer should be passed to 143.Xr free 3 144to release the allocated storage when it is no longer needed. 145If sufficient space cannot be allocated, 146.Fn asprintf 147and 148.Fn vasprintf 149will return \-1 and set 150.Fa ret 151to be a 152.Dv NULL 153pointer. 154.Pp 155The 156.Fn snprintf 157and 158.Fn vsnprintf 159functions 160will write at most 161.Fa size Ns \-1 162of the characters printed into the output string 163(the 164.Fa size Ns 'th 165character then gets the terminating 166.Ql \e0 ) ; 167if the return value is greater than or equal to the 168.Fa size 169argument, the string was too short 170and some of the printed characters were discarded. 171The output is always null-terminated. 172.Pp 173The 174.Fn sprintf 175and 176.Fn vsprintf 177functions 178effectively assume an infinite 179.Fa size . 180.Pp 181The format string is composed of zero or more directives: 182ordinary 183.\" multibyte 184characters (not 185.Cm % ) , 186which are copied unchanged to the output stream; 187and conversion specifications, each of which results 188in fetching zero or more subsequent arguments. 189Each conversion specification is introduced by 190the 191.Cm % 192character. 193The arguments must correspond properly (after type promotion) 194with the conversion specifier. 195After the 196.Cm % , 197the following appear in sequence: 198.Bl -bullet 199.It 200An optional field, consisting of a decimal digit string followed by a 201.Cm $ , 202specifying the next argument to access. 203If this field is not provided, the argument following the last 204argument accessed will be used. 205Arguments are numbered starting at 206.Cm 1 . 207If unaccessed arguments in the format string are interspersed with ones that 208are accessed the results will be indeterminate. 209.It 210Zero or more of the following flags: 211.Bl -tag -width ".So \ Sc (space)" 212.It Sq Cm # 213The value should be converted to an 214.Dq alternate form . 215For 216.Cm c , d , i , n , p , s , 217and 218.Cm u 219conversions, this option has no effect. 220For 221.Cm o 222conversions, the precision of the number is increased to force the first 223character of the output string to a zero (except if a zero value is printed 224with an explicit precision of zero). 225For 226.Cm x 227and 228.Cm X 229conversions, a non-zero result has the string 230.Ql 0x 231(or 232.Ql 0X 233for 234.Cm X 235conversions) prepended to it. 236For 237.Cm e , E , f , F , g , 238and 239.Cm G 240conversions, the result will always contain a decimal point, even if no 241digits follow it (normally, a decimal point appears in the results of 242those conversions only if a digit follows). 243For 244.Cm g 245and 246.Cm G 247conversions, trailing zeros are not removed from the result as they 248would otherwise be. 249.It So Cm 0 Sc (zero) 250Zero padding. 251For all conversions except 252.Cm n , 253the converted value is padded on the left with zeros rather than blanks. 254If a precision is given with a numeric conversion 255.Cm ( d , i , o , u , i , x , 256and 257.Cm X ) , 258the 259.Cm 0 260flag is ignored. 261.It Sq Cm \- 262A negative field width flag; 263the converted value is to be left adjusted on the field boundary. 264Except for 265.Cm n 266conversions, the converted value is padded on the right with blanks, 267rather than on the left with blanks or zeros. 268A 269.Cm \- 270overrides a 271.Cm 0 272if both are given. 273.It So "\ " Sc (space) 274A blank should be left before a positive number 275produced by a signed conversion 276.Cm ( d , e , E , f , F , g , G , 277or 278.Cm i ) . 279.It Sq Cm + 280A sign must always be placed before a 281number produced by a signed conversion. 282A 283.Cm + 284overrides a space if both are used. 285.El 286.It 287An optional decimal digit string specifying a minimum field width. 288If the converted value has fewer characters than the field width, it will 289be padded with spaces on the left (or right, if the left-adjustment 290flag has been given) to fill out 291the field width. 292.It 293An optional precision, in the form of a period 294.Cm \&. 295followed by an 296optional digit string. 297If the digit string is omitted, the precision is taken as zero. 298This gives the minimum number of digits to appear for 299.Cm d , i , o , u , x , 300and 301.Cm X 302conversions, the number of digits to appear after the decimal-point for 303.Cm e , E , f , 304and 305.Cm F 306conversions, the maximum number of significant digits for 307.Cm g 308and 309.Cm G 310conversions, or the maximum number of characters to be printed from a 311string for 312.Cm s 313conversions. 314.It 315An optional length modifier, that specifies the size of the argument. 316The following length modifiers are valid for the 317.Cm d , i , n , o , u , x , 318or 319.Cm X 320conversion: 321.Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *" 322.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n 323.It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *" 324.It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *" 325.It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *" 326.It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *" 327.It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *" 328.It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *" 329.It Cm z Ta (see note) Ta Vt size_t Ta (see note) 330.It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *" 331.El 332.Pp 333Note: 334the 335.Cm t 336modifier, when applied to a 337.Cm o , u , x , 338or 339.Cm X 340conversion, indicates that the argument is of an unsigned type 341equivalent in size to a 342.Vt ptrdiff_t . 343The 344.Cm z 345modifier, when applied to a 346.Cm d 347or 348.Cm i 349conversion, indicates that the argument is of a signed type equivalent in 350size to a 351.Vt size_t . 352Similarly, when applied to an 353.Cm n 354conversion, it indicates that the argument is a pointer to a signed type 355equivalent in size to a 356.Vt size_t . 357.Pp 358The following length modifier is valid for the 359.Cm e , E , f , F , g , 360or 361.Cm G 362conversion: 363.Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G" 364.It Sy Modifier Ta Cm e , E , f , F , g , G 365.It Cm l No (ell) Ta Vt double 366(ignored, same behavior as without it) 367.It Cm L Ta Vt "long double" 368.El 369.Pp 370The following length modifier is valid for the 371.Cm c 372or 373.Cm s 374conversion: 375.Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *" 376.It Sy Modifier Ta Cm c Ta Cm s 377.It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *" 378.El 379.It 380A character that specifies the type of conversion to be applied. 381.El 382.Pp 383A field width or precision, or both, may be indicated by 384an asterisk 385.Ql * 386or an asterisk followed by one or more decimal digits and a 387.Ql $ 388instead of a 389digit string. 390In this case, an 391.Vt int 392argument supplies the field width or precision. 393A negative field width is treated as a left adjustment flag followed by a 394positive field width; a negative precision is treated as though it were 395missing. 396If a single format directive mixes positional 397.Pq Li nn$ 398and non-positional arguments, the results are undefined. 399.Pp 400The conversion specifiers and their meanings are: 401.Bl -tag -width ".Cm 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.Dq Li abcdef 420are used for 421.Cm x 422conversions; the letters 423.Dq Li 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.Sm off 445.Oo \- Oc Ar d Li \&. Ar ddd Li e \\*[Pm] Ar dd 446.Sm on 447where there is one digit before the 448decimal-point character 449and the number of digits after it is equal to the precision; 450if the precision is missing, 451it is taken as 6; if the precision is 452zero, no decimal-point character appears. 453An 454.Cm E 455conversion uses the letter 456.Ql E 457(rather than 458.Ql e ) 459to introduce the exponent. 460The exponent always contains at least two digits; if the value is zero, 461the exponent is 00. 462.Pp 463For 464.Cm e , E , f , F , g , 465and 466.Cm G 467conversions, positive and negative infinity are represented as 468.Li inf 469and 470.Li -inf 471respectively when using the lowercase conversion character, and 472.Li INF 473and 474.Li -INF 475respectively when using the uppercase conversion character. 476Similarly, NaN is represented as 477.Li nan 478when using the lowercase conversion, and 479.Li NAN 480when using the uppercase conversion. 481.It Cm fF 482The 483.Vt double 484argument is rounded and converted to decimal notation in the style 485.Sm off 486.Oo \- Oc Ar ddd Li \&. Ar ddd , 487.Sm on 488where the number of digits after the decimal-point character 489is equal to the precision specification. 490If the precision is missing, it is taken as 6; if the precision is 491explicitly zero, no decimal-point character appears. 492If a decimal point appears, at least one digit appears before it. 493.It Cm gG 494The 495.Vt double 496argument is converted in style 497.Cm f 498or 499.Cm e 500(or 501.Cm F 502or 503.Cm E 504for 505.Cm G 506conversions). 507The precision specifies the number of significant digits. 508If the precision is missing, 6 digits are given; if the precision is zero, 509it is treated as 1. 510Style 511.Cm e 512is used if the exponent from its conversion is less than \-4 or greater than 513or equal to the precision. 514Trailing zeros are removed from the fractional part of the result; a 515decimal point appears only if it is followed by at least one digit. 516.It Cm C 517Treated as 518.Cm c 519with the 520.Cm l 521(ell) modifier. 522.It Cm c 523The 524.Vt int 525argument is converted to an 526.Vt "unsigned char" , 527and the resulting character is written. 528.Pp 529If the 530.Cm l 531(ell) modifier is used, the 532.Vt wint_t 533argument shall be converted to a 534.Vt wchar_t , 535and the (potentially multi-byte) sequence representing the 536single wide character is written, including any shift sequences. 537If a shift sequence is used, the shift state is also restored 538to the original state after the character. 539.It Cm S 540Treated as 541.Cm s 542with the 543.Cm l 544(ell) modifier. 545.It Cm s 546The 547.Vt "char *" 548argument is expected to be a pointer to an array of character type (pointer 549to a string). 550Characters from the array are written up to (but not including) 551a terminating 552.Dv NUL 553character; 554if a precision is specified, no more than the number specified are 555written. 556If a precision is given, no null character 557need be present; if the precision is not specified, or is greater than 558the size of the array, the array must contain a terminating 559.Dv NUL 560character. 561.Pp 562If the 563.Cm l 564(ell) modifier is used, the 565.Vt "wchar_t *" 566argument is expected to be a pointer to an array of wide characters 567(pointer to a wide string). 568For each wide character in the string, the (potentially multi-byte) 569sequence representing the 570wide character is written, including any shift sequences. 571If any shift sequence is used, the shift state is also restored 572to the original state after the string. 573Wide characters from the array are written up to (but not including) 574a terminating wide 575.Dv NUL 576character; 577if a precision is specified, no more than the number of bytes specified are 578written (including shift sequences). 579Partial characters are never written. 580If a precision is given, no null character 581need be present; if the precision is not specified, or is greater than 582the number of bytes required to render the multibyte representation of 583the string, the array must contain a terminating wide 584.Dv NUL 585character. 586.It Cm p 587The 588.Vt "void *" 589pointer argument is printed in hexadecimal (as if by 590.Ql %#x 591or 592.Ql %#lx ) . 593.It Cm n 594The number of characters written so far is stored into the 595integer indicated by the 596.Vt "int *" 597(or variant) pointer argument. 598No argument is converted. 599.It Cm % 600A 601.Ql % 602is written. 603No argument is converted. 604The complete conversion specification 605is 606.Ql %% . 607.El 608.Pp 609The decimal point 610character is defined in the program's locale (category 611.Dv LC_NUMERIC ) . 612.Pp 613In no case does a non-existent or small field width cause truncation of 614a numeric field; if the result of a conversion is wider than the field 615width, the 616field is expanded to contain the conversion result. 617.Sh EXAMPLES 618To print a date and time in the form 619.Dq Li "Sunday, July 3, 10:02" , 620where 621.Fa weekday 622and 623.Fa month 624are pointers to strings: 625.Bd -literal -offset indent 626#include <stdio.h> 627fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", 628 weekday, month, day, hour, min); 629.Ed 630.Pp 631To print \*(Pi 632to five decimal places: 633.Bd -literal -offset indent 634#include <math.h> 635#include <stdio.h> 636fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); 637.Ed 638.Pp 639To allocate a 128 byte string and print into it: 640.Bd -literal -offset indent 641#include <stdio.h> 642#include <stdlib.h> 643#include <stdarg.h> 644char *newfmt(const char *fmt, ...) 645{ 646 char *p; 647 va_list ap; 648 if ((p = malloc(128)) == NULL) 649 return (NULL); 650 va_start(ap, fmt); 651 (void) vsnprintf(p, 128, fmt, ap); 652 va_end(ap); 653 return (p); 654} 655.Ed 656.Sh SECURITY CONSIDERATIONS 657The 658.Fn sprintf 659and 660.Fn vsprintf 661functions are easily misused in a manner which enables malicious users 662to arbitrarily change a running program's functionality through 663a buffer overflow attack. 664Because 665.Fn sprintf 666and 667.Fn vsprintf 668assume an infinitely long string, 669callers must be careful not to overflow the actual space; 670this is often hard to assure. 671For safety, programmers should use the 672.Fn snprintf 673interface instead. 674For example: 675.Bd -literal 676void 677foo(const char *arbitrary_string, const char *and_another) 678{ 679 char onstack[8]; 680 681#ifdef BAD 682 /* 683 * This first sprintf is bad behavior. Do not use sprintf! 684 */ 685 sprintf(onstack, "%s, %s", arbitrary_string, and_another); 686#else 687 /* 688 * The following two lines demonstrate better use of 689 * snprintf(). 690 */ 691 snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string, 692 and_another); 693#endif 694} 695.Ed 696.Pp 697The 698.Fn printf 699and 700.Fn sprintf 701family of functions are also easily misused in a manner 702allowing malicious users to arbitrarily change a running program's 703functionality by either causing the program 704to print potentially sensitive data 705.Dq "left on the stack" , 706or causing it to generate a memory fault or bus error 707by dereferencing an invalid pointer. 708.Pp 709.Cm %n 710can be used to write arbitrary data to potentially carefully-selected 711addresses. 712Programmers are therefore strongly advised to never pass untrusted strings 713as the 714.Fa format 715argument, as an attacker can put format specifiers in the string 716to mangle your stack, 717leading to a possible security hole. 718This holds true even if the string was built using a function like 719.Fn snprintf , 720as the resulting string may still contain user-supplied conversion specifiers 721for later interpolation by 722.Fn printf . 723.Pp 724Always use the proper secure idiom: 725.Pp 726.Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);" 727.Sh ERRORS 728In addition to the errors documented for the 729.Xr write 2 730system call, the 731.Fn printf 732family of functions may fail if: 733.Bl -tag -width Er 734.It Bq Er EILSEQ 735An invalid wide character code was encountered. 736.It Bq Er ENOMEM 737Insufficient storage space is available. 738.El 739.Sh SEE ALSO 740.Xr printf 1 , 741.Xr fmtcheck 3 , 742.Xr scanf 3 , 743.Xr setlocale 3 , 744.Xr wprintf 3 745.Sh STANDARDS 746Subject to the caveats noted in the 747.Sx BUGS 748section below, the 749.Fn fprintf , 750.Fn printf , 751.Fn sprintf , 752.Fn vprintf , 753.Fn vfprintf , 754and 755.Fn vsprintf 756functions 757conform to 758.St -ansiC 759and 760.St -isoC-99 . 761With the same reservation, the 762.Fn snprintf 763and 764.Fn vsnprintf 765functions conform to 766.St -isoC-99 . 767.Sh HISTORY 768The functions 769.Fn asprintf 770and 771.Fn vasprintf 772first appeared in the 773.Tn GNU C 774library. 775These were implemented by 776.An Peter Wemm Aq peter@FreeBSD.org 777in 778.Fx 2.2 , 779but were later replaced with a different implementation 780from 781.An Todd C. Miller Aq Todd.Miller@courtesan.com 782for 783.Ox 2.3 . 784.Sh BUGS 785The conversion formats 786.Cm \&%D , \&%O , 787and 788.Cm %U 789are not standard and 790are provided only for backward compatibility. 791The effect of padding the 792.Cm %p 793format with zeros (either by the 794.Cm 0 795flag or by specifying a precision), and the benign effect (i.e., none) 796of the 797.Cm # 798flag on 799.Cm %n 800and 801.Cm %p 802conversions, as well as other 803nonsensical combinations such as 804.Cm %Ld , 805are not standard; such combinations 806should be avoided. 807.Pp 808The 809.Nm 810family of functions do not correctly handle multibyte characters in the 811.Fa format 812argument. 813