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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d32fe0ca648f1c3537545b5f30f788386ddcee7b Maintainer: seros Status: ready -->
<!-- Reviewed: no -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fopen">
 <refnamediv>
  <refname>fopen</refname>
  <refpurpose>Abre un fichero o un URL</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>resource</type><methodname>fopen</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam><type>string</type><parameter>mode</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter><initializer>false</initializer></methodparam>
   <methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>fopen</function> asocia un recurso con nombre, especificado por
   <parameter>filename</parameter>, a un flujo. 
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       Si <parameter>filename</parameter> está en la forma "esquema://...", se
       asume que será un URL y PHP buscará un gestor de protocolos
       (también conocido como envoltura) para ese protocolo. Si no está registrada
       ninguna envoltura para ese protocolo, PHP emitirá un aviso para ayudar a rastrear
       problemas potenciales en el script y continuará como si
       <parameter>filename</parameter> especificara un fichero normal.
      </para>
      <para>
       Si PHP ha decidido que <parameter>filename</parameter> especifica
       un fichero local, intentará abrir un flujo para ese fichero.
       El fichero debe ser accesible para PHP, por lo que es necesario asegurarse de que
       los permisos de acceso del fichero permiten este acceso.
       Si está habilitado el &safemode;
       o <link linkend="ini.open-basedir">open_basedir</link> se pueden aplicar
       más restricciones.
      </para>
      <para>
       Si PHP ha decidido que <parameter>filename</parameter> especifica
       un protocolo registrado, y ese protocolo está registrado como un
       URL de red, PHP se asegurará de que
       <link linkend="ini.allow-url-fopen">allow_url_fopen</link> está
       habilitado. Si es desactivado, PHP emitirá un aviso y
       la llamada a fopen fallará.
      </para>
      <note>
       <para>
        La lista de protocolos soportados se puede encontrar en <xref
        linkend="wrappers"/>. Algunos protocolos (también descritos como
        <literal>envolturas</literal>) soportan <literal>contexto</literal>
        y/u opciones de &php.ini;. Consulte la página específica del protocolo
        en uso para una lista de opciones que se pueden establecer. (p.ej.
        el valor <literal>user_agent</literal> en &php.ini; usado por la
        envoltura <literal>http</literal>).
       </para>
      </note>
      <para>
       En la plataforma Windows, asegúrese de escapar cualquier barra invertida
       usada en la ruta de fichero, o use barras hacia delante.
       <informalexample>
        <programlisting role="php">
<![CDATA[
<?php
$gestor = fopen("c:\\folder\\resource.txt", "r");
?>
]]>
        </programlisting>
       </informalexample>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       El parámetro <parameter>mode</parameter> especifica el tipo de acceso
       que se necesita para el flujo. Puede ser cualquiera de los siguientes:
       <table>
        <title>
         Una lista de los modos posibles de <function>fopen</function>
         usando <parameter>mode</parameter>
        </title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry><parameter>mode</parameter></entry>
           <entry>Descripción</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><literal>'r'</literal></entry>
           <entry>
            Apertura para sólo lectura; coloca el puntero al fichero al
            principio del fichero.
           </entry>
          </row>
          <row>
           <entry><literal>'r+'</literal></entry>
           <entry>
            Apertura para lectura y escritura; coloca el puntero al fichero al
            principio del fichero.
           </entry>
          </row>
          <row>
           <entry><literal>'w'</literal></entry>
           <entry>
            Apertura para sólo escritura; coloca el puntero al fichero al
            principio del fichero y trunca el fichero a longitud cero.
            Si el fichero no existe se intenta crear.
           </entry>
          </row>
          <row>
           <entry><literal>'w+'</literal></entry>
           <entry>
            Apertura para lectura y escritura; coloca el puntero al fichero al
            principio del fichero y trunca el fichero a longitud cero.
            Si el fichero no existe se intenta crear.
           </entry>
          </row>
          <row>
           <entry><literal>'a'</literal></entry>
           <entry>
            Apertura para sólo escritura; coloca el puntero del fichero al
            final del mismo. Si el fichero no existe, se intenta crear.
            En este modo, <function>fseek</function> solamente afecta a
            la posición de lectura; las lecturas siempre son pospuestas.
           </entry>
          </row>
          <row>
           <entry><literal>'a+'</literal></entry>
           <entry>
            Apertura para lectura y escritura; coloca el puntero del fichero al
            final del mismo. Si el fichero no existe, se intenta crear.
            En este modo, <function>fseek</function> no tiene efecto, las escrituras siempre son pospuestas.
           </entry>
          </row>
          <row>
           <entry><literal>'x'</literal></entry>
           <entry>
            Creación y apertura para sólo escritura; coloca el puntero del fichero al
            principio del mismo. Si el fichero ya existe, la
            llamada a <function>fopen</function> fallará devolviendo &false; y
            generando un error de nivel <constant>E_WARNING</constant>. Si
            el fichero no exite se intenta crear. Esto es equivalente
            a especificar las banderas <literal>O_EXCL|O_CREAT</literal> para la
            llamada al sistema de <literal>open(2)</literal> subyacente.
           </entry>
          </row>
          <row>
           <entry><literal>'x+'</literal></entry>
           <entry>
            Creación y apertura para lectura y escritura; de otro modo tiene
            el mismo comportamiento que <literal>'x'</literal>.
           </entry>
          </row>
          <row>
           <entry><literal>'c'</literal></entry>
           <entry>
            Abrir el fichero para sólo escritura. Si el fichero no existe, se
            crea. Si existe no es truncado (a diferencia de
            <literal>'w'</literal>), ni la llamada a esta función falla (como en
            el caso con <literal>'x'</literal>). El puntero al fichero se
            posiciona en el principio del fichero. Esto puede ser útil si
            se desea obtener un bloqueo asistido (véase <function>flock</function>)
            antes de intentar modificar el fichero, ya que al usar
            <literal>'w'</literal> se podría truncar el fichero antes de haber
            obtenido el bloqueo (si se desea truncar el fichero,
            se puede usar <function>ftruncate</function> después de solicitar el
            bloqueo).
           </entry>
          </row>
          <row>
           <entry><literal>'c+'</literal></entry>
           <entry>
            Abrir el fichero para lectura y escritura; de otro modo tiene el mismo
            comportamiento que <literal>'c'</literal>.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <note>
       <para>
        Diferentes familias de sistemas operativos tienen diferentes convenciones
        para el final de línea. Cuando escribe un fichero de texto y quiere insertar un salto
        de línea, necesita usar el carácter o caracteres correctos de final de línea para su
        sistema operativo. Los sistemas basados en Unix usan <literal>\n</literal> como el
        carácter de final de línea, los sistemas basados en Windows usan <literal>\r\n</literal>
        como caracteres de final de línea y los sistemas basados en Macintosh usan
        <literal>\r</literal> como carácter de final de línea.
       </para>
       <para>
        Si usa los caracteres de final de línea erróneos cuando escribe sus ficheros, se
        podrá encontrar con que otras aplicaciones que abran esos ficheros "parecerán
        raras".
       </para>
       <para>
        Windows ofrece una bandera de traducción en modo texto (<literal>'t'</literal>)
        que traducirá de manera transparente <literal>\n</literal> a
        <literal>\r\n</literal> cuando se trabaja con el fichero. En contraste, puede
        usar <literal>'b'</literal> para forzar el modo binario, lo cual no
        traducirá su información. Para usar estas banderas, especifique
        <literal>'b'</literal> o <literal>'t'</literal> como el último carácter
        del parámetro <parameter>mode</parameter>.
       </para>
       <para>
        El modo de traducción predeterminado depende de la SAPI y de la versión de PHP que
        esté usando, por lo que se le anima a especificar siempre la bandera
        apropiada por razones de portabilidad. Debería usar el modo <literal>'t'</literal>
        si está trabajando con ficheros de texto plano y usa
        <literal>\n</literal> para delimitar los finales de línea es su script, pero
        confíe que sus ficheros serán legibles por aplicaciones tales como notepad. Debería
        usar <literal>'b'</literal> en los demás casos.
       </para>
       <para>
        Si no especifica la bandera 'b' cuando está trabajando con ficheros binarios,
        puede experimentar problemas extraños con su información, incluidos ficheros imagen
        rotos o problemas extraños con los caracteres <literal>\r\n</literal>.
       </para>
      </note>
      <note>
       <para>
        Por portabilidad, se recomienda encarecidamente que siempre use
        la bandera 'b' cuando se abran ficheros con <function>fopen</function>.
       </para>
      </note>
      <note>
       <para>
        De nuevo, por portabilidad, también se recomienda encarecidamente que
        reescriba el código que usa o depende del modo <literal>'t'</literal>
        por lo que use los finales de línea correctos y el modo
        <literal>'b'</literal> en su lugar.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>use_include_path</parameter></term>
     <listitem>
      <para>
       El tercer parámetro opcional <parameter>use_include_path</parameter>
       puede ser establecido a '1' o &true; si se desea buscar un fichero en
       <link linkend="ini.include-path">include_path</link> también.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>context</parameter></term>
     <listitem>
      &note.context-support;
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve un recurso de puntero a fichero si tiene éxito, o &false; si se produjo un error.
  </para>
 </refsect1>
 
 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Si la apertura falla, se generea un error de nivel
   <constant>E_WARNING</constant>. Se puede usar <link
   linkend="language.operators.errorcontrol">@</link> para suprimir esta
   advertencia.
  </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>5.2.6</entry>
       <entry>
        Se añadieron las opciones <literal>'c'</literal> y
        <literal>'c+'</literal>
       </entry>
      </row>
      <row>
       <entry>4.3.2</entry>
       <entry>
        A partir de PHP 4.3.2, el modo predeterminado se establece a binario para todas las
        plataformas que distinguen entre modo binario y modo texto. Si está teniendo
        problemas con sus scripts después de una acutalización, intente usar la
        bandera <literal>'t'</literal> como solución alternativa hasta que haya hecho su
        script más portable, como se mencionó antes
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplos de <function>fopen</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$gestor = fopen("/home/rasmus/fichero.txt", "r");
$gestor = fopen("/home/rasmus/fichero.gif", "wb");
$gestor = fopen("http://www.example.com/", "r");
$gestor = fopen("ftp://user:password@example.com/fichero.txt", "w");
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  &warn.ssl-non-standard;
  &note.sm.uidcheck.dir;
  <note>
   <para>
    Si está experimentando problemas al leer y escribir ficheros y
    está usando la versión de módulo de servidor de PHP, asegúrese de que
    los ficheros y directorios que está usando sean accesibles por el proceso
    del servidor.
   </para>
  </note>
  <note>
   <para>
    Esta función también podría tener éxito cuando <parameter>filename</parameter> es un
    directorio. Si no se está seguro de que <parameter>filename</parameter> sea un
    fichero o un directorio, podría ser necesario utilzar la función
    <function>is_dir</function> antes de llamar a <function>fopen</function>.
   </para>
  </note>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><xref linkend="wrappers"/></member>
    <member><function>fclose</function></member>
    <member><function>fgets</function></member>
    <member><function>fread</function></member>
    <member><function>fwrite</function></member>
    <member><function>fsockopen</function></member>
    <member><function>file</function></member>
    <member><function>file_exists</function></member>
    <member><function>is_readable</function></member>
    <member><function>stream_set_timeout</function></member>
    <member><function>popen</function></member>
    <member><function>stream_context_create</function></member>
    <member><function>umask</function></member>
    <member><classname>SplFileObject</classname></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
-->