lib/libc/stdio/wprintf.3

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