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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
  <refentry id="function.fopen">
   <refnamediv>
    <refname>fopen</refname>
    <refpurpose>Opens file or URL</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <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>int</type><parameter>use_include_path</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>zcontext</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     <function>fopen</function> binds a named resource, specified
     by <parameter>filename</parameter>, to a stream.  If
     <parameter>filename</parameter> is of the form "scheme://...",
     it is assumed to be a URL and PHP will search for a protocol
     handler (also known as a wrapper) for that scheme. If no
     wrappers for that protocol are registered, PHP will emit
     a notice to help you track potential problems in your script
     and then continue as though <parameter>filename</parameter>
     specifies a regular file.
    </simpara>
    <simpara>
     If PHP has decided that <parameter>filename</parameter> specifies
     a local file, then it will try to open a stream on that file.
     The file must be accessible to PHP, so you need to ensure that
     the file access permissions allow this access.  
     If you have enabled &safemode;,
     or <link linkend="ini.open-basedir">open_basedir</link> further
     restrictions may apply.
    </simpara>
    <simpara>
     If PHP has decided that <parameter>filename</parameter> specifies
     a registered protocol, and that protocol is registered as a
     network URL, PHP will check to make sure that
     <link linkend="ini.allow-url-fopen">allow_url_fopen</link> is
     enabled. If it is switched off, PHP will emit a warning and
     the fopen call will fail.
    </simpara>
    <note>
     <simpara>
      The list of supported protocols can be found in <xref linkend="wrappers"/>.
      Some protocols (also referred to as <literal>wrappers</literal>) support
      <literal>context</literal> and/or <literal>php.ini</literal> options.
      Refer to the specific page for the protocol in use for a list of options
      which can be set. ( i.e. <literal>php.ini</literal> value 
      <literal>user_agent</literal> used by the <literal>http</literal> wrapper)
      For a description of <literal>contexts</literal> and the 
      <parameter>zcontext</parameter> parameter , refer to <xref linkend="ref.stream"/>.
     </simpara>
    </note>
    <para>
     The <parameter>mode</parameter> parameter specifies the type of access
     you require to the stream.  It may be any of the following:
     <table>
      <title>
       A list of possible modes for <function>fopen</function> 
       using <parameter>mode</parameter>
      </title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry><parameter>mode</parameter></entry>
         <entry>Description</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry><literal>'r'</literal></entry>
         <entry>
          Open for reading only; place the file pointer at the
          beginning of the file.
         </entry>
        </row>
        <row>
         <entry><literal>'r+'</literal></entry>
         <entry>
          Open for reading and writing; place the file pointer at
          the beginning of the file.
         </entry>
        </row>
        <row>
         <entry><literal>'w'</literal></entry>
         <entry>
          Open for writing only; place the file pointer at the
          beginning of the file and truncate the file to zero length.
          If the file does not exist, attempt to create it.
         </entry>
        </row>
        <row>
         <entry><literal>'w+'</literal></entry>
         <entry>
          Open for reading and writing; place the file pointer at
          the beginning of the file and truncate the file to zero
          length.  If the file does not exist, attempt to create it.
         </entry>
        </row>
        <row>
         <entry><literal>'a'</literal></entry>
         <entry>
          Open for writing only; place the file pointer at the end of 
	  the file. If the file does not exist, attempt to create it.
         </entry>
        </row>
        <row>
         <entry><literal>'a+'</literal></entry>
         <entry>
          Open for reading and writing; place the file pointer at
          the end of the file. If the file does not exist, attempt to
          create it.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <note>
     <para>
      The <parameter>mode</parameter> may contain the letter
      'b'. This is useful only on systems which differentiate between
      binary and text files (i.e. Windows. It's useless on Unix). 
      If not needed, this will be ignored.  You are encouraged to
      include the 'b' flag in order to make your scripts more portable.
     </para>
    </note>
    <para>
     The optional third <parameter>use_include_path</parameter> parameter 
     can be set to '1' or &true; if you want to search for the file in 
     the <link linkend="ini.include-path">include_path</link>, too.
    </para>
    <simpara>
     If the open fails, the function returns &false;.
    </simpara>
    <para>
     <example>
      <title><function>fopen</function> examples</title>
      <programlisting role="php">
<![CDATA[
<?php
$handle = fopen ("/home/rasmus/file.txt", "r");
$handle = fopen ("/home/rasmus/file.gif", "wb");
$handle = fopen ("http://www.example.com/", "r");
$handle = fopen ("ftp://user:password@example.com/somefile.txt", "w");
?>
]]>
      </programlisting>
     </example>
    </para>
    <simpara>
     If you are experiencing problems with reading and writing to
     files and you're using the server module version of PHP, remember
     to make sure that the files and directories you're using are
     accessible to the server process.
    </simpara>
    <para>
     On the Windows platform, be careful to escape any backslashes
     used in the path to the file, or use forward slashes.
     <informalexample>
      <programlisting role="php"> 
<![CDATA[
<?php
$handle = fopen ("c:\\data\\info.txt", "r");
?>
]]>
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     See also <xref linkend="wrappers"/>,
     <function>fclose</function>,
     <function>fgets</function>, 
     <function>fsockopen</function>,
     <function>file</function>,
     <function>file_exists</function>,
     <function>is_readable</function>,
     <function>socket_set_timeout</function>, and
     <function>popen</function>.
    </simpara>
   </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
-->