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