 |
Index for
Section 3 |
|
 |
Alphabetical
listing for W |
|
 |
Bottom of
page |
|
wprintf(3)
NAME
wprintf, fwprintf, swprintf - Print formatted output for wide characters
LIBRARY
Standard C Library (libc.so, libc.a)
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]...);
STANDARDS
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.
PARAMETERS
format
Specifies a wide-character string that combines literal characters with
conversion specifications.
value
Specifies the data to be converted according to the format parameter.
stream
Points to a FILE structure specifying an open stream to which converted
values are written.
wstr
Specifies a character array in which the converted values are stored.
n 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.
DESCRIPTION
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
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 flags that modify the meaning of the conversion
specification. The flag 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 ' flag
with conversions other than decimal is undefined.
- Left align within the field the result of the conversion. If you
do not specify this flag, 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 flag, the converted value begins with a
sign only when the value is negative.
(space)
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 + flags appear, the
(space) flag 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 flag has no effect.
0 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) flags both appear, the 0 flag is ignored. For d, i, o, u,
x, and X conversions, if a precision is specified, the 0 flag 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 flag 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:
d or i
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.
u 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.
o 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.
x, X
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.
f 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 # flag 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.
e or E
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 # flag 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).
g or G
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 #
flag is specified). The style used depends on the value
converted. Style e (E, if G is the flag 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.
c 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.
C [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.
s 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 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.
S [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.
p 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).
n 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:
Quiet NaN: +NaNQ or -NaNQ
Signaling NaN: +NaNS or -NaNS
+/-INF: +INF or -INF
+/-0: +0 or -0
The representation of the + (plus sign) depends on whether the + or (space)
formatting flag 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
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 developing 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:
[E2BIG] [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:
[EAGAIN] [Tru64 UNIX] The O_NONBLOCK flag is set for the file descriptor
underlying stream and the process would be delayed in the write
operation.
[EBADF] [Tru64 UNIX] The file descriptor underlying stream is not a
valid file descriptor open for writing.
[EFBIG] [Tru64 UNIX] An attempt was made to write to a file that
exceeds the process's file size limit or the maximum file size.
[EILSEQ] [Tru64 UNIX] An invalid wide character was detected.
[EINTR] [Tru64 UNIX] The read operation was interrupted by a signal
that was caught, and no data was transferred.
[EIO] [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.
[ENOSPC] [Tru64 UNIX] There was no free space remaining on the device
containing the file.
[EPIPE] [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.
RELATED INFORMATION
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for W |
|
 |
Top of
page |
|