lib/libc/stdio/wprintf.3

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