<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fscanf">
 <refnamediv>
  <refname>fscanf</refname>
  <refpurpose>Parses input from a file according to a format</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>mixed</type><methodname>fscanf</methodname>
   <methodparam><type>resource</type><parameter>handle</parameter></methodparam>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam choice="opt"><type>mixed</type><parameter role="reference">...</parameter></methodparam>
  </methodsynopsis>
  <para>
   The function <function>fscanf</function> is similar to
   <function>sscanf</function>, but it takes its input from a file
   associated with <parameter>handle</parameter> and interprets the
   input according to the specified <parameter>format</parameter>, which is
   described in the documentation for <function>sprintf</function>. 
  </para>
  <para>
   Any whitespace in the format string matches any whitespace in the input
   stream. This means that even a tab <literal>\t</literal> in the format
   string can match a single space character in the input stream.
  </para>
  <para>
   Each call to <function>fscanf</function> reads one line from the file.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>handle</parameter></term>
     <listitem>
      &fs.file.pointer;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       The specified format as described in the 
       <function>sprintf</function> documentation.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>...</parameter></term>
     <listitem>
      <para>
       The optional assigned values.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <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. 
  </para>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4.3.0</entry>
       <entry>
        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.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>fscanf</function> Example</title>
    <programlisting role="php">
<![CDATA[
<?php
$handle = fopen("users.txt", "r");
while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
    list ($name, $profession, $countrycode) = $userinfo;
    //... do something with the values
}
fclose($handle);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Contents of users.txt</title>
    <programlisting role="txt">
<![CDATA[
javier  argonaut        pe
hiroshi sculptor        jp
robert  slacker us
luigi   florist it
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>fread</function></member>
    <member><function>fgets</function></member>
    <member><function>fgetss</function></member>
    <member><function>sscanf</function></member>
    <member><function>printf</function></member>
    <member><function>sprintf</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->