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