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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.25 $ -->
<!-- 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>bool</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>
    &note.context-support;
    <note>
     <simpara>
      As of PHP 4.3.2, the default mode is set to binary for all
      platforms that distinguish between binary and text mode.  If you are
      having problems with your scripts after upgrading, try using the
      <literal>'t'</literal> flag as a workaround until you have made your
      script more portable as mentioned below.
     </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>
        <row>
         <entry><literal>'x'</literal></entry>
         <entry>
          Create and open for writing only; place the file pointer at the
          beginning of the file.  If the file already exists, the 
          <function>fopen</function> call will fail by returning &false; and
          generating an error of level <constant>E_WARNING</constant>.  If
          the file does not exist, attempt to create it.  This is equivalent
          to specifying <literal>O_EXCL|O_CREAT</literal> flags for the
          underlying <literal>open(2)</literal> system call.  This option is
          supported in PHP 4.3.2 and later, and only works for local files.
         </entry>
        </row>
        <row>
         <entry><literal>'x+'</literal></entry>
         <entry>
          Create and open for reading and writing; place the file pointer at
          the beginning of the file.  If the file already exists, the 
          <function>fopen</function> call will fail by returning &false; and
          generating an error of level <constant>E_WARNING</constant>.  If
          the file does not exist, attempt to create it.  This is equivalent
          to specifying <literal>O_EXCL|O_CREAT</literal> flags for the
          underlying <literal>open(2)</literal> system call.  This option is
          supported in PHP 4.3.2 and later, and only works for local files.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <note>
     <para>
      Different operating system families have different line-ending
      conventions.  When you write a text file and want to insert a line
      break, you need to use the correct line-ending character(s) for your
      operating system.  Unix based systems use <literal>\n</literal> as the
      line ending character, Windows based systems use <literal>\r\n</literal>
      as the line ending characters and Macintosh based systems use
      <literal>\r</literal> as the line ending character.
     </para>
     <para>
      If you use the wrong line ending characters when writing your files, you
      might find that other applications that open those files will "look
      funny".
     </para>
     <para>
      Windows offers a text-mode translation flag (<literal>'t'</literal>)
      which will transparently translate <literal>\n</literal> to
      <literal>\r\n</literal> when working with the file.  In contrast, you
      can also use <literal>'b'</literal> to force binary mode, which will not
      translate your data.  To use these flags, specify either
      <literal>'b'</literal> or <literal>'t'</literal> as the last character
      of the <parameter>mode</parameter> parameter.
     </para>
     <para>
      The default translation mode depends on the SAPI and version of PHP that
      you are using, so you are encouraged to always specify the appropriate
      flag for portability reasons.  You should use the <literal>'t'</literal>
      mode if you are working with plain-text files and you use
      <literal>\n</literal> to delimit your line endings in your script, but
      expect your files to be readable with applications such as notepad.  You
      should use the <literal>'b'</literal> in all other cases.
     </para>
     <para>
      If you do not specify the 'b' flag when working with binary files, you
      may experience strange problems with your data, including broken image
      files and strange problems with <literal>\r\n</literal> characters.
     </para>
    </note>
    <note>
     <para>
      For portability, it is strongly recommended that you always
      use the 'b' flag when opening files with <function>fopen</function>.
     </para>
    </note>
    <note>
     <para>
      Again, for portability, it is also strongly recommended that
      you re-write code that uses or relies upon the <literal>'t'</literal>
      mode so that it uses the correct line endings and
      <literal>'b'</literal> mode instead.
     </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; and an error of 
     level <constant>E_WARNING</constant> is generated.  You may use
     <link linkend="language.operators.errorcontrol">@</link> to 
     suppress this warning.
    </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>
    &warn.ssl-non-standard;
    &note.sm.uidcheck.dir;
    <simpara>
     See also <xref linkend="wrappers"/>,
     <function>fclose</function>,
     <function>fgets</function>, 
     <function>fread</function>,
     <function>fwrite</function>,
     <function>fsockopen</function>,
     <function>file</function>,
     <function>file_exists</function>,
     <function>is_readable</function>,
     <function>stream_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
-->