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