<html lang="en">
<head>
<title>Formatted Input Basics - The GNU C Library</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="The GNU C Library">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Formatted-Input.html#Formatted-Input" title="Formatted Input">
<link rel="next" href="Input-Conversion-Syntax.html#Input-Conversion-Syntax" title="Input Conversion Syntax">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU C library.

This is Edition 0.12, last updated 2007-10-27,
of `The GNU C Library Reference Manual', for version
2.8 (Sourcery G++ Lite 2011.03-41).

Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.  Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Formatted-Input-Basics"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Input-Conversion-Syntax.html#Input-Conversion-Syntax">Input Conversion Syntax</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Formatted-Input.html#Formatted-Input">Formatted Input</a>
<hr>
</div>

<h4 class="subsection">12.14.1 Formatted Input Basics</h4>

<p>Calls to <code>scanf</code> are superficially similar to calls to
<code>printf</code> in that arbitrary arguments are read under the control of
a template string.  While the syntax of the conversion specifications in
the template is very similar to that for <code>printf</code>, the
interpretation of the template is oriented more towards free-format
input and simple pattern matching, rather than fixed-field formatting. 
For example, most <code>scanf</code> conversions skip over any amount of
&ldquo;white space&rdquo; (including spaces, tabs, and newlines) in the input
file, and there is no concept of precision for the numeric input
conversions as there is for the corresponding output conversions. 
Ordinarily, non-whitespace characters in the template are expected to
match characters in the input stream exactly, but a matching failure is
distinct from an input error on the stream. 
<a name="index-conversion-specifications-_0028_0040code_007bscanf_007d_0029-1076"></a>
Another area of difference between <code>scanf</code> and <code>printf</code> is
that you must remember to supply pointers rather than immediate values
as the optional arguments to <code>scanf</code>; the values that are read are
stored in the objects that the pointers point to.  Even experienced
programmers tend to forget this occasionally, so if your program is
getting strange errors that seem to be related to <code>scanf</code>, you
might want to double-check this.

   <p>When a <dfn>matching failure</dfn> occurs, <code>scanf</code> returns immediately,
leaving the first non-matching character as the next character to be
read from the stream.  The normal return value from <code>scanf</code> is the
number of values that were assigned, so you can use this to determine if
a matching error happened before all the expected values were read. 
<a name="index-matching-failure_002c-in-_0040code_007bscanf_007d-1077"></a>
The <code>scanf</code> function is typically used for things like reading in
the contents of tables.  For example, here is a function that uses
<code>scanf</code> to initialize an array of <code>double</code>:

<pre class="smallexample">     void
     readarray (double *array, int n)
     {
       int i;
       for (i=0; i&lt;n; i++)
         if (scanf (" %lf", &amp;(array[i])) != 1)
           invalid_input_error ();
     }
</pre>
   <p>The formatted input functions are not used as frequently as the
formatted output functions.  Partly, this is because it takes some care
to use them properly.  Another reason is that it is difficult to recover
from a matching error.

   <p>If you are trying to read input that doesn't match a single, fixed
pattern, you may be better off using a tool such as Flex to generate a
lexical scanner, or Bison to generate a parser, rather than using
<code>scanf</code>.  For more information about these tools, see <a href="../flex/index.html#Top">Top</a>, and <a href="../bison/index.html#Top">Top</a>.

   </body></html>