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