lib/libc/stdio/wprintf.3

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