add directory Ref-docs
This commit is contained in:
gohigh
583
Ref-docs/POSIX/susv3/functions/fwprintf.html
Normal file
583
Ref-docs/POSIX/susv3/functions/fwprintf.html
Normal file
@@ -0,0 +1,583 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
||||
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
||||
<title>fwprintf</title>
|
||||
</head>
|
||||
<body bgcolor="white">
|
||||
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
||||
</script>
|
||||
|
||||
<basefont size="3"> <a name="fwprintf"></a> <a name="tag_03_204"></a><!-- fwprintf -->
|
||||
<!--header start-->
|
||||
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
||||
IEEE Std 1003.1-2001<br>
|
||||
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
||||
|
||||
<!--header end-->
|
||||
<hr size="2" noshade>
|
||||
<h4><a name="tag_03_204_01"></a>NAME</h4>
|
||||
|
||||
<blockquote>fwprintf, swprintf, wprintf - print formatted wide-character output</blockquote>
|
||||
|
||||
<h4><a name="tag_03_204_02"></a>SYNOPSIS</h4>
|
||||
|
||||
<blockquote class="synopsis">
|
||||
<p><code><tt>#include <<a href="../basedefs/stdio.h.html">stdio.h</a>><br>
|
||||
#include <<a href="../basedefs/wchar.h.html">wchar.h</a>><br>
|
||||
<br>
|
||||
int fwprintf(FILE *restrict</tt> <i>stream</i><tt>, const wchar_t *restrict</tt> <i>format</i><tt>, ...);<br>
|
||||
int swprintf(wchar_t *restrict</tt> <i>ws</i><tt>, size_t</tt> <i>n</i><tt>,<br>
|
||||
const wchar_t *restrict</tt> <i>format</i><tt>, ...);<br>
|
||||
int wprintf(const wchar_t *restrict</tt> <i>format</i><tt>, ...);<br>
|
||||
</tt></code></p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_204_03"></a>DESCRIPTION</h4>
|
||||
|
||||
<blockquote>
|
||||
<div class="box"><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]"
|
||||
border="0"> The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the
|
||||
requirements described here and the ISO C standard is unintentional. This volume of IEEE Std 1003.1-2001 defers to
|
||||
the ISO C standard. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></div>
|
||||
|
||||
<p>The <i>fwprintf</i>() function shall place output on the named output <i>stream</i>. The <i>wprintf</i>() function shall place
|
||||
output on the standard output stream <i>stdout</i>. The <i>swprintf</i>() function shall place output followed by the null wide
|
||||
character in consecutive wide characters starting at *<i>ws</i>; no more than <i>n</i> wide characters shall be written, including
|
||||
a terminating null wide character, which is always added (unless <i>n</i> is zero).</p>
|
||||
|
||||
<p>Each of these functions shall convert, format, and print its arguments under control of the <i>format</i> wide-character string.
|
||||
The <i>format</i> is composed of zero or more directives: <i>ordinary wide-characters</i>, which are simply copied to the output
|
||||
stream, and <i>conversion specifications</i>, each of which results in the fetching of zero or more arguments. The results are
|
||||
undefined if there are insufficient arguments for the <i>format</i>. If the <i>format</i> is exhausted while arguments remain, the
|
||||
excess arguments are evaluated but are otherwise ignored.</p>
|
||||
|
||||
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
||||
Conversions can be applied to the <i>n</i>th argument after the <i>format</i> in the argument list, rather than to the next unused
|
||||
argument. In this case, the conversion specifier wide character <tt>%</tt> (see below) is replaced by the sequence <tt>"%n$"</tt> ,
|
||||
where <i>n</i> 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 <i>format</i> wide-character strings that select arguments in an order appropriate to
|
||||
specific languages (see the EXAMPLES section).</p>
|
||||
|
||||
<p>The <i>format</i> can contain either numbered argument specifications (that is, <tt>"%</tt><i>n</i><tt>$"</tt> and
|
||||
<tt>"*</tt><i>m</i><tt>$"</tt>), or unnumbered argument conversion specifications (that is, <tt>%</tt> and <tt>*</tt> ), but not
|
||||
both. The only exception to this is that <tt>%%</tt> can be mixed with the <tt>"%</tt><i>n</i><tt>$"</tt> form. The results of
|
||||
mixing numbered and unnumbered argument specifications in a <i>format</i> wide-character string are undefined. When numbered
|
||||
argument specifications are used, specifying the <i>N</i>th argument requires that all the leading arguments, from the first to the
|
||||
(<i>N</i>-1)th, are specified in the <i>format</i> wide-character string.</p>
|
||||
|
||||
<p>In <i>format</i> wide-character strings containing the <tt>"%</tt><i>n</i><tt>$"</tt> form of conversion specification, numbered
|
||||
arguments in the argument list can be referenced from the <i>format</i> wide-character string as many times as required. <img src=
|
||||
"../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
||||
|
||||
<p>In <i>format</i> wide-character strings containing the <tt>%</tt> form of conversion specification, each argument in the
|
||||
argument list shall be used exactly once.</p>
|
||||
|
||||
<p><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> All
|
||||
forms of the <i>fwprintf</i>() 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 <i>LC_NUMERIC ).</i> In the POSIX
|
||||
locale, or in a locale where the radix character is not defined, the radix character shall default to a period ( <tt>'.'</tt> ).
|
||||
<img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
||||
|
||||
<p>Each conversion specification is introduced by the <tt>'%'</tt> wide character <sup>[<a href=
|
||||
"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> or by the
|
||||
wide-character sequence <tt>"%</tt><i>n</i><tt>$"</tt>, <img src="../images/opt-end.gif" alt="[Option End]" border="0"> after
|
||||
which the following appear in sequence:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>Zero or more <i>flags</i> (in any order), which modify the meaning of the conversion specification.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>An optional minimum <i>field width</i>. 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 ( <tt>'-'</tt> ), described
|
||||
below, is given to the field width. The field width takes the form of an asterisk ( <tt>'*'</tt> ), described below, or a decimal
|
||||
integer.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>An optional <i>precision</i> that gives the minimum number of digits to appear for the <tt>d</tt> , <tt>i</tt> , <tt>o</tt> ,
|
||||
<tt>u</tt> , <tt>x</tt> , and <tt>X</tt> conversion specifiers; the number of digits to appear after the radix character for the
|
||||
<tt>a</tt> , <tt>A</tt> , <tt>e</tt> , <tt>E</tt> , <tt>f</tt> , and <tt>F</tt> conversion specifiers; the maximum number of
|
||||
significant digits for the <tt>g</tt> and <tt>G</tt> conversion specifiers; or the maximum number of wide characters to be printed
|
||||
from a string in the <tt>s</tt> conversion specifiers. The precision takes the form of a period ( <tt>'.'</tt> ) followed either by
|
||||
an asterisk ( <tt>'*'</tt> ), 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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>An optional length modifier that specifies the size of the argument.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>A <i>conversion specifier</i> wide character that indicates the type of conversion to be applied.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>A field width, or precision, or both, may be indicated by an asterisk ( <tt>'*'</tt> ). In this case an argument of type
|
||||
<b>int</b> 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 <tt>'-'</tt> flag
|
||||
followed by a positive field width. A negative precision is taken as if the precision were omitted. <sup>[<a href=
|
||||
"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> In
|
||||
<i>format</i> wide-character strings containing the <tt>"%</tt><i>n</i><tt>$"</tt> form of a conversion specification, a field
|
||||
width or precision may be indicated by the sequence <tt>"*</tt><i>m</i><tt>$"</tt>, where <i>m</i> is a decimal integer in the
|
||||
range [1,{NL_ARGMAX}] giving the position in the argument list (after the <i>format</i> argument) of an integer argument containing
|
||||
the field width or precision, for example:</p>
|
||||
|
||||
<pre>
|
||||
<tt>wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec); <img src="../images/opt-end.gif" alt="[Option End]" border=
|
||||
"0">
|
||||
</tt>
|
||||
</pre>
|
||||
|
||||
<p>The flag wide characters and their meanings are:</p>
|
||||
|
||||
<dl compact>
|
||||
<dt><tt>'</tt></dt>
|
||||
|
||||
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
||||
The integer portion of the result of a decimal conversion ( <tt>%i</tt> , <tt>%d</tt> , <tt>%u</tt> , <tt>%f</tt> , <tt>%F</tt> ,
|
||||
<tt>%g</tt> , or <tt>%G</tt> ) shall be formatted with thousands' grouping wide characters. For other conversions, the behavior is
|
||||
undefined. The numeric grouping wide character is used. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
||||
|
||||
<dt><tt>-</tt></dt>
|
||||
|
||||
<dd>The result of the conversion shall be left-justified within the field. The conversion shall be right-justified if this flag is
|
||||
not specified.</dd>
|
||||
|
||||
<dt><tt>+</tt></dt>
|
||||
|
||||
<dd>The result of a signed conversion shall always begin with a sign ( <tt>'+'</tt> or <tt>'-'</tt> ). The conversion shall begin
|
||||
with a sign only when a negative value is converted if this flag is not specified.</dd>
|
||||
|
||||
<dt><space></dt>
|
||||
|
||||
<dd>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 <tt>'+'</tt> flags both appear, the
|
||||
<space> flag shall be ignored.</dd>
|
||||
|
||||
<dt><tt>#</tt></dt>
|
||||
|
||||
<dd>Specifies that the value is to be converted to an alternative form. For <tt>o</tt> conversion, it increases the precision (if
|
||||
necessary) to force the first digit of the result to be 0. For <tt>x</tt> or <tt>X</tt> conversion specifiers, a non-zero result
|
||||
shall have 0x (or 0X) prefixed to it. For <tt>a</tt> , <tt>A</tt> , <tt>e</tt> , <tt>E</tt> , <tt>f</tt> , <tt>F</tt> , <tt>g</tt>
|
||||
, and <tt>G</tt> 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 <tt>g</tt> and <tt>G</tt>
|
||||
conversion specifiers, trailing zeros shall <i>not</i> be removed from the result as they normally are. For other conversion
|
||||
specifiers, the behavior is undefined.</dd>
|
||||
|
||||
<dt><tt>0</tt></dt>
|
||||
|
||||
<dd>For <tt>d</tt> , <tt>i</tt> , <tt>o</tt> , <tt>u</tt> , <tt>x</tt> , <tt>X</tt> , <tt>a</tt> , <tt>A</tt> , <tt>e</tt> ,
|
||||
<tt>E</tt> , <tt>f</tt> , <tt>F</tt> , <tt>g</tt> , and <tt>G</tt> 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 <tt>'0'</tt> and <tt>'-'</tt> flags both
|
||||
appear, the <tt>'0'</tt> flag shall be ignored. For <tt>d</tt> , <tt>i</tt> , <tt>o</tt> , <tt>u</tt> , <tt>x</tt> , and <tt>X</tt>
|
||||
conversion specifiers, if a precision is specified, the <tt>'0'</tt> flag shall be ignored. If the <tt>'0'</tt> and <tt>'"</tt>
|
||||
flags both appear, the grouping wide characters are inserted before zero padding. For other conversions, the behavior is
|
||||
undefined.</dd>
|
||||
</dl>
|
||||
|
||||
<p>The length modifiers and their meanings are:</p>
|
||||
|
||||
<dl compact>
|
||||
<dt><tt>hh</tt></dt>
|
||||
|
||||
<dd>Specifies that a following <tt>d</tt> , <tt>i</tt> , <tt>o</tt> , <tt>u</tt> , <tt>x</tt> , or <tt>X</tt> conversion specifier
|
||||
applies to a <b>signed char</b> or <b>unsigned char</b> argument (the argument will have been promoted according to the integer
|
||||
promotions, but its value shall be converted to <b>signed char</b> or <b>unsigned char</b> before printing); or that a following
|
||||
<tt>n</tt> conversion specifier applies to a pointer to a <b>signed char</b> argument.</dd>
|
||||
|
||||
<dt><tt>h</tt></dt>
|
||||
|
||||
<dd>Specifies that a following <tt>d</tt> , <tt>i</tt> , <tt>o</tt> , <tt>u</tt> , <tt>x</tt> , or <tt>X</tt> conversion specifier
|
||||
applies to a <b>short</b> or <b>unsigned short</b> argument (the argument will have been promoted according to the integer
|
||||
promotions, but its value shall be converted to <b>short</b> or <b>unsigned short</b> before printing); or that a following
|
||||
<tt>n</tt> conversion specifier applies to a pointer to a <b>short</b> argument.</dd>
|
||||
|
||||
<dt><tt>l</tt> (ell)</dt>
|
||||
|
||||
<dd>Specifies that a following <tt>d</tt> , <tt>i</tt> , <tt>o</tt> , <tt>u</tt> , <tt>x</tt> , or <tt>X</tt> conversion specifier
|
||||
applies to a <b>long</b> or <b>unsigned long</b> argument; that a following <tt>n</tt> conversion specifier applies to a pointer to
|
||||
a <b>long</b> argument; that a following <tt>c</tt> conversion specifier applies to a <b>wint_t</b> argument; that a following
|
||||
<tt>s</tt> conversion specifier applies to a pointer to a <b>wchar_t</b> argument; or has no effect on a following <tt>a</tt> ,
|
||||
<tt>A</tt> , <tt>e</tt> , <tt>E</tt> , <tt>f</tt> , <tt>F</tt> , <tt>g</tt> , or <tt>G</tt> conversion specifier.</dd>
|
||||
|
||||
<dt><tt>ll</tt> (ell-ell)</dt>
|
||||
|
||||
<dd><br>
|
||||
Specifies that a following <tt>d</tt> , <tt>i</tt> , <tt>o</tt> , <tt>u</tt> , <tt>x</tt> , or <tt>X</tt> conversion specifier
|
||||
applies to a <b>long long</b> or <b>unsigned long long</b> argument; or that a following <tt>n</tt> conversion specifier applies to
|
||||
a pointer to a <b>long long</b> argument.</dd>
|
||||
|
||||
<dt><tt>j</tt></dt>
|
||||
|
||||
<dd>Specifies that a following <tt>d</tt> , <tt>i</tt> , <tt>o</tt> , <tt>u</tt> , <tt>x</tt> , or <tt>X</tt> conversion specifier
|
||||
applies to an <b>intmax_t</b> or <b>uintmax_t</b> argument; or that a following <tt>n</tt> conversion specifier applies to a
|
||||
pointer to an <b>intmax_t</b> argument.</dd>
|
||||
|
||||
<dt><tt>z</tt></dt>
|
||||
|
||||
<dd>Specifies that a following <tt>d</tt> , <tt>i</tt> , <tt>o</tt> , <tt>u</tt> , <tt>x</tt> , or <tt>X</tt> conversion specifier
|
||||
applies to a <b>size_t</b> or the corresponding signed integer type argument; or that a following <tt>n</tt> conversion specifier
|
||||
applies to a pointer to a signed integer type corresponding to a <b>size_t</b> argument.</dd>
|
||||
|
||||
<dt><tt>t</tt></dt>
|
||||
|
||||
<dd>Specifies that a following <tt>d</tt> , <tt>i</tt> , <tt>o</tt> , <tt>u</tt> , <tt>x</tt> , or <tt>X</tt> conversion specifier
|
||||
applies to a <b>ptrdiff_t</b> or the corresponding <b>unsigned</b> type argument; or that a following <tt>n</tt> conversion
|
||||
specifier applies to a pointer to a <b>ptrdiff_t</b> argument.</dd>
|
||||
|
||||
<dt><tt>L</tt></dt>
|
||||
|
||||
<dd>Specifies that a following <tt>a</tt> , <tt>A</tt> , <tt>e</tt> , <tt>E</tt> , <tt>f</tt> , <tt>F</tt> , <tt>g</tt> , or
|
||||
<tt>G</tt> conversion specifier applies to a <b>long double</b> argument.</dd>
|
||||
</dl>
|
||||
|
||||
<p>If a length modifier appears with any conversion specifier other than as specified above, the behavior is undefined.</p>
|
||||
|
||||
<p>The conversion specifiers and their meanings are:</p>
|
||||
|
||||
<dl compact>
|
||||
<dt><tt>d</tt>, <tt>i</tt></dt>
|
||||
|
||||
<dd>The <b>int</b> argument shall be converted to a signed decimal in the style <tt>"[-]</tt><i>dddd"</i>. 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.</dd>
|
||||
|
||||
<dt><tt>o</tt></dt>
|
||||
|
||||
<dd>The <b>unsigned</b> argument shall be converted to unsigned octal format in the style <tt>"dddd"</tt> . 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.</dd>
|
||||
|
||||
<dt><tt>u</tt></dt>
|
||||
|
||||
<dd>The <b>unsigned</b> argument shall be converted to unsigned decimal format in the style <tt>"dddd"</tt> . 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.</dd>
|
||||
|
||||
<dt><tt>x</tt></dt>
|
||||
|
||||
<dd>The <b>unsigned</b> argument shall be converted to unsigned hexadecimal format in the style <tt>"dddd"</tt> ; the letters
|
||||
<tt>"abcdef"</tt> 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.</dd>
|
||||
|
||||
<dt><tt>X</tt></dt>
|
||||
|
||||
<dd>Equivalent to the <tt>x</tt> conversion specifier, except that letters <tt>"ABCDEF"</tt> are used instead of <tt>"abcdef"</tt>
|
||||
.</dd>
|
||||
|
||||
<dt><tt>f</tt>, <tt>F</tt></dt>
|
||||
|
||||
<dd>The <b>double</b> argument shall be converted to decimal notation in the style <tt>"[-]</tt><i>ddd.ddd"</i>, 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 <tt>'#'</tt> 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.
|
||||
|
||||
<p>A <b>double</b> argument representing an infinity shall be converted in one of the styles <tt>"[-]inf"</tt> or
|
||||
<tt>"[-]infinity"</tt> ; which style is implementation-defined. A <b>double</b> argument representing a NaN shall be converted in
|
||||
one of the styles <tt>"[-]nan"</tt> or <tt>"[-]nan(</tt><i>n-char-sequence</i><tt>)"</tt>; which style, and the meaning of any
|
||||
<i>n-char-sequence</i>, is implementation-defined. The <tt>F</tt> conversion specifier produces <tt>"INF"</tt> ,
|
||||
<tt>"INFINITY"</tt> , or <tt>"NAN"</tt> instead of <tt>"inf"</tt> , <tt>"infinity"</tt> , or <tt>"nan"</tt> , respectively.</p>
|
||||
</dd>
|
||||
|
||||
<dt><tt>e</tt>, <tt>E</tt></dt>
|
||||
|
||||
<dd>The <b>double</b> argument shall be converted in the style <tt>"[-]</tt><i>d.ddd</i>e<tt>±dd"</tt>, 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 <tt>'#'</tt> 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 <tt>E</tt> conversion wide character shall produce a number with <tt>'E'</tt> instead of <tt>'e'</tt> introducing
|
||||
the exponent. The exponent shall always contain at least two digits. If the value is zero, the exponent shall be zero.
|
||||
|
||||
<p>A <b>double</b> argument representing an infinity or NaN shall be converted in the style of an <tt>f</tt> or <tt>F</tt>
|
||||
conversion specifier.</p>
|
||||
</dd>
|
||||
|
||||
<dt><tt>g</tt>, <tt>G</tt></dt>
|
||||
|
||||
<dd>The <b>double</b> argument shall be converted in the style <tt>f</tt> or <tt>e</tt> (or in the style <tt>F</tt> or <tt>E</tt>
|
||||
in the case of a <tt>G</tt> 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 <tt>e</tt> (or <tt>E</tt> ) 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.
|
||||
|
||||
|
||||
<p>A <b>double</b> argument representing an infinity or NaN shall be converted in the style of an <tt>f</tt> or <tt>F</tt>
|
||||
conversion specifier.</p>
|
||||
</dd>
|
||||
|
||||
<dt><tt>a</tt>, <tt>A</tt></dt>
|
||||
|
||||
<dd>A <b>double</b> argument representing a floating-point number shall be converted in the style <tt>"[-]0xh.hhhhp±d"</tt>,
|
||||
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 <b>double</b>, except that trailing zeros may be omitted; if the precision is zero and the
|
||||
<tt>'#'</tt> flag is not specified, no decimal-point wide character shall appear. The letters <tt>"abcdef"</tt> are used for
|
||||
<tt>a</tt> conversion and the letters <tt>"ABCDEF"</tt> for <tt>A</tt> conversion. The <tt>A</tt> conversion specifier produces a
|
||||
number with <tt>'X'</tt> and <tt>'P'</tt> instead of <tt>'x'</tt> and <tt>'p'</tt> . 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.
|
||||
|
||||
<p>A <b>double</b> argument representing an infinity or NaN shall be converted in the style of an <tt>f</tt> or <tt>F</tt>
|
||||
conversion specifier.</p>
|
||||
</dd>
|
||||
|
||||
<dt><tt>c</tt></dt>
|
||||
|
||||
<dd>If no <tt>l</tt> (ell) qualifier is present, the <b>int</b> argument shall be converted to a wide character as if by calling
|
||||
the <a href="../functions/btowc.html"><i>btowc</i>()</a> function and the resulting wide character shall be written. Otherwise, the
|
||||
<b>wint_t</b> argument shall be converted to <b>wchar_t</b>, and written.</dd>
|
||||
|
||||
<dt><tt>s</tt></dt>
|
||||
|
||||
<dd>If no <tt>l</tt> (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 <a href="../functions/mbrtowc.html"><i>mbrtowc</i>()</a> function, with the conversion state described by an
|
||||
<b>mbstate_t</b> 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.
|
||||
|
||||
<p>If an <tt>l</tt> (ell) qualifier is present, the application shall ensure that the argument is a pointer to an array of type
|
||||
<b>wchar_t</b>. 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.</p>
|
||||
</dd>
|
||||
|
||||
<dt><tt>p</tt></dt>
|
||||
|
||||
<dd>The application shall ensure that the argument is a pointer to <b>void</b>. The value of the pointer shall be converted to a
|
||||
sequence of printable wide characters in an implementation-defined manner.</dd>
|
||||
|
||||
<dt><tt>n</tt></dt>
|
||||
|
||||
<dd>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 <i>fwprintf</i>() 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.</dd>
|
||||
|
||||
<dt><tt>C</tt></dt>
|
||||
|
||||
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
||||
Equivalent to <tt>lc</tt> . <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
||||
|
||||
<dt><tt>S</tt></dt>
|
||||
|
||||
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
||||
Equivalent to <tt>ls</tt> . <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
||||
|
||||
<dt><tt>%</tt></dt>
|
||||
|
||||
<dd>Output a <tt>'%'</tt> wide character; no argument shall be converted. The entire conversion specification shall be <tt>%%</tt>
|
||||
.</dd>
|
||||
</dl>
|
||||
|
||||
<p>If a conversion specification does not match one of the above forms, the behavior is undefined.</p>
|
||||
|
||||
<p>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 <i>fwprintf</i>() and
|
||||
<i>wprintf</i>() shall be printed as if <a href="../functions/fputwc.html"><i>fputwc</i>()</a> had been called.</p>
|
||||
|
||||
<p>For <tt>a</tt> and <tt>A</tt> 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.</p>
|
||||
|
||||
<p>For <tt>e</tt> , <tt>E</tt> , <tt>f</tt> , <tt>F</tt> , <tt>g</tt> , and <tt>G</tt> 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
|
||||
<i>L</i> < <i>U</i>, both having DECIMAL_DIG significant digits; the value of the resultant decimal string <i>D</i> should
|
||||
satisfy <i>L</i> <= <i>D</i> <= <i>U</i>, with the extra stipulation that the error should have a correct sign for the
|
||||
current rounding direction.</p>
|
||||
|
||||
<p><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> The
|
||||
<i>st_ctime</i> and <i>st_mtime</i> fields of the file shall be marked for update between the call to a successful execution of
|
||||
<i>fwprintf</i>() or <i>wprintf</i>() and the next successful completion of a call to <a href=
|
||||
"../functions/fflush.html"><i>fflush</i>()</a> or <a href="../functions/fclose.html"><i>fclose</i>()</a> on the same stream, or a
|
||||
call to <a href="../functions/exit.html"><i>exit</i>()</a> or <a href="../functions/abort.html"><i>abort</i>()</a>. <img src=
|
||||
"../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_204_04"></a>RETURN VALUE</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>Upon successful completion, these functions shall return the number of wide characters transmitted, excluding the terminating
|
||||
null wide character in the case of <i>swprintf</i>(), or a negative value if an output error was encountered, <sup>[<a href=
|
||||
"javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> and set
|
||||
<i>errno</i> to indicate the error. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
||||
|
||||
<p>If <i>n</i> or more wide characters were requested to be written, <i>swprintf</i>() shall return a negative value, <sup>[<a
|
||||
href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> and set
|
||||
<i>errno</i> to indicate the error. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_204_05"></a>ERRORS</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>For the conditions under which <i>fwprintf</i>() and <i>wprintf</i>() fail and may fail, refer to <a href=
|
||||
"fputwc.html"><i>fputwc</i>()</a> .</p>
|
||||
|
||||
<p>In addition, all forms of <i>fwprintf</i>() may fail if:</p>
|
||||
|
||||
<dl compact>
|
||||
<dt>[EILSEQ]</dt>
|
||||
|
||||
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
||||
A wide-character code that does not correspond to a valid character has been detected. <img src="../images/opt-end.gif" alt=
|
||||
"[Option End]" border="0"></dd>
|
||||
|
||||
<dt>[EINVAL]</dt>
|
||||
|
||||
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
||||
There are insufficient arguments. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
||||
</dl>
|
||||
|
||||
<p>In addition, <i>wprintf</i>() and <i>fwprintf</i>() may fail if:</p>
|
||||
|
||||
<dl compact>
|
||||
<dt>[ENOMEM]</dt>
|
||||
|
||||
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
||||
Insufficient storage space is available. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<hr>
|
||||
<div class="box"><em>The following sections are informative.</em></div>
|
||||
|
||||
<h4><a name="tag_03_204_06"></a>EXAMPLES</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>To print the language-independent date and time format, the following statement could be used:</p>
|
||||
|
||||
<pre>
|
||||
<tt>wprintf(format, weekday, month, day, hour, min);
|
||||
</tt>
|
||||
</pre>
|
||||
|
||||
<p>For American usage, <i>format</i> could be a pointer to the wide-character string:</p>
|
||||
|
||||
<pre>
|
||||
<tt>L"%s, %s %d, %d:%.2d\n"
|
||||
</tt>
|
||||
</pre>
|
||||
|
||||
<p>producing the message:</p>
|
||||
|
||||
<pre>
|
||||
<tt>Sunday, July 3, 10:02
|
||||
</tt>
|
||||
</pre>
|
||||
|
||||
<p>whereas for German usage, <i>format</i> could be a pointer to the wide-character string:</p>
|
||||
|
||||
<pre>
|
||||
<tt>L"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
|
||||
</tt>
|
||||
</pre>
|
||||
|
||||
<p>producing the message:</p>
|
||||
|
||||
<pre>
|
||||
<tt>Sonntag, 3. Juli, 10:02
|
||||
</tt>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_204_07"></a>APPLICATION USAGE</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>None.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_204_08"></a>RATIONALE</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>None.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_204_09"></a>FUTURE DIRECTIONS</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>None.</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_204_10"></a>SEE ALSO</h4>
|
||||
|
||||
<blockquote>
|
||||
<p><a href="btowc.html"><i>btowc</i>()</a> , <a href="fputwc.html"><i>fputwc</i>()</a> , <a href=
|
||||
"fwscanf.html"><i>fwscanf</i>()</a> , <a href="mbrtowc.html"><i>mbrtowc</i>()</a> , <a href="setlocale.html"><i>setlocale</i>()</a>
|
||||
, the Base Definitions volume of IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap07.html">Chapter 7, Locale</a>, <a
|
||||
href="../basedefs/stdio.h.html"><i><stdio.h></i></a>, <a href="../basedefs/wchar.h.html"><i><wchar.h></i></a></p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_204_11"></a>CHANGE HISTORY</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 (E).</p>
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="tag_03_204_12"></a>Issue 6</h4>
|
||||
|
||||
<blockquote>
|
||||
<p>The Open Group Corrigendum U040/1 is applied to the RETURN VALUE section, describing the case if <i>n</i> or more wide
|
||||
characters are requested to be written using <i>swprintf</i>().</p>
|
||||
|
||||
<p>The DESCRIPTION is updated to avoid use of the term "must" for application requirements.</p>
|
||||
|
||||
<p>The following changes are made for alignment with the ISO/IEC 9899:1999 standard:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>The prototypes for <i>fwprintf</i>(), <i>swprintf</i>(), and <i>wprintf</i>() are updated.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>The DESCRIPTION is updated.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>The <tt>hh</tt> , <tt>ll</tt> , <tt>j</tt> , <tt>t</tt> , and <tt>z</tt> length modifiers are added.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>The <tt>a</tt> , <tt>A</tt> , and <tt>F</tt> conversion characters are added.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<p>XSI shading is removed from the description of character string representations of infinity and NaN floating-point values.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>The DESCRIPTION is updated to use the terms "conversion specifier" and "conversion specification" consistently.</p>
|
||||
|
||||
<p>ISO/IEC 9899:1999 standard, Technical Corrigendum No. 1 is incorporated.</p>
|
||||
</blockquote>
|
||||
|
||||
<div class="box"><em>End of informative text.</em></div>
|
||||
|
||||
<hr>
|
||||
<hr size="2" noshade>
|
||||
<center><font size="2"><!--footer start-->
|
||||
UNIX ® is a registered Trademark of The Open Group.<br>
|
||||
POSIX ® is a registered Trademark of The IEEE.<br>
|
||||
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
||||
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
||||
]</font></center>
|
||||
|
||||
<!--footer end-->
|
||||
<hr size="2" noshade>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Reference in New Issue
Block a user