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