521 lines
29 KiB
HTML
521 lines
29 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>fscanf</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="fscanf"></a> <a name="tag_03_190"></a><!-- fscanf -->
|
|
<!--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_190_01"></a>NAME</h4>
|
|
|
|
<blockquote>fscanf, scanf, sscanf - convert formatted input</blockquote>
|
|
|
|
<h4><a name="tag_03_190_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/stdio.h.html">stdio.h</a>><br>
|
|
<br>
|
|
int fscanf(FILE *restrict</tt> <i>stream</i><tt>, const char *restrict</tt> <i>format</i><tt>, ... );<br>
|
|
int scanf(const char *restrict</tt> <i>format</i><tt>, ... );<br>
|
|
int sscanf(const char *restrict</tt> <i>s</i><tt>, const char *restrict</tt> <i>format</i><tt>, ... );<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_190_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>fscanf</i>() function shall read from the named input <i>stream</i>. The <i>scanf</i>() function shall read from the
|
|
standard input stream <i>stdin</i>. The <i>sscanf</i>() function shall read from the string <i>s</i>. Each function reads bytes,
|
|
interprets them according to a format, and stores the results in its arguments. Each expects, as arguments, a control 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 format is exhausted while arguments remain, the
|
|
excess arguments shall be evaluated but 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 character <tt>%</tt> (see below) is replaced by the sequence
|
|
<tt>"%</tt><i>n</i><tt>$"</tt>, where <i>n</i> is a decimal integer in the range [1,{NL_ARGMAX}]. This feature provides for the
|
|
definition of format strings that select arguments in an order appropriate to specific languages. In format 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 format 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 be mixed within a single <i>format</i> 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>fscanf</i>() function in all its forms shall allow detection of a language-dependent radix character in the input string. 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 format is a character string, beginning and ending in its initial shift state, if any, composed of zero or more directives.
|
|
Each directive is composed of one of the following: one or more white-space characters ( <space>s, <tab>s,
|
|
<newline>s, <vertical-tab>s, or <form-feed>s); an ordinary character (neither <tt>'%'</tt> nor a white-space
|
|
character); or a conversion specification. Each conversion specification is introduced by the character <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
|
|
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>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 option length modifier that specifies the size of the receiving object.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A <i>conversion specifier</i> character that specifies the type of conversion to be applied. The valid conversion specifiers are
|
|
described below.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The <i>fscanf</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 characters shall be executed by reading input until no more valid input can be
|
|
read, or up to the first byte which is not a white-space character, which remains unread.</p>
|
|
|
|
<p>A directive that is an ordinary character shall be executed as follows: the next byte shall be read from the input and compared
|
|
with the byte that comprises the directive; if the comparison shows that they are not equivalent, the directive shall fail, and the
|
|
differing and subsequent bytes shall remain unread. Similarly, if end-of-file, an encoding error, or a read error prevents a
|
|
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
|
|
character. A conversion specification shall be executed in the following steps.</p>
|
|
|
|
<p>Input white-space characters (as specified by <a href="isspace.html"><i>isspace</i>()</a> ) shall be skipped, unless the
|
|
conversion specification includes a <tt>[</tt> , <tt>c</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. An input
|
|
item shall be defined as the longest sequence of input bytes (up to any specified maximum field width, which may be measured in
|
|
characters or bytes dependent on the conversion specifier) which is an initial subsequence of a matching sequence. The first byte,
|
|
if any, after the input item shall remain unread. If the length of the input item is 0, 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 bytes) shall be converted to a type appropriate to the conversion character. If the input item is
|
|
not a matching sequence, the execution of the conversion specification fails; 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 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>[</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 specifiers 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/strtol.html"><i>strtol</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/strtol.html"><i>strtol</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/strtoul.html"><i>strtoul</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/strtoul.html"><i>strtoul</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/strtoul.html"><i>strtoul</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/strtod.html"><i>strtod</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/fprintf.html"><i>fprintf</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>fscanf</i>() family of functions shall recognize them as input.</p>
|
|
</dd>
|
|
|
|
<dt><tt>s</tt></dt>
|
|
|
|
<dd>Matches a sequence of bytes that are not white-space characters. The application shall ensure that the corresponding argument
|
|
is a pointer to the initial byte of an array of <b>char</b>, <b>signed char</b>, or <b>unsigned char</b> large enough to accept the
|
|
sequence and a terminating null character code, which shall be added automatically.
|
|
|
|
<p>If an <tt>l</tt> (ell) qualifier is present, the input is a sequence of characters that begins in the initial shift state. Each
|
|
character shall be converted to a wide character as if by a call 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. 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 bytes from a set of expected bytes (the <i>scanset</i>). The normal skip over white-space
|
|
characters shall be suppressed in this case. The application shall ensure that the corresponding argument is a pointer to the
|
|
initial byte of an array of <b>char</b>, <b>signed char</b>, or <b>unsigned char</b> large enough to accept the sequence and a
|
|
terminating null byte, which shall be added automatically.
|
|
|
|
<p>If an <tt>l</tt> (ell) qualifier is present, the input is a sequence of characters that begins in the initial shift state. Each
|
|
character in the sequence shall be converted to a wide character as if by a call 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. 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 bytes in the <i>format</i> string up to and including the matching right
|
|
square bracket ( <tt>']'</tt> ). The bytes between the square brackets (the <i>scanlist</i>) comprise the scanset, unless the byte
|
|
after the left square bracket is a circumflex ( <tt>'^'</tt> ), in which case the scanset contains all bytes 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 character, nor the second where the first
|
|
character is a <tt>'^'</tt> , nor the last character, the behavior is implementation-defined.</p>
|
|
</dd>
|
|
|
|
<dt><tt>c</tt></dt>
|
|
|
|
<dd>Matches a sequence of bytes of the number specified by the field width (1 if no field width is present in the conversion
|
|
specification). The application shall ensure that the corresponding argument is a pointer to the initial byte of an array of
|
|
<b>char</b>, <b>signed char</b>, or <b>unsigned char</b> large enough to accept the sequence. No null byte is added. The normal
|
|
skip over white-space characters shall be suppressed in this case.
|
|
|
|
<p>If an <tt>l</tt> (ell) qualifier is present, the input shall be a sequence of characters that begins in the initial shift state.
|
|
Each character in the sequence is converted to a wide character as if by a call 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. The application shall ensure that the corresponding argument is a
|
|
pointer to an array of <b>wchar_t</b> large enough to accept the resulting sequence of wide characters. 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/fprintf.html"><i>fprintf</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 specification 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 shall
|
|
be written the number of bytes read from the input so far by this call to the <i>fscanf</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
|
|
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> character; no conversion or assignment occurs. 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 <tt>a</tt> , <tt>e</tt> , <tt>f</tt> , <tt>g</tt> , and <tt>x</tt> , respectively.</p>
|
|
|
|
<p>If end-of-file is encountered during input, conversion shall be terminated. If end-of-file occurs before any bytes matching the
|
|
current conversion specification (except for <tt>%n</tt> ) have been read (other than leading white-space characters, 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>sscanf</i>() shall be equivalent to encountering end-of-file for <i>fscanf</i>().</p>
|
|
|
|
<p>If conversion terminates on a conflicting input, the offending input is left unread in the input. Any trailing white space
|
|
(including <newline>s) 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>fscanf</i>() and <i>scanf</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/fgets.html"><i>fgets</i>()</a>, <a href=
|
|
"../functions/fread.html"><i>fread</i>()</a>, <a href="../functions/getc.html"><i>getc</i>()</a>, <a href=
|
|
"../functions/getchar.html"><i>getchar</i>()</a>, <a href="../functions/gets.html"><i>gets</i>()</a>, <i>fscanf</i>(), or
|
|
<i>fscanf</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_190_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_190_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>For the conditions under which the <i>fscanf</i>() functions fail and may fail, refer to <a href="fgetc.html"><i>fgetc</i>()</a>
|
|
or <a href="fgetwc.html"><i>fgetwc</i>()</a> .</p>
|
|
|
|
<p>In addition, <i>fscanf</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_190_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The call:</p>
|
|
|
|
<pre>
|
|
<tt>int i, n; float x; char name[50];
|
|
n = scanf("%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) scanf("%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>
|
|
|
|
<h5><a name="tag_03_190_06_01"></a>Reading Data into an Array</h5>
|
|
|
|
<p>The following call uses <i>fscanf</i>() to read three floating-point numbers from standard input into the <i>input</i>
|
|
array.</p>
|
|
|
|
<pre>
|
|
<tt>float input[3]; fscanf (stdin, "%f %f %f", input, input+1, input+2);
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_190_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>If the application calling <i>fscanf</i>() has any objects of type <b>wint_t</b> or <b>wchar_t</b>, it must also include the <a
|
|
href="../basedefs/wchar.h.html"><i><wchar.h></i></a> header to have these objects defined.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_190_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>This function is aligned with the ISO/IEC 9899:1999 standard, and in doing so a few "obvious" things were not included.
|
|
Specifically, the set of characters allowed in a scanset is limited to single-byte characters. In other similar places, multi-byte
|
|
characters have been permitted, but for alignment with the ISO/IEC 9899:1999 standard, it has not been done here. Applications
|
|
needing this could use the corresponding wide-character functions to achieve the desired results.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_190_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_190_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="getc.html"><i>getc</i>()</a> , <a href="printf.html"><i>printf</i>()</a> , <a href=
|
|
"setlocale.html"><i>setlocale</i>()</a> , <a href="strtod.html"><i>strtod</i>()</a> , <a href="strtol.html"><i>strtol</i>()</a> ,
|
|
<a href="strtoul.html"><i>strtoul</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_190_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 1. Derived from Issue 1 of the SVID.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_190_12"></a>Issue 5</h4>
|
|
|
|
<blockquote>
|
|
<p>Aligned with ISO/IEC 9899:1990/Amendment 1:1995 (E). Specifically, the <tt>l</tt> (ell) qualifier is now defined for the
|
|
<tt>c</tt> , <tt>s</tt> , and <tt>[</tt> conversion specifiers.</p>
|
|
|
|
<p>The DESCRIPTION is updated to indicate that if infinity and NaN can be generated by the <a href=
|
|
"../functions/fprintf.html"><i>fprintf</i>()</a> family of functions, then they are recognized by the <i>fscanf</i>() family.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_190_13"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The Open Group Corrigenda U021/7 and U028/10 are applied. These correct several occurrences of "characters" in the text which
|
|
have been replaced with the term "bytes".</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>fscanf</i>(), <i>scanf</i>(), and <i>sscanf</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>
|
|
|