php-doc-en/reference/filesystem/functions/fgets.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
<!-- 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, the length defaults to 1k, or 1024 bytes.
    </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, if omitted, it would assume 1024 as the line length.
      As of PHP 4.3, omitting <parameter>length</parameter> will keep
      reading from the stream until it reaches the end of the line.
      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>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
-->