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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 96c9d88bad9a7d7d44bfb7f26c226df7ee9ddf26 Maintainer: seros Status: ready -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fwrite">
 <refnamediv>
  <refname>fwrite</refname>
  <refpurpose>Escritura de un archivo en modo binario seguro</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>fwrite</methodname>
   <methodparam><type>resource</type><parameter>handle</parameter></methodparam>
   <methodparam><type>string</type><parameter>string</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
  </methodsynopsis>
  <simpara>
   <function>fwrite</function> escribe el contenido de
   <parameter>string</parameter> al flujo de archivo apuntado por
   <parameter>handle</parameter>. 
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>handle</parameter></term>
     <listitem>
      &fs.file.pointer;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       La cadena que va a ser escrita.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>length</parameter></term>
     <listitem>
      <para>
       Si se da el argumento <parameter>length</parameter>, la escritura
       se detendrá después de que <parameter>length</parameter> bytes hayan sido escritos o
       se alcance el final de <parameter>string</parameter>, lo que suceda
       primero.
      </para>
      <para>
       Observe que si el argumento <parameter>length</parameter> se da,
       la opción de configuración <link
       linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
       será ignorada y no se eliminarán las barras de <parameter>string</parameter>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <simpara>
   <function>fwrite</function> devuelve el número de bytes
   escritos, o &false; si se produjo un error.
  </simpara>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Escribir en un flujo de red puede terminar antes de que se haya escrito la cadena completa.
    El valor devuelto por <function>fwrite</function> se puede verificar:
    <programlisting role="php">
<![CDATA[
<?php
function flujo_fwrite($fp, $cadena) {
    for ($escrito = 0; $escrito < strlen($cadena); $escrito += $fwrite) {
        $fwrite = fwrite($fp, substr($cadena, $escrito));
        if ($fwrite === false) {
            return $escrito;
        }
    }
    return $escrito;
}
?>
]]>
    </programlisting>
   </para>
  </note>
  
  <note>
   <para>
    En sistemas en los que se diferencia entre archivos binarios y de texto
    (esto es, Windows) el archivo debe ser abierto con 'b' incluida en el
    parámetro modo de <function>fopen</function>.
   </para>
  </note>
  <note>
   <para>
    Si <parameter>handle</parameter> fue abierto por <function>fopen</function> en
    modo de adición, las escrituras de <function>fwrite</function> son atómicas (a menos
    que el tamaño de <parameter>string</parameter> exceda el tamaño de bloque del sistema
    de archivos, en algunas plataformas, siempre que el archivo esté en un sistema de
    archivos local). Es decir, no hay necesidad de bloquear un recurso con <function>flock</function>
    antes de llamar a <function>fwrite</function>; toda la información será escrita sin
    interrupciones.
   </para>
  </note>
  <note>
   <para>
    Si se escribe dos veces sobre el puntero al archivo la información será añadida al
    final del contenido del archivo:
        <programlisting role="php">
<![CDATA[
<?php
$fp = fopen('data.txt', 'w');
fwrite($fp, '1');
fwrite($fp, '23');
fclose($fp);

// ¡el contenido de 'data.txt' ahora es 123 y no 23!
?>
]]>
        </programlisting>
   </para>
  </note>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Un ejemplo sencillo de <function>fwrite</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$nombre_archivo = 'prueba.txt';
$contenido = "Añade esto al archivo\n";

// Primero vamos a asegurarnos de que el archivo existe y es escribible.
if (is_writable($nombre_archivo)) {

    // En nuestro ejemplo estamos abriendo $nombre_archivo en modo de adición.
    // El puntero al archivo está al final del archivo
    // donde irá $contenido cuando usemos fwrite() sobre él.
    if (!$gestor = fopen($nombre_archivo, 'a')) {
         echo "No se puede abrir el archivo ($nombre_archivo)";
         exit;
    }

    // Escribir $contenido a nuestro archivo abierto.
    if (fwrite($gestor, $contenido) === FALSE) {
        echo "No se puede escribir en el archivo ($nombre_archivo)";
        exit;
    }

    echo "Éxito, se escribió ($contenido) en el archivo ($nombre_archivo)";

    fclose($gestor);

} else {
    echo "El archivo $nombre_archivo no es escribible";
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>fread</function></member>
    <member><function>fopen</function></member>
    <member><function>fsockopen</function></member>
    <member><function>popen</function></member>
    <member><function>file_get_contents</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
-->