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