499 lines
28 KiB
HTML
499 lines
28 KiB
HTML
<!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>fwscanf</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="fwscanf"></a> <a name="tag_03_206"></a><!-- fwscanf -->
|
|
<!--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_206_01"></a>NAME</h4>
|
|
|
|
<blockquote>fwscanf, swscanf, wscanf - convert formatted wide-character input</blockquote>
|
|
|
|
<h4><a name="tag_03_206_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 fwscanf(FILE *restrict</tt> <i>stream</i><tt>, const wchar_t *restrict</tt> <i>format</i><tt>, ... );<br>
|
|
int swscanf(const wchar_t *restrict</tt> <i>ws</i><tt>,<br>
|
|
const wchar_t *restrict</tt> <i>format</i><tt>, ... );<br>
|
|
int wscanf(const wchar_t *restrict</tt> <i>format</i><tt>, ... );<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_206_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>fwscanf</i>() function shall read from the named input <i>stream</i>. The <i>wscanf</i>() function shall read from the
|
|
standard input stream <i>stdin</i>. The <i>swscanf</i>() function shall read from the wide-character string <i>ws</i>. Each
|
|
function reads wide characters, interprets them according to a format, and stores the results in its arguments. Each expects, as
|
|
arguments, a control wide-character string <i>format</i> described below, and a set of <i>pointer</i> arguments indicating where
|
|
the converted input should be stored. The result is undefined if there are insufficient arguments for the format. 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}]. This feature provides for the definition of <i>format</i>
|
|
wide-character strings that select arguments in an order appropriate to specific languages. In <i>format</i> wide-character strings
|
|
containing the <tt>"%</tt><i>n</i><tt>$"</tt> form of conversion specifications, it is unspecified whether numbered arguments in
|
|
the argument list can be referenced from the <i>format</i> wide-character string more than once.</p>
|
|
|
|
<p>The <i>format</i> can contain either form of a conversion specification-that is, <tt>%</tt> or <tt>"%</tt><i>n</i><tt>$"</tt>-
|
|
but the two forms cannot normally be mixed within a single <i>format</i> wide-character string. The only exception to this is that
|
|
<tt>%%</tt> or <tt>%*</tt> can be mixed with the <tt>"%</tt><i>n</i><tt>$"</tt> form. 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
|
|
pointers. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></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>fwscanf</i>() function in all its forms allows for detection of a language-dependent radix character in the input string,
|
|
encoded 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>The <i>format</i> is a wide-character string composed of zero or more directives. Each directive is composed of one of the
|
|
following: one or more white-space wide characters ( <space>s, <tab>s, <newline>s, <vertical-tab>s, or
|
|
<form-feed>s); an ordinary wide character (neither <tt>'%'</tt> nor a white-space character); or a conversion specification.
|
|
Each conversion specification is introduced by a <tt>'%'</tt> <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src=
|
|
"../images/opt-start.gif" alt="[Option Start]" border="0"> or the 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>An optional assignment-suppressing character <tt>'*'</tt> .</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>An optional non-zero decimal integer that specifies the maximum field width.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>An optional length modifier that specifies the size of the receiving object.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A conversion specifier wide character that specifies the type of conversion to be applied. The valid conversion specifiers are
|
|
described below.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The <i>fwscanf</i>() functions shall execute each directive of the format in turn. If a directive fails, as detailed below, the
|
|
function shall return. Failures are described as input failures (due to the unavailability of input bytes) or matching failures
|
|
(due to inappropriate input).</p>
|
|
|
|
<p>A directive composed of one or more white-space wide characters is executed by reading input until no more valid input can be
|
|
read, or up to the first wide character which is not a white-space wide character, which remains unread.</p>
|
|
|
|
<p>A directive that is an ordinary wide character shall be executed as follows. The next wide character is read from the input and
|
|
compared with the wide character that comprises the directive; if the comparison shows that they are not equivalent, the directive
|
|
shall fail, and the differing and subsequent wide characters remain unread. Similarly, if end-of-file, an encoding error, or a read
|
|
error prevents a wide character from being read, the directive shall fail.</p>
|
|
|
|
<p>A directive that is a conversion specification defines a set of matching input sequences, as described below for each conversion
|
|
wide character. A conversion specification is executed in the following steps.</p>
|
|
|
|
<p>Input white-space wide characters (as specified by <a href="iswspace.html"><i>iswspace</i>()</a> ) shall be skipped, unless the
|
|
conversion specification includes a <tt>[</tt> , <tt>c</tt> , or <tt>n</tt> conversion specifier.</p>
|
|
|
|
<p>An item shall be read from the input, unless the conversion specification includes an <tt>n</tt> conversion specifier wide
|
|
character. An input item is defined as the longest sequence of input wide characters, not exceeding any specified field width,
|
|
which is an initial subsequence of a matching sequence. The first wide character, if any, after the input item shall remain unread.
|
|
If the length of the input item is zero, the execution of the conversion specification shall fail; this condition is a matching
|
|
failure, unless end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is an input
|
|
failure.</p>
|
|
|
|
<p>Except in the case of a <tt>%</tt> conversion specifier, the input item (or, in the case of a <tt>%n</tt> conversion
|
|
specification, the count of input wide characters) shall be converted to a type appropriate to the conversion wide character. If
|
|
the input item is not a matching sequence, the execution of the conversion specification shall fail; this condition is a matching
|
|
failure. Unless assignment suppression was indicated by a <tt>'*'</tt> , the result of the conversion shall be placed in the object
|
|
pointed to by the first argument following the <i>format</i> argument that has not already received a conversion result if the
|
|
conversion specification is introduced by <tt>%</tt> , <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src=
|
|
"../images/opt-start.gif" alt="[Option Start]" border="0"> or in the <i>n</i>th argument if introduced by the wide-character
|
|
sequence <tt>"%</tt><i>n</i><tt>$"</tt>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"> If this object does not
|
|
have an appropriate type, or if the result of the conversion cannot be represented in the space provided, the behavior is
|
|
undefined.</p>
|
|
|
|
<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> , <tt>X</tt> , or <tt>n</tt>
|
|
conversion specifier applies to an argument with type pointer to <b>signed char</b> or <b>unsigned char</b>.</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> , <tt>X</tt> , or <tt>n</tt>
|
|
conversion specifier applies to an argument with type pointer to <b>short</b> or <b>unsigned short</b>.</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> , <tt>X</tt> , or <tt>n</tt>
|
|
conversion specifier applies to an argument with type pointer to <b>long</b> or <b>unsigned long</b>; 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 an
|
|
argument with type pointer to <b>double</b>; or that a following <tt>c</tt> , <tt>s</tt> , or <tt>[</tt> conversion specifier
|
|
applies to an argument with type pointer to <b>wchar_t</b>.</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> , <tt>X</tt> , or <tt>n</tt> conversion
|
|
specifier applies to an argument with type pointer to <b>long long</b> or <b>unsigned long long</b>.</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> , <tt>X</tt> , or <tt>n</tt>
|
|
conversion specifier applies to an argument with type pointer to <b>intmax_t</b> or <b>uintmax_t</b>.</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> , <tt>X</tt> , or <tt>n</tt>
|
|
conversion specifier applies to an argument with type pointer to <b>size_t</b> or the corresponding signed integer type.</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> , <tt>X</tt> , or <tt>n</tt>
|
|
conversion specifier applies to an argument with type pointer to <b>ptrdiff_t</b> or the corresponding <b>unsigned</b> type.</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 an argument with type pointer to <b>long double</b>.</dd>
|
|
</dl>
|
|
|
|
<p>If a length modifier appears with any conversion specifier other than as specified above, the behavior is undefined.</p>
|
|
|
|
<p>The following conversion specifier wide characters are valid:</p>
|
|
|
|
<dl compact>
|
|
<dt><tt>d</tt></dt>
|
|
|
|
<dd>Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence of <a href=
|
|
"../functions/wcstol.html"><i>wcstol</i>()</a> with the value 10 for the <i>base</i> argument. In the absence of a size modifier,
|
|
the application shall ensure that the corresponding argument is a pointer to <b>int</b>.</dd>
|
|
|
|
<dt><tt>i</tt></dt>
|
|
|
|
<dd>Matches an optionally signed integer, whose format is the same as expected for the subject sequence of <a href=
|
|
"../functions/wcstol.html"><i>wcstol</i>()</a> with 0 for the <i>base</i> argument. In the absence of a size modifier, the
|
|
application shall ensure that the corresponding argument is a pointer to <b>int</b>.</dd>
|
|
|
|
<dt><tt>o</tt></dt>
|
|
|
|
<dd>Matches an optionally signed octal integer, whose format is the same as expected for the subject sequence of <a href=
|
|
"../functions/wcstoul.html"><i>wcstoul</i>()</a> with the value 8 for the <i>base</i> argument. In the absence of a size modifier,
|
|
the application shall ensure that the corresponding argument is a pointer to <b>unsigned</b>.</dd>
|
|
|
|
<dt><tt>u</tt></dt>
|
|
|
|
<dd>Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence of <a href=
|
|
"../functions/wcstoul.html"><i>wcstoul</i>()</a> with the value 10 for the <i>base</i> argument. In the absence of a size modifier,
|
|
the application shall ensure that the corresponding argument is a pointer to <b>unsigned</b>.</dd>
|
|
|
|
<dt><tt>x</tt></dt>
|
|
|
|
<dd>Matches an optionally signed hexadecimal integer, whose format is the same as expected for the subject sequence of <a href=
|
|
"../functions/wcstoul.html"><i>wcstoul</i>()</a> with the value 16 for the <i>base</i> argument. In the absence of a size modifier,
|
|
the application shall ensure that the corresponding argument is a pointer to <b>unsigned</b>.</dd>
|
|
|
|
<dt><tt>a</tt>, <tt>e</tt>, <tt>f</tt>, <tt>g</tt></dt>
|
|
|
|
<dd><br>
|
|
Matches an optionally signed floating-point number, infinity, or NaN whose format is the same as expected for the subject sequence
|
|
of <a href="../functions/wcstod.html"><i>wcstod</i>()</a>. In the absence of a size modifier, the application shall ensure that the
|
|
corresponding argument is a pointer to <b>float</b>.
|
|
|
|
<p>If the <a href="../functions/fwprintf.html"><i>fwprintf</i>()</a> family of functions generates character string representations
|
|
for infinity and NaN (a symbolic entity encoded in floating-point format) to support IEEE Std 754-1985, the
|
|
<i>fwscanf</i>() family of functions shall recognize them as input.</p>
|
|
</dd>
|
|
|
|
<dt><tt>s</tt></dt>
|
|
|
|
<dd>Matches a sequence of non white-space wide characters. If no <tt>l</tt> (ell) qualifier is present, characters from the input
|
|
field shall be converted as if by repeated calls to the <a href="../functions/wcrtomb.html"><i>wcrtomb</i>()</a> function, with the
|
|
conversion state described by an <b>mbstate_t</b> object initialized to zero before the first wide character is converted. The
|
|
application shall ensure that the corresponding argument is a pointer to a character array large enough to accept the sequence and
|
|
the terminating null character, which shall be added automatically.
|
|
|
|
<p>Otherwise, the application shall ensure that the corresponding argument is a pointer to an array of <b>wchar_t</b> large enough
|
|
to accept the sequence and the terminating null wide character, which shall be added automatically.</p>
|
|
</dd>
|
|
|
|
<dt><tt>[</tt></dt>
|
|
|
|
<dd>Matches a non-empty sequence of wide characters from a set of expected wide characters (the <i>scanset</i>). If no <tt>l</tt>
|
|
(ell) qualifier is present, wide characters from the input field shall be converted as if by repeated calls to the <a href=
|
|
"../functions/wcrtomb.html"><i>wcrtomb</i>()</a> function, with the conversion state described by an <b>mbstate_t</b> object
|
|
initialized to zero before the first wide character is converted. The application shall ensure that the corresponding argument is a
|
|
pointer to a character array large enough to accept the sequence and the terminating null character, which shall be added
|
|
automatically.
|
|
|
|
<p>If an <tt>l</tt> (ell) qualifier is present, the application shall ensure that the corresponding argument is a pointer to an
|
|
array of <b>wchar_t</b> large enough to accept the sequence and the terminating null wide character, which shall be added
|
|
automatically.</p>
|
|
|
|
<p>The conversion specification includes all subsequent wide characters in the <i>format</i> string up to and including the
|
|
matching right square bracket ( <tt>']'</tt> ). The wide characters between the square brackets (the <i>scanlist</i>) comprise the
|
|
scanset, unless the wide character after the left square bracket is a circumflex ( <tt>'^'</tt> ), in which case the scanset
|
|
contains all wide characters that do not appear in the scanlist between the circumflex and the right square bracket. If the
|
|
conversion specification begins with <tt>"[]"</tt> or <tt>"[^]"</tt> , the right square bracket is included in the scanlist and the
|
|
next right square bracket is the matching right square bracket that ends the conversion specification; otherwise, the first right
|
|
square bracket is the one that ends the conversion specification. If a <tt>'-'</tt> is in the scanlist and is not the first wide
|
|
character, nor the second where the first wide character is a <tt>'^'</tt> , nor the last wide character, the behavior is
|
|
implementation-defined.</p>
|
|
</dd>
|
|
|
|
<dt><tt>c</tt></dt>
|
|
|
|
<dd>Matches a sequence of wide characters of exactly the number specified by the field width (1 if no field width is present in the
|
|
conversion specification).
|
|
|
|
<p>If no <tt>l</tt> (ell) length modifier is present, characters from the input field shall be converted as if by repeated calls to
|
|
the <a href="../functions/wcrtomb.html"><i>wcrtomb</i>()</a> function, with the conversion state described by an <b>mbstate_t</b>
|
|
object initialized to zero before the first wide character is converted. The corresponding argument shall be a pointer to the
|
|
initial element of a character array large enough to accept the sequence. No null character is added.</p>
|
|
|
|
<p>If an <tt>l</tt> (ell) length modifier is present, the corresponding argument shall be a pointer to the initial element of an
|
|
array of <b>wchar_t</b> large enough to accept the sequence. No null wide character is added.</p>
|
|
|
|
<p>Otherwise, the application shall ensure that the corresponding argument is a pointer to an array of <b>wchar_t</b> large enough
|
|
to accept the sequence. No null wide character is added.</p>
|
|
</dd>
|
|
|
|
<dt><tt>p</tt></dt>
|
|
|
|
<dd>Matches an implementation-defined set of sequences, which shall be the same as the set of sequences that is produced by the
|
|
<tt>%p</tt> conversion specification of the corresponding <a href="../functions/fwprintf.html"><i>fwprintf</i>()</a> functions. The
|
|
application shall ensure that the corresponding argument is a pointer to a pointer to <b>void</b>. The interpretation of the input
|
|
item is implementation-defined. If the input item is a value converted earlier during the same program execution, the pointer that
|
|
results shall compare equal to that value; otherwise, the behavior of the <tt>%p</tt> conversion is undefined.</dd>
|
|
|
|
<dt><tt>n</tt></dt>
|
|
|
|
<dd>No input is consumed. The application shall ensure that the corresponding argument is a pointer to the integer into which is to
|
|
be written the number of wide characters read from the input so far by this call to the <i>fwscanf</i>() functions. Execution of a
|
|
<tt>%n</tt> conversion specification shall not increment the assignment count returned at the completion of execution of the
|
|
function. No argument shall be converted, but one shall be consumed. If the conversion specification includes an
|
|
assignment-suppressing wide character or a field width, 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>Matches a single <tt>'%'</tt> wide character; no conversion or assignment shall occur. The complete conversion specification
|
|
shall be <tt>%%</tt> .</dd>
|
|
</dl>
|
|
|
|
<p>If a conversion specification is invalid, the behavior is undefined.</p>
|
|
|
|
<p>The conversion specifiers <tt>A</tt> , <tt>E</tt> , <tt>F</tt> , <tt>G</tt> , and <tt>X</tt> are also valid and shall be
|
|
equivalent to, respectively, <tt>a</tt> , <tt>e</tt> , <tt>f</tt> , <tt>g</tt> , and <tt>x</tt> .</p>
|
|
|
|
<p>If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs before any wide characters matching
|
|
the current conversion specification (except for <tt>%n</tt> ) have been read (other than leading white-space, where permitted),
|
|
execution of the current conversion specification shall terminate with an input failure. Otherwise, unless execution of the current
|
|
conversion specification is terminated with a matching failure, execution of the following conversion specification (if any) shall
|
|
be terminated with an input failure.</p>
|
|
|
|
<p>Reaching the end of the string in <i>swscanf</i>() shall be equivalent to encountering end-of-file for <i>fwscanf</i>().</p>
|
|
|
|
<p>If conversion terminates on a conflicting input, the offending input shall be left unread in the input. Any trailing white space
|
|
(including <newline>) shall be left unread unless matched by a conversion specification. The success of literal matches and
|
|
suppressed assignments is only directly determinable via the <tt>%n</tt> conversion specification.</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>fwscanf</i>() and <i>wscanf</i>() functions may mark the <i>st_atime</i> field of the file associated with <i>stream</i> for
|
|
update. The <i>st_atime</i> field shall be marked for update by the first successful execution of <a href=
|
|
"../functions/fgetc.html"><i>fgetc</i>()</a>, <a href="../functions/fgetwc.html"><i>fgetwc</i>()</a>, <a href=
|
|
"../functions/fgets.html"><i>fgets</i>()</a>, <a href="../functions/fgetws.html"><i>fgetws</i>()</a>, <a href=
|
|
"../functions/fread.html"><i>fread</i>()</a>, <a href="../functions/getc.html"><i>getc</i>()</a>, <a href=
|
|
"../functions/getwc.html"><i>getwc</i>()</a>, <a href="../functions/getchar.html"><i>getchar</i>()</a>, <a href=
|
|
"../functions/getwchar.html"><i>getwchar</i>()</a>, <a href="../functions/gets.html"><i>gets</i>()</a>, <a href=
|
|
"../functions/fscanf.html"><i>fscanf</i>()</a>, or <i>fwscanf</i>() using <i>stream</i> that returns data not supplied by a prior
|
|
call to <a href="../functions/ungetc.html"><i>ungetc</i>()</a>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_206_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, these functions shall return the number of successfully matched and assigned input items; this
|
|
number can be zero in the event of an early matching failure. If the input ends before the first matching failure or conversion,
|
|
EOF shall be returned. If a read error occurs, the error indicator for the stream is set, EOF shall be returned, <sup>[<a href=
|
|
"javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> and
|
|
<i>errno</i> shall be set to indicate the error. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_206_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>For the conditions under which the <i>fwscanf</i>() functions shall fail and may fail, refer to <a href=
|
|
"fgetwc.html"><i>fgetwc</i>()</a> .</p>
|
|
|
|
<p>In addition, <i>fwscanf</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">
|
|
Input byte sequence does not form a valid character. <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>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_206_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The call:</p>
|
|
|
|
<pre>
|
|
<tt>int i, n; float x; char name[50];
|
|
n = wscanf(L"%d%f%s", &i, &x, name);
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>with the input line:</p>
|
|
|
|
<pre>
|
|
<tt>25 54.32E-1 Hamster
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>assigns to <i>n</i> the value 3, to <i>i</i> the value 25, to <i>x</i> the value 5.432, and <i>name</i> contains the string
|
|
<tt>"Hamster"</tt> .</p>
|
|
|
|
<p>The call:</p>
|
|
|
|
<pre>
|
|
<tt>int i; float x; char name[50];
|
|
(void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name);
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>with input:</p>
|
|
|
|
<pre>
|
|
<tt>56789 0123 56a72
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>assigns 56 to <i>i</i>, 789.0 to <i>x</i>, skips 0123, and places the string <tt>"56\0"</tt> in <i>name</i>. The next call to <a
|
|
href="../functions/getchar.html"><i>getchar</i>()</a> shall return the character <tt>'a'</tt> .</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_206_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>In format strings containing the <tt>'%'</tt> form of conversion specifications, each argument in the argument list is used
|
|
exactly once.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_206_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_206_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_206_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="getwc.html"><i>getwc</i>()</a> , <a href="fwprintf.html"><i>fwprintf</i>()</a> , <a href=
|
|
"setlocale.html"><i>setlocale</i>()</a> , <a href="wcstod.html"><i>wcstod</i>()</a> , <a href="wcstol.html"><i>wcstol</i>()</a> ,
|
|
<a href="wcstoul.html"><i>wcstoul</i>()</a> , <a href="wcrtomb.html"><i>wcrtomb</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/langinfo.h.html"><i><langinfo.h></i></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_206_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_206_12"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<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>fwscanf</i>() and <i>swscanf</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>
|
|
</ul>
|
|
|
|
<p>The DESCRIPTION is updated to use the terms "conversion specifier" and "conversion specification" consistently.</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>
|
|
|