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