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. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)printf.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD: head/lib/libc/stdio/printf.3 303524 2016-07-30 01:00:16Z bapt $ 34.\" 35.Dd March 21, 2022 36.Dt PRINTF 3 37.Os 38.Sh NAME 39.Nm printf , 40.Nm fprintf , 41.Nm sprintf , 42.Nm snprintf , 43.Nm asprintf , 44.Nm dprintf , 45.Nm vprintf , 46.Nm vfprintf , 47.Nm vsprintf , 48.Nm vsnprintf , 49.Nm vasprintf , 50.Nm vdprintf 51.Nd formatted output conversion 52.Sh LIBRARY 53.Lb libc 54.Sh SYNOPSIS 55.In stdio.h 56.Ft int 57.Fn printf "const char * restrict format" ... 58.Ft int 59.Fn fprintf "FILE * restrict stream" "const char * restrict format" ... 60.Ft int 61.Fn sprintf "char * restrict str" "const char * restrict format" ... 62.Ft int 63.Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ... 64.Ft int 65.Fn asprintf "char **ret" "const char *format" ... 66.Ft int 67.Fn dprintf "int" "const char * restrict format" ... 68.In stdarg.h 69.Ft int 70.Fn vprintf "const char * restrict format" "va_list ap" 71.Ft int 72.Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap" 73.Ft int 74.Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap" 75.Ft int 76.Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap" 77.Ft int 78.Fn vasprintf "char **ret" "const char *format" "va_list ap" 79.Ft int 80.Fn vdprintf "int fd" "const char * restrict format" "va_list ap" 81.Sh DESCRIPTION 82The 83.Fn printf 84family of functions produces output according to a 85.Fa format 86as described below. 87The 88.Fn printf 89and 90.Fn vprintf 91functions 92write output to 93.Dv stdout , 94the standard output stream; 95.Fn fprintf 96and 97.Fn vfprintf 98write output to the given output 99.Fa stream ; 100.Fn dprintf 101and 102.Fn vdprintf 103write output to the given file descriptor; 104.Fn sprintf , 105.Fn snprintf , 106.Fn vsprintf , 107and 108.Fn vsnprintf 109write to the character string 110.Fa str ; 111and 112.Fn asprintf 113and 114.Fn vasprintf 115dynamically allocate a new string with 116.Xr malloc 3 . 117.Pp 118These functions write the output under the control of a 119.Fa format 120string that specifies how subsequent arguments 121(or arguments accessed via the variable-length argument facilities of 122.Xr stdarg 3 ) 123are converted for output. 124.Pp 125The 126.Fn asprintf 127and 128.Fn vasprintf 129functions 130set 131.Fa *ret 132to be a pointer to a buffer sufficiently large to hold the formatted string. 133This pointer should be passed to 134.Xr free 3 135to release the allocated storage when it is no longer needed. 136If sufficient space cannot be allocated, 137.Fn asprintf 138and 139.Fn vasprintf 140will return \-1 and set 141.Fa ret 142to be a 143.Dv NULL 144pointer. 145.Pp 146The 147.Fn snprintf 148and 149.Fn vsnprintf 150functions 151will write at most 152.Fa size Ns \-1 153of the characters printed into the output string 154(the 155.Fa size Ns 'th 156character then gets the terminating 157.Ql \e0 ) ; 158if the return value is greater than or equal to the 159.Fa size 160argument, the string was too short 161and some of the printed characters were discarded. 162The output is always null-terminated, unless 163.Fa size 164is 0. 165.Pp 166The 167.Fn sprintf 168and 169.Fn vsprintf 170functions 171effectively assume a 172.Fa size 173of 174.Dv INT_MAX 175+ 1. 176.Pp 177The format string is composed of zero or more directives: 178ordinary 179.\" multibyte 180characters (not 181.Cm % ) , 182which are copied unchanged to the output stream; 183and conversion specifications, each of which results 184in fetching zero or more subsequent arguments. 185Each conversion specification is introduced by 186the 187.Cm % 188character. 189The arguments must correspond properly (after type promotion) 190with the conversion specifier. 191After the 192.Cm % , 193the following appear in sequence: 194.Bl -bullet 195.It 196An optional field, consisting of a decimal digit string followed by a 197.Cm $ , 198specifying the next argument to access. 199If this field is not provided, the argument following the last 200argument accessed will be used. 201Arguments are numbered starting at 202.Cm 1 . 203If unaccessed arguments in the format string are interspersed with ones that 204are accessed the results will be indeterminate. 205.It 206Zero or more of the following flags: 207.Bl -tag -width ".So \ Sc (space)" 208.It Sq Cm # 209The value should be converted to an 210.Dq alternate form . 211For 212.Cm c , d , i , n , p , s , 213and 214.Cm u 215conversions, this option has no effect. 216For 217.Cm o 218conversions, the precision of the number is increased to force the first 219character of the output string to a 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 a , A , e , E , f , 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 So Cm 0 Sc (zero) 245Zero padding. 246For all conversions except 247.Cm n , 248the converted value is padded on the left with zeros rather than blanks. 249If a precision is given with a numeric conversion 250.Cm ( d , i , o , u , i , x , 251and 252.Cm X ) , 253the 254.Cm 0 255flag is ignored. 256.It Sq Cm \- 257A negative field width flag; 258the converted value is to be left adjusted on the field boundary. 259Except for 260.Cm n 261conversions, the converted value is padded on the right with blanks, 262rather than on the left with blanks or zeros. 263A 264.Cm \- 265overrides a 266.Cm 0 267if both are given. 268.It So "\ " Sc (space) 269A blank should be left before a positive number 270produced by a signed conversion 271.Cm ( a , A , d , e , E , f , F , g , G , 272or 273.Cm i ) . 274.It Sq Cm + 275A sign must always be placed before a 276number produced by a signed conversion. 277A 278.Cm + 279overrides a space if both are used. 280.It So "'" Sc (apostrophe) 281Decimal conversions 282.Cm ( d , u , 283or 284.Cm i ) 285or the integral portion of a floating point conversion 286.Cm ( f 287or 288.Cm F ) 289should be grouped and separated by thousands using 290the non-monetary separator returned by 291.Xr localeconv 3 . 292.El 293.It 294An optional decimal digit string specifying a minimum field width. 295If the converted value has fewer characters than the field width, it will 296be padded with spaces on the left (or right, if the left-adjustment 297flag has been given) to fill out 298the field width. 299.It 300An optional precision, in the form of a period 301.Cm \&. 302followed by an 303optional digit string. 304If the digit string is omitted, the precision is taken as zero. 305This gives the minimum number of digits to appear for 306.Cm d , i , o , u , x , 307and 308.Cm X 309conversions, the number of digits to appear after the decimal-point for 310.Cm a , A , e , E , f , 311and 312.Cm F 313conversions, the maximum number of significant digits for 314.Cm g 315and 316.Cm G 317conversions, or the maximum number of characters to be printed from a 318string for 319.Cm s 320conversions. 321.It 322An optional length modifier, that specifies the size of the argument. 323The following length modifiers are valid for the 324.Cm d , i , n , o , u , x , 325or 326.Cm X 327conversion: 328.Bl -column ".Cm q Em (non-standard)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *" 329.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n 330.It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *" 331.It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *" 332.It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *" 333.It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *" 334.It Cm L Em (non-standard) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *" 335.It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *" 336.It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *" 337.It Cm z Ta (see note) Ta Vt size_t Ta (see note) 338.It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *" 339.El 340.Pp 341Note: 342the 343.Cm t 344modifier, when applied to a 345.Cm o , u , x , 346or 347.Cm X 348conversion, indicates that the argument is of an unsigned type 349equivalent in size to a 350.Vt ptrdiff_t . 351The 352.Cm z 353modifier, when applied to a 354.Cm d 355or 356.Cm i 357conversion, indicates that the argument is of a signed type equivalent in 358size to a 359.Vt size_t . 360Similarly, when applied to an 361.Cm n 362conversion, it indicates that the argument is a pointer to a signed type 363equivalent in size to a 364.Vt size_t . 365.Pp 366The following length modifier is valid for the 367.Cm a , A , e , E , f , F , g , 368or 369.Cm G 370conversion: 371.Bl -column ".Cm ll Em (non-standard)" ".Cm a , A , e , E , f , F , g , G" 372.It Sy Modifier Ta Cm a , A , e , E , f , F , g , G 373.It Cm l No (ell) Ta Vt double 374(ignored, same behavior as without it) 375.It Cm L Ta Vt "long double" 376.It Cm ll Em (non-standard) Ta Vt "long double" 377.El 378.Pp 379The following length modifier is valid for the 380.Cm c 381or 382.Cm s 383conversion: 384.Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *" 385.It Sy Modifier Ta Cm c Ta Cm s 386.It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *" 387.El 388.It 389A character that specifies the type of conversion to be applied. 390.El 391.Pp 392A field width or precision, or both, may be indicated by 393an asterisk 394.Ql * 395or an asterisk followed by one or more decimal digits and a 396.Ql $ 397instead of a 398digit string. 399In this case, an 400.Vt int 401argument supplies the field width or precision. 402A negative field width is treated as a left adjustment flag followed by a 403positive field width; a negative precision is treated as though it were 404missing. 405If a single format directive mixes positional 406.Pq Li nn$ 407and non-positional arguments, the results are undefined. 408.Pp 409The conversion specifiers and their meanings are: 410.Bl -tag -width ".Cm 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.Dq Li abcdef 429are used for 430.Cm x 431conversions; the letters 432.Dq Li 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.Sm off 454.Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd 455.Sm on 456where there is one digit before the 457decimal-point character 458and the number of digits after it is equal to the precision; 459if the precision is missing, 460it is taken as 6; if the precision is 461zero, no decimal-point character appears. 462An 463.Cm E 464conversion uses the letter 465.Ql E 466(rather than 467.Ql e ) 468to introduce the exponent. 469The exponent always contains at least two digits; if the value is zero, 470the exponent is 00. 471.Pp 472For 473.Cm a , A , e , E , f , F , g , 474and 475.Cm G 476conversions, positive and negative infinity are represented as 477.Li inf 478and 479.Li -inf 480respectively when using the lowercase conversion character, and 481.Li INF 482and 483.Li -INF 484respectively when using the uppercase conversion character. 485Similarly, NaN is represented as 486.Li nan 487when using the lowercase conversion, and 488.Li NAN 489when using the uppercase conversion. 490.It Cm fF 491The 492.Vt double 493argument is rounded and converted to decimal notation in the style 494.Sm off 495.Oo \- Oc Ar ddd Li \&. Ar ddd , 496.Sm on 497where the number of digits after the decimal-point character 498is equal to the precision specification. 499If the precision is missing, it is taken as 6; if the precision is 500explicitly zero, no decimal-point character appears. 501If a decimal point appears, at least one digit appears before it. 502.It Cm gG 503The 504.Vt double 505argument is converted in style 506.Cm f 507or 508.Cm e 509(or 510.Cm F 511or 512.Cm E 513for 514.Cm G 515conversions). 516The precision specifies the number of significant digits. 517If the precision is missing, 6 digits are given; if the precision is zero, 518it is treated as 1. 519Style 520.Cm e 521is used if the exponent from its conversion is less than \-4 or greater than 522or equal to the precision. 523Trailing zeros are removed from the fractional part of the result; a 524decimal point appears only if it is followed by at least one digit. 525.It Cm aA 526The 527.Vt double 528argument is rounded and converted to hexadecimal notation in the style 529.Sm off 530.Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d , 531.Sm on 532where the number of digits after the hexadecimal-point character 533is equal to the precision specification. 534If the precision is missing, it is taken as enough to represent 535the floating-point number exactly, and no rounding occurs. 536If the precision is zero, no hexadecimal-point character appears. 537The 538.Cm p 539is a literal character 540.Ql p , 541and the exponent consists of a positive or negative sign 542followed by a decimal number representing an exponent of 2. 543The 544.Cm A 545conversion uses the prefix 546.Dq Li 0X 547(rather than 548.Dq Li 0x ) , 549the letters 550.Dq Li ABCDEF 551(rather than 552.Dq Li abcdef ) 553to represent the hex digits, and the letter 554.Ql P 555(rather than 556.Ql p ) 557to separate the mantissa and exponent. 558.Pp 559Note that there may be multiple valid ways to represent floating-point 560numbers in this hexadecimal format. 561For example, 562.Li 0x1.92p+1 , 0x3.24p+0 , 0x6.48p-1 , 563and 564.Li 0xc.9p-2 565are all equivalent. 566.Fx 8.0 567and later always prints finite non-zero numbers using 568.Ql 1 569as the digit before the hexadecimal point. 570Zeroes are always represented with a mantissa of 0 (preceded by a 571.Ql - 572if appropriate) and an exponent of 573.Li +0 . 574.It Cm C 575Treated as 576.Cm c 577with the 578.Cm l 579(ell) modifier. 580.It Cm c 581The 582.Vt int 583argument is converted to an 584.Vt "unsigned char" , 585and the resulting character is written. 586.Pp 587If the 588.Cm l 589(ell) modifier is used, the 590.Vt wint_t 591argument shall be converted to a 592.Vt wchar_t , 593and the (potentially multi-byte) sequence representing the 594single wide character is written, including any shift sequences. 595If a shift sequence is used, the shift state is also restored 596to the original state after the character. 597.It Cm S 598Treated as 599.Cm s 600with the 601.Cm l 602(ell) modifier. 603.It Cm s 604The 605.Vt "char *" 606argument is expected to be a pointer to an array of character type (pointer 607to a string). 608Characters from the array are written up to (but not including) 609a terminating 610.Dv NUL 611character; 612if a precision is specified, no more than the number specified are 613written. 614If a precision is given, no null character 615need be present; if the precision is not specified, or is greater than 616the size of the array, the array must contain a terminating 617.Dv NUL 618character. 619.Pp 620If the 621.Cm l 622(ell) modifier is used, the 623.Vt "wchar_t *" 624argument is expected to be a pointer to an array of wide characters 625(pointer to a wide string). 626For each wide character in the string, the (potentially multi-byte) 627sequence representing the 628wide character is written, including any shift sequences. 629If any shift sequence is used, the shift state is also restored 630to the original state after the string. 631Wide characters from the array are written up to (but not including) 632a terminating wide 633.Dv NUL 634character; 635if a precision is specified, no more than the number of bytes specified are 636written (including shift sequences). 637Partial characters are never written. 638If a precision is given, no null character 639need be present; if the precision is not specified, or is greater than 640the number of bytes required to render the multibyte representation of 641the string, the array must contain a terminating wide 642.Dv NUL 643character. 644.It Cm p 645The 646.Vt "void *" 647pointer argument is printed in hexadecimal (as if by 648.Ql %#x 649or 650.Ql %#lx ) . 651.It Cm n 652The number of characters written so far is stored into the 653integer indicated by the 654.Vt "int *" 655(or variant) pointer argument. 656No argument is converted. 657.It Cm % 658A 659.Ql % 660is written. 661No argument is converted. 662The complete conversion specification 663is 664.Ql %% . 665.El 666.Pp 667The decimal point 668character is defined in the program's locale (category 669.Dv LC_NUMERIC ) . 670.Pp 671In no case does a non-existent or small field width cause truncation of 672a numeric field; if the result of a conversion is wider than the field 673width, the 674field is expanded to contain the conversion result. 675.Sh RETURN VALUES 676These functions return the number of characters printed 677(not including the trailing 678.Ql \e0 679used to end output to strings), 680except for 681.Fn snprintf 682and 683.Fn vsnprintf , 684which return the number of characters that would have been printed if the 685.Fa size 686were unlimited 687(again, not including the final 688.Ql \e0 ) . 689These functions return a negative value if an error occurs. 690.Sh EXAMPLES 691To print a date and time in the form 692.Dq Li "Sunday, July 3, 10:02" , 693where 694.Fa weekday 695and 696.Fa month 697are pointers to strings: 698.Bd -literal -offset indent 699#include <stdio.h> 700fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", 701 weekday, month, day, hour, min); 702.Ed 703.Pp 704To print \*(Pi 705to five decimal places: 706.Bd -literal -offset indent 707#include <math.h> 708#include <stdio.h> 709fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); 710.Ed 711.Pp 712To allocate a 128 byte string and print into it: 713.Bd -literal -offset indent 714#include <stdio.h> 715#include <stdlib.h> 716#include <stdarg.h> 717char *newfmt(const char *fmt, ...) 718{ 719 char *p; 720 va_list ap; 721 if ((p = malloc(128)) == NULL) 722 return (NULL); 723 va_start(ap, fmt); 724 (void) vsnprintf(p, 128, fmt, ap); 725 va_end(ap); 726 return (p); 727} 728.Ed 729.Sh COMPATIBILITY 730The conversion formats 731.Cm \&%D , \&%O , 732and 733.Cm \&%U 734are not standard and 735are provided only for backward compatibility. 736The effect of padding the 737.Cm %p 738format with zeros (either by the 739.Cm 0 740flag or by specifying a precision), and the benign effect (i.e., none) 741of the 742.Cm # 743flag on 744.Cm %n 745and 746.Cm %p 747conversions, as well as other 748nonsensical combinations such as 749.Cm %Ld , 750are not standard; such combinations 751should be avoided. 752.Sh ERRORS 753In addition to the errors documented for the 754.Xr write 2 755system call, the 756.Fn printf 757family of functions may fail if: 758.Bl -tag -width Er 759.It Bq Er EILSEQ 760An invalid wide character code was encountered. 761.It Bq Er ENOMEM 762Insufficient storage space is available. 763.It Bq Er EOVERFLOW 764The 765.Fa size 766argument exceeds 767.Dv INT_MAX + 1 , 768or the return value would be too large to be represented by an 769.Vt int . 770.El 771.Sh SEE ALSO 772.Xr printf 1 , 773.Xr fmtcheck 3 , 774.Xr scanf 3 , 775.Xr setlocale 3 , 776.Xr snprintb 3 , 777.Xr wprintf 3 778.Sh STANDARDS 779Subject to the caveats noted in the 780.Sx BUGS 781section below, the 782.Fn fprintf , 783.Fn printf , 784.Fn sprintf , 785.Fn vprintf , 786.Fn vfprintf , 787and 788.Fn vsprintf 789functions 790conform to 791.St -ansiC 792and 793.St -isoC-99 . 794With the same reservation, the 795.Fn snprintf 796and 797.Fn vsnprintf 798functions conform to 799.St -isoC-99 , 800while 801.Fn dprintf 802and 803.Fn vdprintf 804conform to 805.St -p1003.1-2008 . 806.Pp 807As an extension, 808.Dx 809treats the length modifiers 810.Cm ll 811and 812.Cm L 813as synonyms, so that the non-standard 814.Cm %Ld 815is equivalent to 816.Cm %ld 817and the non-standard 818.Cm %llg 819is equivalent 820to 821.Cm %Lg . 822.Sh HISTORY 823The functions 824.Fn asprintf 825and 826.Fn vasprintf 827first appeared in the 828.Tn GNU C 829library. 830These were implemented by 831.An Peter Wemm Aq Mt peter@FreeBSD.org 832in 833.Fx 2.2 , 834but were later replaced with a different implementation 835from 836.Ox 2.3 837by 838.An Todd C. Miller Aq Mt Todd.Miller@courtesan.com . 839The 840.Fn dprintf 841and 842.Fn vdprintf 843functions were added in 844.Fx 8.0 . 845.Sh BUGS 846The 847.Nm 848family of functions do not correctly handle multibyte characters in the 849.Fa format 850argument. 851.Sh SECURITY CONSIDERATIONS 852The 853.Fn sprintf 854and 855.Fn vsprintf 856functions are easily misused in a manner which enables malicious users 857to arbitrarily change a running program's functionality through 858a buffer overflow attack. 859Because 860.Fn sprintf 861and 862.Fn vsprintf 863assume an infinitely long string, 864callers must be careful not to overflow the actual space; 865this is often hard to assure. 866For safety, programmers should use the 867.Fn snprintf 868interface instead. 869For example: 870.Bd -literal 871void 872foo(const char *arbitrary_string, const char *and_another) 873{ 874 char onstack[8]; 875 876#ifdef BAD 877 /* 878 * This first sprintf is bad behavior. Do not use sprintf! 879 */ 880 sprintf(onstack, "%s, %s", arbitrary_string, and_another); 881#else 882 /* 883 * The following two lines demonstrate better use of 884 * snprintf(). 885 */ 886 snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string, 887 and_another); 888#endif 889} 890.Ed 891.Pp 892The 893.Fn printf 894and 895.Fn sprintf 896family of functions are also easily misused in a manner 897allowing malicious users to arbitrarily change a running program's 898functionality by either causing the program 899to print potentially sensitive data 900.Dq "left on the stack" , 901or causing it to generate a memory fault or bus error 902by dereferencing an invalid pointer. 903.Pp 904.Cm %n 905can be used to write arbitrary data to potentially carefully-selected 906addresses. 907Programmers are therefore strongly advised to never pass untrusted strings 908as the 909.Fa format 910argument, as an attacker can put format specifiers in the string 911to mangle your stack, 912leading to a possible security hole. 913This holds true even if the string was built using a function like 914.Fn snprintf , 915as the resulting string may still contain user-supplied conversion specifiers 916for later interpolation by 917.Fn printf . 918.Pp 919Always use the proper secure idiom: 920.Pp 921.Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);" 922