<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<!-- EN-Revision: 18bac8389b98d513c89e965000086acfcdfdd0a9 Maintainer: Marqitos 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 class="union"><type>resource</type><type>false</type></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 class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></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

<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

$handle = 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>

Abre para lectura y escritura; de otro modo, tiene

el mismo comportamiento que <literal>'w'</literal>.

</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> no tiene efecto, escribe siempre agregando.

</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> solo afecta

a la posición de lectura, escribe siempre agregando.

</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 existe se intenta crear. Esto es equivalente

a especificar las flags <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>

Abre 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>

Abre el fichero para lectura y escritura; de otro modo tiene el mismo

comportamiento que <literal>'c'</literal>.

</entry>

</row>

<row>

<entry><literal>'e'</literal></entry>

<entry>

Establece el flag 'close-on-exec' en el descriptor de fichero abierto. Disponible

solamente en PHP compilado en sistemas compatibles con POSIX.1-2008.

</entry>

</row>

<row>

<entry><literal>'n'</literal></entry>

<entry>

Establecer el flag de no bloqueo en el descriptor de fichero abierto. Disponible

solamente en PHP compilado en sistemas compatibles con POSIX.1-2008.

</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 un flag de trasnformación en modo texto (<literal>'t'</literal>)

que transformará 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

transformará su información. Para usar estas flags, especifique

<literal>'b'</literal> o <literal>'t'</literal> como el último carácter

del parámetro <parameter>mode</parameter>.

</para>

<para>

El modo de transformación por omición es <literal>'b'</literal>.

Puede 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

espera que sus ficheros sean legibles con aplicaciones como versiones antiguas de notepad. Debería

usar el <literal>'b'</literal> en todos los demás casos.

</para>

<para>

Si especifica el flag 't' cuando trabaja con archivos binarios,

puede experimentar problemas extraños con sus datos, incluyendo archivos de imagen rotos

y problemas extraños con los caracteres <literal>\r\n</literal>.

</para>

</note>

<note>

<para>

Por portabilidad, También se recomienda encarecidamente que

reescriba el código que usa o se basa en el modo <literal>'t'</literal>

para que use las terminaciones de línea correctas y el modo

<literal>'b'</literal> en su lugar.

</para>

</note>

<note>

<simpara>

El <parameter>mode</parameter> modo es ignorado para <filename>php://output</filename>,

<filename>php://input</filename>, <filename>php://stdin</filename>,

<filename>php://stdout</filename>, <filename>php://stderr</filename> Y

envoluturas de flujo <filename>php://fd</filename>.

</simpara>

</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 también en

<link linkend="ini.include-path">include_path</link>.

</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,

&return.falseforfailure;

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

&fs.emits.warning.on.failure;

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>7.0.16, 7.1.2</entry>

<entry>

Se añadió la opción <literal>'e'</literal>.

</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

$handle = fopen("/home/rasmus/fichero.txt", "r");

$handle = fopen("/home/rasmus/fichero.gif", "wb");

$handle = fopen("http://www.ejemplo.com/", "r");

$handle = fopen("ftp://user:[email protected]/fichero.txt", "w");

?>

]]>

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

&warn.ssl-non-standard;

<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

-->