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: src/lib/libc/stdio/printf.3,v 1.47 2002/09/06 11:23:55 tjr Exp 34.\" 35.Dd July 5, 2003 36.Dt WPRINTF 3 37.Os 38.Sh NAME 39.Nm wprintf , fwprintf , swprintf , 40.Nm vwprintf , vfwprintf , vswprintf 41.Nd formatted wide character output conversion 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In stdio.h 46.In wchar.h 47.Ft int 48.Fn fwprintf "FILE * restrict stream" "const wchar_t * restrict format" ... 49.Ft int 50.Fn swprintf "wchar_t * restrict ws" "size_t n" "const wchar_t * restrict format" ... 51.Ft int 52.Fn wprintf "const wchar_t * restrict format" ... 53.In stdarg.h 54.Ft int 55.Fn vfwprintf "FILE * restrict stream" "const wchar_t * restrict" "va_list ap" 56.Ft int 57.Fn vswprintf "wchar_t * restrict ws" "size_t n" "const wchar_t *restrict format" "va_list ap" 58.Ft int 59.Fn vwprintf "const wchar_t * restrict format" "va_list ap" 60.Sh DESCRIPTION 61The 62.Fn wprintf 63family of functions produces output according to a 64.Fa format 65as described below. 66The 67.Fn wprintf 68and 69.Fn vwprintf 70functions 71write output to 72.Dv stdout , 73the standard output stream; 74.Fn fwprintf 75and 76.Fn vfwprintf 77write output to the given output 78.Fa stream ; 79.Fn swprintf 80and 81.Fn vswprintf 82write to the wide character string 83.Fa ws . 84.Pp 85These functions write the output under the control of a 86.Fa format 87string that specifies how subsequent arguments 88(or arguments accessed via the variable-length argument facilities of 89.Xr stdarg 3 ) 90are converted for output. 91.Pp 92These functions return the number of characters printed 93(not including the trailing 94.Ql \e0 95used to end output to strings). 96.Pp 97The 98.Fn swprintf 99and 100.Fn vswprintf 101functions will fail if 102.Fa n 103or more wide characters were requested to be written, 104.Pp 105The format string is composed of zero or more directives: 106ordinary 107characters (not 108.Cm % ) , 109which are copied unchanged to the output stream; 110and conversion specifications, each of which results 111in fetching zero or more subsequent arguments. 112Each conversion specification is introduced by 113the 114.Cm % 115character. 116The arguments must correspond properly (after type promotion) 117with the conversion specifier. 118After the 119.Cm % , 120the following appear in sequence: 121.Bl -bullet 122.It 123An optional field, consisting of a decimal digit string followed by a 124.Cm $ , 125specifying the next argument to access. 126If this field is not provided, the argument following the last 127argument accessed will be used. 128Arguments are numbered starting at 129.Cm 1 . 130If unaccessed arguments in the format string are interspersed with ones that 131are accessed the results will be indeterminate. 132.It 133Zero or more of the following flags: 134.Bl -tag -width ".So \ Sc (space)" 135.It Sq Cm # 136The value should be converted to an 137.Dq alternate form . 138For 139.Cm c , d , i , n , p , s , 140and 141.Cm u 142conversions, this option has no effect. 143For 144.Cm o 145conversions, the precision of the number is increased to force the first 146character of the output string to a zero (except if a zero value is printed 147with an explicit precision of zero). 148For 149.Cm x 150and 151.Cm X 152conversions, a non-zero result has the string 153.Ql 0x 154(or 155.Ql 0X 156for 157.Cm X 158conversions) prepended to it. 159For 160.Cm a , A , e , E , f , F , g , 161and 162.Cm G 163conversions, the result will always contain a decimal point, even if no 164digits follow it (normally, a decimal point appears in the results of 165those conversions only if a digit follows). 166For 167.Cm g 168and 169.Cm G 170conversions, trailing zeros are not removed from the result as they 171would otherwise be. 172.It So Cm 0 Sc (zero) 173Zero padding. 174For all conversions except 175.Cm n , 176the converted value is padded on the left with zeros rather than blanks. 177If a precision is given with a numeric conversion 178.Cm ( d , i , o , u , i , x , 179and 180.Cm X ) , 181the 182.Cm 0 183flag is ignored. 184.It Sq Cm \- 185A negative field width flag; 186the converted value is to be left adjusted on the field boundary. 187Except for 188.Cm n 189conversions, the converted value is padded on the right with blanks, 190rather than on the left with blanks or zeros. 191A 192.Cm \- 193overrides a 194.Cm 0 195if both are given. 196.It So "\ " Sc (space) 197A blank should be left before a positive number 198produced by a signed conversion 199.Cm ( a , A , d , e , E , f , F , g , G , 200or 201.Cm i ) . 202.It Sq Cm + 203A sign must always be placed before a 204number produced by a signed conversion. 205A 206.Cm + 207overrides a space if both are used. 208.It Sq Cm ' 209Decimal conversions 210.Cm ( d , u , 211or 212.Cm i ) 213or the integral portion of a floating point conversion 214.Cm ( f 215or 216.Cm F ) 217should be grouped and separated by thousands using 218the non-monetary separator returned by 219.Xr localeconv 3 . 220.El 221.It 222An optional decimal digit string specifying a minimum field width. 223If the converted value has fewer characters than the field width, it will 224be padded with spaces on the left (or right, if the left-adjustment 225flag has been given) to fill out 226the field width. 227.It 228An optional precision, in the form of a period 229.Cm \&. 230followed by an 231optional digit string. 232If the digit string is omitted, the precision is taken as zero. 233This gives the minimum number of digits to appear for 234.Cm d , i , o , u , x , 235and 236.Cm X 237conversions, the number of digits to appear after the decimal-point for 238.Cm a , A , e , E , f , 239and 240.Cm F 241conversions, the maximum number of significant digits for 242.Cm g 243and 244.Cm G 245conversions, or the maximum number of characters to be printed from a 246string for 247.Cm s 248conversions. 249.It 250An optional length modifier, that specifies the size of the argument. 251The following length modifiers are valid for the 252.Cm d , i , n , o , u , x , 253or 254.Cm X 255conversion: 256.Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *" 257.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n 258.It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *" 259.It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *" 260.It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *" 261.It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *" 262.It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *" 263.It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *" 264.It Cm z Ta (see note) Ta Vt size_t Ta (see note) 265.It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *" 266.El 267.Pp 268Note: 269the 270.Cm t 271modifier, when applied to a 272.Cm o , u , x , 273or 274.Cm X 275conversion, indicates that the argument is of an unsigned type 276equivalent in size to a 277.Vt ptrdiff_t . 278The 279.Cm z 280modifier, when applied to a 281.Cm d 282or 283.Cm i 284conversion, indicates that the argument is of a signed type equivalent in 285size to a 286.Vt size_t . 287Similarly, when applied to an 288.Cm n 289conversion, it indicates that the argument is a pointer to a signed type 290equivalent in size to a 291.Vt size_t . 292.Pp 293The following length modifier is valid for the 294.Cm a , A , e , E , f , F , g , 295or 296.Cm G 297conversion: 298.Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G" 299.It Sy Modifier Ta Cm a , A , e , E , f , F , g , G 300.It Cm L Ta Vt "long double" 301.El 302.Pp 303The following length modifier is valid for the 304.Cm c 305or 306.Cm s 307conversion: 308.Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *" 309.It Sy Modifier Ta Cm c Ta Cm s 310.It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *" 311.El 312.It 313A character that specifies the type of conversion to be applied. 314.El 315.Pp 316A field width or precision, or both, may be indicated by 317an asterisk 318.Ql * 319or an asterisk followed by one or more decimal digits and a 320.Ql $ 321instead of a 322digit string. 323In this case, an 324.Vt int 325argument supplies the field width or precision. 326A negative field width is treated as a left adjustment flag followed by a 327positive field width; a negative precision is treated as though it were 328missing. 329If a single format directive mixes positional 330.Pq Li nn$ 331and non-positional arguments, the results are undefined. 332.Pp 333The conversion specifiers and their meanings are: 334.Bl -tag -width ".Cm diouxX" 335.It Cm diouxX 336The 337.Vt int 338(or appropriate variant) argument is converted to signed decimal 339.Cm ( d 340and 341.Cm i ) , 342unsigned octal 343.Pq Cm o , 344unsigned decimal 345.Pq Cm u , 346or unsigned hexadecimal 347.Cm ( x 348and 349.Cm X ) 350notation. 351The letters 352.Dq Li abcdef 353are used for 354.Cm x 355conversions; the letters 356.Dq Li ABCDEF 357are used for 358.Cm X 359conversions. 360The precision, if any, gives the minimum number of digits that must 361appear; if the converted value requires fewer digits, it is padded on 362the left with zeros. 363.It Cm DOU 364The 365.Vt "long int" 366argument is converted to signed decimal, unsigned octal, or unsigned 367decimal, as if the format had been 368.Cm ld , lo , 369or 370.Cm lu 371respectively. 372These conversion characters are deprecated, and will eventually disappear. 373.It Cm eE 374The 375.Vt double 376argument is rounded and converted in the style 377.Sm off 378.Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd 379.Sm on 380where there is one digit before the 381decimal-point character 382and the number of digits after it is equal to the precision; 383if the precision is missing, 384it is taken as 6; if the precision is 385zero, no decimal-point character appears. 386An 387.Cm E 388conversion uses the letter 389.Ql E 390(rather than 391.Ql e ) 392to introduce the exponent. 393The exponent always contains at least two digits; if the value is zero, 394the exponent is 00. 395.Pp 396For 397.Cm a , A , e , E , f , F , g , 398and 399.Cm G 400conversions, positive and negative infinity are represented as 401.Li inf 402and 403.Li -inf 404respectively when using the lowercase conversion character, and 405.Li INF 406and 407.Li -INF 408respectively when using the uppercase conversion character. 409Similarly, NaN is represented as 410.Li nan 411when using the lowercase conversion, and 412.Li NAN 413when using the uppercase conversion. 414.It Cm fF 415The 416.Vt double 417argument is rounded and converted to decimal notation in the style 418.Sm off 419.Oo \- Oc Ar ddd Li \&. Ar ddd , 420.Sm on 421where the number of digits after the decimal-point character 422is equal to the precision specification. 423If the precision is missing, it is taken as 6; if the precision is 424explicitly zero, no decimal-point character appears. 425If a decimal point appears, at least one digit appears before it. 426.It Cm gG 427The 428.Vt double 429argument is converted in style 430.Cm f 431or 432.Cm e 433(or 434.Cm F 435or 436.Cm E 437for 438.Cm G 439conversions). 440The precision specifies the number of significant digits. 441If the precision is missing, 6 digits are given; if the precision is zero, 442it is treated as 1. 443Style 444.Cm e 445is used if the exponent from its conversion is less than \-4 or greater than 446or equal to the precision. 447Trailing zeros are removed from the fractional part of the result; a 448decimal point appears only if it is followed by at least one digit. 449.It Cm aA 450The 451.Vt double 452argument is converted to hexadecimal notation in the style 453.Sm off 454.Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d , 455.Sm on 456where the number of digits after the hexadecimal-point character 457is equal to the precision specification. 458If the precision is missing, it is taken as enough to exactly 459represent the floating-point number; if the precision is 460explicitly zero, no hexadecimal-point character appears. 461This is an exact conversion of the mantissa+exponent internal 462floating point representation; the 463.Sm off 464.Oo \- Oc Li 0x Ar h Li \&. Ar hhh 465.Sm on 466portion represents exactly the mantissa; only denormalized 467mantissas have a zero value to the left of the hexadecimal 468point. 469The 470.Cm p 471is a literal character 472.Ql p ; 473the exponent is preceded by a positive or negative sign 474and is represented in decimal, using only enough characters 475to represent the exponent. 476The 477.Cm A 478conversion uses the prefix 479.Dq Li 0X 480(rather than 481.Dq Li 0x ) , 482the letters 483.Dq Li ABCDEF 484(rather than 485.Dq Li abcdef ) 486to represent the hex digits, and the letter 487.Ql P 488(rather than 489.Ql p ) 490to separate the mantissa and exponent. 491.It Cm C 492Treated as 493.Cm c 494with the 495.Cm l 496(ell) modifier. 497.It Cm c 498The 499.Vt int 500argument is converted to an 501.Vt "unsigned char" , 502then to a 503.Vt wchar_t 504as if by 505.Xr btowc 3 , 506and the resulting character is written. 507.Pp 508If the 509.Cm l 510(ell) modifier is used, the 511.Vt wint_t 512argument is converted to a 513.Vt wchar_t 514and written. 515.It Cm S 516Treated as 517.Cm s 518with the 519.Cm l 520(ell) modifier. 521.It Cm s 522The 523.Vt "char *" 524argument is expected to be a pointer to an array of character type (pointer 525to a string) containing a multibyte sequence. 526Characters from the array are converted to wide characters and written up to 527(but not including) 528a terminating 529.Dv NUL 530character; 531if a precision is specified, no more than the number specified are 532written. 533If a precision is given, no null character 534need be present; if the precision is not specified, or is greater than 535the size of the array, the array must contain a terminating 536.Dv NUL 537character. 538.Pp 539If the 540.Cm l 541(ell) modifier is used, the 542.Vt "wchar_t *" 543argument is expected to be a pointer to an array of wide characters 544(pointer to a wide string). 545Each wide character in the string 546is written. 547Wide characters from the array are written up to (but not including) 548a terminating wide 549.Dv NUL 550character; 551if a precision is specified, no more than the number specified are 552written (including shift sequences). 553If a precision is given, no null character 554need be present; if the precision is not specified, or is greater than 555the number of characters in 556the string, the array must contain a terminating wide 557.Dv NUL 558character. 559.It Cm p 560The 561.Vt "void *" 562pointer argument is printed in hexadecimal (as if by 563.Ql %#x 564or 565.Ql %#lx ) . 566.It Cm n 567The number of characters written so far is stored into the 568integer indicated by the 569.Vt "int *" 570(or variant) pointer argument. 571No argument is converted. 572.It Cm % 573A 574.Ql % 575is written. 576No argument is converted. 577The complete conversion specification 578is 579.Ql %% . 580.El 581.Pp 582The decimal point 583character is defined in the program's locale (category 584.Dv LC_NUMERIC ) . 585.Pp 586In no case does a non-existent or small field width cause truncation of 587a numeric field; if the result of a conversion is wider than the field 588width, the 589field is expanded to contain the conversion result. 590.Sh SEE ALSO 591.Xr btowc 3 , 592.Xr fputws 3 , 593.Xr printf 3 , 594.Xr putwc 3 , 595.Xr setlocale 3 , 596.Xr wcsrtombs 3 , 597.Xr wscanf 3 598.Sh STANDARDS 599Subject to the caveats noted in the 600.Sx BUGS 601section 602of 603.Xr printf 3 , 604the 605.Fn wprintf , 606.Fn fwprintf , 607.Fn swprintf , 608.Fn vwprintf , 609.Fn vfwprintf 610and 611.Fn vswprintf 612functions 613conform to 614.St -isoC-99 . 615.Sh SECURITY CONSIDERATIONS 616Refer to 617.Xr printf 3 . 618