wprintf, fwprintf, swprintf - Print formatted output for
wide characters
#include <wchar.h>
int wprintf(
const wchar_t *format,
[,value] ... ); #include <stdio.h> #include
<wchar.h>
int fwprintf(
FILE *stream,
const wchar_t *format,
[,value] ... ); #include <wchar.h>
int swprintf(
wchar_t *wstr,
size_t n,
const wchar_t *format,
[,value] ... );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
fwprintf(), swprintf(), wprintf(): ISO C
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies a wide-character string that combines literal
characters with conversion specifications. Specifies the
data to be converted according to the format parameter.
Points to a FILE structure specifying an open stream to
which converted values are written. Specifies a character
array in which the converted values are stored. Specifies
the maximum number of output wide characters, including
the terminating null wide character. Unless n is zero, a
terminating null wide character is always added to output.
The wprintf() function converts, formats, and writes its
value parameters, under control of the format parameter,
to the standard output stream stdout.
The fwprintf() function converts, formats, and writes its
value parameters, under control of the format parameter,
to the output stream specified by the stream parameter.
The swprintf() function converts, formats, and stores its
value parameters, under control of the format parameter,
into consecutive wide characters starting at the address
specified by the wstr parameter. The swprintf() function
places a null wide character (L'/0') at the end of the
wide-character string. Specify the n parameter to limit
the formatted wide-character string to the allotted space
for wstr.
The format parameter is a wide-character string that contains
the following types of objects: Literal characters,
which are copied to the output stream Conversion specifications,
each of which causes zero or more items to be
fetched from the value parameter list
If there are not enough items for format in the value
parameter list, the results are unpredictable. If more
value parameters remain after the entire format has been
processed, they are ignored.
Conversion Specifications [Toc] [Back]
Each conversion specification in the format parameter has
the following syntax: A % (percent sign).
The % (percent sign) is the normal conversion character.
[Tru64 UNIX] The wprintf(), fwprintf(), and
swprintf(), functions can also handle a format
string that enables the system to process elements
of the parameter list in variable order. In such a
case, the normal conversion character % (percent
sign) is replaced by %digit$, where digit is a decimal
number in the range from 1 to NL_ARGMAX. Conversion
is then applied to the specified argument,
rather than to the next unused argument. This feature
provides for the definition of format strings
in an order appropriate to specific languages. When
variable ordering is used, the * (asterisk) specification
for field width in precision is replaced
by *digit$. If the variable ordering feature is
used, it must be specified for all conversions.
Zero or more options that modify the meaning of the
conversion specification. The option characters and
their meanings are as follows: [Tru64 UNIX] Format
the integer portion of a decimal conversion (%i,
%d, %u, %f, %g, %G) with the thousands' grouping
character. The thousands' grouping character used
in the result is the one specified by the current
locale for numeric values rather than the one specified
for monetary values. The result of using the
' option with conversions other than decimal is
undefined. Left align within the field the result
of the conversion. If you do not specify this
option, the converted value is right aligned within
the field. Begin the result of a signed conversion
with a sign (+ or -). If you do not specify this
option, the converted value begins with a sign only
when the value is negative. Prefix a space to the
result if the first wide character of a signed conversion
is not a sign or if a signed conversion
results in no wide characters. If both the (space)
and + options appear, the (space) option is
ignored. Convert the value to an alternative form.
For an o conversion, the function increases the
precision to force the first digit of the result to
be a 0 (zero). For x and X conversions, a nonzero
result has 0x or 0X prefixed to it. For e, E, f, g,
and G conversions, the result always contains a
radix character, even if no digits follow it. For g
and G conversions, trailing zeros are not removed
from the result. For c, C, d, i, s, S, and u conversions,
the option has no effect. Pad to field
width by using leading zeros (following any indication
of sign or base) for d, i, o, u, x, X, e, E,
f, g, and G conversions; no space padding is performed.
If the 0 and - (dash) options both appear,
the 0 option is ignored. For d, i, o, u, x, and X
conversions, if a precision is specified, the 0
option is also ignored. For other conversions, the
behavior is undefined. An optional decimal digit
string that specifies the minimum field width. If
the converted value has fewer wide characters than
the field width, the field is padded on the left to
the length specified by the field width. If the
left-adjustment option is specified, the field is
padded on the right.
A field width can be indicated by an * (asterisk)
instead of a digit string. In this case, an integer
(int) value parameter supplies the field width. The
value parameter converted for output is not fetched
until the conversion letter is reached, so the
parameters specifying field width or precision must
appear before the value (if any) to be converted.
If the corresponding parameter has a negative
value, it is treated as a - left alignment option
followed by a positive field width.
[Tru64 UNIX] When variable ordering with the
%digit$ format is used, the * (asterisk) specification
for field width in precision is replaced by
*digit$. An optional precision. The precision is a
(dot) followed by a decimal digit string. If no
precision is given, the decimal digit string is
treated as 0 (zero). The precision specifies: The
minimum number of digits to appear for the d, u, o,
x, or X conversions. The number of digits to
appear after the radix character for the e, E, and
f conversions. The maximum number of significant
digits for the g and G conversions. The maximum
number of bytes to be printed from a string in the
s or the S conversion.
A field precision can be indicated by an * (asterisk)
instead of a digit string. In this case, an
integer (int) value parameter supplies the field
precision. The value parameter converted for output
is not fetched until the conversion letter is
reached, so the parameters specifying field width
or precision must appear before the value (if any)
to be converted. If the value of the corresponding
parameter is negative, the value is treated as if
the precision had not been specified.
[Tru64 UNIX] When variable ordering with the
%digit$ format is used, the * (asterisk) specification
for field width in precision is replaced by
*digit$. An optional h or l indicating the size of
the argument corresponding to the following integer
or floating-point conversion specifier. An h followed
by a d, i, o, u, x, or X conversion specifier
indicates that the argument will be treated as a
short int or unsigned short int. An h followed by a
n indicates that the argument will be treated as a
pointer to a short int. An l followed by a c conversion
specifier applies to a wint_t argument. An
l followed by an s conversion specifier applies to
a pointer to a wchar_t argument. An l followed by a
d, i, o, u, x, or X conversion specifier indicates
that the argument will be treated as a long int or
unsigned long int. An l followed by a n indicates
that the argument will be treated as a pointer to a
long int. One of the following wide characters to
indicate the type of conversion to be applied:
Accepts an integer (int) value and converts it to
signed decimal notation. The precision specifies
the minimum number of digits to appear. If the
value being converted can be represented in fewer
digits, it is expanded with leading zeros. The
default precision is 1. The result of converting a
0 (zero) value with a precision of 0 (zero) is a
null string. Specifying a field width with a 0
(zero) as a leading character causes the field
width value to be padded with leading zeros.
Accepts an integer (int) value and converts it to
unsigned decimal notation. The precision specifies
the minimum number of digits to appear. If the
value being converted can be represented in fewer
digits, it is expanded with leading zeros. The
default precision is 1. The result of converting a
0 (zero) value with a precision of 0 (zero) is a
null string. Specifying a field width with a 0
(zero) as a leading character causes the field
width value to be padded with leading zeros.
Accepts an integer (int) value and converts it to
unsigned octal notation. The precision specifies
the minimum number of digits to appear. If the
value being converted can be represented in fewer
digits, it is expanded with leading zeros. The
default precision is 1. The result of converting a
0 (zero) value with a precision of 0 (zero) is a
null string. Specifying a field width with a 0
(zero) as a leading character causes the field
width value to be padded with leading zeros. An
octal value for field width is not implied.
Accepts an integer (int) value and converts it to
unsigned hexadecimal notation. The letters abcdef
are used for the x conversion and the letters
ABCDEF are used for the X conversion. The precision
specifies the minimum number digits to appear. If
the value being converted can be represented in
fewer digits, it is expanded with leading zeros.
The default precision is 1. The result of converting
a 0 (zero) value with a precision of 0 (zero)
is a null string. Specifying a field width with a 0
(zero) as a leading character causes the field
width value to be padded with leading zeros.
Accepts a float or double value and converts it to
decimal notation in the format [-]ddd.ddd. The number
of digits after the radix character is equal to
the precision specification. If no precision is
specified, six digits are output. If the precision
is 0 (zero), no radix character appears (unless the
# option is specified). If a radix character is
output, at least one digit is output before it. The
value is rounded to the appropriate number of digits.
Accepts a float or double value and converts
it to the exponential form [-]d.ddde+/-dd. There is
one digit before the radix character and the number
of digits after the radix character is equal to the
precision specification. If no precision is specified,
six digits are output. If the precision is 0
(zero), no radix character appears (unless the #
option is specified). The E conversion produces a
number with E instead of e before the exponent. The
exponent always contains at least two digits. If
the value is 0 (zero), the exponent is 0 (zero).
Accepts a float or double value and converts it in
the style of the e, E, or f conversions, with the
precision specifying the number of significant digits.
If the precision is zero, it is ignored.
Trailing zeros are removed from the fractional portion
of the result. A radix character appears only
if it is followed by a digit (except that the radix
character always appears if the # option is specified).
The style used depends on the value converted.
Style e (E, if G is the option used)
results only if the exponent resulting from the
conversion is less than -4, or if the exponent is
greater than or equal to the precision. If the l
qualifier is not present, accepts and prints an
integer (int) value converted to a wide character
as if btowc() were called. If the l qualifier is
present, treats the c argument as wint_t, converts
it to a two-element wchar_t array, (the first element
being the wint_t argument and the second being
a null wide character), and prints the converted
value. [Tru64 UNIX] Accepts a wchar_t value, converts
it to an array of bytes containing a multibyte
character, and prints the character. If a minimum
field width is specified and the multibyte
character occupies fewer bytes than the specified
width, the multibyte character is padded with space
characters to the specified width. If the l qualifier
is not present, accepts a pointer to a character
array that contains a multibyte sequence beginning
in the initial shift state. Multibyte characters
are converted as if by repeated calls to mbrtowc(),
with the conversion state described by an
mbstate_t object initialized to zero before the
first multibyte 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 are written. If the
precision is not specified or is greater than the
size of the converted array, the converted array
contains a null wide character.
If the l qualifier is present, the s argument is
treated as a pointer to an array of type wchar_t.
Wide characters from the array are converted to
multibyte characters. Conversion of each wide-character
is done as if by a call to the wcrtomb()
function (with the conversion state described by an
mbstate_t object initialized to zero before the
first wide character is converted) up to (but not
including) the terminating null wide character. The
resulting bytes (including shift sequences) are
written up to (but not including) the terminating
null byte. If no precision is specified, the widecharacter
array contains a null wide character. If,
for a specified precision, the function would need
to access one wide character past the end of the
array to equal the length of a complete multibytecharacter
sequence, the array also contains a null
wide character; in other words, the function does
not output a partial multibyte character. [Tru64
UNIX] Accepts a pointer to an array of wchar_t
type. Wide characters from the array are converted
to an array of bytes containing multibyte
characters and the multibyte characters up to (but
not including) the null character are printed. If
a precision is specified, then no more than the
number of bytes specified by the precision are
printed. If the precision is not specified or is
greater than the size of the array of bytes, then
the array of wide characters must be terminated by
a null wide character. If a minimum field width is
specified and the array of bytes occupy fewer bytes
than the specified width, the array is padded with
space characters to the specified width. Accepts a
pointer to void. The value of the pointer is converted
to a sequence of printable characters, the
same as unsigned long hexadecimal (lx). Accepts a
pointer to an integer into which is written the
number of wide characters written to the output
stream so far by this call. No argument is converted.
Prints a % wide character. No argument is
converted. The complete conversion specification is
%%.
If a conversion specification is invalid, results are
undefined.
If any argument is, or points to, a union or an aggregate
(except for an array of char type using %s conversion, an
array of wchar_t using %s conversion, or a pointer using
%p conversion), the function's behavior is undefined.
If the result of a conversion is wider than the field
width, the field is expanded to contain the converted
result. No truncation occurs. However, a small precision
can cause truncation on the right.
[Tru64 UNIX] The e, E, f, and g formats represent the
special floating-point values as follows: +NaNQ or -NaNQ
+NaNS or -NaNS +INF or -INF +0 or -0
The representation of the + (plus sign) depends on whether
the + or (space) formatting option is specified.
The wprintf(), fwprintf(), and swprintf() functions allow
for the insertion of a language-dependent radix character
in the output wide-character string. The radix character
is defined by langinfo data in the program's locale (category
LC_NUMERIC). In the POSIX (C) locale, or in a locale
where the radix character is not defined, the radix character
defaults to (period).
[Tru64 UNIX] The st_ctime and st_mtime fields of the file
are marked for update between the successful execution of
the wprintf() or fwprintf() function and the next successful
completion of a call to one of the following: The
fflush() or fclose() function on the same stream The
exit() or abort() function
Currently, the Tru64 UNIX product does not include locales
that use shift-state encoding. Some sections of this reference
page refer to the mb_state object or describe
behavior that is dependent on shift-state encoding. This
information is included for your convenience in developing
portable applications that run on multiple platforms, some
of which may supply locales that do use shift-state encoding.
Upon successful completion, each of these functions
returns the number of wide characters that are output.
Otherwise, they return a negative value.
The swprintf() function returns -1 if the number of wide
characters to be output would not fit in the wstr output
buffer.
[Tru64 UNIX] The swprintf() function sets errno to the
following value: [Tru64 UNIX] The swprintf() function was
asked to print more characters than are allowed in the
output buffer.
[Tru64 UNIX] The wprintf() and fwprintf() functions fail
if either stream is unbuffered or stream's buffer needed
to be flushed and the function call caused an underlying
write() or lseek() function to be invoked. In addition, if
the wprintf() or fwprintf() function fails, errno is set
to one of the following values: [Tru64 UNIX] The O_NONBLOCK
option is set for the file descriptor underlying
stream and the process would be delayed in the write operation.
[Tru64 UNIX] The file descriptor underlying
stream is not a valid file descriptor open for writing.
[Tru64 UNIX] An attempt was made to write to a file that
exceeds the process's file size limit or the maximum file
size. [Tru64 UNIX] An invalid wide character was
detected. [Tru64 UNIX] The read operation was interrupted
by a signal that was caught, and no data was transferred.
[Tru64 UNIX] The implementation supports job
control; the process is a member of a background process
group and is attempting to write to its controlling terminal;
TOSTOP is set; the process is neither ignoring nor
blocking SIGTTOU; and the process group of the process is
orphaned. [Tru64 UNIX] There was no free space remaining
on the device containing the file. [Tru64 UNIX] An
attempt was made to write to a pipe or FIFO that is not
open for reading by any process. A SIGPIPE signal will
also be sent to the process.
Functions: fopen(3), printf(3), putwc(3), scanf(3), towctrans(3), towlower(3), vprintf(3), vwprintf(3),
wctrans(3), wscanf(3)
Files: locale(4)
Standards: standards(5)
wprintf(3)
[ Back ] |
