<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
  <refentry id="function.fgets">
   <refnamediv>
    <refname>fgets</refname>
    <refpurpose>Gets line from file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>fgets</methodname>
      <methodparam><type>resource</type><parameter>handle</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns a string of up to <parameter>length</parameter> - 1 bytes read from
     the file pointed to by <parameter>handle</parameter>. Reading ends when
     <parameter>length</parameter> - 1 bytes have been read, on a newline (which is
     included in the return value), or on EOF (whichever comes first). If no length
     is specified, it will keep reading from the stream until it reaches 
     the end of the line.
    </para>
    <para>
     If an error occurs, returns &false;.
    </para>
    <para>
     Common Pitfalls:
    </para>
    <simpara>
     People used to the 'C' semantics of <function>fgets</function>
     should note the difference in how <literal>EOF</literal> is returned.
    </simpara>
    
    &fs.validfp.all;

    <para>
     A simple example follows:
     <example> 
      <title>Reading a file line by line</title>
      <programlisting role="php">
<![CDATA[
<?php
$handle = @fopen("/tmp/inputfile.txt", "r");
if ($handle) {
    while (!feof($handle)) {
        $buffer = fgets($handle, 4096);
        echo $buffer;
    }
    fclose($handle);
}
?>
]]>
      </programlisting>
     </example>
    </para>
    <note>
     <simpara>
      The <parameter>length</parameter> parameter became optional in PHP
      4.2.0. Until PHP 4.3.0, omitting it would assume 1024 as the line length.
      If the majority of the lines in the file are all larger than 8KB,
      it is more resource efficient for your script to specify the maximum
      line length.
     </simpara>
    </note>
    <note>
     <simpara>
      This function is binary safe as of PHP 4.3.  Earlier versions
      were not binary safe.
     </simpara>
    </note>
    &note.line-endings;
    <para> 
     See also <function>fgetss</function>
     <function>fread</function>, 
     <function>fgetc</function>,
     <function>stream_get_line</function>,
     <function>fopen</function>,
     <function>popen</function>, 
     <function>fsockopen</function>, and
     <function>stream_set_timeout</function>.
    </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:"../../../../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
-->