<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Parses input from a file according to a format</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.fread.html">fread</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.fseek.html">fseek</a></div>
<div class="up"><a href="ref.filesystem.html">Filesystem Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.fscanf" class="refentry">
<div class="refnamediv">
<h1 class="refname">fscanf</h1>
<p class="verinfo">(PHP 4 >= 4.0.1, PHP 5)</p><p class="refpurpose"><span class="refname">fscanf</span> — <span class="dc-title">Parses input from a file according to a format</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.fscanf-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <span class="methodname"><strong>fscanf</strong></span>
( <span class="methodparam"><span class="type">resource</span> <code class="parameter">$handle</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$format</code></span>
[, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter reference">&$...</code></span>
] )</div>
<p class="para rdfs-comment">
The function <span class="function"><strong>fscanf()</strong></span> is similar to
<span class="function"><a href="function.sscanf.html" class="function">sscanf()</a></span>, but it takes its input from a file
associated with <em><code class="parameter">handle</code></em> and interprets the
input according to the specified <em><code class="parameter">format</code></em>, which is
described in the documentation for <span class="function"><a href="function.sprintf.html" class="function">sprintf()</a></span>.
</p>
<p class="para">
Any whitespace in the format string matches any whitespace in the input
stream. This means that even a tab <em>\t</em> in the format
string can match a single space character in the input stream.
</p>
<p class="para">
Each call to <span class="function"><strong>fscanf()</strong></span> reads one line from the file.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.fscanf-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">handle</code></em></span>
<dd>
<p class="para">A file system pointer <span class="type"><a href="language.types.resource.html" class="type resource">resource</a></span>
that is typically created using <span class="function"><a href="function.fopen.html" class="function">fopen()</a></span>.</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">format</code></em></span>
<dd>
<p class="para">
The specified format as described in the
<span class="function"><a href="function.sprintf.html" class="function">sprintf()</a></span> documentation.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">...</code></em></span>
<dd>
<p class="para">
The optional assigned values.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.fscanf-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
If only two parameters were passed to this function, the values parsed will be
returned as an array. Otherwise, if optional parameters are passed, the
function will return the number of assigned values. The optional
parameters must be passed by reference.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.fscanf-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>4.3.0</td>
<td>
Before this time, the maximum number of characters read from
the file was 512 (or up to the first \n, whichever came first).
But now, arbitrarily long lines will be read and scanned.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.fscanf-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-2391">
<p><strong>Example #1 <span class="function"><strong>fscanf()</strong></span> Example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$handle </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">"users.txt"</span><span style="color: #007700">, </span><span style="color: #DD0000">"r"</span><span style="color: #007700">);<br />while (</span><span style="color: #0000BB">$userinfo </span><span style="color: #007700">= </span><span style="color: #0000BB">fscanf</span><span style="color: #007700">(</span><span style="color: #0000BB">$handle</span><span style="color: #007700">, </span><span style="color: #DD0000">"%s\t%s\t%s\n"</span><span style="color: #007700">)) {<br /> list (</span><span style="color: #0000BB">$name</span><span style="color: #007700">, </span><span style="color: #0000BB">$profession</span><span style="color: #007700">, </span><span style="color: #0000BB">$countrycode</span><span style="color: #007700">) = </span><span style="color: #0000BB">$userinfo</span><span style="color: #007700">;<br /> </span><span style="color: #FF8000">//... do something with the values<br /></span><span style="color: #007700">}<br /></span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$handle</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-2392">
<p><strong>Example #2 Contents of users.txt</strong></p>
<div class="example-contents">
<div class="txtcode"><pre class="txtcode">javier argonaut pe
hiroshi sculptor jp
robert slacker us
luigi florist it</pre>
</div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-function.fscanf-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.fread.html" class="function" rel="rdfs-seeAlso">fread()</a> - Binary-safe file read</span></li>
<li class="member"> <span class="function"><a href="function.fgets.html" class="function" rel="rdfs-seeAlso">fgets()</a> - Gets line from file pointer</span></li>
<li class="member"> <span class="function"><a href="function.fgetss.html" class="function" rel="rdfs-seeAlso">fgetss()</a> - Gets line from file pointer and strip HTML tags</span></li>
<li class="member"> <span class="function"><a href="function.sscanf.html" class="function" rel="rdfs-seeAlso">sscanf()</a> - Parses input from a string according to a format</span></li>
<li class="member"> <span class="function"><a href="function.printf.html" class="function" rel="rdfs-seeAlso">printf()</a> - Output a formatted string</span></li>
<li class="member"> <span class="function"><a href="function.sprintf.html" class="function" rel="rdfs-seeAlso">sprintf()</a> - Return a formatted string</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.fread.html">fread</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.fseek.html">fseek</a></div>
<div class="up"><a href="ref.filesystem.html">Filesystem Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
