mirror of https://github.com/mkerrisk/man-pages
611 lines
24 KiB
Plaintext
611 lines
24 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "FWPRINTF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" fwprintf
|
|
.SH NAME
|
|
fwprintf, swprintf, wprintf \- print formatted wide-character output
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <stdio.h>
|
|
.br
|
|
#include <wchar.h>
|
|
.br
|
|
.sp
|
|
int fwprintf(FILE *restrict\fP \fIstream\fP\fB, const wchar_t *restrict\fP
|
|
\fIformat\fP\fB, ...);
|
|
.br
|
|
int swprintf(wchar_t *restrict\fP \fIws\fP\fB, size_t\fP \fIn\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ const wchar_t *restrict\fP \fIformat\fP\fB, ...);
|
|
.br
|
|
int wprintf(const wchar_t *restrict\fP \fIformat\fP\fB, ...);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIfwprintf\fP() function shall place output on the named output
|
|
\fIstream\fP. The \fIwprintf\fP() function shall place
|
|
output on the standard output stream \fIstdout\fP. The \fIswprintf\fP()
|
|
function shall place output followed by the null wide
|
|
character in consecutive wide characters starting at *\fIws\fP; no
|
|
more than \fIn\fP wide characters shall be written, including
|
|
a terminating null wide character, which is always added (unless \fIn\fP
|
|
is zero).
|
|
.LP
|
|
Each of these functions shall convert, format, and print its arguments
|
|
under control of the \fIformat\fP wide-character string.
|
|
The \fIformat\fP is composed of zero or more directives: \fIordinary
|
|
wide-characters\fP, which are simply copied to the output
|
|
stream, and \fIconversion specifications\fP, each of which results
|
|
in the fetching of zero or more arguments. The results are
|
|
undefined if there are insufficient arguments for the \fIformat\fP.
|
|
If the \fIformat\fP is exhausted while arguments remain, the
|
|
excess arguments are evaluated but are otherwise ignored.
|
|
.LP
|
|
Conversions can be applied to the \fIn\fPth argument after the \fIformat\fP
|
|
in the argument list, rather than to the next unused
|
|
argument. In this case, the conversion specifier wide character \fB%\fP
|
|
(see below) is replaced by the sequence \fB"%n$"\fP ,
|
|
where \fIn\fP is a decimal integer in the range [1,{NL_ARGMAX}], giving
|
|
the position of the argument in the argument list. This
|
|
feature provides for the definition of \fIformat\fP wide-character
|
|
strings that select arguments in an order appropriate to
|
|
specific languages (see the EXAMPLES section).
|
|
.LP
|
|
The \fIformat\fP can contain either numbered argument specifications
|
|
(that is, \fB"%\fP\fIn\fP\fB$"\fP and
|
|
\fB"*\fP\fIm\fP\fB$"\fP), or unnumbered argument conversion specifications
|
|
(that is, \fB%\fP and \fB*\fP ), but not
|
|
both. The only exception to this is that \fB%%\fP can be mixed with
|
|
the \fB"%\fP\fIn\fP\fB$"\fP form. The results of
|
|
mixing numbered and unnumbered argument specifications in a \fIformat\fP
|
|
wide-character string are undefined. When numbered
|
|
argument specifications are used, specifying the \fIN\fPth argument
|
|
requires that all the leading arguments, from the first to the
|
|
(\fIN\fP-1)th, are specified in the \fIformat\fP wide-character string.
|
|
.LP
|
|
In \fIformat\fP wide-character strings containing the \fB"%\fP\fIn\fP\fB$"\fP
|
|
form of conversion specification, numbered
|
|
arguments in the argument list can be referenced from the \fIformat\fP
|
|
wide-character string as many times as required.
|
|
.LP
|
|
In \fIformat\fP wide-character strings containing the \fB%\fP form
|
|
of conversion specification, each argument in the
|
|
argument list shall be used exactly once.
|
|
.LP
|
|
All
|
|
forms of the \fIfwprintf\fP() function allow for the insertion of
|
|
a locale-dependent radix character in the output string, output
|
|
as a wide-character value. The radix character is defined in the program's
|
|
locale (category \fILC_NUMERIC ).\fP In the POSIX
|
|
locale, or in a locale where the radix character is not defined, the
|
|
radix character shall default to a period ( \fB'.'\fP ).
|
|
.LP
|
|
Each conversion specification is introduced by the \fB'%'\fP wide
|
|
character \ or by the
|
|
wide-character sequence \fB"%\fP\fIn\fP\fB$"\fP, \ after
|
|
which the following appear in sequence:
|
|
.IP " *" 3
|
|
Zero or more \fIflags\fP (in any order), which modify the meaning
|
|
of the conversion specification.
|
|
.LP
|
|
.IP " *" 3
|
|
An optional minimum \fIfield width\fP. If the converted value has
|
|
fewer wide characters than the field width, it shall be
|
|
padded with spaces by default on the left; it shall be padded on the
|
|
right, if the left-adjustment flag ( \fB'-'\fP ), described
|
|
below, is given to the field width. The field width takes the form
|
|
of an asterisk ( \fB'*'\fP ), described below, or a decimal
|
|
integer.
|
|
.LP
|
|
.IP " *" 3
|
|
An optional \fIprecision\fP that gives the minimum number of digits
|
|
to appear for the \fBd\fP , \fBi\fP , \fBo\fP ,
|
|
\fBu\fP , \fBx\fP , and \fBX\fP conversion specifiers; the number
|
|
of digits to appear after the radix character for the
|
|
\fBa\fP , \fBA\fP , \fBe\fP , \fBE\fP , \fBf\fP , and \fBF\fP conversion
|
|
specifiers; the maximum number of
|
|
significant digits for the \fBg\fP and \fBG\fP conversion specifiers;
|
|
or the maximum number of wide characters to be printed
|
|
from a string in the \fBs\fP conversion specifiers. The precision
|
|
takes the form of a period ( \fB'.'\fP ) followed either by
|
|
an asterisk ( \fB'*'\fP ), described below, or an optional decimal
|
|
digit string, where a null digit string is treated as 0. If a
|
|
precision appears with any other conversion wide character, the behavior
|
|
is undefined.
|
|
.LP
|
|
.IP " *" 3
|
|
An optional length modifier that specifies the size of the argument.
|
|
.LP
|
|
.IP " *" 3
|
|
A \fIconversion specifier\fP wide character that indicates the type
|
|
of conversion to be applied.
|
|
.LP
|
|
.LP
|
|
A field width, or precision, or both, may be indicated by an asterisk
|
|
( \fB'*'\fP ). In this case an argument of type
|
|
\fBint\fP supplies the field width or precision. Applications shall
|
|
ensure that arguments specifying field width, or precision, or
|
|
both appear in that order before the argument, if any, to be converted.
|
|
A negative field width is taken as a \fB'-'\fP flag
|
|
followed by a positive field width. A negative precision is taken
|
|
as if the precision were omitted. \ In
|
|
\fIformat\fP wide-character strings containing the \fB"%\fP\fIn\fP\fB$"\fP
|
|
form of a conversion specification, a field
|
|
width or precision may be indicated by the sequence \fB"*\fP\fIm\fP\fB$"\fP,
|
|
where \fIm\fP is a decimal integer in the
|
|
range [1,{NL_ARGMAX}] giving the position in the argument list (after
|
|
the \fIformat\fP argument) of an integer argument containing
|
|
the field width or precision, for example:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBwprintf(L"%1$d:%2$.*3$d:%4$.*3$d\\n", hour, min, precision, sec);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The flag wide characters and their meanings are:
|
|
.TP 7
|
|
\fB'\fP
|
|
The integer portion of the result of a decimal conversion ( \fB%i\fP
|
|
, \fB%d\fP , \fB%u\fP , \fB%f\fP , \fB%F\fP ,
|
|
\fB%g\fP , or \fB%G\fP ) shall be formatted with thousands' grouping
|
|
wide characters. For other conversions, the behavior is
|
|
undefined. The numeric grouping wide character is used.
|
|
.TP 7
|
|
\fB-\fP
|
|
The result of the conversion shall be left-justified within the field.
|
|
The conversion shall be right-justified if this flag is
|
|
not specified.
|
|
.TP 7
|
|
\fB+\fP
|
|
The result of a signed conversion shall always begin with a sign (
|
|
\fB'+'\fP or \fB'-'\fP ). The conversion shall begin
|
|
with a sign only when a negative value is converted if this flag is
|
|
not specified.
|
|
.TP 7
|
|
<space>
|
|
If the first wide character of a signed conversion is not a sign,
|
|
or if a signed conversion results in no wide characters, a
|
|
<space> shall be prefixed to the result. This means that if the <space>
|
|
and \fB'+'\fP flags both appear, the
|
|
<space> flag shall be ignored.
|
|
.TP 7
|
|
\fB#\fP
|
|
Specifies that the value is to be converted to an alternative form.
|
|
For \fBo\fP conversion, it increases the precision (if
|
|
necessary) to force the first digit of the result to be 0. For \fBx\fP
|
|
or \fBX\fP conversion specifiers, a non-zero result
|
|
shall have 0x (or 0X) prefixed to it. For \fBa\fP , \fBA\fP , \fBe\fP
|
|
, \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP
|
|
, and \fBG\fP conversion specifiers, the result shall always contain
|
|
a radix character, even if no digits follow it. Without
|
|
this flag, a radix character appears in the result of these conversions
|
|
only if a digit follows it. For \fBg\fP and \fBG\fP
|
|
conversion specifiers, trailing zeros shall \fInot\fP be removed from
|
|
the result as they normally are. For other conversion
|
|
specifiers, the behavior is undefined.
|
|
.TP 7
|
|
\fB0\fP
|
|
For \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , \fBx\fP , \fBX\fP , \fBa\fP
|
|
, \fBA\fP , \fBe\fP ,
|
|
\fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , and \fBG\fP conversion specifiers,
|
|
leading zeros (following any indication
|
|
of sign or base) are used to pad to the field width; no space padding
|
|
is performed. If the \fB'0'\fP and \fB'-'\fP flags both
|
|
appear, the \fB'0'\fP flag shall be ignored. For \fBd\fP , \fBi\fP
|
|
, \fBo\fP , \fBu\fP , \fBx\fP , and \fBX\fP
|
|
conversion specifiers, if a precision is specified, the \fB'0'\fP
|
|
flag shall be ignored. If the \fB'0'\fP and \fB'"\fP
|
|
flags both appear, the grouping wide characters are inserted before
|
|
zero padding. For other conversions, the behavior is
|
|
undefined.
|
|
.sp
|
|
.LP
|
|
The length modifiers and their meanings are:
|
|
.TP 7
|
|
\fBhh\fP
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
\fBx\fP , or \fBX\fP conversion specifier
|
|
applies to a \fBsigned char\fP or \fBunsigned char\fP argument (the
|
|
argument will have been promoted according to the integer
|
|
promotions, but its value shall be converted to \fBsigned char\fP
|
|
or \fBunsigned char\fP before printing); or that a following
|
|
\fBn\fP conversion specifier applies to a pointer to a \fBsigned char\fP
|
|
argument.
|
|
.TP 7
|
|
\fBh\fP
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
\fBx\fP , or \fBX\fP conversion specifier
|
|
applies to a \fBshort\fP or \fBunsigned short\fP argument (the argument
|
|
will have been promoted according to the integer
|
|
promotions, but its value shall be converted to \fBshort\fP or \fBunsigned
|
|
short\fP before printing); or that a following
|
|
\fBn\fP conversion specifier applies to a pointer to a \fBshort\fP
|
|
argument.
|
|
.TP 7
|
|
\fBl\fP\ (ell)
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
\fBx\fP , or \fBX\fP conversion specifier
|
|
applies to a \fBlong\fP or \fBunsigned long\fP argument; that a following
|
|
\fBn\fP conversion specifier applies to a pointer to
|
|
a \fBlong\fP argument; that a following \fBc\fP conversion specifier
|
|
applies to a \fBwint_t\fP argument; that a following
|
|
\fBs\fP conversion specifier applies to a pointer to a \fBwchar_t\fP
|
|
argument; or has no effect on a following \fBa\fP ,
|
|
\fBA\fP , \fBe\fP , \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , or \fBG\fP
|
|
conversion specifier.
|
|
.TP 7
|
|
\fBll\fP\ (ell-ell)
|
|
.sp
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
\fBx\fP , or \fBX\fP conversion specifier
|
|
applies to a \fBlong long\fP or \fBunsigned long long\fP argument;
|
|
or that a following \fBn\fP conversion specifier applies to
|
|
a pointer to a \fBlong long\fP argument.
|
|
.TP 7
|
|
\fBj\fP
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
\fBx\fP , or \fBX\fP conversion specifier
|
|
applies to an \fBintmax_t\fP or \fBuintmax_t\fP argument; or that
|
|
a following \fBn\fP conversion specifier applies to a
|
|
pointer to an \fBintmax_t\fP argument.
|
|
.TP 7
|
|
\fBz\fP
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
\fBx\fP , or \fBX\fP conversion specifier
|
|
applies to a \fBsize_t\fP or the corresponding signed integer type
|
|
argument; or that a following \fBn\fP conversion specifier
|
|
applies to a pointer to a signed integer type corresponding to a \fBsize_t\fP
|
|
argument.
|
|
.TP 7
|
|
\fBt\fP
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
\fBx\fP , or \fBX\fP conversion specifier
|
|
applies to a \fBptrdiff_t\fP or the corresponding \fBunsigned\fP type
|
|
argument; or that a following \fBn\fP conversion
|
|
specifier applies to a pointer to a \fBptrdiff_t\fP argument.
|
|
.TP 7
|
|
\fBL\fP
|
|
Specifies that a following \fBa\fP , \fBA\fP , \fBe\fP , \fBE\fP ,
|
|
\fBf\fP , \fBF\fP , \fBg\fP , or
|
|
\fBG\fP conversion specifier applies to a \fBlong double\fP argument.
|
|
.sp
|
|
.LP
|
|
If a length modifier appears with any conversion specifier other than
|
|
as specified above, the behavior is undefined.
|
|
.LP
|
|
The conversion specifiers and their meanings are:
|
|
.TP 7
|
|
\fBd\fP,\ \fBi\fP
|
|
The \fBint\fP argument shall be converted to a signed decimal in the
|
|
style \fB"[-]\fP\fIdddd"\fP. The precision specifies
|
|
the minimum number of digits to appear; if the value being converted
|
|
can be represented in fewer digits, it shall be expanded with
|
|
leading zeros. The default precision shall be 1. The result of converting
|
|
zero with an explicit precision of zero shall be no wide
|
|
characters.
|
|
.TP 7
|
|
\fBo\fP
|
|
The \fBunsigned\fP argument shall be converted to unsigned octal format
|
|
in the style \fB"dddd"\fP . The precision specifies
|
|
the minimum number of digits to appear; if the value being converted
|
|
can be represented in fewer digits, it shall be expanded with
|
|
leading zeros. The default precision shall be 1. The result of converting
|
|
zero with an explicit precision of zero shall be no wide
|
|
characters.
|
|
.TP 7
|
|
\fBu\fP
|
|
The \fBunsigned\fP argument shall be converted to unsigned decimal
|
|
format in the style \fB"dddd"\fP . The precision
|
|
specifies the minimum number of digits to appear; if the value being
|
|
converted can be represented in fewer digits, it shall be
|
|
expanded with leading zeros. The default precision shall be 1. The
|
|
result of converting zero with an explicit precision of zero
|
|
shall be no wide characters.
|
|
.TP 7
|
|
\fBx\fP
|
|
The \fBunsigned\fP argument shall be converted to unsigned hexadecimal
|
|
format in the style \fB"dddd"\fP ; the letters
|
|
\fB"abcdef"\fP are used. The precision specifies the minimum number
|
|
of digits to appear; if the value being converted can be
|
|
represented in fewer digits, it shall be expanded with leading zeros.
|
|
The default precision shall be 1. The result of converting
|
|
zero with an explicit precision of zero shall be no wide characters.
|
|
.TP 7
|
|
\fBX\fP
|
|
Equivalent to the \fBx\fP conversion specifier, except that letters
|
|
\fB"ABCDEF"\fP are used instead of \fB"abcdef"\fP
|
|
\&.
|
|
.TP 7
|
|
\fBf\fP,\ \fBF\fP
|
|
The \fBdouble\fP argument shall be converted to decimal notation in
|
|
the style \fB"[-]\fP\fIddd.ddd"\fP, where the number
|
|
of digits after the radix character shall be equal to the precision
|
|
specification. If the precision is missing, it shall be taken
|
|
as 6; if the precision is explicitly zero and no \fB'#'\fP flag is
|
|
present, no radix character shall appear. If a radix
|
|
character appears, at least one digit shall appear before it. The
|
|
value shall be rounded in an implementation-defined manner to the
|
|
appropriate number of digits.
|
|
.LP
|
|
A \fBdouble\fP argument representing an infinity shall be converted
|
|
in one of the styles \fB"[-]inf"\fP or
|
|
\fB"[-]infinity"\fP ; which style is implementation-defined. A \fBdouble\fP
|
|
argument representing a NaN shall be converted in
|
|
one of the styles \fB"[-]nan"\fP or \fB"[-]nan(\fP\fIn-char-sequence\fP\fB)"\fP;
|
|
which style, and the meaning of any
|
|
\fIn-char-sequence\fP, is implementation-defined. The \fBF\fP conversion
|
|
specifier produces \fB"INF"\fP ,
|
|
\fB"INFINITY"\fP , or \fB"NAN"\fP instead of \fB"inf"\fP , \fB"infinity"\fP
|
|
, or \fB"nan"\fP , respectively.
|
|
.TP 7
|
|
\fBe\fP,\ \fBE\fP
|
|
The \fBdouble\fP argument shall be converted in the style \fB"[-]\fP\fId.ddd\fPe\fB\(+-dd"\fP,
|
|
where there shall be
|
|
one digit before the radix character (which is non-zero if the argument
|
|
is non-zero) and the number of digits after it shall be
|
|
equal to the precision; if the precision is missing, it shall be taken
|
|
as 6; if the precision is zero and no \fB'#'\fP flag is
|
|
present, no radix character shall appear. The value shall be rounded
|
|
in an implementation-defined manner to the appropriate number
|
|
of digits. The \fBE\fP conversion wide character shall produce a number
|
|
with \fB'E'\fP instead of \fB'e'\fP introducing
|
|
the exponent. The exponent shall always contain at least two digits.
|
|
If the value is zero, the exponent shall be zero.
|
|
.LP
|
|
A \fBdouble\fP argument representing an infinity or NaN shall be converted
|
|
in the style of an \fBf\fP or \fBF\fP
|
|
conversion specifier.
|
|
.TP 7
|
|
\fBg\fP,\ \fBG\fP
|
|
The \fBdouble\fP argument shall be converted in the style \fBf\fP
|
|
or \fBe\fP (or in the style \fBF\fP or \fBE\fP
|
|
in the case of a \fBG\fP conversion specifier), with the precision
|
|
specifying the number of significant digits. If an explicit
|
|
precision is zero, it shall be taken as 1. The style used depends
|
|
on the value converted; style \fBe\fP (or \fBE\fP ) shall
|
|
be used only if the exponent resulting from such a conversion is less
|
|
than -4 or greater than or equal to the precision. Trailing
|
|
zeros shall be removed from the fractional portion of the result;
|
|
a radix character shall appear only if it is followed by a digit.
|
|
.LP
|
|
A \fBdouble\fP argument representing an infinity or NaN shall be converted
|
|
in the style of an \fBf\fP or \fBF\fP
|
|
conversion specifier.
|
|
.TP 7
|
|
\fBa\fP,\ \fBA\fP
|
|
A \fBdouble\fP argument representing a floating-point number shall
|
|
be converted in the style \fB"[-]0xh.hhhhp\(+-d"\fP,
|
|
where there shall be one hexadecimal digit (which is non-zero if the
|
|
argument is a normalized floating-point number and is
|
|
otherwise unspecified) before the decimal-point wide character and
|
|
the number of hexadecimal digits after it shall be equal to the
|
|
precision; if the precision is missing and FLT_RADIX is a power of
|
|
2, then the precision shall be sufficient for an exact
|
|
representation of the value; if the precision is missing and FLT_RADIX
|
|
is not a power of 2, then the precision shall be sufficient
|
|
to distinguish values of type \fBdouble\fP, except that trailing zeros
|
|
may be omitted; if the precision is zero and the
|
|
\fB'#'\fP flag is not specified, no decimal-point wide character shall
|
|
appear. The letters \fB"abcdef"\fP are used for
|
|
\fBa\fP conversion and the letters \fB"ABCDEF"\fP for \fBA\fP conversion.
|
|
The \fBA\fP conversion specifier produces a
|
|
number with \fB'X'\fP and \fB'P'\fP instead of \fB'x'\fP and \fB'p'\fP
|
|
\&. The exponent shall always contain at least one
|
|
digit, and only as many more digits as necessary to represent the
|
|
decimal exponent of 2. If the value is zero, the exponent shall
|
|
be zero.
|
|
.LP
|
|
A \fBdouble\fP argument representing an infinity or NaN shall be converted
|
|
in the style of an \fBf\fP or \fBF\fP
|
|
conversion specifier.
|
|
.TP 7
|
|
\fBc\fP
|
|
If no \fBl\fP (ell) qualifier is present, the \fBint\fP argument shall
|
|
be converted to a wide character as if by calling
|
|
the \fIbtowc\fP() function and the resulting wide character shall
|
|
be written. Otherwise, the
|
|
\fBwint_t\fP argument shall be converted to \fBwchar_t\fP, and written.
|
|
.TP 7
|
|
\fBs\fP
|
|
If no \fBl\fP (ell) qualifier is present, the application shall ensure
|
|
that the argument is a pointer to a character array
|
|
containing a character sequence beginning in the initial shift state.
|
|
Characters from the array shall be converted as if by
|
|
repeated calls to the \fImbrtowc\fP() function, with the conversion
|
|
state described by an
|
|
\fBmbstate_t\fP object initialized to zero before the first character
|
|
is converted, and written up to (but not including) the
|
|
terminating null wide character. If the precision is specified, no
|
|
more than that many wide characters shall be written. If the
|
|
precision is not specified, or is greater than the size of the array,
|
|
the application shall ensure that the array contains a null
|
|
wide character.
|
|
.LP
|
|
If an \fBl\fP (ell) qualifier is present, the application shall ensure
|
|
that the argument is a pointer to an array of type
|
|
\fBwchar_t\fP. Wide characters from the array shall be written up
|
|
to (but not including) a terminating null wide character. If no
|
|
precision is specified, or is greater than the size of the array,
|
|
the application shall ensure that the array contains a null wide
|
|
character. If a precision is specified, no more than that many wide
|
|
characters shall be written.
|
|
.TP 7
|
|
\fBp\fP
|
|
The application shall ensure that the argument is a pointer to \fBvoid\fP.
|
|
The value of the pointer shall be converted to a
|
|
sequence of printable wide characters in an implementation-defined
|
|
manner.
|
|
.TP 7
|
|
\fBn\fP
|
|
The application shall ensure that the argument is a pointer to an
|
|
integer into which is written the number of wide characters
|
|
written to the output so far by this call to one of the \fIfwprintf\fP()
|
|
functions. No argument shall be converted, but one shall
|
|
be consumed. If the conversion specification includes any flags, a
|
|
field width, or a precision, the behavior is undefined.
|
|
.TP 7
|
|
\fBC\fP
|
|
Equivalent to \fBlc\fP .
|
|
.TP 7
|
|
\fBS\fP
|
|
Equivalent to \fBls\fP .
|
|
.TP 7
|
|
\fB%\fP
|
|
Output a \fB'%'\fP wide character; no argument shall be converted.
|
|
The entire conversion specification shall be \fB%%\fP
|
|
\&.
|
|
.sp
|
|
.LP
|
|
If a conversion specification does not match one of the above forms,
|
|
the behavior is undefined.
|
|
.LP
|
|
In no case does a nonexistent or small field width cause truncation
|
|
of a field; if the result of a conversion is wider than the
|
|
field width, the field shall be expanded to contain the conversion
|
|
result. Characters generated by \fIfwprintf\fP() and
|
|
\fIwprintf\fP() shall be printed as if \fIfputwc\fP() had been called.
|
|
.LP
|
|
For \fBa\fP and \fBA\fP conversions, if FLT_RADIX is not a power of
|
|
2 and the result is not exactly representable in the
|
|
given precision, the result should be one of the two adjacent numbers
|
|
in hexadecimal floating style with the given precision, with
|
|
the extra stipulation that the error should have a correct sign for
|
|
the current rounding direction.
|
|
.LP
|
|
For \fBe\fP , \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , and \fBG\fP
|
|
conversion specifiers, if the number of
|
|
significant decimal digits is at most DECIMAL_DIG, then the result
|
|
should be correctly rounded. If the number of significant
|
|
decimal digits is more than DECIMAL_DIG but the source value is exactly
|
|
representable with DECIMAL_DIG digits, then the result
|
|
should be an exact representation with trailing zeros. Otherwise,
|
|
the source value is bounded by two adjacent decimal strings
|
|
\fIL\fP < \fIU\fP, both having DECIMAL_DIG significant digits; the
|
|
value of the resultant decimal string \fID\fP should
|
|
satisfy \fIL\fP <= \fID\fP <= \fIU\fP, with the extra stipulation
|
|
that the error should have a correct sign for the
|
|
current rounding direction.
|
|
.LP
|
|
The
|
|
\fIst_ctime\fP and \fIst_mtime\fP fields of the file shall be marked
|
|
for update between the call to a successful execution of
|
|
\fIfwprintf\fP() or \fIwprintf\fP() and the next successful completion
|
|
of a call to \fIfflush\fP() or \fIfclose\fP() on the same stream,
|
|
or a
|
|
call to \fIexit\fP() or \fIabort\fP().
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, these functions shall return the number
|
|
of wide characters transmitted, excluding the terminating
|
|
null wide character in the case of \fIswprintf\fP(), or a negative
|
|
value if an output error was encountered, \ and set
|
|
\fIerrno\fP to indicate the error.
|
|
.LP
|
|
If \fIn\fP or more wide characters were requested to be written, \fIswprintf\fP()
|
|
shall return a negative value, \ and set
|
|
\fIerrno\fP to indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
For the conditions under which \fIfwprintf\fP() and \fIwprintf\fP()
|
|
fail and may fail, refer to \fIfputwc\fP() .
|
|
.LP
|
|
In addition, all forms of \fIfwprintf\fP() may fail if:
|
|
.TP 7
|
|
.B EILSEQ
|
|
A wide-character code that does not correspond to a valid character
|
|
has been detected.
|
|
.TP 7
|
|
.B EINVAL
|
|
There are insufficient arguments.
|
|
.sp
|
|
.LP
|
|
In addition, \fIwprintf\fP() and \fIfwprintf\fP() may fail if:
|
|
.TP 7
|
|
.B ENOMEM
|
|
Insufficient storage space is available.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
To print the language-independent date and time format, the following
|
|
statement could be used:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBwprintf(format, weekday, month, day, hour, min);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
For American usage, \fIformat\fP could be a pointer to the wide-character
|
|
string:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBL"%s, %s %d, %d:%.2d\\n"
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
producing the message:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBSunday, July 3, 10:02
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
whereas for German usage, \fIformat\fP could be a pointer to the wide-character
|
|
string:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBL"%1$s, %3$d. %2$s, %4$d:%5$.2d\\n"
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
producing the message:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBSonntag, 3. Juli, 10:02
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIbtowc\fP() , \fIfputwc\fP() , \fIfwscanf\fP() , \fImbrtowc\fP()
|
|
, \fIsetlocale\fP()
|
|
, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 7,
|
|
Locale, \fI<stdio.h>\fP, \fI<wchar.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|