<refentry id="scanf">
<refnamediv>
<refname>Scanf</refname>
<refname>Fscanf</refname>
<refname>Sscanf</refname>
<refpurpose>input string interpretation</refpurpose>
</refnamediv>

<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;stdio.h&gt;
</funcsynopsisinfo>
<funcprototype>
  <funcdef><function>fscanf</function></funcdef>
  <paramdef>FILE *<parameter>fp</parameter></paramdef>
  <paramdef>char *<parameter>control</parameter></paramdef>
  <paramdef>char *<parameter>pointer...</parameter></paramdef>
</funcprototype>

<funcprototype>
  <funcdef><function>scanf</function></funcdef>
  <paramdef>char *<parameter>control</parameter></paramdef>
  <paramdef>char *<parameter>pointer...</parameter></paramdef>
</funcprototype>

<funcprototype>
  <funcdef><function>sscanf</function></funcdef>
  <paramdef>char *<parameter>string</parameter></paramdef>
  <paramdef>char *<parameter>control</parameter></paramdef>
  <paramdef>char *<parameter>pointer...</parameter></paramdef>
</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
These functions perform the complement to "printf()" etc.
</para>
<para>
Fscanf performs conversions from the file "fp", scanf from the
standard input, and sscanf from the string pointed to by
"string".
</para>
<para>
Each function expects a control string containing conversion
specifications, and zero or more pointers to objects into which
the converted values are stored.
</para>
<para>
The control string may contain three types of fields:
<orderedlist numeration="loweralpha" spacing="compact">
<listitem><para>
Space, tab characters, or "\n" which match any of
the three in the input.
</para></listitem>
<listitem><para>
Characters not among the above and not "%" which must
match characters in the input.
</para></listitem>
<listitem><para>
A "%" followed by an optional "*" indicates
suppression of assignment, an optional field width
maximum and a conversion character indicating the
type expected.
</para></listitem>
</orderedlist>
</para>
<para>
A conversion character controls the conversion to be applied
to the next field and indicates the type of the corresponding
pointer argument. A field consists of consecutive non-space
characters and ends at either a character inappropiate for the
conversion or when a specified field is exhausted.
When one field is finished, white-space characters are passed
over until the next field is found.
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="0.5in"/>
<colspec colwidth="3.5in"/>
<tbody>
<row>
<entry>d</entry>
<entry>A decimal string is to be converted to an integer.</entry>
</row>
<row>
<entry>o</entry>
<entry>An octal string; the coresponding argument should
point to an integer.</entry>
</row>
<row>
<entry>x</entry>
<entry>A hexadecimal string for conversion to an integer.</entry>
</row>
<row>
<entry>s</entry>
<entry>A string of non-space characters is expected and
will be copied to the buffer pointed to by the
corresponding argument and a null ("\0") appended.
The user must ensure that the buffer is large
enough. The input string is considered terminated
by a space, tab of ("\n").</entry>
</row>
<row>
<entry>c</entry>
<entry>A character is expected and is copied into the byte
pointed to by the argument. The white-space
skipping is suppressed for this conversion. If a
field width is given, the argument is assumed to
point to a character array and the number of
characters indicated is copied to it. NOTE to ensure
that the next non-white-space character is read use
"%1s" and that TWO bytes are pointed to by the
argument.</entry>
</row>
<row>
<entry>e,f</entry>
<entry>A floating point representation is expected on the
input and the argument must be a pointer to a float.
Any of the usual ways of writing floating point
numbers are recognized.</entry>
</row>
<row>
<entry>[</entry>
<entry>This denotes the start of a set of match characters;
the inclusion or exclusion of which delimits the
input field. The white-space skipping is
suppressed. The corresponding argument should be a
pointer to a character array. If the first
character in the match string is not "^",
characters are copied from the input as long as they
can be found in the match string. If the first
character is the "^", copying continues while characters
cannot be found in the match string. The match
string is delimited by a "]".</entry>
</row>
<row>
<entry>D,O,X</entry>
<entry>Similar to d,o,x above, but the corresponding
argument is considered to point to a long integer.</entry>
</row>
<row>
<entry>E,F</entry>
<entry>Similar to e,f above, but the corresponding
should point to a double.</entry>
</row>
<row>
<entry>%</entry>
<entry>A match for "%" is sought; no conversion takes place.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
Each of the functions returns a count of the number of
fields successfully matched and assigned.
</para>
</refsect1>

<refsect1><title>Caveats</title>
<para>
The returned count of matches/assigments does not include
character matches and assigments suppressed by "*". The
arguments must ALL be pointers. It is a common error to call
scanf with the value of an item rather than a pointer to it.
</para>
</refsect1>

<refsect1><title>Diagnostics</title>
<para>
These functions return EOF on end of input or error and a count
which is shorter than expected for unexpected or unmatched
items.
</para>
</refsect1>

<refsect1><title>See Also</title>
<para>
<link linkend="atof">Atoi(), atof()</link>,
<link linkend="getc">getc()</link>,
<link linkend="printf">printf()</link>
Kernighan and Ritchie pp 147-150
</para>
</refsect1>

</refentry>