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