fscanf.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.fscanf" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>fscanf</refname>
  <refpurpose>Parses input from a file according to a format</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>int</type><type>false</type><type>null</type></type><methodname>fscanf</methodname>
   <methodparam><type>resource</type><parameter>stream</parameter></methodparam>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</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>stream</parameter> and interprets the
   input according to the specified <parameter>format</parameter>. 
  </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>stream</parameter></term>
     <listitem>
      &fs.file.pointer;
     </listitem>
    </varlistentry>
    &strings.scanf.parameter.format;
    <varlistentry>
     <term><parameter>vars</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>
  <para>
   If there are more substrings expected in the <parameter>format</parameter>
   than there are available within <parameter>string</parameter>,
   &null; will be returned. On other errors, &false; will be returned.
  </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
-->