mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 18:38:55 +00:00
ef51b90769
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@303804 c90b9560-bf6c-de11-be94-00142212c4b1
398 lines
14 KiB
XML
398 lines
14 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fopen">
|
|
<refnamediv>
|
|
<refname>fopen</refname>
|
|
<refpurpose>Opens file or 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> binds a named resource, specified by
|
|
<parameter>filename</parameter>, to a stream.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>filename</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
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. (e.g.
|
|
&php.ini; value <literal>user_agent</literal> used by the
|
|
<literal>http</literal> wrapper).
|
|
</para>
|
|
</note>
|
|
<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:\\folder\\resource.txt", "r");
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>mode</parameter></term>
|
|
<listitem>
|
|
<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.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>'x+'</literal></entry>
|
|
<entry>
|
|
Create and open for reading and writing; otherwise it has the
|
|
same behavior as <literal>'x'</literal>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>'c'</literal></entry>
|
|
<entry>
|
|
Open the file for writing only. If the file does not exist, it is
|
|
created. If it exists, it is neither truncated (as opposed to
|
|
<literal>'w'</literal>), nor the call to this function fails (as is
|
|
the case with <literal>'x'</literal>). The file pointer is
|
|
positioned on the beginning of the file. This may be useful if it's
|
|
desired to get an advisory lock (see <function>flock</function>)
|
|
before attempting to modify the file, as using
|
|
<literal>'w'</literal> could truncate the file before the lock
|
|
was obtained (if truncation is desired,
|
|
<function>ftruncate</function> can be used after the lock is
|
|
requested).
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>'c+'</literal></entry>
|
|
<entry>
|
|
Open the file for reading and writing; otherwise it has the same
|
|
behavior as <literal>'c'</literal>.
|
|
</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>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>use_include_path</parameter></term>
|
|
<listitem>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>context</parameter></term>
|
|
<listitem>
|
|
¬e.context-support;
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
Returns a file pointer resource on success, or &false; on error.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="errors">
|
|
&reftitle.errors;
|
|
<para>
|
|
If the open fails, an error of level
|
|
<constant>E_WARNING</constant> is generated. You may use <link
|
|
linkend="language.operators.errorcontrol">@</link> to suppress this
|
|
warning.
|
|
</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>4.3.2</entry>
|
|
<entry>
|
|
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 before
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>4.3.2</entry>
|
|
<entry>
|
|
The <literal>'x'</literal> and <literal>'x+'</literal> options were
|
|
added
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.2.6</entry>
|
|
<entry>
|
|
The <literal>'c'</literal> and <literal>'c+'</literal> options were
|
|
added
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<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>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
&warn.ssl-non-standard;
|
|
¬e.sm.uidcheck.dir;
|
|
<para>
|
|
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.
|
|
</para>
|
|
</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>
|
|
</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
|
|
-->
|