sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-17 01:18:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

WS, preparing for the new doc style

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@228836 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2007-02-03 08:13:44 +00:00
parent b45863667f
commit a142babd0f
72 changed files with 3599 additions and 3597 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

84
reference/filesystem/functions/basename.xml
View file

@ -1,34 +1,34 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.basename">
<refnamediv>
<refname>basename</refname>
<refpurpose>Returns filename component of path</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>basename</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>suffix</parameter></methodparam>
</methodsynopsis>
<para>
Given a string containing a path to a file, this function will
return the base name of the file.
If the filename ends in <parameter>suffix</parameter> this will
also be cut off.
</para>
<para>
On Windows, both slash (<literal>/</literal>) and backslash
(<literal>\</literal>) are used as directory separator character. In
other environments, it is the forward slash
(<literal>/</literal>).
</para>
<para>
<example>
<title><function>basename</function> example</title>
<programlisting role="php">
<refentry id="function.basename">
<refnamediv>
<refname>basename</refname>
<refpurpose>Returns filename component of path</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>basename</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>suffix</parameter></methodparam>
</methodsynopsis>
<para>
Given a string containing a path to a file, this function will
return the base name of the file.
If the filename ends in <parameter>suffix</parameter> this will
also be cut off.
</para>
<para>
On Windows, both slash (<literal>/</literal>) and backslash
(<literal>\</literal>) are used as directory separator character. In
other environments, it is the forward slash
(<literal>/</literal>).
</para>
<para>
<example>
<title><function>basename</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$path = "/home/httpd/html/index.php";
@ -36,19 +36,19 @@ $file = basename($path); // $file is set to "index.php"
$file = basename($path, ".php"); // $file is set to "index"
?>
]]>
</programlisting>
</example>
</para>
<note>
<para>
The <parameter>suffix</parameter> parameter was added in PHP 4.1.0.
</para>
</note>
<para>
See also <function>dirname</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<note>
<para>
The <parameter>suffix</parameter> parameter was added in PHP 4.1.0.
</para>
</note>
<para>
See also <function>dirname</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

60
reference/filesystem/functions/chgrp.xml
View file

@ -1,35 +1,35 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.chgrp">
<refnamediv>
<refname>chgrp</refname>
<refpurpose>Changes file group</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>chgrp</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>mixed</type><parameter>group</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to change the group of the file <parameter>filename</parameter>
to <parameter>group</parameter> (specified by name or number). Only the
superuser may change the group of a file arbitrarily; other users may
change the group of a file to any group of which that user is a member.
</para>
<para>
&return.success;
</para>
&note.no-remote;
&note.sm.uidcheck;
<para>
See also <function>chown</function> and
<function>chmod</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.chgrp">
<refnamediv>
<refname>chgrp</refname>
<refpurpose>Changes file group</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>chgrp</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>mixed</type><parameter>group</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to change the group of the file <parameter>filename</parameter>
to <parameter>group</parameter> (specified by name or number). Only the
superuser may change the group of a file arbitrarily; other users may
change the group of a file to any group of which that user is a member.
</para>
<para>
&return.success;
</para>
&note.no-remote;
&note.sm.uidcheck;
<para>
See also <function>chown</function> and
<function>chmod</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

150
reference/filesystem/functions/chmod.xml
View file

@ -1,56 +1,56 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- $Revision: 1.14 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.chmod">
<refnamediv>
<refname>chmod</refname>
<refpurpose>Changes file mode</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>chmod</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>int</type><parameter>mode</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to change the mode of the file specified by
<parameter>filename</parameter> to that given in
<parameter>mode</parameter>.
</para>
<para>
Note that <parameter>mode</parameter> is not automatically
assumed to be an octal value, so strings (such as "g+w") will
not work properly. To ensure the expected operation,
you need to prefix <parameter>mode</parameter> with a zero (0):
</para>
<para>
<informalexample>
<programlisting role="php">
<refentry id="function.chmod">
<refnamediv>
<refname>chmod</refname>
<refpurpose>Changes file mode</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>chmod</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>int</type><parameter>mode</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to change the mode of the file specified by
<parameter>filename</parameter> to that given in
<parameter>mode</parameter>.
</para>
<para>
Note that <parameter>mode</parameter> is not automatically
assumed to be an octal value, so strings (such as "g+w") will
not work properly. To ensure the expected operation,
you need to prefix <parameter>mode</parameter> with a zero (0):
</para>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
chmod("/somedir/somefile", 755); // decimal; probably incorrect
chmod("/somedir/somefile", "u+rwx,go+rx"); // string; incorrect
chmod("/somedir/somefile", 755); // decimal; probably incorrect
chmod("/somedir/somefile", "u+rwx,go+rx"); // string; incorrect
chmod("/somedir/somefile", 0755); // octal; correct value of mode
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
The <parameter>mode</parameter> parameter consists of three octal
number components specifying access restrictions for the owner,
the user group in which the owner is in, and to everybody else in
this order. One component can be computed by adding up the needed
permissions for that target user base. Number 1 means that you
grant execute rights, number 2 means that you make the file
writeable, number 4 means that you make the file readable. Add
up these numbers to specify needed rights. You can also read more
about modes on Unix systems with 'man 1 chmod' and 'man 2 chmod'.
</para>
<para>
<informalexample>
<programlisting role="php">
</programlisting>
</informalexample>
</para>
<para>
The <parameter>mode</parameter> parameter consists of three octal
number components specifying access restrictions for the owner,
the user group in which the owner is in, and to everybody else in
this order. One component can be computed by adding up the needed
permissions for that target user base. Number 1 means that you
grant execute rights, number 2 means that you make the file
writeable, number 4 means that you make the file readable. Add
up these numbers to specify needed rights. You can also read more
about modes on Unix systems with 'man 1 chmod' and 'man 2 chmod'.
</para>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
// Read and write for owner, nothing for everybody else
@ -66,35 +66,35 @@ chmod("/somedir/somefile", 0755);
chmod("/somedir/somefile", 0750);
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
&return.success;
</para>
<note>
<para>
The current user is the user under which PHP runs. It is
probably not the same user you use for normal shell or FTP
access.
The mode can be changed only by user who owns the file on most systems.
</para>
</note>
&note.no-remote;
<note>
<simpara>
When &safemode; is enabled, PHP
checks whether the files or directories you are about to operate on have
the same UID (owner) as the script that is being executed. In addition,
you cannot set the SUID, SGID and sticky bits.
</simpara>
</note>
<para>
See also <function>chown</function> and
<function>chgrp</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</informalexample>
</para>
<para>
&return.success;
</para>
<note>
<para>
The current user is the user under which PHP runs. It is
probably not the same user you use for normal shell or FTP
access.
The mode can be changed only by user who owns the file on most systems.
</para>
</note>
&note.no-remote;
<note>
<simpara>
When &safemode; is enabled, PHP
checks whether the files or directories you are about to operate on have
the same UID (owner) as the script that is being executed. In addition,
you cannot set the SUID, SGID and sticky bits.
</simpara>
</note>
<para>
See also <function>chown</function> and
<function>chgrp</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

56
reference/filesystem/functions/chown.xml
View file

@ -1,33 +1,33 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.chown">
<refnamediv>
<refname>chown</refname>
<refpurpose>Changes file owner</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>chown</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>mixed</type><parameter>user</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to change the owner of the file <parameter>filename</parameter>
to user <parameter>user</parameter> (specified by name or number). Only
the superuser may change the owner of a file.
</para>
<para>
&return.success;
</para>
&note.no-remote;
&note.sm.uidcheck;
<para>
See also <function>chmod</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.chown">
<refnamediv>
<refname>chown</refname>
<refpurpose>Changes file owner</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>chown</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>mixed</type><parameter>user</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to change the owner of the file <parameter>filename</parameter>
to user <parameter>user</parameter> (specified by name or number). Only
the superuser may change the owner of a file.
</para>
<para>
&return.success;
</para>
&note.no-remote;
&note.sm.uidcheck;
<para>
See also <function>chmod</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

120
reference/filesystem/functions/clearstatcache.xml
View file

@ -1,65 +1,65 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- $Revision: 1.9 $ -->
<!-- split from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.clearstatcache">
<refnamediv>
<refname>clearstatcache</refname>
<refpurpose>Clears file status cache</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>void</type><methodname>clearstatcache</methodname>
<void/>
</methodsynopsis>
<para>
When you use <function>stat</function>, <function>lstat</function>, or
any of the other functions listed in the affected functions list (below),
PHP caches the information those functions return in order to provide
faster performance. However, in certain cases, you may want to clear the
cached information. For instance, if the same file is being checked
multiple times within a single script, and that file is in danger of
being removed or changed during that script's operation, you may elect to
clear the status cache. In these cases, you can use the
<function>clearstatcache</function> function to clear the information
that PHP caches about a file.
</para>
<para>
You should also note that PHP doesn't cache information about non-existent
files. So, if you call <function>file_exists</function> on a file that
doesn't exist, it will return &false; until you create the file. If you
create the file, it will return &true; even if you then delete the file.
</para>
<note>
<para>
This function caches information about specific filenames, so you only
need to call <function>clearstatcache</function> if you are performing
multiple operations on the same filename and require the information
about that particular file to not be cached.
</para>
</note>
<para>
Affected functions include <function>stat</function>,
<function>lstat</function>,
<function>file_exists</function>,
<function>is_writable</function>,
<function>is_readable</function>,
<function>is_executable</function>,
<function>is_file</function>,
<function>is_dir</function>,
<function>is_link</function>,
<function>filectime</function>,
<function>fileatime</function>,
<function>filemtime</function>,
<function>fileinode</function>,
<function>filegroup</function>,
<function>fileowner</function>,
<function>filesize</function>,
<function>filetype</function>, and
<function>fileperms</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.clearstatcache">
<refnamediv>
<refname>clearstatcache</refname>
<refpurpose>Clears file status cache</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>void</type><methodname>clearstatcache</methodname>
<void/>
</methodsynopsis>
<para>
When you use <function>stat</function>, <function>lstat</function>, or
any of the other functions listed in the affected functions list (below),
PHP caches the information those functions return in order to provide
faster performance. However, in certain cases, you may want to clear the
cached information. For instance, if the same file is being checked
multiple times within a single script, and that file is in danger of
being removed or changed during that script's operation, you may elect to
clear the status cache. In these cases, you can use the
<function>clearstatcache</function> function to clear the information
that PHP caches about a file.
</para>
<para>
You should also note that PHP doesn't cache information about non-existent
files. So, if you call <function>file_exists</function> on a file that
doesn't exist, it will return &false; until you create the file. If you
create the file, it will return &true; even if you then delete the file.
</para>
<note>
<para>
This function caches information about specific filenames, so you only
need to call <function>clearstatcache</function> if you are performing
multiple operations on the same filename and require the information
about that particular file to not be cached.
</para>
</note>
<para>
Affected functions include <function>stat</function>,
<function>lstat</function>,
<function>file_exists</function>,
<function>is_writable</function>,
<function>is_readable</function>,
<function>is_executable</function>,
<function>is_file</function>,
<function>is_dir</function>,
<function>is_link</function>,
<function>filectime</function>,
<function>fileatime</function>,
<function>filemtime</function>,
<function>fileinode</function>,
<function>filegroup</function>,
<function>fileowner</function>,
<function>filesize</function>,
<function>filetype</function>, and
<function>fileperms</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

108
reference/filesystem/functions/copy.xml
View file

@ -1,24 +1,24 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- $Revision: 1.14 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.copy">
<refnamediv>
<refname>copy</refname>
<refpurpose>Copies file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>copy</methodname>
<methodparam><type>string</type><parameter>source</parameter></methodparam>
<methodparam><type>string</type><parameter>dest</parameter></methodparam>
</methodsynopsis>
<para>
Makes a copy of the file <parameter>source</parameter> to
<parameter>dest</parameter>. &return.success;
<example>
<title><function>copy</function> example</title>
<programlisting role="php">
<refentry id="function.copy">
<refnamediv>
<refname>copy</refname>
<refpurpose>Copies file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>copy</methodname>
<methodparam><type>string</type><parameter>source</parameter></methodparam>
<methodparam><type>string</type><parameter>dest</parameter></methodparam>
</methodsynopsis>
<para>
Makes a copy of the file <parameter>source</parameter> to
<parameter>dest</parameter>. &return.success;
<example>
<title><function>copy</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$file = 'example.txt';
@ -29,41 +29,41 @@ if (!copy($file, $newfile)) {
}
?>
]]>
</programlisting>
</example>
</para>
<para>
If you wish to move a file, use the <function>rename</function> function.
</para>
<note>
<para>
As of PHP 4.3.0, both <parameter>source</parameter> and
<parameter>dest</parameter> may be URLs if the "fopen wrappers"
have been enabled. See <function>fopen</function> for more details.
If <parameter>dest</parameter> is a URL, the copy operation may
fail if the wrapper does not support overwriting of existing files.
</para>
</note>
<warning>
<para>
If the destination file already exists, it will be overwritten.
</para>
</warning>
<note>
<para>
Windows compatibility: If you copy a file with no size,
<function>copy</function> will return &false;, but the file will be correctly
copied.
</para>
</note>
<para>
See also <function>move_uploaded_file</function>,
<function>rename</function>, and the section of the manual
about <link linkend="features.file-upload">handling file
uploads</link>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<para>
If you wish to move a file, use the <function>rename</function> function.
</para>
<note>
<para>
As of PHP 4.3.0, both <parameter>source</parameter> and
<parameter>dest</parameter> may be URLs if the "fopen wrappers"
have been enabled. See <function>fopen</function> for more details.
If <parameter>dest</parameter> is a URL, the copy operation may
fail if the wrapper does not support overwriting of existing files.
</para>
</note>
<warning>
<para>
If the destination file already exists, it will be overwritten.
</para>
</warning>
<note>
<para>
Windows compatibility: If you copy a file with no size,
<function>copy</function> will return &false;, but the file will be correctly
copied.
</para>
</note>
<para>
See also <function>move_uploaded_file</function>,
<function>rename</function>, and the section of the manual
about <link linkend="features.file-upload">handling file
uploads</link>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

46
reference/filesystem/functions/delete.xml
View file

@ -1,28 +1,28 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.delete">
<refnamediv>
<refname>delete</refname>
<refpurpose>See <function>unlink</function> or <function>unset</function></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>void</type><methodname>delete</methodname>
<methodparam><type>string</type><parameter>file</parameter></methodparam>
</methodsynopsis>
<para>
This is a dummy manual entry to satisfy those people who are
looking for <function>unlink</function> or
<function>unset</function> in the wrong place.
</para>
<para>
See also <function>unlink</function> to delete files,
<function>unset</function> to delete variables.
</para>
</refsect1>
</refentry>
<refentry id="function.delete">
<refnamediv>
<refname>delete</refname>
<refpurpose>See <function>unlink</function> or <function>unset</function></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>void</type><methodname>delete</methodname>
<methodparam><type>string</type><parameter>file</parameter></methodparam>
</methodsynopsis>
<para>
This is a dummy manual entry to satisfy those people who are
looking for <function>unlink</function> or
<function>unset</function> in the wrong place.
</para>
<para>
See also <function>unlink</function> to delete files,
<function>unset</function> to delete variables.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

120
reference/filesystem/functions/dirname.xml
View file

@ -1,59 +1,59 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.dirname">
<refnamediv>
<refname>dirname</refname>
<refpurpose>Returns directory name component of path</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>dirname</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
</methodsynopsis>
<para>
Given a string containing a path to a file, this function will
return the name of the directory.
</para>
<para>
On Windows, both slash (<literal>/</literal>) and backslash
(<literal>\</literal>) are used as directory separator character. In
other environments, it is the forward slash
(<literal>/</literal>).
</para>
<para>
<example>
<title><function>dirname</function> example</title>
<programlisting role="php">
<refentry id="function.dirname">
<refnamediv>
<refname>dirname</refname>
<refpurpose>Returns directory name component of path</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>dirname</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
</methodsynopsis>
<para>
Given a string containing a path to a file, this function will
return the name of the directory.
</para>
<para>
On Windows, both slash (<literal>/</literal>) and backslash
(<literal>\</literal>) are used as directory separator character. In
other environments, it is the forward slash
(<literal>/</literal>).
</para>
<para>
<example>
<title><function>dirname</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$path = "/etc/passwd";
$file = dirname($path); // $file is set to "/etc"
?>
]]>
</programlisting>
</example>
</para>
<note>
<para>
In PHP 4.0.3, <function>dirname</function> was fixed to be
POSIX-compliant. Essentially, this means that if there are no
slashes in <parameter>path</parameter> , a dot
('<literal>.</literal>') is returned, indicating the current
directory. Otherwise, the returned string is
<parameter>path</parameter> with any trailing
<literal>/component</literal> removed. Note that this means that
you will often get a slash or a dot back from
<function>dirname</function> in situations where the older
functionality would have given you the empty string.
</para>
</note>
<para>
<function>dirname</function> has changed its behaviour in PHP 4.3.0.
Check the following examples:
<informalexample>
<programlisting role="php">
</programlisting>
</example>
</para>
<note>
<para>
In PHP 4.0.3, <function>dirname</function> was fixed to be
POSIX-compliant. Essentially, this means that if there are no
slashes in <parameter>path</parameter> , a dot
('<literal>.</literal>') is returned, indicating the current
directory. Otherwise, the returned string is
<parameter>path</parameter> with any trailing
<literal>/component</literal> removed. Note that this means that
you will often get a slash or a dot back from
<function>dirname</function> in situations where the older
functionality would have given you the empty string.
</para>
</note>
<para>
<function>dirname</function> has changed its behaviour in PHP 4.3.0.
Check the following examples:
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
@ -65,18 +65,18 @@ dirname('c:/'); // returns 'c:'
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
<function>dirname</function> has been binary safe since PHP 5.0.0
</para>
<para>
See also <function>basename</function>, <function>pathinfo</function>,
and <function>realpath</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</informalexample>
</para>
<para>
<function>dirname</function> has been binary safe since PHP 5.0.0
</para>
<para>
See also <function>basename</function>, <function>pathinfo</function>,
and <function>realpath</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

62
reference/filesystem/functions/disk-free-space.xml
View file

@ -1,26 +1,26 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.86 -->
<refentry id="function.disk-free-space">
<refnamediv>
<refname>disk_free_space</refname>
<refpurpose>Returns available space in directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>float</type><methodname>disk_free_space</methodname>
<methodparam><type>string</type><parameter>directory</parameter></methodparam>
</methodsynopsis>
<para>
Given a string containing a directory, this function will return
the number of bytes available on the corresponding filesystem or
disk partition.
</para>
<para>
<example>
<title><function>disk_free_space</function> example</title>
<programlisting role="php">
<refentry id="function.disk-free-space">
<refnamediv>
<refname>disk_free_space</refname>
<refpurpose>Returns available space in directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>float</type><methodname>disk_free_space</methodname>
<methodparam><type>string</type><parameter>directory</parameter></methodparam>
</methodsynopsis>
<para>
Given a string containing a directory, this function will return
the number of bytes available on the corresponding filesystem or
disk partition.
</para>
<para>
<example>
<title><function>disk_free_space</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
// $df contains the number of bytes available on "/"
@ -31,17 +31,17 @@ disk_free_space("C:");
disk_free_space("D:");
?>
]]>
</programlisting>
</example>
</para>
&note.no-remote;
</programlisting>
</example>
</para>
<simpara>
See also <function>disk_total_space</function>
</simpara>
</refsect1>
</refentry>
&note.no-remote;
<simpara>
See also <function>disk_total_space</function>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

62
reference/filesystem/functions/disk-total-space.xml
View file

@ -1,26 +1,26 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.64 -->
<refentry id="function.disk-total-space">
<refnamediv>
<refname>disk_total_space</refname>
<refpurpose>Returns the total size of a directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>float</type><methodname>disk_total_space</methodname>
<methodparam><type>string</type><parameter>directory</parameter></methodparam>
</methodsynopsis>
<para>
Given a string containing a directory, this function will return
the total number of bytes on the corresponding filesystem or disk
partition.
</para>
<para>
<example>
<title><function>disk_total_space</function> example</title>
<programlisting role="php">
<refentry id="function.disk-total-space">
<refnamediv>
<refname>disk_total_space</refname>
<refpurpose>Returns the total size of a directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>float</type><methodname>disk_total_space</methodname>
<methodparam><type>string</type><parameter>directory</parameter></methodparam>
</methodsynopsis>
<para>
Given a string containing a directory, this function will return
the total number of bytes on the corresponding filesystem or disk
partition.
</para>
<para>
<example>
<title><function>disk_total_space</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
// $df contains the total number of bytes available on "/"
@ -31,17 +31,17 @@ disk_total_space("C:");
disk_total_space("D:");
?>
]]>
</programlisting>
</example>
</para>
</programlisting>
</example>
</para>
&note.no-remote;
<simpara>
See also <function>disk_free_space</function>
</simpara>
</refsect1>
</refentry>
&note.no-remote;
<simpara>
See also <function>disk_free_space</function>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

68
reference/filesystem/functions/fclose.xml
View file

@ -1,46 +1,46 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fclose">
<refnamediv>
<refname>fclose</refname>
<refpurpose>Closes an open file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>fclose</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
The file pointed to by <parameter>handle</parameter> is closed.
</para>
<para>
&return.success;
</para>
<para>
The file pointer must be valid, and must point to a file
successfully opened by <function>fopen</function> or
<function>fsockopen</function>.
</para>
<para>
<example>
<title>A simple <function>fclose</function> example</title>
<programlisting role="php">
<refentry id="function.fclose">
<refnamediv>
<refname>fclose</refname>
<refpurpose>Closes an open file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>fclose</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
The file pointed to by <parameter>handle</parameter> is closed.
</para>
<para>
&return.success;
</para>
<para>
The file pointer must be valid, and must point to a file
successfully opened by <function>fopen</function> or
<function>fsockopen</function>.
</para>
<para>
<example>
<title>A simple <function>fclose</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$handle = fopen('somefile.txt', 'r');
fclose($handle);
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

76
reference/filesystem/functions/feof.xml
View file

@ -1,38 +1,38 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- $Revision: 1.13 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.feof">
<refnamediv>
<refname>feof</refname>
<refpurpose>Tests for end-of-file on a file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>feof</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<refentry id="function.feof">
<refnamediv>
<refname>feof</refname>
<refpurpose>Tests for end-of-file on a file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>feof</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the file pointer is at EOF or an error occurs
(including socket timeout); otherwise returns &false;.
</para>
<warning>
<simpara>
If a connection opened by <function>fsockopen</function> wasn't closed
by the server, <function>feof</function> will wait until a timeout has
been reached to return &true;. The default timeout value is 60 seconds.
You may use <function>stream_set_timeout</function> to change this
value.
</simpara>
</warning>
&fs.validfp.all;
<warning>
<para>
Returns &true; if the file pointer is at EOF or an error occurs
(including socket timeout); otherwise returns &false;.
</para>
<warning>
<simpara>
If a connection opened by <function>fsockopen</function> wasn't closed
by the server, <function>feof</function> will wait until a timeout has
been reached to return &true;. The default timeout value is 60 seconds.
You may use <function>stream_set_timeout</function> to change this
value.
</simpara>
</warning>
&fs.validfp.all;
<warning>
<para>
If passed file pointer is not valid you may get an infinite loop, because
EOF fails to return TRUE.
<example>
<title><function>feof</function> example with an invalid file pointer</title>
<programlisting role="php">
If passed file pointer is not valid you may get an infinite loop, because
EOF fails to return TRUE.
<example>
<title><function>feof</function> example with an invalid file pointer</title>
<programlisting role="php">
<![CDATA[
<?php
// if file can not be read or doesn't exist fopen function returns FALSE
@ -45,12 +45,12 @@ while (!feof($file)) {
fclose($file);
?>
]]>
</programlisting>
</example>
</para>
</warning>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</warning>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

40
reference/filesystem/functions/fflush.xml
View file

@ -1,25 +1,25 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.43 -->
<refentry id="function.fflush">
<refnamediv>
<refname>fflush</refname>
<refpurpose>Flushes the output to a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>fflush</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
This function forces a write of all buffered output to the
resource pointed to by the file handle <parameter>handle</parameter>.
&return.success;
</para>
&fs.validfp.all;
</refsect1>
</refentry>
<refentry id="function.fflush">
<refnamediv>
<refname>fflush</refname>
<refpurpose>Flushes the output to a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>fflush</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
This function forces a write of all buffered output to the
resource pointed to by the file handle <parameter>handle</parameter>.
&return.success;
</para>
&fs.validfp.all;
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

72
reference/filesystem/functions/fgetc.xml
View file

@ -1,30 +1,30 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fgetc">
<refnamediv>
<refname>fgetc</refname>
<refpurpose>Gets character from file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>fgetc</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
Returns a string containing a single character read from the
file pointed to by <parameter>handle</parameter>.
Returns &false; on EOF.
</para>
<refentry id="function.fgetc">
<refnamediv>
<refname>fgetc</refname>
<refpurpose>Gets character from file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>fgetc</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
Returns a string containing a single character read from the
file pointed to by <parameter>handle</parameter>.
Returns &false; on EOF.
</para>
&fs.validfp.all;
&return.falseproblem;
<para>
<example>
<title>A <function>fgetc</function> example</title>
<programlisting role="php">
&fs.validfp.all;
&return.falseproblem;
<para>
<example>
<title>A <function>fgetc</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$fp = fopen('somefile.txt', 'r');
@ -36,19 +36,19 @@ while (false !== ($char = fgetc($fp))) {
}
?>
]]>
</programlisting>
</example>
</para>
&note.bin-safe;
</programlisting>
</example>
</para>
<para>
See also <function>fread</function>, <function>fopen</function>,
<function>popen</function>, <function>fsockopen</function>, and
<function>fgets</function>.
</para>
</refsect1>
</refentry>
&note.bin-safe;
<para>
See also <function>fread</function>, <function>fopen</function>,
<function>popen</function>, <function>fsockopen</function>, and
<function>fgets</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

192
reference/filesystem/functions/fgetcsv.xml
View file

@ -1,83 +1,83 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.20 $ -->
<!-- $Revision: 1.21 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fgetcsv">
<refnamediv>
<refname>fgetcsv</refname>
<refpurpose>Gets line from file pointer and parse for CSV fields</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>fgetcsv</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>delimiter</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>enclosure</parameter></methodparam>
</methodsynopsis>
<refentry id="function.fgetcsv">
<refnamediv>
<refname>fgetcsv</refname>
<refpurpose>Gets line from file pointer and parse for CSV fields</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>fgetcsv</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>delimiter</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>enclosure</parameter></methodparam>
</methodsynopsis>
<para>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<listitem>
<simpara>
A valid file pointer to a file successfully opened by <function>fopen</function>,
<function>popen</function>, or <function>fsockopen</function>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>length</parameter> (Optional)</term>
<listitem>
<simpara>
Must be greater than the longest line (in characters) to be found in the CSV file
(allowing for trailing line-end characters). It became optional in PHP 5. Omitting
this parameter (or setting it to 0 in PHP 5.0.4 and later) the maximum line length
is not limited, which is slightly slower.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>delimiter</parameter> (Optional)</term>
<listitem>
<simpara>
Set the field delimiter (one character only). Defaults as a comma.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>enclosure</parameter> (Optional)</term>
<listitem>
<simpara>
Set the field enclosure character (one character only). Defaults as a double quotation mark. Added in PHP 4.3.0.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter></term>
<listitem>
<simpara>
A valid file pointer to a file successfully opened by <function>fopen</function>,
<function>popen</function>, or <function>fsockopen</function>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>length</parameter> (Optional)</term>
<listitem>
<simpara>
Must be greater than the longest line (in characters) to be found in the CSV file
(allowing for trailing line-end characters). It became optional in PHP 5. Omitting
this parameter (or setting it to 0 in PHP 5.0.4 and later) the maximum line length
is not limited, which is slightly slower.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>delimiter</parameter> (Optional)</term>
<listitem>
<simpara>
Set the field delimiter (one character only). Defaults as a comma.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>enclosure</parameter> (Optional)</term>
<listitem>
<simpara>
Set the field enclosure character (one character only). Defaults as a double quotation mark. Added in PHP 4.3.0.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
<simpara>
Similar to <function>fgets</function> except that
<function>fgetcsv</function> parses the line it reads for fields
in <acronym>CSV</acronym> format and returns an array containing
the fields read.
</simpara>
<simpara>
<function>fgetcsv</function> returns &false; on error, including
end of file.
</simpara>
<note>
<simpara>
A blank line in a CSV file will be returned as an array
comprising a single <type>null</type> field, and will not be treated
as an error.
</simpara>
</note>
<para>
<example>
<title>Read and print the entire contents of a CSV file</title>
<programlisting role="php">
<simpara>
Similar to <function>fgets</function> except that
<function>fgetcsv</function> parses the line it reads for fields
in <acronym>CSV</acronym> format and returns an array containing
the fields read.
</simpara>
<simpara>
<function>fgetcsv</function> returns &false; on error, including
end of file.
</simpara>
<note>
<simpara>
A blank line in a CSV file will be returned as an array
comprising a single <type>null</type> field, and will not be treated
as an error.
</simpara>
</note>
<para>
<example>
<title>Read and print the entire contents of a CSV file</title>
<programlisting role="php">
<![CDATA[
<?php
$row = 1;
@ -93,26 +93,26 @@ while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
fclose($handle);
?>
]]>
</programlisting>
</example>
</para>
<para>
<function>fgetcsv</function> has been binary safe since PHP 4.3.5
</para>
<note>
<simpara>
Locale setting is taken into account by this function. If
<varname>LANG</varname> is e.g. <literal>en_US.UTF-8</literal>, files in
one-byte encoding are read wrong by this function.
</simpara>
</note>
&note.line-endings;
<para>
See also <function>explode</function>, <function>file</function>,
<function>pack</function> and <function>fputcsv</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<para>
<function>fgetcsv</function> has been binary safe since PHP 4.3.5
</para>
<note>
<simpara>
Locale setting is taken into account by this function. If
<varname>LANG</varname> is e.g. <literal>en_US.UTF-8</literal>, files in
one-byte encoding are read wrong by this function.
</simpara>
</note>
&note.line-endings;
<para>
See also <function>explode</function>, <function>file</function>,
<function>pack</function> and <function>fputcsv</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

138
reference/filesystem/functions/fgets.xml
View file

@ -1,44 +1,44 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
<!-- $Revision: 1.17 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fgets">
<refnamediv>
<refname>fgets</refname>
<refpurpose>Gets line from file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>fgets</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
</methodsynopsis>
<para>
Returns a string of up to <parameter>length</parameter> - 1 bytes read from
the file pointed to by <parameter>handle</parameter>. Reading ends when
<parameter>length</parameter> - 1 bytes have been read, on a newline (which is
included in the return value), or on EOF (whichever comes first). If no length
is specified, it will keep reading from the stream until it reaches
the end of the line.
</para>
<para>
If an error occurs, returns &false;.
</para>
<para>
Common Pitfalls:
</para>
<simpara>
People used to the 'C' semantics of <function>fgets</function>
should note the difference in how <literal>EOF</literal> is returned.
</simpara>
&fs.validfp.all;
<refentry id="function.fgets">
<refnamediv>
<refname>fgets</refname>
<refpurpose>Gets line from file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>fgets</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
</methodsynopsis>
<para>
Returns a string of up to <parameter>length</parameter> - 1 bytes read from
the file pointed to by <parameter>handle</parameter>. Reading ends when
<parameter>length</parameter> - 1 bytes have been read, on a newline (which is
included in the return value), or on EOF (whichever comes first). If no length
is specified, it will keep reading from the stream until it reaches
the end of the line.
</para>
<para>
If an error occurs, returns &false;.
</para>
<para>
Common Pitfalls:
</para>
<simpara>
People used to the 'C' semantics of <function>fgets</function>
should note the difference in how <literal>EOF</literal> is returned.
</simpara>
<para>
A simple example follows:
<example>
<title>Reading a file line by line</title>
<programlisting role="php">
&fs.validfp.all;
<para>
A simple example follows:
<example>
<title>Reading a file line by line</title>
<programlisting role="php">
<![CDATA[
<?php
$handle = @fopen("/tmp/inputfile.txt", "r");
@ -51,37 +51,37 @@ if ($handle) {
}
?>
]]>
</programlisting>
</example>
</para>
<note>
<simpara>
The <parameter>length</parameter> parameter became optional in PHP
4.2.0. Until PHP 4.3.0, omitting it would assume 1024 as the line length.
If the majority of the lines in the file are all larger than 8KB,
it is more resource efficient for your script to specify the maximum
line length.
</simpara>
</note>
<note>
<simpara>
This function is binary safe as of PHP 4.3. Earlier versions
were not binary safe.
</simpara>
</note>
&note.line-endings;
<para>
See also <function>fgetss</function>
<function>fread</function>,
<function>fgetc</function>,
<function>stream_get_line</function>,
<function>fopen</function>,
<function>popen</function>,
<function>fsockopen</function>, and
<function>stream_set_timeout</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<note>
<simpara>
The <parameter>length</parameter> parameter became optional in PHP
4.2.0. Until PHP 4.3.0, omitting it would assume 1024 as the line length.
If the majority of the lines in the file are all larger than 8KB,
it is more resource efficient for your script to specify the maximum
line length.
</simpara>
</note>
<note>
<simpara>
This function is binary safe as of PHP 4.3. Earlier versions
were not binary safe.
</simpara>
</note>
&note.line-endings;
<para>
See also <function>fgetss</function>
<function>fread</function>,
<function>fgetc</function>,
<function>stream_get_line</function>,
<function>fopen</function>,
<function>popen</function>,
<function>fsockopen</function>, and
<function>stream_set_timeout</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

76
reference/filesystem/functions/fgetss.xml
View file

@ -1,45 +1,45 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fgetss">
<refnamediv>
<refname>fgetss</refname>
<refpurpose>Gets line from file pointer and strip HTML tags</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>fgetss</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>allowable_tags</parameter></methodparam>
</methodsynopsis>
<refentry id="function.fgetss">
<refnamediv>
<refname>fgetss</refname>
<refpurpose>Gets line from file pointer and strip HTML tags</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>fgetss</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>allowable_tags</parameter></methodparam>
</methodsynopsis>
<para>
Identical to <function>fgets</function>, except that fgetss
attempts to strip any HTML and PHP tags from the text it
reads.
</para>
<para>
You can use the optional third parameter to specify tags which
should not be stripped.
<note>
<para>
Identical to <function>fgets</function>, except that fgetss
attempts to strip any HTML and PHP tags from the text it
reads.
<parameter>allowable_tags</parameter> was added in PHP 3.0.13,
PHP 4.0.0.
</para>
<para>
You can use the optional third parameter to specify tags which
should not be stripped.
<note>
<para>
<parameter>allowable_tags</parameter> was added in PHP 3.0.13,
PHP 4.0.0.
</para>
</note>
</para>
<para>
Parameter <parameter>length</parameter> is optional since PHP 5.
</para>
&note.line-endings;
<para>
See also <function>fgets</function>, <function>fopen</function>,
<function>fsockopen</function>, <function>popen</function>, and
<function>strip_tags</function>.
</para>
</refsect1>
</refentry>
</note>
</para>
<para>
Parameter <parameter>length</parameter> is optional since PHP 5.
</para>
&note.line-endings;
<para>
See also <function>fgets</function>, <function>fopen</function>,
<function>fsockopen</function>, <function>popen</function>, and
<function>strip_tags</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

92
reference/filesystem/functions/file-exists.xml
View file

@ -1,30 +1,30 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
<!-- $Revision: 1.15 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.file-exists">
<refnamediv>
<refname>file_exists</refname>
<refpurpose>Checks whether a file or directory exists</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>file_exists</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns &true; if the file or directory specified by
<parameter>filename</parameter> exists; &false; otherwise.
</simpara>
<para>
On windows, use <filename>//computername/share/filename</filename> or
<filename>\\computername\share\filename</filename> to check files on
network shares.
</para>
<para>
<example>
<title>Testing whether a file exists</title>
<programlisting role="php">
<refentry id="function.file-exists">
<refnamediv>
<refname>file_exists</refname>
<refpurpose>Checks whether a file or directory exists</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>file_exists</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns &true; if the file or directory specified by
<parameter>filename</parameter> exists; &false; otherwise.
</simpara>
<para>
On windows, use <filename>//computername/share/filename</filename> or
<filename>\\computername\share\filename</filename> to check files on
network shares.
</para>
<para>
<example>
<title>Testing whether a file exists</title>
<programlisting role="php">
<![CDATA[
<?php
$filename = '/path/to/foo.txt';
@ -36,30 +36,30 @@ if (file_exists($filename)) {
}
?>
]]>
</programlisting>
</example>
</para>
</programlisting>
</example>
</para>
&note.clearstatcache;
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<warning>
<para>
This function returns &false; for files inaccessible due to <link
linkend="features.safe-mode">safe mode</link> restrictions. However these
files still can be <link linkend="function.include">included</link> if
they are located in <link
linkend="ini.safe-mode-include-dir">safe_mode_include_dir</link>.
</para>
</warning>
&tip.fopen-wrapper.stat;
<para>
See also <function>is_readable</function>, <function>is_writable</function>,
<function>is_file</function> and <function>file</function>.
</para>
</refsect1>
</refentry>
<warning>
<para>
This function returns &false; for files inaccessible due to <link
linkend="features.safe-mode">safe mode</link> restrictions. However these
files still can be <link linkend="function.include">included</link> if
they are located in <link
linkend="ini.safe-mode-include-dir">safe_mode_include_dir</link>.
</para>
</warning>
<para>
See also <function>is_readable</function>, <function>is_writable</function>,
<function>is_file</function> and <function>file</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

124
reference/filesystem/functions/file.xml
View file

@ -1,37 +1,37 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.19 $ -->
<!-- $Revision: 1.20 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.file">
<refnamediv>
<refname>file</refname>
<refpurpose>Reads entire file into an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>use_include_path</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Identical to <function>file_get_contents</function>, except that
<function>file</function> returns the file in an array. Each
element of the array corresponds to a line in the file, with the
newline still attached. Upon failure, <function>file</function>
returns &false;.
</para>
<para>
You can use the optional <parameter>use_include_path</parameter> parameter
and set it to "1", if you want to search for the file in the <link
linkend="ini.include-path">include_path</link>, too.
</para>
<para>
<informalexample>
<programlisting role="php">
<refentry id="function.file">
<refnamediv>
<refname>file</refname>
<refpurpose>Reads entire file into an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>use_include_path</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Identical to <function>file_get_contents</function>, except that
<function>file</function> returns the file in an array. Each
element of the array corresponds to a line in the file, with the
newline still attached. Upon failure, <function>file</function>
returns &false;.
</para>
<para>
You can use the optional <parameter>use_include_path</parameter> parameter
and set it to "1", if you want to search for the file in the <link
linkend="ini.include-path">include_path</link>, too.
</para>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
// Get a file into an array. In this example we'll go through HTTP to get
// Get a file into an array. In this example we'll go through HTTP to get
// the HTML source of a URL.
$lines = file('http://www.example.com/');
@ -44,38 +44,38 @@ foreach ($lines as $line_num => $line) {
$html = implode('', file('http://www.example.com/'));
?>
]]>
</programlisting>
</informalexample>
</para>
&tip.fopen-wrapper;
<note>
<para>
Each line in the resulting array will include the line ending, so you
still need to use <function>rtrim</function> if you do not want the line
ending present.
</para>
</note>
&note.line-endings;
<note>
<para>
As of PHP 4.3.0 you can use <function>file_get_contents</function> to
return the contents of a file as a string.
</para>
<para>
In PHP 4.3.0 <function>file</function> became binary safe.
</para>
</note>
&note.context-support;
&warn.ssl-non-standard;
<para>
See also <function>readfile</function>,
<function>fopen</function>, <function>fsockopen</function>,
<function>popen</function>, <function>file_get_contents</function>,
<function>include</function>, and
<function>stream_context_create</function>
</para>
</refsect1>
</refentry>
</programlisting>
</informalexample>
</para>
&tip.fopen-wrapper;
<note>
<para>
Each line in the resulting array will include the line ending, so you
still need to use <function>rtrim</function> if you do not want the line
ending present.
</para>
</note>
&note.line-endings;
<note>
<para>
As of PHP 4.3.0 you can use <function>file_get_contents</function> to
return the contents of a file as a string.
</para>
<para>
In PHP 4.3.0 <function>file</function> became binary safe.
</para>
</note>
&note.context-support;
&warn.ssl-non-standard;
<para>
See also <function>readfile</function>,
<function>fopen</function>, <function>fsockopen</function>,
<function>popen</function>, <function>file_get_contents</function>,
<function>include</function>, and
<function>stream_context_create</function>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

88
reference/filesystem/functions/fileatime.xml
View file

@ -1,40 +1,40 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fileatime">
<refnamediv>
<refname>fileatime</refname>
<refpurpose>Gets last access time of file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fileatime</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns the time the file was last accessed, or &false; in case of
an error. The time is returned as a Unix timestamp.
</simpara>
<simpara>
Note: The atime of a file is supposed to change whenever
the data blocks of a file are being read. This can be
costly performance-wise when an application regularly
accesses a very large number of files or directories. Some
Unix filesystems can be mounted with atime updates disabled
to increase the performance of such applications; USENET
news spools are a common example. On such filesystems
this function will be useless.
</simpara>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<refentry id="function.fileatime">
<refnamediv>
<refname>fileatime</refname>
<refpurpose>Gets last access time of file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fileatime</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns the time the file was last accessed, or &false; in case of
an error. The time is returned as a Unix timestamp.
</simpara>
<simpara>
Note: The atime of a file is supposed to change whenever
the data blocks of a file are being read. This can be
costly performance-wise when an application regularly
accesses a very large number of files or directories. Some
Unix filesystems can be mounted with atime updates disabled
to increase the performance of such applications; USENET
news spools are a common example. On such filesystems
this function will be useless.
</simpara>
<para>
<example>
<title><function>fileatime</function> example</title>
<programlisting role="php">
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<para>
<example>
<title><function>fileatime</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -47,16 +47,16 @@ if (file_exists($filename)) {
?>
]]>
</programlisting>
</example>
</para>
<simpara>
See also <function>filemtime</function>,
<function>fileinode</function>, and
<function>date</function>.
</simpara>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<simpara>
See also <function>filemtime</function>,
<function>fileinode</function>, and
<function>date</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

90
reference/filesystem/functions/filectime.xml
View file

@ -1,43 +1,43 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.filectime">
<refnamediv>
<refname>filectime</refname>
<refpurpose>Gets inode change time of file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>filectime</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the time the file was last changed, or &false; in case of
an error. The time is returned as a Unix timestamp.
</para>
<para>
Note: In most Unix filesystems, a file is considered
changed when its inode data is changed; that is, when
the permissions, owner, group, or other metadata
from the inode is updated. See also
<function>filemtime</function> (which is what you want to use
when you want to create "Last Modified" footers on web pages) and
<function>fileatime</function>.
</para>
<para>Note also that in some Unix texts the ctime of a file is
referred to as being the creation time of the file. This is wrong.
There is no creation time for Unix files in most Unix filesystems.
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<refentry id="function.filectime">
<refnamediv>
<refname>filectime</refname>
<refpurpose>Gets inode change time of file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>filectime</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the time the file was last changed, or &false; in case of
an error. The time is returned as a Unix timestamp.
</para>
<para>
Note: In most Unix filesystems, a file is considered
changed when its inode data is changed; that is, when
the permissions, owner, group, or other metadata
from the inode is updated. See also
<function>filemtime</function> (which is what you want to use
when you want to create "Last Modified" footers on web pages) and
<function>fileatime</function>.
</para>
<para>Note also that in some Unix texts the ctime of a file is
referred to as being the creation time of the file. This is wrong.
There is no creation time for Unix files in most Unix filesystems.
</para>
<para>
<example>
<title>A <function>filectime</function> example</title>
<programlisting role="php">
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<para>
<example>
<title>A <function>filectime</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -50,14 +50,14 @@ if (file_exists($filename)) {
?>
]]>
</programlisting>
</example>
</para>
<simpara>
See also <function>filemtime</function>
</simpara>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<simpara>
See also <function>filemtime</function>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

60
reference/filesystem/functions/filegroup.xml
View file

@ -1,35 +1,35 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.filegroup">
<refnamediv>
<refname>filegroup</refname>
<refpurpose>Gets file group</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>filegroup</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the group ID of the file, or &false; in case
of an error. The group ID is returned in numerical format, use
<function>posix_getgrgid</function> to resolve it to a group name.
Upon failure, &false; is returned along with an error of level
<constant>E_WARNING</constant>.
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<simpara>
See also <function>fileowner</function>, and
<link linkend="ini.safe-mode-gid">safe_mode_gid</link>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.filegroup">
<refnamediv>
<refname>filegroup</refname>
<refpurpose>Gets file group</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>filegroup</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the group ID of the file, or &false; in case
of an error. The group ID is returned in numerical format, use
<function>posix_getgrgid</function> to resolve it to a group name.
Upon failure, &false; is returned along with an error of level
<constant>E_WARNING</constant>.
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<simpara>
See also <function>fileowner</function>, and
<link linkend="ini.safe-mode-gid">safe_mode_gid</link>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

52
reference/filesystem/functions/fileinode.xml
View file

@ -1,31 +1,31 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fileinode">
<refnamediv>
<refname>fileinode</refname>
<refpurpose>Gets file inode</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fileinode</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the inode number of the file, or &false; in case of an
error.
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<simpara>
See also <function>stat</function>
</simpara>
</refsect1>
</refentry>
<refentry id="function.fileinode">
<refnamediv>
<refname>fileinode</refname>
<refpurpose>Gets file inode</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fileinode</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the inode number of the file, or &false; in case of an
error.
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<simpara>
See also <function>stat</function>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

78
reference/filesystem/functions/filemtime.xml
View file

@ -1,36 +1,36 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.filemtime">
<refnamediv>
<refname>filemtime</refname>
<refpurpose>Gets file modification time</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>filemtime</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the time the file was last modified, or &false; in case of
an error. The time is returned as a Unix timestamp, which is
suitable for the <function>date</function> function.
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<refentry id="function.filemtime">
<refnamediv>
<refname>filemtime</refname>
<refpurpose>Gets file modification time</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>filemtime</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the time the file was last modified, or &false; in case of
an error. The time is returned as a Unix timestamp, which is
suitable for the <function>date</function> function.
</para>
<para>
This function returns the time when the data
blocks of a file were being written to, that is, the time
when the content of the file was changed.
</para>
<para>
<example>
<title><function>filemtime</function> example</title>
<programlisting role="php">
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<para>
This function returns the time when the data
blocks of a file were being written to, that is, the time
when the content of the file was changed.
</para>
<para>
<example>
<title><function>filemtime</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
// outputs e.g. somefile.txt was last modified: December 29 2002 22:16:23.
@ -41,15 +41,15 @@ if (file_exists($filename)) {
}
?>
]]>
</programlisting>
</example>
</para>
<para>
See also <function>filectime</function>, <function>stat</function>,
<function>touch</function>, and <function>getlastmod</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<para>
See also <function>filectime</function>, <function>stat</function>,
<function>touch</function>, and <function>getlastmod</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

54
reference/filesystem/functions/fileowner.xml
View file

@ -1,33 +1,33 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fileowner">
<refnamediv>
<refname>fileowner</refname>
<refpurpose>Gets file owner</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fileowner</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the user ID of the owner of the file, or &false; in case of
an error. The user ID is returned in numerical format, use
<function>posix_getpwuid</function> to resolve it to a username.
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<simpara>
See also <function>stat</function>
</simpara>
<refentry id="function.fileowner">
<refnamediv>
<refname>fileowner</refname>
<refpurpose>Gets file owner</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fileowner</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the user ID of the owner of the file, or &false; in case of
an error. The user ID is returned in numerical format, use
<function>posix_getpwuid</function> to resolve it to a username.
</para>
</refsect1>
</refentry>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<simpara>
See also <function>stat</function>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

82
reference/filesystem/functions/fileperms.xml
View file

@ -1,43 +1,45 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fileperms">
<refnamediv>
<refname>fileperms</refname>
<refpurpose>Gets file permissions</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fileperms</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the permissions on the file, or &false; in case of an error.
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<example>
<title>Display permissions as an octal value</title>
<programlisting role="php">
<refentry id="function.fileperms">
<refnamediv>
<refname>fileperms</refname>
<refpurpose>Gets file permissions</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fileperms</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the permissions on the file, or &false; in case of an error.
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<example>
<title>Display permissions as an octal value</title>
<programlisting role="php">
<![CDATA[
<?php
echo substr(sprintf('%o', fileperms('/tmp')), -4);
echo substr(sprintf('%o', fileperms('/etc/passwd')), -4);
?>
]]>
</programlisting>
<para>This would produce the output:</para>
<screen>
</programlisting>
<para>
This would produce the output:
</para>
<screen>
<![CDATA[
1777
0644
]]>
</screen>
</example>
<example>
<title>Display full permissions</title>
<programlisting role="php">
</screen>
</example>
<example>
<title>Display full permissions</title>
<programlisting role="php">
<![CDATA[
<?php
$perms = fileperms('/etc/passwd');
@ -92,20 +94,22 @@ $info .= (($perms & 0x0001) ?
echo $info;
?>
]]>
</programlisting>
<para>This would produce the output:</para>
<screen>
</programlisting>
<para>
This would produce the output:
</para>
<screen>
<![CDATA[
-rw-r--r--
]]>
</screen>
</example>
<simpara>
See also <function>is_readable</function>,
and <function>stat</function>
</simpara>
</refsect1>
</refentry>
</screen>
</example>
<simpara>
See also <function>is_readable</function>,
and <function>stat</function>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

78
reference/filesystem/functions/filesize.xml
View file

@ -1,38 +1,38 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.filesize">
<refnamediv>
<refname>filesize</refname>
<refpurpose>Gets file size</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>filesize</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the size of the file in bytes, or &false; (and generates an error
of level <constant>E_WARNING</constant>) in case of an error.
</para>
<note>
<simpara>
Because PHP's integer type is signed and many platforms use 32bit integers,
<function>filesize</function> may return unexpected results for files which
are larger than 2GB. For files between 2GB and 4GB in size this can usually
be overcome by using <literal>sprintf("%u", filesize($file))</literal>.
</simpara>
</note>
&note.clearstatcache;
<refentry id="function.filesize">
<refnamediv>
<refname>filesize</refname>
<refpurpose>Gets file size</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>filesize</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the size of the file in bytes, or &false; (and generates an error
of level <constant>E_WARNING</constant>) in case of an error.
</para>
<note>
<simpara>
Because PHP's integer type is signed and many platforms use 32bit integers,
<function>filesize</function> may return unexpected results for files which
are larger than 2GB. For files between 2GB and 4GB in size this can usually
be overcome by using <literal>sprintf("%u", filesize($file))</literal>.
</simpara>
</note>
&tip.fopen-wrapper.stat;
&note.clearstatcache;
<para>
<example>
<title><function>filesize</function> example</title>
<programlisting role="php">
&tip.fopen-wrapper.stat;
<para>
<example>
<title><function>filesize</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -43,14 +43,14 @@ echo $filename . ': ' . filesize($filename) . ' bytes';
?>
]]>
</programlisting>
</example>
</para>
<simpara>
See also <function>file_exists</function>
</simpara>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<simpara>
See also <function>file_exists</function>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

78
reference/filesystem/functions/filetype.xml
View file

@ -1,35 +1,35 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.filetype">
<refnamediv>
<refname>filetype</refname>
<refpurpose>Gets file type</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>filetype</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the type of the file. Possible values are fifo, char,
dir, block, link, file, and unknown.
</para>
<para>
Returns &false; if an error occurs. <function>filetype</function> will also
produce an <constant>E_NOTICE</constant> message if the stat call fails
or if the file type is unknown.
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<refentry id="function.filetype">
<refnamediv>
<refname>filetype</refname>
<refpurpose>Gets file type</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>filetype</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns the type of the file. Possible values are fifo, char,
dir, block, link, file, and unknown.
</para>
<para>
Returns &false; if an error occurs. <function>filetype</function> will also
produce an <constant>E_NOTICE</constant> message if the stat call fails
or if the file type is unknown.
</para>
<para>
<example>
<title><function>filetype</function> example</title>
<programlisting role="php">
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<para>
<example>
<title><function>filetype</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -38,16 +38,16 @@ echo filetype('/etc/'); // dir
?>
]]>
</programlisting>
</example>
</para>
<simpara>
See also <function>is_dir</function>, <function>is_file</function>,
<function>is_link</function>, <function>file_exists</function>,
<function>stat</function>, and <function>mime_content_type</function>.
</simpara>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<simpara>
See also <function>is_dir</function>, <function>is_file</function>,
<function>is_link</function>, <function>file_exists</function>,
<function>stat</function>, and <function>mime_content_type</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

220
reference/filesystem/functions/flock.xml
View file

@ -1,82 +1,82 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.flock">
<refnamediv>
<refname>flock</refname>
<refpurpose>Portable advisory file locking</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>flock</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>int</type><parameter>operation</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter role="reference">wouldblock</parameter></methodparam>
</methodsynopsis>
<simpara>
PHP supports a portable way of locking complete files in an
advisory way (which means all accessing programs have to use the
same way of locking or it will not work).
</simpara>
<note>
<para>
<function>flock</function> is mandatory under Windows.
</para>
</note>
<simpara>
<function>flock</function> operates on <parameter>handle</parameter>
which must be an open file
pointer. <parameter>operation</parameter> is one of the following
values:
</simpara>
<para>
<itemizedlist>
<listitem>
<simpara>
To acquire a shared lock (reader), set
<parameter>operation</parameter> to <constant>LOCK_SH</constant> (set to 1 prior to
PHP 4.0.1).
</simpara>
</listitem>
<listitem>
<simpara>
To acquire an exclusive lock (writer), set
<parameter>operation</parameter> to <constant>LOCK_EX</constant> (set to 2 prior to
PHP 4.0.1).
</simpara>
</listitem>
<listitem>
<simpara>
To release a lock (shared or exclusive), set
<parameter>operation</parameter> to <constant>LOCK_UN</constant> (set to 3 prior to
PHP 4.0.1).
</simpara>
</listitem>
<listitem>
<simpara>
If you don't want <function>flock</function> to block while
locking, add <constant>LOCK_NB</constant> (4 prior to PHP 4.0.1) to
<parameter>operation</parameter>.
</simpara>
</listitem>
</itemizedlist>
</para>
<simpara>
<function>flock</function> allows you to perform a simple
reader/writer model which can be used on virtually every platform
(including most Unix derivatives and even Windows). The optional third
argument is set to &true; if the lock would block (EWOULDBLOCK
errno condition). The lock is released also by <function>fclose</function>
(which is also called automatically when script finished).
</simpara>
<simpara>
&return.success;
</simpara>
<para>
<example>
<title><function>flock</function> example</title>
<programlisting role="php">
<refentry id="function.flock">
<refnamediv>
<refname>flock</refname>
<refpurpose>Portable advisory file locking</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>flock</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>int</type><parameter>operation</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter role="reference">wouldblock</parameter></methodparam>
</methodsynopsis>
<simpara>
PHP supports a portable way of locking complete files in an
advisory way (which means all accessing programs have to use the
same way of locking or it will not work).
</simpara>
<note>
<para>
<function>flock</function> is mandatory under Windows.
</para>
</note>
<simpara>
<function>flock</function> operates on <parameter>handle</parameter>
which must be an open file
pointer. <parameter>operation</parameter> is one of the following
values:
</simpara>
<para>
<itemizedlist>
<listitem>
<simpara>
To acquire a shared lock (reader), set
<parameter>operation</parameter> to <constant>LOCK_SH</constant> (set to 1 prior to
PHP 4.0.1).
</simpara>
</listitem>
<listitem>
<simpara>
To acquire an exclusive lock (writer), set
<parameter>operation</parameter> to <constant>LOCK_EX</constant> (set to 2 prior to
PHP 4.0.1).
</simpara>
</listitem>
<listitem>
<simpara>
To release a lock (shared or exclusive), set
<parameter>operation</parameter> to <constant>LOCK_UN</constant> (set to 3 prior to
PHP 4.0.1).
</simpara>
</listitem>
<listitem>
<simpara>
If you don't want <function>flock</function> to block while
locking, add <constant>LOCK_NB</constant> (4 prior to PHP 4.0.1) to
<parameter>operation</parameter>.
</simpara>
</listitem>
</itemizedlist>
</para>
<simpara>
<function>flock</function> allows you to perform a simple
reader/writer model which can be used on virtually every platform
(including most Unix derivatives and even Windows). The optional third
argument is set to &true; if the lock would block (EWOULDBLOCK
errno condition). The lock is released also by <function>fclose</function>
(which is also called automatically when script finished).
</simpara>
<simpara>
&return.success;
</simpara>
<para>
<example>
<title><function>flock</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -93,39 +93,39 @@ fclose($fp);
?>
]]>
</programlisting>
</example>
</para>
<note>
<para>
Because <function>flock</function> requires a file pointer, you may have
to use a special lock file to protect access to a file that you intend
to truncate by opening it in write mode (with a "w" or "w+" argument to
<function>fopen</function>).
</para>
</note>
<warning>
<para>
<function>flock</function> will not work on NFS and many other networked
file systems. Check your operating system documentation for more
details.
</para>
<para>
On some operating systems <function>flock</function> is implemented at
the process level. When using a multithreaded server API like ISAPI you
may not be able to rely on <function>flock</function> to protect files
against other PHP scripts running in parallel threads of the same server
instance!
</para>
<para>
<function>flock</function> is not supported on antiquated filesystems like
<literal>FAT</literal> and its derivates and will therefore always
return &false; under this environments (this is especially true for
Windows 98 users).
</para>
</warning>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<note>
<para>
Because <function>flock</function> requires a file pointer, you may have
to use a special lock file to protect access to a file that you intend
to truncate by opening it in write mode (with a "w" or "w+" argument to
<function>fopen</function>).
</para>
</note>
<warning>
<para>
<function>flock</function> will not work on NFS and many other networked
file systems. Check your operating system documentation for more
details.
</para>
<para>
On some operating systems <function>flock</function> is implemented at
the process level. When using a multithreaded server API like ISAPI you
may not be able to rely on <function>flock</function> to protect files
against other PHP scripts running in parallel threads of the same server
instance!
</para>
<para>
<function>flock</function> is not supported on antiquated filesystems like
<literal>FAT</literal> and its derivates and will therefore always
return &false; under this environments (this is especially true for
Windows 98 users).
</para>
</warning>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

96
reference/filesystem/functions/fnmatch.xml
View file

@ -1,35 +1,35 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<refentry id="function.fnmatch">
<refnamediv>
<refname>fnmatch</refname>
<refpurpose>Match filename against a pattern</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>fnmatch</methodname>
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
<function>fnmatch</function> checks if the passed <parameter>string</parameter> would
match the given shell wildcard <parameter>pattern</parameter>.
</para>
<para>
This is especially useful for filenames, but may also be used on regular strings.
The average user may be used to shell patterns or at least in their simplest form
to <literal>'?'</literal> and <literal>'*'</literal> wildcards so using
<function>fnmatch</function> instead of <function>ereg</function> or
<function>preg_match</function> for frontend search expression input may be
way more convenient for non-programming users.
</para>
<example>
<title>
Checking a color name against a shell wildcard pattern.
</title>
<programlisting role="php">
<!-- $Revision: 1.11 $ -->
<refentry id="function.fnmatch">
<refnamediv>
<refname>fnmatch</refname>
<refpurpose>Match filename against a pattern</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>fnmatch</methodname>
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
<function>fnmatch</function> checks if the passed <parameter>string</parameter> would
match the given shell wildcard <parameter>pattern</parameter>.
</para>
<para>
This is especially useful for filenames, but may also be used on regular strings.
The average user may be used to shell patterns or at least in their simplest form
to <literal>'?'</literal> and <literal>'*'</literal> wildcards so using
<function>fnmatch</function> instead of <function>ereg</function> or
<function>preg_match</function> for frontend search expression input may be
way more convenient for non-programming users.
</para>
<example>
<title>
Checking a color name against a shell wildcard pattern.
</title>
<programlisting role="php">
<![CDATA[
<?php
if (fnmatch("*gr[ae]y", $color)) {
@ -37,23 +37,23 @@ if (fnmatch("*gr[ae]y", $color)) {
}
?>
]]>
</programlisting>
</example>
<warning>
<para>
For now this function is not available on Windows or other non-POSIX
compliant systems.
</para>
</warning>
<para>
See also <function>glob</function>,
<function>ereg</function>,
<function>preg_match</function>
and the Unix manpage on <literal>fnmatch(3)</literal> for flag names
(as long as they are not documented here <!-- TODO hartmut -->).
</para>
</refsect1>
</refentry>
</programlisting>
</example>
<warning>
<para>
For now this function is not available on Windows or other non-POSIX
compliant systems.
</para>
</warning>
<para>
See also <function>glob</function>,
<function>ereg</function>,
<function>preg_match</function>
and the Unix manpage on <literal>fnmatch(3)</literal> for flag names
(as long as they are not documented here <!-- TODO hartmut -->).
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

514
reference/filesystem/functions/fopen.xml
View file

@ -1,227 +1,227 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.29 $ -->
<!-- $Revision: 1.30 $ -->
<!-- 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>context</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. (e.g. &php.ini; value
<literal>user_agent</literal> used by the <literal>http</literal> wrapper).
</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">
<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>context</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. (e.g. &php.ini; value
<literal>user_agent</literal> used by the <literal>http</literal> wrapper).
</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");
@ -230,46 +230,46 @@ $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">
</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>,
<function>popen</function>, and
<function>stream_context_create</function>.
</simpara>
</refsect1>
</refentry>
</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>,
<function>popen</function>, and
<function>stream_context_create</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

122
reference/filesystem/functions/fpassthru.xml
View file

@ -1,56 +1,56 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fpassthru">
<refnamediv>
<refname>fpassthru</refname>
<refpurpose>Output all remaining data on a file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fpassthru</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<simpara>
Reads to EOF on the given file pointer from the current position and
writes the results to the output buffer.
</simpara>
<simpara>
If an error occurs, <function>fpassthru</function> returns
&false;. Otherwise, <function>fpassthru</function> returns
the number of characters read from <parameter>handle</parameter>
and passed through to the output.
</simpara>
&fs.validfp.all;
<simpara>
You may need to call <function>rewind</function> to reset the file
pointer to the beginning of the file if you have already written data
to the file.
</simpara>
<simpara>
If you just want to dump the contents of a file to the output buffer,
without first modifying it or seeking to a particular offset, you may
want to use the <function>readfile</function>, which saves you
the <function>fopen</function> call.
</simpara>
<note>
<para>
When using <function>fpassthru</function> on a binary file on Windows
systems, you should make sure to open the file in binary mode by
appending a <literal>b</literal> to the mode used in the call to
<function>fopen</function>.
</para>
<para>
You are encouraged to use the <literal>b</literal> flag when dealing
with binary files, even if your system does not require it, so that
your scripts will be more portable.
</para>
</note>
<para>
<example>
<title>Using <function>fpassthru</function> with binary files</title>
<programlisting role="php">
<refentry id="function.fpassthru">
<refnamediv>
<refname>fpassthru</refname>
<refpurpose>Output all remaining data on a file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fpassthru</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<simpara>
Reads to EOF on the given file pointer from the current position and
writes the results to the output buffer.
</simpara>
<simpara>
If an error occurs, <function>fpassthru</function> returns
&false;. Otherwise, <function>fpassthru</function> returns
the number of characters read from <parameter>handle</parameter>
and passed through to the output.
</simpara>
&fs.validfp.all;
<simpara>
You may need to call <function>rewind</function> to reset the file
pointer to the beginning of the file if you have already written data
to the file.
</simpara>
<simpara>
If you just want to dump the contents of a file to the output buffer,
without first modifying it or seeking to a particular offset, you may
want to use the <function>readfile</function>, which saves you
the <function>fopen</function> call.
</simpara>
<note>
<para>
When using <function>fpassthru</function> on a binary file on Windows
systems, you should make sure to open the file in binary mode by
appending a <literal>b</literal> to the mode used in the call to
<function>fopen</function>.
</para>
<para>
You are encouraged to use the <literal>b</literal> flag when dealing
with binary files, even if your system does not require it, so that
your scripts will be more portable.
</para>
</note>
<para>
<example>
<title>Using <function>fpassthru</function> with binary files</title>
<programlisting role="php">
<![CDATA[
<?php
@ -68,16 +68,16 @@ exit;
?>
]]>
</programlisting>
</example>
</para>
<simpara>
See also <function>readfile</function>,
<function>fopen</function>, <function>popen</function>, and
<function>fsockopen</function>
</simpara>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<simpara>
See also <function>readfile</function>,
<function>fopen</function>, <function>popen</function>, and
<function>fsockopen</function>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

88
reference/filesystem/functions/fputcsv.xml
View file

@ -1,40 +1,38 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.3 $ -->
<refentry id="function.fputcsv">
<refnamediv>
<refname>fputcsv</refname>
<refpurpose>
Format line as CSV and write to file pointer
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fputcsv</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>fields</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>delimiter</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>enclosure</parameter></methodparam>
</methodsynopsis>
<para>
<function>fputcsv</function> formats a line (passed as a
<parameter>fields</parameter> array) as CSV and write it to the
specified file <parameter>handle</parameter>. Returns the length of the
written string, or &false; on failure.
</para>
<para>
The optional <parameter>delimiter</parameter> parameter sets the field
delimiter (one character only). Defaults as a comma: <literal>,</literal>.
</para>
<para>
The optional <parameter>enclosure</parameter> parameter sets the field
enclosure (one character only) and defaults to a double quotation mark:
<literal>"</literal>.
</para>
<para>
<example>
<title><function>fputcsv</function> example</title>
<programlisting role="php">
<!-- $Revision: 1.4 $ -->
<refentry id="function.fputcsv">
<refnamediv>
<refname>fputcsv</refname>
<refpurpose>Format line as CSV and write to file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fputcsv</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>fields</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>delimiter</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>enclosure</parameter></methodparam>
</methodsynopsis>
<para>
<function>fputcsv</function> formats a line (passed as a
<parameter>fields</parameter> array) as CSV and write it to the
specified file <parameter>handle</parameter>. Returns the length of the
written string, or &false; on failure.
</para>
<para>
The optional <parameter>delimiter</parameter> parameter sets the field
delimiter (one character only). Defaults as a comma: <literal>,</literal>.
</para>
<para>
The optional <parameter>enclosure</parameter> parameter sets the field
enclosure (one character only) and defaults to a double quotation mark:
<literal>"</literal>.
</para>
<para>
<example>
<title><function>fputcsv</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -53,15 +51,15 @@ foreach ($list as $line) {
fclose($fp);
?>
]]>
</programlisting>
</example>
</para>
&note.line-endings;
<para>
See also <function>fgetcsv</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
&note.line-endings;
<para>
See also <function>fgetcsv</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

164
reference/filesystem/functions/fread.xml
View file

@ -1,33 +1,33 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.21 $ -->
<!-- $Revision: 1.22 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.25 -->
<refentry id="function.fread">
<refnamediv>
<refname>fread</refname>
<refpurpose>Binary-safe file read</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>fread</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>int</type><parameter>length</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>fread</function> reads up to
<parameter>length</parameter> bytes from the file pointer
referenced by <parameter>handle</parameter>. Reading stops when up to
<parameter>length</parameter> bytes have been read, EOF
(end of file) is reached, (for network streams) when a packet becomes
available, or (after opening userspace stream) when 8192 bytes have been read
whichever comes first.
</simpara>
<simpara>
Returns the read string or &false; in case of error.
</simpara>
<para>
<informalexample>
<programlisting role="php">
<refentry id="function.fread">
<refnamediv>
<refname>fread</refname>
<refpurpose>Binary-safe file read</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>fread</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>int</type><parameter>length</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>fread</function> reads up to
<parameter>length</parameter> bytes from the file pointer
referenced by <parameter>handle</parameter>. Reading stops when up to
<parameter>length</parameter> bytes have been read, EOF
(end of file) is reached, (for network streams) when a packet becomes
available, or (after opening userspace stream) when 8192 bytes have been read
whichever comes first.
</simpara>
<simpara>
Returns the read string or &false; in case of error.
</simpara>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
// get contents of a file into a string
@ -37,19 +37,19 @@ $contents = fread($handle, filesize($filename));
fclose($handle);
?>
]]>
</programlisting>
</informalexample>
</para>
<warning>
<para>
On systems which differentiate between binary and text files
(i.e. Windows) the file must be opened with 'b' included in
<function>fopen</function> mode parameter.
</para>
</warning>
<para>
<informalexample>
<programlisting role="php">
</programlisting>
</informalexample>
</para>
<warning>
<para>
On systems which differentiate between binary and text files
(i.e. Windows) the file must be opened with 'b' included in
<function>fopen</function> mode parameter.
</para>
</warning>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$filename = "c:\\files\\somepic.gif";
@ -58,23 +58,23 @@ $contents = fread($handle, filesize($filename));
fclose($handle);
?>
]]>
</programlisting>
</informalexample>
</para>
</programlisting>
</informalexample>
</para>
<warning>
<para>
When reading from anything that is not a regular local file, such as
streams returned when
reading <link linkend="features.remote-files">remote files</link> or from
<function>popen</function> and <function>fsockopen</function>, reading
will stop after a packet is available. This means that you should
collect the data together in chunks as shown in the examples below.
</para>
</warning>
<para>
<informalexample>
<programlisting role="php">
<warning>
<para>
When reading from anything that is not a regular local file, such as
streams returned when
reading <link linkend="features.remote-files">remote files</link> or from
<function>popen</function> and <function>fsockopen</function>, reading
will stop after a packet is available. This means that you should
collect the data together in chunks as shown in the examples below.
</para>
</warning>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
// For PHP 5 and up
@ -83,12 +83,12 @@ $contents = stream_get_contents($handle);
fclose($handle);
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
<informalexample>
<programlisting role="php">
</programlisting>
</informalexample>
</para>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$handle = fopen("http://www.example.com/", "rb");
@ -99,25 +99,25 @@ while (!feof($handle)) {
fclose($handle);
?>
]]>
</programlisting>
</informalexample>
</para>
<note>
<para>
If you just want to get the contents of a file into a string, use
<function>file_get_contents</function> as it has much better performance
than the code above.
</para>
</note>
<simpara>
See also <function>fwrite</function>, <function>fopen</function>,
<function>fsockopen</function>, <function>popen</function>,
<function>fgets</function>, <function>fgetss</function>,
<function>fscanf</function>, <function>file</function>, and
<function>fpassthru</function>.
</simpara>
</refsect1>
</refentry>
</programlisting>
</informalexample>
</para>
<note>
<para>
If you just want to get the contents of a file into a string, use
<function>file_get_contents</function> as it has much better performance
than the code above.
</para>
</note>
<simpara>
See also <function>fwrite</function>, <function>fopen</function>,
<function>fsockopen</function>, <function>popen</function>,
<function>fgets</function>, <function>fgetss</function>,
<function>fscanf</function>, <function>file</function>, and
<function>fpassthru</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

112
reference/filesystem/functions/fscanf.xml
View file

@ -1,39 +1,39 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
<!-- $Revision: 1.17 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fscanf">
<refnamediv>
<refname>fscanf</refname>
<refpurpose>Parses input from a file according to a format</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>fscanf</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter role="reference">...</parameter></methodparam>
</methodsynopsis>
<para>
The function <function>fscanf</function> is similar to
<function>sscanf</function>, but it takes its input from a file
associated with <parameter>handle</parameter> and interprets the
input according to the specified <parameter>format</parameter>, which is
described in the documentation for <function>sprintf</function>. If only
two parameters were passed to this function, the values parsed will be
returned as an array. Otherwise, if optional parameters are passed, the
function will return the number of assigned values. The optional
parameters must be passed by reference.
</para>
<para>
Any whitespace in the format string matches any whitespace in the input
stream. This means that even a tab <literal>\t</literal> in the format
string can match a single space character in the input stream.
</para>
<para>
<example>
<title><function>fscanf</function> Example</title>
<programlisting role="php">
<refentry id="function.fscanf">
<refnamediv>
<refname>fscanf</refname>
<refpurpose>Parses input from a file according to a format</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>fscanf</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter role="reference">...</parameter></methodparam>
</methodsynopsis>
<para>
The function <function>fscanf</function> is similar to
<function>sscanf</function>, but it takes its input from a file
associated with <parameter>handle</parameter> and interprets the
input according to the specified <parameter>format</parameter>, which is
described in the documentation for <function>sprintf</function>. If only
two parameters were passed to this function, the values parsed will be
returned as an array. Otherwise, if optional parameters are passed, the
function will return the number of assigned values. The optional
parameters must be passed by reference.
</para>
<para>
Any whitespace in the format string matches any whitespace in the input
stream. This means that even a tab <literal>\t</literal> in the format
string can match a single space character in the input stream.
</para>
<para>
<example>
<title><function>fscanf</function> Example</title>
<programlisting role="php">
<![CDATA[
<?php
$handle = fopen("users.txt", "r");
@ -44,34 +44,34 @@ while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
fclose($handle);
?>
]]>
</programlisting>
</example>
<example>
<title>Contents of users.txt</title>
<programlisting role="txt">
</programlisting>
</example>
<example>
<title>Contents of users.txt</title>
<programlisting role="txt">
<![CDATA[
javier argonaut pe
hiroshi sculptor jp
robert slacker us
luigi florist it
]]>
</programlisting>
</example>
</para>
<note>
<simpara>
Prior to PHP 4.3.0, the maximum number of characters read from
the file was 512 (or up to the first \n, whichever came first).
As of PHP 4.3.0 arbitrarily long lines will be read and scanned.
</simpara>
</note>
<para>
See also <function>fread</function>, <function>fgets</function>,
<function>fgetss</function>, <function>sscanf</function>,
<function>printf</function>, and <function>sprintf</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<note>
<simpara>
Prior to PHP 4.3.0, the maximum number of characters read from
the file was 512 (or up to the first \n, whichever came first).
As of PHP 4.3.0 arbitrarily long lines will be read and scanned.
</simpara>
</note>
<para>
See also <function>fread</function>, <function>fgets</function>,
<function>fgetss</function>, <function>sscanf</function>,
<function>printf</function>, and <function>sprintf</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

134
reference/filesystem/functions/fseek.xml
View file

@ -1,46 +1,46 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fseek">
<refnamediv>
<refname>fseek</refname>
<refpurpose>Seeks on a file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fseek</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>int</type><parameter>offset</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>whence</parameter></methodparam>
</methodsynopsis>
<para>
Sets the file position indicator for the file referenced by
<parameter>handle</parameter>. The new position, measured in bytes
from the beginning of the file, is obtained by adding
<parameter>offset</parameter> to the position specified by
<parameter>whence</parameter>, whose values are defined as
follows:
<simplelist>
<member><constant>SEEK_SET</constant> - Set position equal to <parameter>offset</parameter> bytes.</member>
<member><constant>SEEK_CUR</constant> - Set position to current location plus <parameter>offset</parameter>.</member>
<member><constant>SEEK_END</constant> - Set position to end-of-file plus <parameter>offset</parameter>.
(To move to a position before the end-of-file, you need to pass a negative
value in <parameter>offset</parameter>.)</member>
</simplelist>
</para>
<para>
If <parameter>whence</parameter> is not specified, it is assumed to be
<constant>SEEK_SET</constant>.
</para>
<para>
Upon success, returns 0; otherwise, returns -1. Note that seeking
past EOF is not considered an error.
</para>
<para>
<example>
<title><function>fseek</function> example</title>
<programlisting role="php">
<refentry id="function.fseek">
<refnamediv>
<refname>fseek</refname>
<refpurpose>Seeks on a file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fseek</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>int</type><parameter>offset</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>whence</parameter></methodparam>
</methodsynopsis>
<para>
Sets the file position indicator for the file referenced by
<parameter>handle</parameter>. The new position, measured in bytes
from the beginning of the file, is obtained by adding
<parameter>offset</parameter> to the position specified by
<parameter>whence</parameter>, whose values are defined as
follows:
<simplelist>
<member><constant>SEEK_SET</constant> - Set position equal to <parameter>offset</parameter> bytes.</member>
<member><constant>SEEK_CUR</constant> - Set position to current location plus <parameter>offset</parameter>.</member>
<member><constant>SEEK_END</constant> - Set position to end-of-file plus <parameter>offset</parameter>.
(To move to a position before the end-of-file, you need to pass a negative
value in <parameter>offset</parameter>.)</member>
</simplelist>
</para>
<para>
If <parameter>whence</parameter> is not specified, it is assumed to be
<constant>SEEK_SET</constant>.
</para>
<para>
Upon success, returns 0; otherwise, returns -1. Note that seeking
past EOF is not considered an error.
</para>
<para>
<example>
<title><function>fseek</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -55,32 +55,32 @@ fseek($fp, 0);
?>
]]>
</programlisting>
</example>
</para>
<para>
May not be used on file pointers returned by
<function>fopen</function> if they use the "http://" or "ftp://"
formats. <function>fseek</function> gives also undefined results for
append-only streams (opened with "a" flag).
</para>
<note>
<para>
The <parameter>whence</parameter> argument was added after PHP 4.0.0.
</para>
</note>
<note>
<para>
If you have opened the file in append ("a" or "a+") mode, any data you write
to the file will always be appended, regardless of the file position.
</para>
</note>
<para>
See also <function>ftell</function> and
<function>rewind</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<para>
May not be used on file pointers returned by
<function>fopen</function> if they use the "http://" or "ftp://"
formats. <function>fseek</function> gives also undefined results for
append-only streams (opened with "a" flag).
</para>
<note>
<para>
The <parameter>whence</parameter> argument was added after PHP 4.0.0.
</para>
</note>
<note>
<para>
If you have opened the file in append ("a" or "a+") mode, any data you write
to the file will always be appended, regardless of the file position.
</para>
</note>
<para>
See also <function>ftell</function> and
<function>rewind</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

72
reference/filesystem/functions/fstat.xml
View file

@ -1,31 +1,31 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.24 -->
<refentry id="function.fstat">
<refnamediv>
<refname>fstat</refname>
<refpurpose>Gets information about a file using an open file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>fstat</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
Gathers the statistics of the file opened by the file
pointer <parameter>handle</parameter>. This function is similar to the
<function>stat</function> function except that it operates
on an open file pointer instead of a filename.
</para>
<para>
Returns an array with the statistics of the file; the format of the array
is described in detail on the <function>stat</function> manual page.
</para>
<para>
<example>
<title><function>fstat</function> example</title>
<programlisting role="php">
<refentry id="function.fstat">
<refnamediv>
<refname>fstat</refname>
<refpurpose>Gets information about a file using an open file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>fstat</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
Gathers the statistics of the file opened by the file
pointer <parameter>handle</parameter>. This function is similar to the
<function>stat</function> function except that it operates
on an open file pointer instead of a filename.
</para>
<para>
Returns an array with the statistics of the file; the format of the array
is described in detail on the <function>stat</function> manual page.
</para>
<para>
<example>
<title><function>fstat</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -43,9 +43,9 @@ print_r(array_slice($fstat, 13));
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Array
(
@ -64,14 +64,14 @@ Array
[blocks] => 8
)
]]>
</screen>
</example>
</para>
&note.no-remote;
</screen>
</example>
</para>
</refsect1>
</refentry>
&note.no-remote;
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

80
reference/filesystem/functions/ftell.xml
View file

@ -1,36 +1,36 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.ftell">
<refnamediv>
<refname>ftell</refname>
<refpurpose>Tells file pointer read/write position</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>ftell</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
Returns the position of the file pointer referenced by
<parameter>handle</parameter>; i.e., its offset into the
file stream.
</para>
<para>
If an error occurs, returns &false;.
</para>
<para>
The file pointer must be valid, and must point to a file
successfully opened by <function>fopen</function> or
<function>popen</function>.
<function>ftell</function> gives undefined results for append-only streams
(opened with "a" flag).
</para>
<para>
<example>
<title><function>ftell</function> example</title>
<programlisting role="php">
<refentry id="function.ftell">
<refnamediv>
<refname>ftell</refname>
<refpurpose>Tells file pointer read/write position</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>ftell</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
Returns the position of the file pointer referenced by
<parameter>handle</parameter>; i.e., its offset into the
file stream.
</para>
<para>
If an error occurs, returns &false;.
</para>
<para>
The file pointer must be valid, and must point to a file
successfully opened by <function>fopen</function> or
<function>popen</function>.
<function>ftell</function> gives undefined results for append-only streams
(opened with "a" flag).
</para>
<para>
<example>
<title><function>ftell</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -45,15 +45,15 @@ fclose($fp);
?>
]]>
</programlisting>
</example>
</para>
<para>
See also <function>fopen</function>, <function>popen</function>,
<function>fseek</function>, and <function>rewind</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<para>
See also <function>fopen</function>, <function>popen</function>,
<function>fseek</function>, and <function>rewind</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

74
reference/filesystem/functions/ftruncate.xml
View file

@ -1,42 +1,42 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.14 -->
<refentry id="function.ftruncate">
<refnamediv>
<refname>ftruncate</refname>
<refpurpose>Truncates a file to a given length</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>ftruncate</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>int</type><parameter>size</parameter></methodparam>
</methodsynopsis>
<para>
Takes the filepointer, <parameter>handle</parameter>, and truncates the file to
length, <parameter>size</parameter>. &return.success;
</para>
<note>
<para>
The file pointer is changed only in <emphasis>append</emphasis> mode. In
<emphasis>write</emphasis> mode, additional <function>fseek</function>
call is needed.
</para>
</note>
<note>
<para>
Prior to PHP 4.3.3, <function>ftruncate</function> returns an
<type>integer</type> value of 1 on success, instead of
<type>boolean</type> &true;.
</para>
</note>
<para>
See also <function>fopen</function> and
<function>fseek</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.ftruncate">
<refnamediv>
<refname>ftruncate</refname>
<refpurpose>Truncates a file to a given length</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>ftruncate</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>int</type><parameter>size</parameter></methodparam>
</methodsynopsis>
<para>
Takes the filepointer, <parameter>handle</parameter>, and truncates the file to
length, <parameter>size</parameter>. &return.success;
</para>
<note>
<para>
The file pointer is changed only in <emphasis>append</emphasis> mode. In
<emphasis>write</emphasis> mode, additional <function>fseek</function>
call is needed.
</para>
</note>
<note>
<para>
Prior to PHP 4.3.3, <function>ftruncate</function> returns an
<type>integer</type> value of 1 on success, instead of
<type>boolean</type> &true;.
</para>
</note>
<para>
See also <function>fopen</function> and
<function>fseek</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

122
reference/filesystem/functions/fwrite.xml
View file

@ -1,51 +1,51 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- $Revision: 1.14 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fwrite">
<refnamediv>
<refname>fwrite</refname>
<refpurpose>Binary-safe file write</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fwrite</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>fwrite</function> writes the contents of
<parameter>string</parameter> to the file stream pointed to by
<parameter>handle</parameter>. If the <parameter>length</parameter>
argument is given, writing will stop after
<parameter>length</parameter> bytes have been written or the end
of <parameter>string</parameter> is reached, whichever comes
first.
</simpara>
<simpara>
<function>fwrite</function> returns the number of bytes
written, or &false; on error.
</simpara>
<simpara>
Note that if the <parameter>length</parameter> argument is given,
then the <link
linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
configuration option will be ignored and no slashes will be
stripped from <parameter>string</parameter>.
</simpara>
<note>
<para>
On systems which differentiate between binary and text files
(i.e. Windows) the file must be opened with 'b' included in
<function>fopen</function> mode parameter.
</para>
</note>
<para>
<example>
<title>A simple <function>fwrite</function> example</title>
<programlisting role="php">
<![CDATA[
<refentry id="function.fwrite">
<refnamediv>
<refname>fwrite</refname>
<refpurpose>Binary-safe file write</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>fwrite</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>fwrite</function> writes the contents of
<parameter>string</parameter> to the file stream pointed to by
<parameter>handle</parameter>. If the <parameter>length</parameter>
argument is given, writing will stop after
<parameter>length</parameter> bytes have been written or the end
of <parameter>string</parameter> is reached, whichever comes
first.
</simpara>
<simpara>
<function>fwrite</function> returns the number of bytes
written, or &false; on error.
</simpara>
<simpara>
Note that if the <parameter>length</parameter> argument is given,
then the <link
linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
configuration option will be ignored and no slashes will be
stripped from <parameter>string</parameter>.
</simpara>
<note>
<para>
On systems which differentiate between binary and text files
(i.e. Windows) the file must be opened with 'b' included in
<function>fopen</function> mode parameter.
</para>
</note>
<para>
<example>
<title>A simple <function>fwrite</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$filename = 'test.txt';
$somecontent = "Add this to the file\n";
@ -54,7 +54,7 @@ $somecontent = "Add this to the file\n";
if (is_writable($filename)) {
// In our example we're opening $filename in append mode.
// The file pointer is at the bottom of the file hence
// The file pointer is at the bottom of the file hence
// that's where $somecontent will go when we fwrite() it.
if (!$handle = fopen($filename, 'a')) {
echo "Cannot open file ($filename)";
@ -66,9 +66,9 @@ if (is_writable($filename)) {
echo "Cannot write to file ($filename)";
exit;
}
echo "Success, wrote ($somecontent) to file ($filename)";
fclose($handle);
} else {
@ -76,18 +76,18 @@ if (is_writable($filename)) {
}
?>
]]>
</programlisting>
</example>
</para>
<simpara>
See also <function>fread</function>,
<function>fopen</function>,
<function>fsockopen</function>,
<function>popen</function>, and
<function>file_put_contents</function>.
</simpara>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<simpara>
See also <function>fread</function>,
<function>fopen</function>,
<function>fsockopen</function>,
<function>popen</function>, and
<function>file_put_contents</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

220
reference/filesystem/functions/glob.xml
View file

@ -1,93 +1,93 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.22 $ -->
<refentry id="function.glob">
<refnamediv>
<refname>glob</refname>
<refpurpose>Find pathnames matching a pattern</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>glob</methodname>
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
The <function>glob</function> function searches for all the pathnames
matching <parameter>pattern</parameter> according to the rules used by
the libc glob() function, which is similar to the rules used by common
shells. No tilde expansion or parameter substitution is done.
</para>
<para>
Returns an array containing the matched files/directories, an empty array
if no file matched or &false; on error.
</para>
<para>
Valid flags:
<itemizedlist>
<listitem>
<simpara>
<constant>GLOB_MARK</constant> - Adds a slash to each item returned
</simpara>
</listitem>
<listitem>
<simpara>
<constant>GLOB_NOSORT</constant> - Return files as they appear in the
directory (no sorting)
</simpara>
</listitem>
<listitem>
<simpara>
<constant>GLOB_NOCHECK</constant> - Return the search pattern if no
files matching it were found
</simpara>
</listitem>
<listitem>
<simpara>
<constant>GLOB_NOESCAPE</constant> - Backslashes do not quote
metacharacters
</simpara>
</listitem>
<listitem>
<simpara>
<constant>GLOB_BRACE</constant> - Expands {a,b,c} to match 'a', 'b',
or 'c'
</simpara>
<note>
<simpara>
This flag is not available on some non GNU systems, like Solaris.
</simpara>
</note>
</listitem>
<listitem>
<simpara>
<constant>GLOB_ONLYDIR</constant> - Return only directory entries
which match the pattern
</simpara>
<note>
<simpara>
Before PHP 4.3.3 <constant>GLOB_ONLYDIR</constant> was
<emphasis role="strong">not</emphasis>
available on Windows and other systems not using the GNU
C library.
</simpara>
</note>
</listitem>
<listitem>
<simpara>
<constant>GLOB_ERR</constant> - Stop on read errors (like unreadable
directories), by default errors are ignored. Added in PHP 5.1.0.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
<example>
<title>
Convenient way how <function>glob</function> can replace
<function>opendir</function> and friends.
</title>
<programlisting role="php">
<!-- $Revision: 1.23 $ -->
<refentry id="function.glob">
<refnamediv>
<refname>glob</refname>
<refpurpose>Find pathnames matching a pattern</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>glob</methodname>
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
The <function>glob</function> function searches for all the pathnames
matching <parameter>pattern</parameter> according to the rules used by
the libc glob() function, which is similar to the rules used by common
shells. No tilde expansion or parameter substitution is done.
</para>
<para>
Returns an array containing the matched files/directories, an empty array
if no file matched or &false; on error.
</para>
<para>
Valid flags:
<itemizedlist>
<listitem>
<simpara>
<constant>GLOB_MARK</constant> - Adds a slash to each item returned
</simpara>
</listitem>
<listitem>
<simpara>
<constant>GLOB_NOSORT</constant> - Return files as they appear in the
directory (no sorting)
</simpara>
</listitem>
<listitem>
<simpara>
<constant>GLOB_NOCHECK</constant> - Return the search pattern if no
files matching it were found
</simpara>
</listitem>
<listitem>
<simpara>
<constant>GLOB_NOESCAPE</constant> - Backslashes do not quote
metacharacters
</simpara>
</listitem>
<listitem>
<simpara>
<constant>GLOB_BRACE</constant> - Expands {a,b,c} to match 'a', 'b',
or 'c'
</simpara>
<note>
<simpara>
This flag is not available on some non GNU systems, like Solaris.
</simpara>
</note>
</listitem>
<listitem>
<simpara>
<constant>GLOB_ONLYDIR</constant> - Return only directory entries
which match the pattern
</simpara>
<note>
<simpara>
Before PHP 4.3.3 <constant>GLOB_ONLYDIR</constant> was
<emphasis role="strong">not</emphasis>
available on Windows and other systems not using the GNU
C library.
</simpara>
</note>
</listitem>
<listitem>
<simpara>
<constant>GLOB_ERR</constant> - Stop on read errors (like unreadable
directories), by default errors are ignored. Added in PHP 5.1.0.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
<example>
<title>
Convenient way how <function>glob</function> can replace
<function>opendir</function> and friends.
</title>
<programlisting role="php">
<![CDATA[
<?php
foreach (glob("*.txt") as $filename) {
@ -95,32 +95,32 @@ foreach (glob("*.txt") as $filename) {
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
funclist.txt size 44686
funcsummary.txt size 267625
quickref.txt size 137820
]]>
</screen>
</example>
</para>
&note.no-remote;
<note>
<simpara>
This function isn't available on some systems (e.g. old Sun OS).
</simpara>
</note>
<para>
See also <function>opendir</function>,
<function>readdir</function>,
<function>closedir</function>, and <function>fnmatch</function>.
</para>
</refsect1>
</refentry>
</screen>
</example>
</para>
&note.no-remote;
<note>
<simpara>
This function isn't available on some systems (e.g. old Sun OS).
</simpara>
</note>
<para>
See also <function>opendir</function>,
<function>readdir</function>,
<function>closedir</function>, and <function>fnmatch</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

72
reference/filesystem/functions/is-dir.xml
View file

@ -1,27 +1,27 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.is-dir">
<refnamediv>
<refname>is_dir</refname>
<refpurpose>Tells whether the filename is a directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_dir</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the filename exists and is a directory. If
<parameter>filename</parameter> is a relative filename, it will be
checked relative to the current working directory.
</para>
&note.clearstatcache;
<para>
<example>
<title><function>is_dir</function> example</title>
<programlisting role="php">
<refentry id="function.is-dir">
<refnamediv>
<refname>is_dir</refname>
<refpurpose>Tells whether the filename is a directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_dir</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the filename exists and is a directory. If
<parameter>filename</parameter> is a relative filename, it will be
checked relative to the current working directory.
</para>
&note.clearstatcache;
<para>
<example>
<title><function>is_dir</function> example</title>
<programlisting role="php">
<![CDATA[
<?
var_dump(is_dir('a_file.txt')) . "\n";
@ -30,26 +30,26 @@ var_dump(is_dir('bogus_dir/abc')) . "\n";
var_dump(is_dir('..')); //one dir up
?>
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
bool(false)
bool(false)
bool(true)
]]>
</screen>
</example>
</para>
&tip.fopen-wrapper.stat;
</screen>
</example>
</para>
&tip.fopen-wrapper.stat;
<para>
See also <function>chdir</function>, <link linkend="class.dir">dir</link>,
<function>opendir</function>, <function>is_file</function> and
<function>is_link</function>.
</para>
</refsect1>
</refentry>
<para>
See also <function>chdir</function>, <link linkend="class.dir">dir</link>,
<function>opendir</function>, <function>is_file</function> and
<function>is_link</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

70
reference/filesystem/functions/is-executable.xml
View file

@ -1,28 +1,28 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- $Revision: 1.13 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.is-executable">
<refnamediv>
<refname>is_executable</refname>
<refpurpose>Tells whether the filename is executable</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_executable</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the filename exists and is executable.
</para>
<para>
<function>is_executable</function> became available with
<productname>Windows</productname> in PHP version 5.0.0.
</para>
<para>
<example>
<title><function>is_executable</function> example</title>
<programlisting role="php">
<refentry id="function.is-executable">
<refnamediv>
<refname>is_executable</refname>
<refpurpose>Tells whether the filename is executable</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_executable</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the filename exists and is executable.
</para>
<para>
<function>is_executable</function> became available with
<productname>Windows</productname> in PHP version 5.0.0.
</para>
<para>
<example>
<title><function>is_executable</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -36,20 +36,20 @@ if (is_executable($file)) {
?>
]]>
</programlisting>
</example>
</para>
&note.clearstatcache;
</programlisting>
</example>
</para>
&tip.fopen-wrapper.stat;
&note.clearstatcache;
<para>
See also <function>is_file</function> and
<function>is_link</function>.
</para>
</refsect1>
</refentry>
&tip.fopen-wrapper.stat;
<para>
See also <function>is_file</function> and
<function>is_link</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

68
reference/filesystem/functions/is-file.xml
View file

@ -1,51 +1,51 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- $Revision: 1.9 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.is-file">
<refnamediv>
<refname>is_file</refname>
<refpurpose>Tells whether the filename is a regular file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the filename exists and is a regular file.
</para>
<para>
<example>
<title><function>is_file</function> example</title>
<programlisting role="php">
<refentry id="function.is-file">
<refnamediv>
<refname>is_file</refname>
<refpurpose>Tells whether the filename is a regular file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the filename exists and is a regular file.
</para>
<para>
<example>
<title><function>is_file</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
var_dump(is_file('a_file.txt')) . "\n";
var_dump(is_file('/usr/bin/')) . "\n";
?>
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
bool(true)
bool(false)
]]>
</screen>
</example>
</para>
</screen>
</example>
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
&note.clearstatcache;
<para>
See also <function>is_dir</function> and
<function>is_link</function>.
</para>
</refsect1>
</refentry>
&tip.fopen-wrapper.stat;
<para>
See also <function>is_dir</function> and
<function>is_link</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

50
reference/filesystem/functions/is-link.xml
View file

@ -1,31 +1,31 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.is-link">
<refnamediv>
<refname>is_link</refname>
<refpurpose>Tells whether the filename is a symbolic link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_link</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the filename exists and is a symbolic link.
</para>
&note.clearstatcache;
<refentry id="function.is-link">
<refnamediv>
<refname>is_link</refname>
<refpurpose>Tells whether the filename is a symbolic link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_link</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the filename exists and is a symbolic link.
</para>
&tip.fopen-wrapper.stat;
<para>
See also <function>is_dir</function>,
<function>is_file</function>, and <function>readlink</function>.
</para>
</refsect1>
</refentry>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<para>
See also <function>is_dir</function>,
<function>is_file</function>, and <function>readlink</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

76
reference/filesystem/functions/is-readable.xml
View file

@ -1,31 +1,31 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.is-readable">
<refnamediv>
<refname>is_readable</refname>
<refpurpose>Tells whether the filename is readable</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_readable</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the file or directory specified by
<parameter>filename</parameter> exists and is readable.
</para>
<para>
Keep in mind that PHP may be accessing the file as the user
id that the web server runs as (often 'nobody'). Safe mode
limitations are not taken into account.
</para>
<para>
<example>
<title><function>is_readable</function> example</title>
<programlisting role="php">
<![CDATA[
<refentry id="function.is-readable">
<refnamediv>
<refname>is_readable</refname>
<refpurpose>Tells whether the filename is readable</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_readable</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the file or directory specified by
<parameter>filename</parameter> exists and is readable.
</para>
<para>
Keep in mind that PHP may be accessing the file as the user
id that the web server runs as (often 'nobody'). Safe mode
limitations are not taken into account.
</para>
<para>
<example>
<title><function>is_readable</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$filename = 'test.txt';
if (is_readable($filename)) {
@ -35,21 +35,21 @@ if (is_readable($filename)) {
}
?>
]]>
</programlisting>
</example>
</para>
</programlisting>
</example>
</para>
&note.clearstatcache;
&note.clearstatcache;
&tip.fopen-wrapper.stat;
&tip.fopen-wrapper.stat;
<para>
See also <function>is_writable</function>,
<function>file_exists</function>, and
<function>fgets</function>.
</para>
</refsect1>
</refentry>
<para>
See also <function>is_writable</function>,
<function>file_exists</function>, and
<function>fgets</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

118
reference/filesystem/functions/is-uploaded-file.xml
View file

@ -1,38 +1,38 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.39 -->
<refentry id="function.is-uploaded-file">
<refnamediv>
<refname>is_uploaded_file</refname>
<refpurpose>Tells whether the file was uploaded via HTTP POST</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_uploaded_file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the file named by <parameter>filename</parameter> was
uploaded via HTTP POST. This is useful to help ensure that a
malicious user hasn't tried to trick the script into working on
files upon which it should not be working--for instance,
<filename>/etc/passwd</filename>.
</para>
<para>
This sort of check is especially important if there is any chance
that anything done with uploaded files could reveal their
contents to the user, or even to other users on the same
system.
</para>
<para>
For proper working, the function <function>is_uploaded_file</function> needs
an argument like $_FILES['userfile']['tmp_name'], - the name of the uploaded
file on the clients machine $_FILES['userfile']['name'] does not work.
</para>
<example>
<title><function>is_uploaded_file</function> example</title>
<programlisting role="php">
<refentry id="function.is-uploaded-file">
<refnamediv>
<refname>is_uploaded_file</refname>
<refpurpose>Tells whether the file was uploaded via HTTP POST</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_uploaded_file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the file named by <parameter>filename</parameter> was
uploaded via HTTP POST. This is useful to help ensure that a
malicious user hasn't tried to trick the script into working on
files upon which it should not be working--for instance,
<filename>/etc/passwd</filename>.
</para>
<para>
This sort of check is especially important if there is any chance
that anything done with uploaded files could reveal their
contents to the user, or even to other users on the same
system.
</para>
<para>
For proper working, the function <function>is_uploaded_file</function> needs
an argument like $_FILES['userfile']['tmp_name'], - the name of the uploaded
file on the clients machine $_FILES['userfile']['name'] does not work.
</para>
<example>
<title><function>is_uploaded_file</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -46,28 +46,28 @@ if (is_uploaded_file($_FILES['userfile']['tmp_name'])) {
}
?>]]>
</programlisting>
</example>
</programlisting>
</example>
<para>
<function>is_uploaded_file</function> is available only in
versions of PHP 3 after PHP 3.0.16, and in versions of PHP 4
after 4.0.2. If you are stuck using an earlier version, you can
use the following function to help protect yourself:
<note>
<para>
<function>is_uploaded_file</function> is available only in
versions of PHP 3 after PHP 3.0.16, and in versions of PHP 4
after 4.0.2. If you are stuck using an earlier version, you can
use the following function to help protect yourself:
<note>
<para>
The following example will <emphasis>not</emphasis> work in
versions of PHP 4 after 4.0.2. It depends on internal
functionality of PHP which changed after that version.
</para>
</note>
The following example will <emphasis>not</emphasis> work in
versions of PHP 4 after 4.0.2. It depends on internal
functionality of PHP which changed after that version.
</para>
<example>
<title><function>is_uploaded_file</function> example for PHP 4 &lt; 4.0.3</title>
<programlisting role="php">
</note>
</para>
<example>
<title><function>is_uploaded_file</function> example for PHP 4 &lt; 4.0.3</title>
<programlisting role="php">
<![CDATA[
<?php
/* Userland test for uploaded file. */
function is_uploaded_file_4_0_2($filename)
function is_uploaded_file_4_0_2($filename)
{
if (!$tmp_file = get_cfg_var('upload_tmp_dir')) {
$tmp_file = dirname(tempnam('', ''));
@ -86,15 +86,15 @@ if (is_uploaded_file_4_0_2($HTTP_POST_FILES['userfile'])) {
}
?>
]]>
</programlisting>
</example>
<para>
See also <function>move_uploaded_file</function>, and the section
<link linkend="features.file-upload">Handling file uploads</link>
for a simple usage example.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
<para>
See also <function>move_uploaded_file</function>, and the section
<link linkend="features.file-upload">Handling file uploads</link>
for a simple usage example.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

82
reference/filesystem/functions/is-writable.xml
View file

@ -1,32 +1,32 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- $Revision: 1.9 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.is-writable">
<refnamediv>
<refname>is_writable</refname>
<refpurpose>Tells whether the filename is writable</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_writable</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the <parameter>filename</parameter> exists and is
writable. The filename argument may be a directory name allowing you
to check if a directory is writeable.
</para>
<para>
Keep in mind that PHP may be accessing the file as the user id
that the web server runs as (often 'nobody'). Safe mode
limitations are not taken into account.
</para>
<para>
<example>
<title><function>is_writable</function> example</title>
<programlisting role="php">
<![CDATA[
<refentry id="function.is-writable">
<refnamediv>
<refname>is_writable</refname>
<refpurpose>Tells whether the filename is writable</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>is_writable</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the <parameter>filename</parameter> exists and is
writable. The filename argument may be a directory name allowing you
to check if a directory is writeable.
</para>
<para>
Keep in mind that PHP may be accessing the file as the user id
that the web server runs as (often 'nobody'). Safe mode
limitations are not taken into account.
</para>
<para>
<example>
<title><function>is_writable</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$filename = 'test.txt';
if (is_writable($filename)) {
@ -36,21 +36,21 @@ if (is_writable($filename)) {
}
?>
]]>
</programlisting>
</example>
</para>
</programlisting>
</example>
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<para>
See also <function>is_readable</function>,
<function>file_exists</function>, and
<function>fwrite</function>.
</para>
</refsect1>
</refentry>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<para>
See also <function>is_readable</function>,
<function>file_exists</function>, and
<function>fwrite</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

64
reference/filesystem/functions/lchgrp.xml
View file

@ -1,36 +1,36 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.lchgrp">
<refnamediv>
<refname>lchgrp</refname>
<refpurpose>Changes group ownership of symlink</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>lchgrp</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>mixed</type><parameter>group</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to change the group of the symlink <parameter>filename</parameter>
to <parameter>group</parameter> (specified by name or number). Only the
superuser may change the group of a symlink arbitrarily; other users may
change the group of a symlink to any group of which that user is a member.
</para>
<para>
&return.success;
</para>
&note.no-remote;
&note.sm.uidcheck;
<para>
See also <function>chgrp</function>,
<function>lchown</function>
<function>chown</function>&listendand;
<function>chmod</function>.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.2 $ -->
<refentry id="function.lchgrp">
<refnamediv>
<refname>lchgrp</refname>
<refpurpose>Changes group ownership of symlink</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>lchgrp</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>mixed</type><parameter>group</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to change the group of the symlink <parameter>filename</parameter>
to <parameter>group</parameter> (specified by name or number). Only the
superuser may change the group of a symlink arbitrarily; other users may
change the group of a symlink to any group of which that user is a member.
</para>
<para>
&return.success;
</para>
&note.no-remote;
&note.sm.uidcheck;
<para>
See also <function>chgrp</function>,
<function>lchown</function>
<function>chown</function>&listendand;
<function>chmod</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

62
reference/filesystem/functions/lchown.xml
View file

@ -1,35 +1,35 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.lchown">
<refnamediv>
<refname>lchown</refname>
<refpurpose>Changes user ownership of symlink</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>lchown</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>mixed</type><parameter>user</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to change the owner of the symlink <parameter>filename</parameter>
to user <parameter>user</parameter> (specified by name or number). Only
the superuser may change the owner of a symlink.
</para>
<para>
&return.success;
</para>
&note.no-remote;
&note.sm.uidcheck;
<para>
See also <function>chown</function>,
<function>lchgrp</function>,
<function>chgrp</function>&listendand;
<function>chmod</function>.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.2 $ -->
<refentry id="function.lchown">
<refnamediv>
<refname>lchown</refname>
<refpurpose>Changes user ownership of symlink</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>lchown</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>mixed</type><parameter>user</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to change the owner of the symlink <parameter>filename</parameter>
to user <parameter>user</parameter> (specified by name or number). Only
the superuser may change the owner of a symlink.
</para>
<para>
&return.success;
</para>
&note.no-remote;
&note.sm.uidcheck;
<para>
See also <function>chown</function>,
<function>lchgrp</function>,
<function>chgrp</function>&listendand;
<function>chmod</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

52
reference/filesystem/functions/link.xml
View file

@ -1,32 +1,32 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.link">
<refnamediv>
<refname>link</refname>
<refpurpose>Create a hard link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>link</methodname>
<methodparam><type>string</type><parameter>target</parameter></methodparam>
<methodparam><type>string</type><parameter>link</parameter></methodparam>
</methodsynopsis>
<para>
<function>link</function> creates a hard link. &return.success;
</para>
&note.no-remote;
&note.no-windows;
<refentry id="function.link">
<refnamediv>
<refname>link</refname>
<refpurpose>Create a hard link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>link</methodname>
<methodparam><type>string</type><parameter>target</parameter></methodparam>
<methodparam><type>string</type><parameter>link</parameter></methodparam>
</methodsynopsis>
<para>
<function>link</function> creates a hard link. &return.success;
</para>
<para>
See also the <function>symlink</function> to create soft links,
and <function>readlink</function> along with
<function>linkinfo</function>.
</para>
</refsect1>
</refentry>
&note.no-remote;
&note.no-windows;
<para>
See also the <function>symlink</function> to create soft links,
and <function>readlink</function> along with
<function>linkinfo</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

70
reference/filesystem/functions/linkinfo.xml
View file

@ -1,30 +1,30 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.linkinfo">
<refnamediv>
<refname>linkinfo</refname>
<refpurpose>Gets information about a link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>linkinfo</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
</methodsynopsis>
<para>
<function>linkinfo</function> returns the <literal>st_dev</literal>
field of the Unix C stat structure returned by the <literal>lstat</literal>
system call. This function is used to verify if a link (pointed to by
<parameter>path</parameter>) really exists (using the same method
as the S_ISLNK macro defined in <filename>stat.h</filename>).
Returns 0 or &false; in
case of error.
</para>
<para>
<example>
<title><function>linkinfo</function> example</title>
<programlisting role="php">
<refentry id="function.linkinfo">
<refnamediv>
<refname>linkinfo</refname>
<refpurpose>Gets information about a link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>linkinfo</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
</methodsynopsis>
<para>
<function>linkinfo</function> returns the <literal>st_dev</literal>
field of the Unix C stat structure returned by the <literal>lstat</literal>
system call. This function is used to verify if a link (pointed to by
<parameter>path</parameter>) really exists (using the same method
as the S_ISLNK macro defined in <filename>stat.h</filename>).
Returns 0 or &false; in
case of error.
</para>
<para>
<example>
<title><function>linkinfo</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -32,16 +32,16 @@ echo linkinfo('/vmlinuz'); // 835
?>
]]>
</programlisting>
</example>
</para>
&note.no-windows;
<para>
See also <function>symlink</function>, <function>link</function>,
and <function>readlink</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
&note.no-windows;
<para>
See also <function>symlink</function>, <function>link</function>,
and <function>readlink</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

66
reference/filesystem/functions/lstat.xml
View file

@ -1,39 +1,39 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.lstat">
<refnamediv>
<refname>lstat</refname>
<refpurpose>Gives information about a file or symbolic link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>lstat</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Gathers the statistics of the file or symbolic link named by
<parameter>filename</parameter>. This function is identical to the
<function>stat</function> function except that if the
<parameter>filename</parameter> parameter is a symbolic link, the
status of the symbolic link is returned, not the status of the
file pointed to by the symbolic link.
</para>
<para>
See the manual page for <function>stat</function> for information on
the structure of the array that <function>lstat</function> returns.
</para>
<refentry id="function.lstat">
<refnamediv>
<refname>lstat</refname>
<refpurpose>Gives information about a file or symbolic link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>lstat</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Gathers the statistics of the file or symbolic link named by
<parameter>filename</parameter>. This function is identical to the
<function>stat</function> function except that if the
<parameter>filename</parameter> parameter is a symbolic link, the
status of the symbolic link is returned, not the status of the
file pointed to by the symbolic link.
</para>
<para>
See the manual page for <function>stat</function> for information on
the structure of the array that <function>lstat</function> returns.
</para>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<simpara>
See also <function>stat</function>.
</simpara>
</refsect1>
</refentry>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<simpara>
See also <function>stat</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

122
reference/filesystem/functions/mkdir.xml
View file

@ -1,73 +1,73 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.17 $ -->
<!-- $Revision: 1.18 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.39 -->
<refentry id="function.mkdir">
<refnamediv>
<refname>mkdir</refname>
<refpurpose>Makes directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>mkdir</methodname>
<methodparam><type>string</type><parameter>pathname</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>recursive</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<refentry id="function.mkdir">
<refnamediv>
<refname>mkdir</refname>
<refpurpose>Makes directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>mkdir</methodname>
<methodparam><type>string</type><parameter>pathname</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>recursive</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to create the directory specified by pathname.
</para>
<para>
Note that you probably want to specify the mode as an
octal number, which means it should have a leading zero.
The mode is also modified by the current umask, which you
can change using <function>umask</function>.
</para>
<para>
<note>
<para>
Attempts to create the directory specified by pathname.
Mode is ignored on Windows, and became optional in PHP 4.2.0.
</para>
<para>
Note that you probably want to specify the mode as an
octal number, which means it should have a leading zero.
The mode is also modified by the current umask, which you
can change using <function>umask</function>.
</para>
<para>
<note>
<para>
Mode is ignored on Windows, and became optional in PHP 4.2.0.
</para>
</note>
</para>
<para>
The mode is 0777 by default, which means the widest possible
access. For more information on modes, read the details
on the <function>chmod</function> page.
<example>
<title><function>mkdir</function> example</title>
<programlisting role="php">
</note>
</para>
<para>
The mode is 0777 by default, which means the widest possible
access. For more information on modes, read the details
on the <function>chmod</function> page.
<example>
<title><function>mkdir</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
mkdir("/path/to/my/dir", 0700);
?>
]]>
</programlisting>
</example>
</para>
<para>
&return.success;
</para>
<note>
<simpara>
As of PHP 5.0.0 <function>mkdir</function> can also be
used with <emphasis>some</emphasis> URL wrappers. Refer to <xref linkend="wrappers"/>
for a listing of which wrappers support <function>mkdir</function>.
</simpara>
</note>
&note.context-support;
<note>
<simpara>
The <parameter>recursive</parameter> parameter was added as of PHP 5.0.0.
</simpara>
</note>
&note.sm.uidcheck.dir;
<para>
See also <function>rmdir</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<para>
&return.success;
</para>
<note>
<simpara>
As of PHP 5.0.0 <function>mkdir</function> can also be
used with <emphasis>some</emphasis> URL wrappers. Refer to <xref linkend="wrappers"/>
for a listing of which wrappers support <function>mkdir</function>.
</simpara>
</note>
&note.context-support;
<note>
<simpara>
The <parameter>recursive</parameter> parameter was added as of PHP 5.0.0.
</simpara>
</note>
&note.sm.uidcheck.dir;
<para>
See also <function>rmdir</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

124
reference/filesystem/functions/move-uploaded-file.xml
View file

@ -1,67 +1,67 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.move-uploaded-file">
<refnamediv>
<refname>move_uploaded_file</refname>
<refpurpose>Moves an uploaded file to a new location</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>move_uploaded_file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>string</type><parameter>destination</parameter></methodparam>
</methodsynopsis>
<para>
This function checks to ensure that the file designated by
<parameter>filename</parameter> is a valid upload file (meaning
that it was uploaded via PHP's HTTP POST upload mechanism). If
the file is valid, it will be moved to the filename given by
<parameter>destination</parameter>.
</para>
<para>
If <parameter>filename</parameter> is not a valid upload file,
then no action will occur, and
<function>move_uploaded_file</function> will return
&false;.
</para>
<para>
If <parameter>filename</parameter> is a valid upload file, but
cannot be moved for some reason, no action will occur, and
<function>move_uploaded_file</function> will return
&false;. Additionally, a warning will be issued.
</para>
<para>
This sort of check is especially important if there is any chance
that anything done with uploaded files could reveal their
contents to the user, or even to other users on the same
system.
</para>
<note>
<para>
<function>move_uploaded_file</function> is both &safemode;
and <link linkend="ini.open-basedir">open_basedir</link>
aware. However, restrictions are placed only on the
<parameter>destination</parameter> path as to allow the moving
of uploaded files in which <parameter>filename</parameter> may conflict
with such restrictions. <function>move_uploaded_file</function> ensures
the safety of this operation by allowing only those files uploaded
through PHP to be moved.
</para>
</note>
<warning>
<para>
If the destination file already exists, it will be overwritten.
</para>
</warning>
<para>
See also <function>is_uploaded_file</function>, and the section
<link linkend="features.file-upload">Handling file uploads</link>
for a simple usage example.
</para>
</refsect1>
</refentry>
<refentry id="function.move-uploaded-file">
<refnamediv>
<refname>move_uploaded_file</refname>
<refpurpose>Moves an uploaded file to a new location</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>move_uploaded_file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>string</type><parameter>destination</parameter></methodparam>
</methodsynopsis>
<para>
This function checks to ensure that the file designated by
<parameter>filename</parameter> is a valid upload file (meaning
that it was uploaded via PHP's HTTP POST upload mechanism). If
the file is valid, it will be moved to the filename given by
<parameter>destination</parameter>.
</para>
<para>
If <parameter>filename</parameter> is not a valid upload file,
then no action will occur, and
<function>move_uploaded_file</function> will return
&false;.
</para>
<para>
If <parameter>filename</parameter> is a valid upload file, but
cannot be moved for some reason, no action will occur, and
<function>move_uploaded_file</function> will return
&false;. Additionally, a warning will be issued.
</para>
<para>
This sort of check is especially important if there is any chance
that anything done with uploaded files could reveal their
contents to the user, or even to other users on the same
system.
</para>
<note>
<para>
<function>move_uploaded_file</function> is both &safemode;
and <link linkend="ini.open-basedir">open_basedir</link>
aware. However, restrictions are placed only on the
<parameter>destination</parameter> path as to allow the moving
of uploaded files in which <parameter>filename</parameter> may conflict
with such restrictions. <function>move_uploaded_file</function> ensures
the safety of this operation by allowing only those files uploaded
through PHP to be moved.
</para>
</note>
<warning>
<para>
If the destination file already exists, it will be overwritten.
</para>
</warning>
<para>
See also <function>is_uploaded_file</function>, and the section
<link linkend="features.file-upload">Handling file uploads</link>
for a simple usage example.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

186
reference/filesystem/functions/parse-ini-file.xml
View file

@ -1,75 +1,75 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.23 $ -->
<!-- $Revision: 1.24 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.87 -->
<refentry id="function.parse-ini-file">
<refnamediv>
<refname>parse_ini_file</refname>
<refpurpose>Parse a configuration file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>parse_ini_file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>process_sections</parameter></methodparam>
</methodsynopsis>
<para>
<function>parse_ini_file</function> loads in the
ini file specified in <parameter>filename</parameter>,
and returns the settings in it in an associative array.
By setting the last <parameter>process_sections</parameter>
parameter to &true;, you get a multidimensional array, with
the section names and settings included. The default
for <parameter>process_sections</parameter> is &false;
</para>
<note>
<para>
This function has nothing to do with the
&php.ini; file. It is already processed,
the time you run your script. This function can be used to
read in your own application's configuration files.
</para>
</note>
<note>
<para>
If a value in the ini file contains any non-alphanumeric
characters it needs to be enclosed in double-quotes (").
</para>
</note>
<note>
<simpara>
Since PHP 4.2.1 this function is also affected by &safemode;
and <link linkend="ini.open-basedir">open_basedir</link>.
</simpara>
</note>
<note>
<para>
As of PHP 5.0 this function also handles new lines in values.
</para>
</note>
<note>
<simpara>
There are reserved words which must not be used as keys for
ini files. These include: null, yes, no, true, and false.
Values null, no and false results in "", yes and true results in "1".
Characters <literal>{}|&amp;~![()"</literal> must not be used anywhere in
the key and have a special meaning in the value.
</simpara>
</note>
<para>
The structure of the ini file is similar to that of
the &php.ini;'s.
</para>
<para>
<link linkend="language.constants">Constants</link> may also be parsed
in the ini file so if you define a constant as an ini value before
running <function>parse_ini_file</function>, it will be integrated into
the results. Only ini values are evaluated. For example:
</para>
<para>
<example>
<title>Contents of <filename>sample.ini</filename></title>
<programlisting>
<refentry id="function.parse-ini-file">
<refnamediv>
<refname>parse_ini_file</refname>
<refpurpose>Parse a configuration file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>parse_ini_file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>process_sections</parameter></methodparam>
</methodsynopsis>
<para>
<function>parse_ini_file</function> loads in the
ini file specified in <parameter>filename</parameter>,
and returns the settings in it in an associative array.
By setting the last <parameter>process_sections</parameter>
parameter to &true;, you get a multidimensional array, with
the section names and settings included. The default
for <parameter>process_sections</parameter> is &false;
</para>
<note>
<para>
This function has nothing to do with the
&php.ini; file. It is already processed,
the time you run your script. This function can be used to
read in your own application's configuration files.
</para>
</note>
<note>
<para>
If a value in the ini file contains any non-alphanumeric
characters it needs to be enclosed in double-quotes (").
</para>
</note>
<note>
<simpara>
Since PHP 4.2.1 this function is also affected by &safemode;
and <link linkend="ini.open-basedir">open_basedir</link>.
</simpara>
</note>
<note>
<para>
As of PHP 5.0 this function also handles new lines in values.
</para>
</note>
<note>
<simpara>
There are reserved words which must not be used as keys for
ini files. These include: null, yes, no, true, and false.
Values null, no and false results in "", yes and true results in "1".
Characters <literal>{}|&amp;~![()"</literal> must not be used anywhere in
the key and have a special meaning in the value.
</simpara>
</note>
<para>
The structure of the ini file is similar to that of
the &php.ini;'s.
</para>
<para>
<link linkend="language.constants">Constants</link> may also be parsed
in the ini file so if you define a constant as an ini value before
running <function>parse_ini_file</function>, it will be integrated into
the results. Only ini values are evaluated. For example:
</para>
<para>
<example>
<title>Contents of <filename>sample.ini</filename></title>
<programlisting>
<![CDATA[
; This is a sample configuration file
; Comments start with ';', as in php.ini
@ -83,13 +83,13 @@ animal = BIRD
path = "/usr/local/bin"
URL = "http://www.example.com/~username"
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title><function>parse_ini_file</function> example</title>
<programlisting role="php">
</programlisting>
</example>
</para>
<para>
<example>
<title><function>parse_ini_file</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -105,11 +105,11 @@ print_r($ini_array);
?>
]]>
</programlisting>
<para>
Would produce:
</para>
<screen>
</programlisting>
<para>
Would produce:
</para>
<screen>
<![CDATA[
Array
(
@ -136,17 +136,17 @@ Array
)
]]>
</screen>
</example>
</para>
<para>
Keys and section names consisting from numbers are evaluated as PHP
<link linkend="language.types.integer">integers</link> thus numbers
starting by 0 are evaluated as octals and numbers starting by 0x are
evaluated as hexadecimals.
</para>
</refsect1>
</refentry>
</screen>
</example>
</para>
<para>
Keys and section names consisting from numbers are evaluated as PHP
<link linkend="language.types.integer">integers</link> thus numbers
starting by 0 are evaluated as octals and numbers starting by 0x are
evaluated as hexadecimals.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

114
reference/filesystem/functions/pathinfo.xml
View file

@ -1,39 +1,39 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- $Revision: 1.13 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.61 -->
<refentry id="function.pathinfo">
<refnamediv>
<refname>pathinfo</refname>
<refpurpose>Returns information about a file path</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>pathinfo</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
<function>pathinfo</function> returns an associative array
containing information about <parameter>path</parameter>. The
following array elements are returned:
<literal>dirname</literal>, <literal>basename</literal>
and <literal>extension</literal> if any.
</para>
<para>
You can specify which elements are returned with optional parameter
<parameter>options</parameter>. It composes from
<constant>PATHINFO_DIRNAME</constant>,
<constant>PATHINFO_BASENAME</constant>,
<constant>PATHINFO_EXTENSION</constant> and
<constant>PATHINFO_FILENAME</constant> (available since PHP 5.2.0). It
defaults to return all elements. This function returns string if not all
elements are requested.
</para>
<para>
<example>
<title><function>pathinfo</function> Example</title>
<programlisting role="php">
<refentry id="function.pathinfo">
<refnamediv>
<refname>pathinfo</refname>
<refpurpose>Returns information about a file path</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>pathinfo</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
<function>pathinfo</function> returns an associative array
containing information about <parameter>path</parameter>. The
following array elements are returned:
<literal>dirname</literal>, <literal>basename</literal>
and <literal>extension</literal> if any.
</para>
<para>
You can specify which elements are returned with optional parameter
<parameter>options</parameter>. It composes from
<constant>PATHINFO_DIRNAME</constant>,
<constant>PATHINFO_BASENAME</constant>,
<constant>PATHINFO_EXTENSION</constant> and
<constant>PATHINFO_FILENAME</constant> (available since PHP 5.2.0). It
defaults to return all elements. This function returns string if not all
elements are requested.
</para>
<para>
<example>
<title><function>pathinfo</function> Example</title>
<programlisting role="php">
<![CDATA[
<?php
$path_parts = pathinfo('/www/htdocs/index.html');
@ -44,35 +44,35 @@ echo $path_parts['extension'], "\n";
echo $path_parts['filename'], "\n"; // since PHP 5.2.0
?>
]]>
</programlisting>
<para>
Would produce:
</para>
<screen>
</programlisting>
<para>
Would produce:
</para>
<screen>
<![CDATA[
/www/htdocs
index.html
html
index
]]>
</screen>
</example>
</para>
<note>
<para>
For information on retrieving the current path info, read
the section on <link linkend="language.variables.predefined">
predefined reserved variables</link>.
</para>
</note>
<para>
See also <function>dirname</function>,
<function>basename</function>,
<function>parse_url</function>
and <function>realpath</function>.
</para>
</refsect1>
</refentry>
</screen>
</example>
</para>
<note>
<para>
For information on retrieving the current path info, read
the section on <link linkend="language.variables.predefined">
predefined reserved variables</link>.
</para>
</note>
<para>
See also <function>dirname</function>,
<function>basename</function>,
<function>parse_url</function>
and <function>realpath</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

58
reference/filesystem/functions/pclose.xml
View file

@ -1,34 +1,34 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.pclose">
<refnamediv>
<refname>pclose</refname>
<refpurpose>Closes process file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>pclose</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
Closes a file pointer to a pipe opened by
<function>popen</function>.
</para>
<para>
The file pointer must be valid, and must have been returned by a
successful call to <function>popen</function>.
</para>
<para>
Returns the termination status of the process that was
run.
</para>
<para>
See also <function>popen</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pclose">
<refnamediv>
<refname>pclose</refname>
<refpurpose>Closes process file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>pclose</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
Closes a file pointer to a pipe opened by
<function>popen</function>.
</para>
<para>
The file pointer must be valid, and must have been returned by a
successful call to <function>popen</function>.
</para>
<para>
Returns the termination status of the process that was
run.
</para>
<para>
See also <function>popen</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

116
reference/filesystem/functions/popen.xml
View file

@ -1,57 +1,57 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- $Revision: 1.14 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.popen">
<refnamediv>
<refname>popen</refname>
<refpurpose>Opens process file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>popen</methodname>
<methodparam><type>string</type><parameter>command</parameter></methodparam>
<methodparam><type>string</type><parameter>mode</parameter></methodparam>
</methodsynopsis>
<para>
Opens a pipe to a process executed by forking the command given
by command.
</para>
<para>
Returns a file pointer identical to that returned by
<function>fopen</function>, except that it is unidirectional (may
only be used for reading or writing) and must be closed with
<function>pclose</function>. This pointer may be used with
<function>fgets</function>, <function>fgetss</function>, and
<function>fwrite</function>.
</para>
<para>
If an error occurs, returns &false;.
</para>
<note>
<para>
If you're looking for bi-directional support (two-way), use
<function>proc_open</function>.
</para>
</note>
<para>
<example>
<title><function>popen</function> example</title>
<programlisting role="php">
<refentry id="function.popen">
<refnamediv>
<refname>popen</refname>
<refpurpose>Opens process file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>popen</methodname>
<methodparam><type>string</type><parameter>command</parameter></methodparam>
<methodparam><type>string</type><parameter>mode</parameter></methodparam>
</methodsynopsis>
<para>
Opens a pipe to a process executed by forking the command given
by command.
</para>
<para>
Returns a file pointer identical to that returned by
<function>fopen</function>, except that it is unidirectional (may
only be used for reading or writing) and must be closed with
<function>pclose</function>. This pointer may be used with
<function>fgets</function>, <function>fgetss</function>, and
<function>fwrite</function>.
</para>
<para>
If an error occurs, returns &false;.
</para>
<note>
<para>
If you're looking for bi-directional support (two-way), use
<function>proc_open</function>.
</para>
</note>
<para>
<example>
<title><function>popen</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$handle = popen("/bin/ls", "r");
?>
]]>
</programlisting>
</example>
</para>
<para>
If the command to be executed could not be found, a valid
resource is returned. This may seem odd, but makes sense; it
allows you to access any error message returned by the shell:
<informalexample>
<programlisting role="php">
</programlisting>
</example>
</para>
<para>
If the command to be executed could not be found, a valid
resource is returned. This may seem odd, but makes sense; it
allows you to access any error message returned by the shell:
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
error_reporting(E_ALL);
@ -64,17 +64,17 @@ echo $read;
pclose($handle);
?>
]]>
</programlisting>
</informalexample>
</para>
&note.exec-path;
&warn.sm.exec;
<para>
See also <function>pclose</function>, <function>fopen</function>,
and <function>proc_open</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</informalexample>
</para>
&note.exec-path;
&warn.sm.exec;
<para>
See also <function>pclose</function>, <function>fopen</function>,
and <function>proc_open</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

76
reference/filesystem/functions/readfile.xml
View file

@ -1,43 +1,43 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.readfile">
<refnamediv>
<refname>readfile</refname>
<refpurpose>Outputs a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>readfile</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Reads a file and writes it to the output buffer.
</para>
<para>
Returns the number of bytes read from the file. If an error
occurs, &false; is returned and unless the function was called as
@<function>readfile</function>, an error message is printed.
</para>
&tip.fopen-wrapper;
<para>
You can use the optional second parameter and set it to &true;, if
you want to search for the file in the <link
linkend="ini.include-path">include_path</link>, too.
</para>
&note.context-support;
<para>
See also <function>fpassthru</function>,
<function>file</function>, <function>fopen</function>,
<function>include</function>, <function>require</function>,
<function>virtual</function>, <function>file_get_contents</function>,
and <xref linkend="wrappers"/>.
</para>
</refsect1>
</refentry>
<refentry id="function.readfile">
<refnamediv>
<refname>readfile</refname>
<refpurpose>Outputs a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>readfile</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Reads a file and writes it to the output buffer.
</para>
<para>
Returns the number of bytes read from the file. If an error
occurs, &false; is returned and unless the function was called as
@<function>readfile</function>, an error message is printed.
</para>
&tip.fopen-wrapper;
<para>
You can use the optional second parameter and set it to &true;, if
you want to search for the file in the <link
linkend="ini.include-path">include_path</link>, too.
</para>
&note.context-support;
<para>
See also <function>fpassthru</function>,
<function>file</function>, <function>fopen</function>,
<function>include</function>, <function>require</function>,
<function>virtual</function>, <function>file_get_contents</function>,
and <xref linkend="wrappers"/>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

64
reference/filesystem/functions/readlink.xml
View file

@ -1,26 +1,26 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.readlink">
<refnamediv>
<refname>readlink</refname>
<refpurpose>Returns the target of a symbolic link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>readlink</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
</methodsynopsis>
<para>
<function>readlink</function> does the same as the readlink C
function and returns the contents of the symbolic link path or &false;
in case of error.
</para>
<para>
<example>
<title><function>readlink</function> example</title>
<programlisting role="php">
<refentry id="function.readlink">
<refnamediv>
<refname>readlink</refname>
<refpurpose>Returns the target of a symbolic link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>readlink</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
</methodsynopsis>
<para>
<function>readlink</function> does the same as the readlink C
function and returns the contents of the symbolic link path or &false;
in case of error.
</para>
<para>
<example>
<title><function>readlink</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -29,17 +29,17 @@ echo readlink('/vmlinuz');
?>
]]>
</programlisting>
</example>
</para>
&note.no-windows;
<para>
See also <function>is_link</function>,
<function>symlink</function>, and
<function>linkinfo</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
&note.no-windows;
<para>
See also <function>is_link</function>,
<function>symlink</function>, and
<function>linkinfo</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

84
reference/filesystem/functions/realpath.xml
View file

@ -1,56 +1,56 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.23 -->
<refentry id="function.realpath">
<refnamediv>
<refname>realpath</refname>
<refpurpose>Returns canonicalized absolute pathname</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>realpath</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
</methodsynopsis>
<para>
<function>realpath</function> expands all symbolic links and
resolves references to '/./', '/../' and extra '/' characters in
the input <parameter>path</parameter> and return the canonicalized
absolute pathname. The resulting path will have no symbolic link,
'/./' or '/../' components.
</para>
<para>
<function>realpath</function> returns &false; on failure, e.g. if
the file does not exist. On BSD systems <function>realpath</function>
doesn't fail if only the last <parameter>path</parameter> component
doesn't exist, while other systems will return &false;.
</para>
<para>
<example>
<title><function>realpath</function> example</title>
<programlisting role="php">
<refentry id="function.realpath">
<refnamediv>
<refname>realpath</refname>
<refpurpose>Returns canonicalized absolute pathname</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>realpath</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
</methodsynopsis>
<para>
<function>realpath</function> expands all symbolic links and
resolves references to '/./', '/../' and extra '/' characters in
the input <parameter>path</parameter> and return the canonicalized
absolute pathname. The resulting path will have no symbolic link,
'/./' or '/../' components.
</para>
<para>
<function>realpath</function> returns &false; on failure, e.g. if
the file does not exist. On BSD systems <function>realpath</function>
doesn't fail if only the last <parameter>path</parameter> component
doesn't exist, while other systems will return &false;.
</para>
<para>
<example>
<title><function>realpath</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
chdir('/var/www/');
echo realpath('./../../etc/passwd');
?>
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
/etc/passwd
]]>
</screen>
</example>
</para>
<para>
See also <function>basename</function>,
<function>dirname</function>, and
<function>pathinfo</function>.
</para>
</refsect1>
</refentry>
</screen>
</example>
</para>
<para>
See also <function>basename</function>,
<function>dirname</function>, and
<function>pathinfo</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

110
reference/filesystem/functions/rename.xml
View file

@ -1,65 +1,65 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.rename">
<refnamediv>
<refname>rename</refname>
<refpurpose>Renames a file or directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>rename</methodname>
<methodparam><type>string</type><parameter>oldname</parameter></methodparam>
<methodparam><type>string</type><parameter>newname</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to rename <parameter>oldname</parameter> to
<parameter>newname</parameter>.
</para>
<para>
&return.success;
</para>
<para>
<example>
<title>Example with <function>rename</function></title>
<programlisting role="php">
<refentry id="function.rename">
<refnamediv>
<refname>rename</refname>
<refpurpose>Renames a file or directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>rename</methodname>
<methodparam><type>string</type><parameter>oldname</parameter></methodparam>
<methodparam><type>string</type><parameter>newname</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to rename <parameter>oldname</parameter> to
<parameter>newname</parameter>.
</para>
<para>
&return.success;
</para>
<para>
<example>
<title>Example with <function>rename</function></title>
<programlisting role="php">
<![CDATA[
<?php
rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");
?>
]]>
</programlisting>
</example>
</para>
<note>
<para>
Prior to PHP 4.3.3, <function>rename</function> could not rename files
across partitions on *nix based systems.
</para>
</note>
<note>
<simpara>
As of PHP 5.0.0 <function>rename</function> can also be
used with <emphasis>some</emphasis> URL wrappers. Refer to <xref linkend="wrappers"/>
for a listing of which wrappers support <function>rename</function>.
</simpara>
</note>
<note>
<simpara>
The wrapper used in <parameter>oldname</parameter> <emphasis>MUST</emphasis>
match the wrapper used in <parameter>newname</parameter>.
</simpara>
</note>
&note.context-support;
<para>
See also <function>copy</function>,
<function>unlink</function>, and
<function>move_uploaded_file</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<note>
<para>
Prior to PHP 4.3.3, <function>rename</function> could not rename files
across partitions on *nix based systems.
</para>
</note>
<note>
<simpara>
As of PHP 5.0.0 <function>rename</function> can also be
used with <emphasis>some</emphasis> URL wrappers. Refer to <xref linkend="wrappers"/>
for a listing of which wrappers support <function>rename</function>.
</simpara>
</note>
<note>
<simpara>
The wrapper used in <parameter>oldname</parameter> <emphasis>MUST</emphasis>
match the wrapper used in <parameter>newname</parameter>.
</simpara>
</note>
&note.context-support;
<para>
See also <function>copy</function>,
<function>unlink</function>, and
<function>move_uploaded_file</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

70
reference/filesystem/functions/rewind.xml
View file

@ -1,40 +1,40 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- $Revision: 1.9 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.rewind">
<refnamediv>
<refname>rewind</refname>
<refpurpose>Rewind the position of a file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>rewind</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
Sets the file position indicator for <parameter>handle</parameter>
to the beginning of the file stream.
</para>
<para>
&return.success;
</para>
<para>
The file pointer must be valid, and must point to a file
successfully opened by <function>fopen</function>.
</para>
<note>
<para>
If you have opened the file in append ("a" or "a+") mode, any data you write
to the file will always be appended, regardless of the file position.
</para>
</note>
<para>
See also <function>fseek</function> and
<function>ftell</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.rewind">
<refnamediv>
<refname>rewind</refname>
<refpurpose>Rewind the position of a file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>rewind</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
<para>
Sets the file position indicator for <parameter>handle</parameter>
to the beginning of the file stream.
</para>
<para>
&return.success;
</para>
<para>
The file pointer must be valid, and must point to a file
successfully opened by <function>fopen</function>.
</para>
<note>
<para>
If you have opened the file in append ("a" or "a+") mode, any data you write
to the file will always be appended, regardless of the file position.
</para>
</note>
<para>
See also <function>fseek</function> and
<function>ftell</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

64
reference/filesystem/functions/rmdir.xml
View file

@ -1,37 +1,37 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.rmdir">
<refnamediv>
<refname>rmdir</refname>
<refpurpose>Removes directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>rmdir</methodname>
<methodparam><type>string</type><parameter>dirname</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to remove the directory named by <parameter>dirname</parameter>.
The directory must be empty, and the relevant permissions must permit this.
&return.success;
</para>
<note>
<simpara>
As of PHP 5.0.0 <function>rmdir</function> can also be
used with <emphasis>some</emphasis> URL wrappers. Refer to <xref linkend="wrappers"/>
for a listing of which wrappers support <function>rmdir</function>.
</simpara>
</note>
&note.context-support;
&note.sm.uidcheck.dir;
<para>
See also <function>mkdir</function> and <function>unlink</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.rmdir">
<refnamediv>
<refname>rmdir</refname>
<refpurpose>Removes directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>rmdir</methodname>
<methodparam><type>string</type><parameter>dirname</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to remove the directory named by <parameter>dirname</parameter>.
The directory must be empty, and the relevant permissions must permit this.
&return.success;
</para>
<note>
<simpara>
As of PHP 5.0.0 <function>rmdir</function> can also be
used with <emphasis>some</emphasis> URL wrappers. Refer to <xref linkend="wrappers"/>
for a listing of which wrappers support <function>rmdir</function>.
</simpara>
</note>
&note.context-support;
&note.sm.uidcheck.dir;
<para>
See also <function>mkdir</function> and <function>unlink</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

254
reference/filesystem/functions/stat.xml
View file

@ -1,135 +1,135 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- $Revision: 1.14 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.stat">
<refnamediv>
<refname>stat</refname>
<refpurpose>Gives information about a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stat</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Gathers the statistics of the file named by
<parameter>filename</parameter>. If <parameter>filename</parameter>
is a symbolic link, statistics are from the file itself, not the
symlink. <function>lstat</function> is identical to <function>
stat</function> except it would instead be based off the symlinks
status.
</para>
<para>
In case of error, <function>stat</function> returns &false;. It also
will throw a warning.
</para>
<para>
Returns an array with the statistics of the file with the
following elements. This array is zero-based. In addition to
returning these attributes in a numeric array, they can be accessed
with associative indices, as noted next to each parameter; this is
available since PHP 4.0.6:
</para>
<para>
<table>
<title><function>stat</function> and <function>fstat</function> result
format</title>
<tgroup cols="3">
<thead>
<row>
<entry>Numeric</entry>
<entry>Associative (since PHP 4.0.6)</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry>dev</entry>
<entry>device number</entry>
</row>
<row>
<entry>1</entry>
<entry>ino</entry>
<entry>inode number</entry>
</row>
<row>
<entry>2</entry>
<entry>mode</entry>
<entry>inode protection mode</entry>
</row>
<row>
<entry>3</entry>
<entry>nlink</entry>
<entry>number of links</entry>
</row>
<row>
<entry>4</entry>
<entry>uid</entry>
<entry>userid of owner</entry>
</row>
<row>
<entry>5</entry>
<entry>gid</entry>
<entry>groupid of owner</entry>
</row>
<row>
<entry>6</entry>
<entry>rdev</entry>
<entry>device type, if inode device *</entry>
</row>
<row>
<entry>7</entry>
<entry>size</entry>
<entry>size in bytes</entry>
</row>
<row>
<entry>8</entry>
<entry>atime</entry>
<entry>time of last access (Unix timestamp)</entry>
</row>
<row>
<entry>9</entry>
<entry>mtime</entry>
<entry>time of last modification (Unix timestamp)</entry>
</row>
<row>
<entry>10</entry>
<entry>ctime</entry>
<entry>time of last inode change (Unix timestamp)</entry>
</row>
<row>
<entry>11</entry>
<entry>blksize</entry>
<entry>blocksize of filesystem IO *</entry>
</row>
<row>
<entry>12</entry>
<entry>blocks</entry>
<entry>number of blocks allocated</entry>
</row>
<refentry id="function.stat">
<refnamediv>
<refname>stat</refname>
<refpurpose>Gives information about a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stat</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Gathers the statistics of the file named by
<parameter>filename</parameter>. If <parameter>filename</parameter>
is a symbolic link, statistics are from the file itself, not the
symlink. <function>lstat</function> is identical to <function>
stat</function> except it would instead be based off the symlinks
status.
</para>
<para>
In case of error, <function>stat</function> returns &false;. It also
will throw a warning.
</para>
<para>
Returns an array with the statistics of the file with the
following elements. This array is zero-based. In addition to
returning these attributes in a numeric array, they can be accessed
with associative indices, as noted next to each parameter; this is
available since PHP 4.0.6:
</para>
<para>
<table>
<title><function>stat</function> and <function>fstat</function> result
format</title>
<tgroup cols="3">
<thead>
<row>
<entry>Numeric</entry>
<entry>Associative (since PHP 4.0.6)</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry>dev</entry>
<entry>device number</entry>
</row>
<row>
<entry>1</entry>
<entry>ino</entry>
<entry>inode number</entry>
</row>
<row>
<entry>2</entry>
<entry>mode</entry>
<entry>inode protection mode</entry>
</row>
<row>
<entry>3</entry>
<entry>nlink</entry>
<entry>number of links</entry>
</row>
<row>
<entry>4</entry>
<entry>uid</entry>
<entry>userid of owner</entry>
</row>
<row>
<entry>5</entry>
<entry>gid</entry>
<entry>groupid of owner</entry>
</row>
<row>
<entry>6</entry>
<entry>rdev</entry>
<entry>device type, if inode device *</entry>
</row>
<row>
<entry>7</entry>
<entry>size</entry>
<entry>size in bytes</entry>
</row>
<row>
<entry>8</entry>
<entry>atime</entry>
<entry>time of last access (Unix timestamp)</entry>
</row>
<row>
<entry>9</entry>
<entry>mtime</entry>
<entry>time of last modification (Unix timestamp)</entry>
</row>
<row>
<entry>10</entry>
<entry>ctime</entry>
<entry>time of last inode change (Unix timestamp)</entry>
</row>
<row>
<entry>11</entry>
<entry>blksize</entry>
<entry>blocksize of filesystem IO *</entry>
</row>
<row>
<entry>12</entry>
<entry>blocks</entry>
<entry>number of blocks allocated</entry>
</row>
</tbody>
</tgroup>
</table>
</tbody>
</tgroup>
</table>
* Only valid on systems supporting the st_blksize type - other
systems (e.g. Windows) return -1.
</para>
&note.clearstatcache;
* Only valid on systems supporting the st_blksize type - other
systems (e.g. Windows) return -1.
</para>
&tip.fopen-wrapper.stat;
<para>
See also <function>lstat</function>,
<function>fstat</function>,
<function>filemtime</function>, and
<function>filegroup</function>.
</para>
</refsect1>
</refentry>
&note.clearstatcache;
&tip.fopen-wrapper.stat;
<para>
See also <function>lstat</function>,
<function>fstat</function>,
<function>filemtime</function>, and
<function>filegroup</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

58
reference/filesystem/functions/symlink.xml
View file

@ -1,34 +1,34 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.symlink">
<refnamediv>
<refname>symlink</refname>
<refpurpose>Creates a symbolic link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>symlink</methodname>
<methodparam><type>string</type><parameter>target</parameter></methodparam>
<methodparam><type>string</type><parameter>link</parameter></methodparam>
</methodsynopsis>
<para>
<function>symlink</function> creates a symbolic link
to the existing <parameter>target</parameter> with
the specified name <parameter>link</parameter>.
</para>
<para>
&return.success;
</para>
&note.no-windows;
<para>
See also <function>link</function> to create hard links,
and <function>readlink</function> along with
<function>linkinfo</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.symlink">
<refnamediv>
<refname>symlink</refname>
<refpurpose>Creates a symbolic link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>symlink</methodname>
<methodparam><type>string</type><parameter>target</parameter></methodparam>
<methodparam><type>string</type><parameter>link</parameter></methodparam>
</methodsynopsis>
<para>
<function>symlink</function> creates a symbolic link
to the existing <parameter>target</parameter> with
the specified name <parameter>link</parameter>.
</para>
<para>
&return.success;
</para>
&note.no-windows;
<para>
See also <function>link</function> to create hard links,
and <function>readlink</function> along with
<function>linkinfo</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

120
reference/filesystem/functions/tempnam.xml
View file

@ -1,46 +1,46 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.tempnam">
<refnamediv>
<refname>tempnam</refname>
<refpurpose>Create file with unique file name</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>tempnam</methodname>
<methodparam><type>string</type><parameter>dir</parameter></methodparam>
<methodparam><type>string</type><parameter>prefix</parameter></methodparam>
</methodsynopsis>
<para>
Creates a file with a unique filename in the specified directory.
If the directory does not exist, <function>tempnam</function> may
generate a file in the system's temporary directory, and return
the name of that.
</para>
<para>
Prior to PHP 4.0.6, the behaviour of the
<function>tempnam</function> function was system dependent. On
Windows the TMP environment variable will override the
<parameter>dir</parameter> parameter, on Linux the TMPDIR
environment variable has precedence, while SVR4 will always use
your <parameter>dir</parameter> parameter if the directory it
points to exists. Consult your system documentation on the
tempnam(3) function if in doubt.
</para>
<note>
<simpara>
If PHP cannot create a file in the specified <parameter>dir</parameter>
parameter, it falls back on the system default.
</simpara>
</note>
<para>
Returns the new temporary filename, or &false; on
failure.
<example>
<title><function>tempnam</function> example</title>
<programlisting role="php">
<refentry id="function.tempnam">
<refnamediv>
<refname>tempnam</refname>
<refpurpose>Create file with unique file name</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>tempnam</methodname>
<methodparam><type>string</type><parameter>dir</parameter></methodparam>
<methodparam><type>string</type><parameter>prefix</parameter></methodparam>
</methodsynopsis>
<para>
Creates a file with a unique filename in the specified directory.
If the directory does not exist, <function>tempnam</function> may
generate a file in the system's temporary directory, and return
the name of that.
</para>
<para>
Prior to PHP 4.0.6, the behaviour of the
<function>tempnam</function> function was system dependent. On
Windows the TMP environment variable will override the
<parameter>dir</parameter> parameter, on Linux the TMPDIR
environment variable has precedence, while SVR4 will always use
your <parameter>dir</parameter> parameter if the directory it
points to exists. Consult your system documentation on the
tempnam(3) function if in doubt.
</para>
<note>
<simpara>
If PHP cannot create a file in the specified <parameter>dir</parameter>
parameter, it falls back on the system default.
</simpara>
</note>
<para>
Returns the new temporary filename, or &false; on
failure.
<example>
<title><function>tempnam</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$tmpfname = tempnam("/tmp", "FOO");
@ -54,25 +54,25 @@ fclose($handle);
unlink($tmpfname);
?>
]]>
</programlisting>
</example>
</para>
<note>
<simpara>
This function's behavior changed in 4.0.3. The temporary file is also
created to avoid a race condition where the file might appear in the
filesystem between the time the string was generated and before
the script gets around to creating the file. Note, that you need
to remove the file in case you need it no more, it is not done
automatically.
</simpara>
</note>
<para>
See also <function>tmpfile</function>, <function>sys_get_temp_dir</function>
and <function>unlink</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<note>
<simpara>
This function's behavior changed in 4.0.3. The temporary file is also
created to avoid a race condition where the file might appear in the
filesystem between the time the string was generated and before
the script gets around to creating the file. Note, that you need
to remove the file in case you need it no more, it is not done
automatically.
</simpara>
</note>
<para>
See also <function>tmpfile</function>, <function>sys_get_temp_dir</function>
and <function>unlink</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

78
reference/filesystem/functions/tmpfile.xml
View file

@ -1,33 +1,33 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- $Revision: 1.9 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.32 -->
<refentry id="function.tmpfile">
<refnamediv>
<refname>tmpfile</refname>
<refpurpose>Creates a temporary file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>tmpfile</methodname>
<void/>
</methodsynopsis>
<para>
Creates a temporary file with a unique name in read-write (w+) mode,
returning a file handle similar to the one returned by
<function>fopen</function>.
The file is automatically removed when closed (using
<function>fclose</function>), or when the script ends.
</para>
<para>
For details, consult your system documentation on the
<literal>tmpfile(3)</literal> function, as well as the
<filename>stdio.h</filename> header file.
</para>
<para>
<example>
<title><function>tmpfile</function> example</title>
<programlisting role="php">
<refentry id="function.tmpfile">
<refnamediv>
<refname>tmpfile</refname>
<refpurpose>Creates a temporary file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>tmpfile</methodname>
<void/>
</methodsynopsis>
<para>
Creates a temporary file with a unique name in read-write (w+) mode,
returning a file handle similar to the one returned by
<function>fopen</function>.
The file is automatically removed when closed (using
<function>fclose</function>), or when the script ends.
</para>
<para>
For details, consult your system documentation on the
<literal>tmpfile(3)</literal> function, as well as the
<filename>stdio.h</filename> header file.
</para>
<para>
<example>
<title><function>tmpfile</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$temp = tmpfile();
@ -37,20 +37,20 @@ echo fread($temp, 1024);
fclose($temp); // this removes the file
?>
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
writing to tempfile
]]>
</screen>
</example>
</para>
<para>
See also <function>tempnam</function>, <function>sys_get_temp_dir</function>.
</para>
</refsect1>
</refentry>
</screen>
</example>
</para>
<para>
See also <function>tempnam</function>, <function>sys_get_temp_dir</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

84
reference/filesystem/functions/touch.xml
View file

@ -1,42 +1,42 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.touch">
<refnamediv>
<refname>touch</refname>
<refpurpose>Sets access and modification time of file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>touch</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>time</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>atime</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to set the access and modification times of the file named in the
<parameter>filename</parameter> parameter to the value given in
<parameter>time</parameter>. If <parameter>time</parameter>
is not supplied, the current system time is used. If the third parameter,
is present, the access time of the given
filename is set to the value of <parameter>atime</parameter>.
Note that the access time is always modified, regardless of the number
of parameters.
</para>
<para>
If the file does not exist, it will be created. &return.success;
</para>
<warning>
<para>
It is not currently possible to change the modification time of a
directory with this function under Windows.
</para>
</warning>
<para>
<example>
<title><function>touch</function> example</title>
<programlisting role="php">
<refentry id="function.touch">
<refnamediv>
<refname>touch</refname>
<refpurpose>Sets access and modification time of file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>touch</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>time</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>atime</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to set the access and modification times of the file named in the
<parameter>filename</parameter> parameter to the value given in
<parameter>time</parameter>. If <parameter>time</parameter>
is not supplied, the current system time is used. If the third parameter,
is present, the access time of the given
filename is set to the value of <parameter>atime</parameter>.
Note that the access time is always modified, regardless of the number
of parameters.
</para>
<para>
If the file does not exist, it will be created. &return.success;
</para>
<warning>
<para>
It is not currently possible to change the modification time of a
directory with this function under Windows.
</para>
</warning>
<para>
<example>
<title><function>touch</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
if (touch($FileName)) {
@ -46,11 +46,11 @@ if (touch($FileName)) {
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

80
reference/filesystem/functions/umask.xml
View file

@ -1,40 +1,40 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.umask">
<refnamediv>
<refname>umask</refname>
<refpurpose>Changes the current umask</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>umask</methodname>
<methodparam choice="opt"><type>int</type><parameter>mask</parameter></methodparam>
</methodsynopsis>
<para>
<function>umask</function> sets PHP's umask to
<parameter>mask</parameter> &amp; 0777 and returns the old
umask. When PHP is being used as a server module, the umask
is restored when each request is finished.
</para>
<para>
<function>umask</function> without arguments simply returns the
current umask.
</para>
<note>
<para>
Avoid using this function in multithreaded webservers. It is better to
change the file permissions with <function>chmod</function> after
creating the file. Using <function>umask</function> can lead to
unexpected behavior of concurrently running scripts and the webserver
itself because they all use the same umask.
</para>
</note>
<para>
<example>
<title><function>umask</function> example</title>
<programlisting role="php">
<refentry id="function.umask">
<refnamediv>
<refname>umask</refname>
<refpurpose>Changes the current umask</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>umask</methodname>
<methodparam choice="opt"><type>int</type><parameter>mask</parameter></methodparam>
</methodsynopsis>
<para>
<function>umask</function> sets PHP's umask to
<parameter>mask</parameter> &amp; 0777 and returns the old
umask. When PHP is being used as a server module, the umask
is restored when each request is finished.
</para>
<para>
<function>umask</function> without arguments simply returns the
current umask.
</para>
<note>
<para>
Avoid using this function in multithreaded webservers. It is better to
change the file permissions with <function>chmod</function> after
creating the file. Using <function>umask</function> can lead to
unexpected behavior of concurrently running scripts and the webserver
itself because they all use the same umask.
</para>
</note>
<para>
<example>
<title><function>umask</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$old = umask(0);
@ -47,11 +47,11 @@ if ($old != umask()) {
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

60
reference/filesystem/functions/unlink.xml
View file

@ -1,35 +1,35 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.unlink">
<refnamediv>
<refname>unlink</refname>
<refpurpose>Deletes a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>unlink</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Deletes <parameter>filename</parameter>. Similar to the Unix C
unlink() function. &return.success;
</para>
<note>
<simpara>
As of PHP 5.0.0 <function>unlink</function> can also be
used with <emphasis>some</emphasis> URL wrappers. Refer to <xref linkend="wrappers"/>
for a listing of which wrappers support <function>unlink</function>.
</simpara>
</note>
&note.context-support;
<para>
See also <function>rmdir</function> for removing directories.
</para>
</refsect1>
</refentry>
<refentry id="function.unlink">
<refnamediv>
<refname>unlink</refname>
<refpurpose>Deletes a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>unlink</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Deletes <parameter>filename</parameter>. Similar to the Unix C
unlink() function. &return.success;
</para>
<note>
<simpara>
As of PHP 5.0.0 <function>unlink</function> can also be
used with <emphasis>some</emphasis> URL wrappers. Refer to <xref linkend="wrappers"/>
for a listing of which wrappers support <function>unlink</function>.
</simpara>
</note>
&note.context-support;
<para>
See also <function>rmdir</function> for removing directories.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables: