<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual describes how to install and use the GNU multiple precision
arithmetic library, version 6.1.0.
Copyright 1991, 1993-2015 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 no Invariant Sections,
with the Front-Cover Texts being "A GNU Manual", and with the Back-Cover
Texts being "You have freedom to copy and modify this GNU Manual, like GNU
software". A copy of the license is included in
GNU Free Documentation License. -->
<!-- Created by GNU Texinfo 6.4, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Formatted Input Functions (GNU MP 6.1.0)</title>
<meta name="description" content="How to install and use the GNU multiple precision arithmetic library, version 6.1.0.">
<meta name="keywords" content="Formatted Input Functions (GNU MP 6.1.0)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="Formatted-Input.html#Formatted-Input" rel="up" title="Formatted Input">
<link href="C_002b_002b-Formatted-Input.html#C_002b_002b-Formatted-Input" rel="next" title="C++ Formatted Input">
<link href="Formatted-Input-Strings.html#Formatted-Input-Strings" rel="prev" title="Formatted Input Strings">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<a name="Formatted-Input-Functions"></a>
<div class="header">
<p>
Next: <a href="C_002b_002b-Formatted-Input.html#C_002b_002b-Formatted-Input" accesskey="n" rel="next">C++ Formatted Input</a>, Previous: <a href="Formatted-Input-Strings.html#Formatted-Input-Strings" accesskey="p" rel="prev">Formatted Input Strings</a>, Up: <a href="Formatted-Input.html#Formatted-Input" accesskey="u" rel="up">Formatted Input</a> [<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Formatted-Input-Functions-1"></a>
<h3 class="section">11.2 Formatted Input Functions</h3>
<a name="index-Input-functions-3"></a>
<p>Each of the following functions is similar to the corresponding C library
function. The plain <code>scanf</code> forms take a variable argument list. The
<code>vscanf</code> forms take an argument pointer, see <a href="http://www.gnu.org/software/libc/manual/html_node/Variadic-Functions.html#Variadic-Functions">Variadic Functions</a> in <cite>The GNU C Library Reference Manual</cite>, or ‘<samp>man 3
va_start</samp>’.
</p>
<p>It should be emphasised that if a format string is invalid, or the arguments
don’t match what the format specifies, then the behaviour of any of these
functions will be unpredictable. GCC format string checking is not available,
since it doesn’t recognise the GMP extensions.
</p>
<p>No overlap is permitted between the <var>fmt</var> string and any of the results
produced.
</p>
<dl>
<dt><a name="index-gmp_005fscanf"></a>Function: <em>int</em> <strong>gmp_scanf</strong> <em>(const char *<var>fmt</var>, …)</em></dt>
<dt><a name="index-gmp_005fvscanf"></a>Function: <em>int</em> <strong>gmp_vscanf</strong> <em>(const char *<var>fmt</var>, va_list <var>ap</var>)</em></dt>
<dd><p>Read from the standard input <code>stdin</code>.
</p></dd></dl>
<dl>
<dt><a name="index-gmp_005ffscanf"></a>Function: <em>int</em> <strong>gmp_fscanf</strong> <em>(FILE *<var>fp</var>, const char *<var>fmt</var>, …)</em></dt>
<dt><a name="index-gmp_005fvfscanf"></a>Function: <em>int</em> <strong>gmp_vfscanf</strong> <em>(FILE *<var>fp</var>, const char *<var>fmt</var>, va_list <var>ap</var>)</em></dt>
<dd><p>Read from the stream <var>fp</var>.
</p></dd></dl>
<dl>
<dt><a name="index-gmp_005fsscanf"></a>Function: <em>int</em> <strong>gmp_sscanf</strong> <em>(const char *<var>s</var>, const char *<var>fmt</var>, …)</em></dt>
<dt><a name="index-gmp_005fvsscanf"></a>Function: <em>int</em> <strong>gmp_vsscanf</strong> <em>(const char *<var>s</var>, const char *<var>fmt</var>, va_list <var>ap</var>)</em></dt>
<dd><p>Read from a null-terminated string <var>s</var>.
</p></dd></dl>
<p>The return value from each of these functions is the same as the standard C99
<code>scanf</code>, namely the number of fields successfully parsed and stored.
‘<samp>%n</samp>’ fields and fields read but suppressed by ‘<samp>*</samp>’ don’t count
towards the return value.
</p>
<p>If end of input (or a file error) is reached before a character for a field or
a literal, and if no previous non-suppressed fields have matched, then the
return value is <code>EOF</code> instead of 0. A whitespace character in the format
string is only an optional match and doesn’t induce an <code>EOF</code> in this
fashion. Leading whitespace read and discarded for a field don’t count as
characters for that field.
</p>
<p>For the GMP types, input parsing follows C99 rules, namely one character of
lookahead is used and characters are read while they continue to meet the
format requirements. If this doesn’t provide a complete number then the
function terminates, with that field not stored nor counted towards the return
value. For instance with <code>mpf_t</code> an input ‘<samp>1.23e-XYZ</samp>’ would be read
up to the ‘<samp>X</samp>’ and that character pushed back since it’s not a digit. The
string ‘<samp>1.23e-</samp>’ would then be considered invalid since an ‘<samp>e</samp>’ must
be followed by at least one digit.
</p>
<p>For the standard C types, in the current implementation GMP calls the C
library <code>scanf</code> functions, which might have looser rules about what
constitutes a valid input.
</p>
<p>Note that <code>gmp_sscanf</code> is the same as <code>gmp_fscanf</code> and only does one
character of lookahead when parsing. Although clearly it could look at its
entire input, it is deliberately made identical to <code>gmp_fscanf</code>, the same
way C99 <code>sscanf</code> is the same as <code>fscanf</code>.
</p>
<hr>
<div class="header">
<p>
Next: <a href="C_002b_002b-Formatted-Input.html#C_002b_002b-Formatted-Input" accesskey="n" rel="next">C++ Formatted Input</a>, Previous: <a href="Formatted-Input-Strings.html#Formatted-Input-Strings" accesskey="p" rel="prev">Formatted Input Strings</a>, Up: <a href="Formatted-Input.html#Formatted-Input" accesskey="u" rel="up">Formatted Input</a> [<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>