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