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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- 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 &php.ini; options.
      Refer to the specific page for the protocol in use for a list of options
      which can be set. ( i.e. &php.ini; 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>
      On systems that differentiate between binary ('b') and text ('t') mode
      translation (such as Windows), the <parameter>mode</parameter> may contain
      either the letter 'b' or the letter 't' as the last character to force
      the translation mode to be either binary or text mode respectively.
     </para>
     <para>
      The default translation mode depends on the SAPI that you are using, so
      you are encouraged to always specify the appropriate flag; you will
      usually always want to specify 'b' if you intend for your script to be
      portable between different platforms.
     </para>
     <para>
      If you do not specify the 'b' flag when working with binary files, you
      will experience strange problems with your data, including broken image
      files and strange problems with <literal>\r\n</literal> characters.
     </para>
     <para>
      <emphasis>It is strongly recommended that you always use the 'b' flag
      when opening files with <function>fopen</function></emphasis>.
     </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
-->