fwprintf(3S) fwprintf(3S)
NAME
fwprintf, wprintf, swprintf, vfwprintf, vwprintf, vswprintf - format-
ted wide-character output
SYNOPSIS
cc [flag ...] file ... -lw [library ...]
#include <stdarg.h>
#include <stdio.h>
#include <wchar.h>
int fwprintf(FILE *stream, const wchart *format, ...);
int wprintf(const wchart *format, ...);
int swprintf(wchart *s, sizet n, const wchart *format, ...);
int vfwprintf(FILE *stream, const wchart *format, valist arg);
int vwprintf(const wchart *format, valist arg);
int vswprintf(wchart *s, sizet n, const wchart *format, valist arg);
DESCRIPTION
The fwprintf() function writes output to the stream pointed to by
stream, under control of the wide string pointed to by format that
specifies how subsequent arguments are converted for output. If there
are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess argu-
ments are evaluated (as always) but are otherwise ignored. The
fwprintf() function returns when the end of the format string is
encountered.
The wprintf() function is equivalent to fwprintf() with the argument
stdout interposed before the arguments to wprintf().
The swprintf() function is equivalent to fwprintf(), except that the
argument s specifies an array of wide-characters into which the gen-
erated output is to be written, rather than written to a stream. No
more than n wide-characters are written, including a terminating null
wide-character, which is always added (unless n is zero).
The vfwprintf() function is equivalent to fwprintf(), with the vari-
able argument list replaced by arg, which shall have been initialized
by the vastart macro (and possibly subsequent vaarg calls). The
vfwprintf() function does not invoke the vaend macro.
Note:
As the functions vfwprintf(), vswprintf(), and vwprintf() invoke the
vaarg macro, the value of arg after the return is unspecified.
Page 1 Reliant UNIX 5.44 Printed 11/98
fwprintf(3S) fwprintf(3S)
The vwprintf() function is equivalent to swprintf(), with the variable
argument list replaced by arg, which shall have been initialized by
the vastart macro (and possibly subsequent vaarg calls). The
vwprintf() function does not invoke the vaend macro.
The vswprintf() function is equivalent to swprintf(), with the vari-
able argument list replaced by arg, which shall have been initialized
by the vastart macro (and possibly subsequent vaarg calls). The
vswprintf() function does not invoke the vaend macro.
Format
The format is composed of zero or more directives: ordinary wide-char-
acters (not %) and conversion specifications. The processing of con-
version specifications is as if they were replaced in the format
string by wide-character strings that are each the result of fetching
zero or more subsequent arguments and converting them, if applicable,
according to the corresponding conversion specified. The expanded
wide-character format string is then written to the output stream.
Each conversion specification is introduced by the wide-character %.
After the %, the following appear in sequence:
- Zero or more flags (in any order) that modify the meaning of the
conversion specification.
- An optional minimum field width. If the converted value has fewer
wide-characters than the field width, it is padded with spaces (by
default) on the left (or right, if the left adjustment flag,
described later, has been given) to the field width. The field
width takes the form of an asterisk * (described later) or a deci-
mal integer. (Note that 0 is taken as a flag, not as the beginning
of a field width.)
- An optional precision that gives the minimum number of digits to
appear for the d, i, o, u, x and X conversions, the number of
digits to appear after the decimal-point characters for the e, E
and f conversions, the maximum number of significant digits for the
g and G conversion or the maximum number of wide-characters to be
written from a string in s conversion. The precision takes the form
of a period (.) followed either by an asterisk * (described later)
or by an optional decimal integer, if only the period is specified,
the precision is taken as zero. If a precision appears with any
other conversion specifier, the behavior is undefined.
- An optional l specifying that a following c conversion specifier
applies to a wintt argument; and specifying that a following s
conversion specifier applies to a pointer to a wchart argument.
Page 2 Reliant UNIX 5.44 Printed 11/98
fwprintf(3S) fwprintf(3S)
An optional h specifying that a following d, i, o, u, x, or X con-
version specifier applies to a short int or unsigned short int
argument; (the argument is promoted according to the integral pro-
motions, and its value is converted to short int or unsigned short
int before printing); and specifying that a following n conversion
specifier applies to a pointer to a short int argument.
An optional l specifying that a following d, i, o, u, x, or X con-
version specifier applies to a pointer to a long int or unsigned
long int argument; and specifying that a following n conversion
specifier applies to a pointer to a long int argument; or an option
L specifying that a following e, E, f, g or G conversion specifier
applies to a long double argument.
If an h, l or L appears with any other conversion specifier, the
behavior is undefined.
- A wide-character that specifies the type of conversion to be
applied.
As noted above, a field width, or precision, or both, may be indicated
by an asterisk *. In this case, an int argument supplies the field
width or precision. The arguments specifying field width, or preci-
sion, or both, shall appear (in that order) before the argument (if
any) to be converted. A negative field width argument is taken as a -
flag followed by a positive field width. A negative precision argument
is taken as if the precision were omitted.
Flags
The wide-character flags and their meanings are:
- The result of the conversion is left-justified within the field.
(It is right-justified if this flag is not specified.)
+ The result of a signed conversion always begins with a plus or
minus sign. (It begins with a sign only when a negative value is
converted if this flag is not specified.)
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
is prefixed to the result. If the space and + flags both appear,
the space flag is ignored.
# The result is to be converted to an "alternate form". For o con-
version, it increases the precision to force the first digit of
the result to be a zero, if necessary. For x (or X) conversion, a
nonzero result has Ox (or 0X) prefixed to it. For e, E, f, g, and
G conversions, the result always contains a decimal-point wide-
character, even if no digits follow it. (Normally, a decimal-
point wide-character appears in the result of these conversions
only if a digit follows its.) For g and G conversions, trailing
Page 3 Reliant UNIX 5.44 Printed 11/98
fwprintf(3S) fwprintf(3S)
zeros are not to be removed from the result. For other conver-
sion, the behavior is undefined.
0 For d, i, o, u, x, X, e, E, f, g, and G conversions, leading
zeros (following any indication of sign or base are used to pad
to the field width; no space padding is performed. If the 0 and -
flags both appear, the 0 flag is ignored. For d, i, o, u, x, and
X conversion, if a precision is specified, the 0 flag is ignored.
For other conversion, the behavior is undefined.
Conversion specifiers
The conversion specifiers and their meanings are:
d, i The int argument is converted to signed decimal in the style
[-]dddd. 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 zero value with a precision of
zero is no wide-characters.
o, u, x, X
The unsigned int argument is converted to unsigned octal (o),
unsigned decimal (u), or unsigned hexadecimal notation (or X) in
the style dddd; the letters abcdef are used for x conversion and
the letters ABCDEF for X conversion. 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
zero value with a precision of zero is no wide-characters.
f The double int argument is converted to decimal notation in the
style [-]ddd.ddd, where the number of digits after the decimal-
point wide-character is equal to the precision specification. If
the precision is missing, it is taken as 6; if the precision is
zero and the # flag is not specified, no decimal-point wide-char-
acter appears. If a decimal-point wide-character appears, at
least one digit appears before it. The value is rounded to the
appropriate number of digits.
e, E The double argument is converted in the style [-]d.ddde±dd, where
there is one digit before the decimal-point wide-character (which
is nonzero if the argument is nonzero) and the number of digits
after it is equal to the precision; if the precision is missing,
it is taken as 6; if the precision is zero and the # flag is not
specified, no decimal-point wide-character appears. The value is
rounded to the appropriate number of digits. The E conversion
specifier produces a number with E instead of e introducing the
exponent. The exponent always contains at least two digits. If
the value is zero, the exponent is zero.
Page 4 Reliant UNIX 5.44 Printed 11/98
fwprintf(3S) fwprintf(3S)
g, G The double argument is converted in style f or e (or in style E
in the G conversion specifier), with the precision specifying the
number of significant digits. If the precision is zero, it is
taken as 1. The style used depends on the value converted; style
e (or E) is used only if the exponent resulting from such a con-
version is less that -4 or greater than or equal to the preci-
sion. Trailing zeros are removed from the fractional portion of
the result; a decimal-point wide-character appears only if it is
followed by a digit.
c If no l qualifier is present, the int argument is converted to a
wide-character as if by calling btowc() and the resulting wide-
character is written. Otherwise, the wintt argument is converted
to wchart and written.
s If no l qualifier is present, the argument shall be a pointer to
a character array containing a multibyte sequence beginning in
the initial shift state. Characters from the array are converted
as if by repeated calls to the mbrtowc() function, with the con-
version state described by an mstatet 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-charac-
ters are written. If the precision is not specified or is greater
than the size of the converted array, the converted array shall
contain a null wide-character.
If an l qualifier is present, the argument shall be a pointer to
an array of wchart type. Wide-characters from the array are
written up to (but not including) a terminating null wide-charac-
ter. 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 array, the array shall contain a
null wide-character.
P The argument shall be a pointer to void. The value of the pointer
is converted to a sequence of printable wide-characters, in an
implementation-defined manner.
n The argument shall be a pointer to an integer into which is writ-
ten the number of wide-characters written to the output stream so
far by this call to fwprintf(). No argument is converted.
% A % wide-character is written. No argument is converted. The com-
plete conversion specification shall be %%.
If a conversion specification is invalid, the behavior is undefined.
If an argument is, or points to, a union or an aggregate (except for
an array of char type using %s conversion, an array of chart type
using %ls conversion, or a pointer using %p conversion, the behavior
is undefined.
Page 5 Reliant UNIX 5.44 Printed 11/98
fwprintf(3S) fwprintf(3S)
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 is expanded to contain the conversion result.
RETURN VALUES
The fwprintf(), wprintf(), vfwprintf() and vwprintf() functions return
the number of wide-characters transmitted, or a negative value if an
output error occurred.
The swprintf() and vswprintf() functions return the number of wide-
characters written in the array, not counting the terminating null
wide-character, or a negative value if n or more wide-characters were
requested to be written.
NOTES
The minimum value for the maximum number of wide-characters produced
by any single conversion shall be 509.
EXAMPLES
To print a date and time in the form "Sunday, July 3, 10:02" followed
by pi to five decimal places:
#include <math.h>
#include <stdio.h>
#include <wchar.h>
/* ... */
wchart *weekday, *month; /* pointers to wide string */
int day, hour, min;
fwprintf(stdout, L"%ls, %ls %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
fwprintf(stdout, l"pi = %.5f\n", 4 * atan(1.0));
SEE ALSO
btowc(3C), mbrtowc(3C), stdarg(5), stdio(5), wchar(5).
Page 6 Reliant UNIX 5.44 Printed 11/98