wprintf(3)wprintf(3)NAME
wprintf, fwprintf, swprintf - Print formatted output for wide charac‐
ters
SYNOPSIS
#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] ... );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
fwprintf(), swprintf(), wprintf(): ISO C
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies a wide-character string that combines literal characters with
conversion specifications. Specifies the data to be converted accord‐
ing to the format parameter. Points to a FILE structure specifying an
open stream to which converted values are written. Specifies a charac‐
ter array in which the converted values are stored. Specifies the max‐
imum 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.
DESCRIPTION
The wprintf() function converts, formats, and writes its value parame‐
ters, under control of the format parameter, to the standard output
stream stdout.
The fwprintf() function converts, formats, and writes its value parame‐
ters, under control of the format parameter, to the output stream spec‐
ified by the stream parameter.
The swprintf() function converts, formats, and stores its value parame‐
ters, 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 format‐
ted wide-character string to the allotted space for wstr.
The format parameter is a wide-character string that contains the fol‐
lowing 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
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(), func‐
tions 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 pre‐
cision 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 con‐
verted 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 behav‐
ior is undefined. An optional decimal digit string that speci‐
fies 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 out‐
put 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 align‐
ment 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 preci‐
sion is replaced by *digit$. An optional precision. The preci‐
sion is a (dot) followed by a decimal digit string. If no preci‐
sion 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 conver‐
sions. 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 preci‐
sion 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 fol‐
lowed 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 preci‐
sion 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 con‐
verted can be represented in fewer digits, it is expanded with
leading zeros. The default precision is 1. The result of con‐
verting 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 pre‐
cision 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 char‐
acter appears (unless the # option is specified). The E conver‐
sion 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 dou‐
ble value and converts it in the style of the e, E, or f conver‐
sions, 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 speci‐
fied). 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 expo‐
nent is greater than or equal to the precision. If the l quali‐
fier 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, con‐
verts it to a two-element wchar_t array, (the first element
being the wint_t argument and the second being a null wide char‐
acter), 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 writ‐
ten. 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 ini‐
tialized 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 preci‐
sion is specified, the wide-character 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 multibyte-character 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 char‐
acters from the array are converted to an array of bytes con‐
taining multibyte characters and the multibyte characters up to
(but not including) the null character are printed. If a preci‐
sion is specified, then no more than the number of bytes speci‐
fied by the precision are printed. If the precision is not spec‐
ified 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 conver‐
sion 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. How‐
ever, a small precision can cause truncation on the right.
[Tru64 UNIX] The e, E, f, and g formats represent the special float‐
ing-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 charac‐
ter 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
RESTRICTIONS
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 develop‐
ing portable applications that run on multiple platforms, some of which
may supply locales that do use shift-state encoding.
RETURN VALUES
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.
ERRORS
[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_NON‐
BLOCK 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.
SEE ALSO
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)
