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