archived-doc-es/reference/filesystem/functions/fgets.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 8b5940cadeb4f1c8492f4a7f70743a2be807cf39 Maintainer: seros Status: ready -->
<!-- Reviewed: yes Maintainer: seros -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fgets">
 <refnamediv>
  <refname>fgets</refname>
  <refpurpose>Obtiene una línea desde el puntero a un fichero</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <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>
   Obtiene una línea desde el puntero al fichero.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>handle</parameter></term>
     <listitem>
      &fs.validfp.all;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>length</parameter></term>
     <listitem>
      <para>
       La lectura termina cuando se han leído <parameter>length</parameter> - 1
       bytes, o una nueva línea (la cual está incluida en el valor de retorno), o un EOF
       (lo que suceda primero). Si no se especifica una longitud, se seguirá
       leyendo desde el flujo hasta que alcance el final de la línea.
      </para>
      <note>
       <para>
        Hasta PHP 4.3.0, al omitirlo se asumía una longitud de línea de 1024.
        Si la mayoría de las lineas del fichero son todas mayores de 8KB,
        es más eficiente para el script en cuestión de recursos especificar la
        longitud máxima de línea.
       </para>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve una cadena de hasta <parameter>length</parameter> - 1 bytes leídos desde
   el fichero apuntado por <parameter>handle</parameter>. Si no hay más datos
   que leer en el puntero al fichero, devuelve &false;.
  </para>
  <para>
   Si se produjo un error, devuelve &false;.
  </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>
        <function>fgets</function> ahora es segura al trabajar con datos binarios
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Leer un fichero línea a línea</title>
    <programlisting role="php">
<![CDATA[
<?php
$gestor = @fopen("/tmp/inputfile.txt", "r");
if ($gestor) {
    while (($búfer = fgets($gestor, 4096)) !== false) {
        echo $búfer;
    }
    if (!feof($gestor)) {
        echo "Error: fallo inesperado de fgets()\n";
    }
    fclose($gestor);
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  &note.line-endings;
  <note>
   <para>
    Las personas que suele usar la semántica tipo 'C' de <function>fgets</function>
    deberían observar la diferencia de cómo se devuelve <literal>EOF</literal>.
   </para>
  </note>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>fgetss</function></member>
    <member><function>fread</function></member>
    <member><function>fgetc</function></member>
    <member><function>stream_get_line</function></member>
    <member><function>fopen</function></member>
    <member><function>popen</function></member>
    <member><function>fsockopen</function></member>
    <member><function>stream_set_timeout</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
-->