didou Sun Jul 1 21:31:17 2007 UTC
Modified files:
/phpdoc/en/reference/filesystem/functions basename.xml chmod.xml
clearstatcache.xml
dirname.xml fgetc.xml
fgetss.xml fileatime.xml
filetype.xml flock.xml
fnmatch.xml fpassthru.xml
fputcsv.xml
Log:
More new doc style
# Also fixed fputcsv() where the fields parameters is required
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/basename.xml?r1=1.8&r2=1.9&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/basename.xml
diff -u phpdoc/en/reference/filesystem/functions/basename.xml:1.8
phpdoc/en/reference/filesystem/functions/basename.xml:1.9
--- phpdoc/en/reference/filesystem/functions/basename.xml:1.8 Wed Jun 20
22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/basename.xml Sun Jul 1
21:31:16 2007
@@ -1,30 +1,87 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
-<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
+<!-- $Revision: 1.9 $ -->
<refentry xmlns="http://docbook.org/ns/docbook"; xml:id="function.basename">
<refnamediv>
<refname>basename</refname>
<refpurpose>Returns filename component of path</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+
+ <refsect1 role="description">
+ &reftitle.description;
<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.
+ Given a string containing a path to a file, this function will return the
+ base name of the file.
</para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>path</parameter></term>
+ <listitem>
+ <para>
+ A path.
+ </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>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>suffix</parameter></term>
+ <listitem>
+ <para>
+ If the filename ends in <parameter>suffix</parameter> this will also
+ be cut off.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
<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>).
+ Returns the base name of the given <parameter>path</parameter>.
</para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>4.1.0</entry>
+ <entry>
+ The <parameter>suffix</parameter> parameter was added
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
<para>
<example>
<title><function>basename</function> example</title>
@@ -32,22 +89,24 @@
<![CDATA[
<?php
$path = "/home/httpd/html/index.php";
-$file = basename($path); // $file is set to "index.php"
+$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>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- See also <function>dirname</function>.
+ <simplelist>
+ <member><function>dirname</function></member>
+ </simplelist>
</para>
</refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/chmod.xml?r1=1.15&r2=1.16&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/chmod.xml
diff -u phpdoc/en/reference/filesystem/functions/chmod.xml:1.15
phpdoc/en/reference/filesystem/functions/chmod.xml:1.16
--- phpdoc/en/reference/filesystem/functions/chmod.xml:1.15 Wed Jun 20
22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/chmod.xml Sun Jul 1 21:31:16 2007
@@ -1,32 +1,48 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.15 $ -->
-<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
+<!-- $Revision: 1.16 $ -->
<refentry xmlns="http://docbook.org/ns/docbook"; xml:id="function.chmod">
<refnamediv>
<refname>chmod</refname>
<refpurpose>Changes file mode</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+
+ <refsect1 role="description">
+ &reftitle.description;
<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
+ Attempts to change the mode of the specified file to that given in
<parameter>mode</parameter>.
</para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
<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">
+ <variablelist>
+ <varlistentry>
+ <term><parameter>filename</parameter></term>
+ <listitem>
+ <para>
+ Path to the file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>mode</parameter></term>
+ <listitem>
+ <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
@@ -34,23 +50,23 @@
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,34 +82,52 @@
chmod("/somedir/somefile", 0750);
?>
]]>
- </programlisting>
- </informalexample>
+ </programlisting>
+ </informalexample>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
<para>
&return.success;
</para>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
<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.
+ 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>
¬e.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>
+ <para>
+ 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.
+ </para>
</note>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- See also <function>chown</function> and
- <function>chgrp</function>.
+ <simplelist>
+ <member><function>chown</function></member>
+ <member><function>chgrp</function></member>
+ </simplelist>
</para>
</refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/clearstatcache.xml?r1=1.10&r2=1.11&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/clearstatcache.xml
diff -u phpdoc/en/reference/filesystem/functions/clearstatcache.xml:1.10
phpdoc/en/reference/filesystem/functions/clearstatcache.xml:1.11
--- phpdoc/en/reference/filesystem/functions/clearstatcache.xml:1.10 Wed Jun
20 22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/clearstatcache.xml Sun Jul 1
21:31:16 2007
@@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.10 $ -->
-<!-- split from ./en/functions/filesystem.xml, last change in rev 1.2 -->
+<!-- $Revision: 1.11 $ -->
<refentry xmlns="http://docbook.org/ns/docbook";
xml:id="function.clearstatcache">
<refnamediv>
<refname>clearstatcache</refname>
<refpurpose>Clears file status cache</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+
+ <refsect1 role="description">
+ &reftitle.description;
<methodsynopsis>
<type>void</type><methodname>clearstatcache</methodname>
<void/>
@@ -32,10 +32,10 @@
</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.
+ 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>
@@ -59,6 +59,14 @@
<function>fileperms</function>.
</para>
</refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ &return.void;
+ </para>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/dirname.xml?r1=1.11&r2=1.12&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/dirname.xml
diff -u phpdoc/en/reference/filesystem/functions/dirname.xml:1.11
phpdoc/en/reference/filesystem/functions/dirname.xml:1.12
--- phpdoc/en/reference/filesystem/functions/dirname.xml:1.11 Wed Jun 20
22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/dirname.xml Sun Jul 1
21:31:16 2007
@@ -1,27 +1,87 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.11 $ -->
-<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
+<!-- $Revision: 1.12 $ -->
<refentry xmlns="http://docbook.org/ns/docbook"; xml:id="function.dirname">
<refnamediv>
<refname>dirname</refname>
<refpurpose>Returns directory name component of path</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+
+ <refsect1 role="description">
+ &reftitle.description;
<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.
+ Given a string containing a path to a file, this function will return the
+ name of the directory.
</para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>path</parameter></term>
+ <listitem>
+ <para>
+ A path.
+ </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>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
<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>).
+ Returns the name of the directory. 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.
</para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>5.0.0</entry>
+ <entry>
+ <function>dirname</function> is now binary safe
+ </entry>
+ </row>
+ <row>
+ <entry>4.0.3</entry>
+ <entry>
+ <function>dirname</function> was fixed to be POSIX-compliant.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
<para>
<example>
<title><function>dirname</function> example</title>
@@ -35,23 +95,19 @@
</programlisting>
</example>
</para>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
<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
+ Since PHP 4.3.0, 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:
+ Check the following change example:
<informalexample>
<programlisting role="php">
<![CDATA[
@@ -68,14 +124,19 @@
</programlisting>
</informalexample>
</para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<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>.
+ <simplelist>
+ <member><function>basename</function></member>
+ <member><function>pathinfo</function></member>
+ <member><function>realpath</function></member>
+ </simplelist>
</para>
</refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/fgetc.xml?r1=1.12&r2=1.13&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/fgetc.xml
diff -u phpdoc/en/reference/filesystem/functions/fgetc.xml:1.12
phpdoc/en/reference/filesystem/functions/fgetc.xml:1.13
--- phpdoc/en/reference/filesystem/functions/fgetc.xml:1.12 Wed Jun 20
22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/fgetc.xml Sun Jul 1 21:31:16 2007
@@ -1,26 +1,47 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.12 $ -->
-<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
+<!-- $Revision: 1.13 $ -->
<refentry xmlns="http://docbook.org/ns/docbook"; xml:id="function.fgetc">
<refnamediv>
<refname>fgetc</refname>
<refpurpose>Gets character from file pointer</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+
+ <refsect1 role="description">
+ &reftitle.description;
<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.
+ Gets a character from the given file pointer.
</para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>handle</parameter></term>
+ <listitem>
+ &fs.validfp.all;
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
- &fs.validfp.all;
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Returns a string containing a single character read from the file pointed
+ to by <parameter>handle</parameter>. Returns &false; on EOF.
+ </para>
&return.falseproblem;
+ </refsect1>
+ <refsect1 role="examples">
+ &reftitle.examples;
<para>
<example>
<title>A <function>fgetc</function> example</title>
@@ -39,15 +60,26 @@
</programlisting>
</example>
</para>
+ </refsect1>
+ <refsect1 role="notes">
+ &reftitle.notes;
¬e.bin-safe;
+ </refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- See also <function>fread</function>, <function>fopen</function>,
- <function>popen</function>, <function>fsockopen</function>, and
- <function>fgets</function>.
+ <simplelist>
+ <member><function>fread</function></member>
+ <member><function>fopen</function></member>
+ <member><function>popen</function></member>
+ <member><function>fsockopen</function></member>
+ <member><function>fgets</function></member>
+ </simplelist>
</para>
</refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/fgetss.xml?r1=1.8&r2=1.9&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/fgetss.xml
diff -u phpdoc/en/reference/filesystem/functions/fgetss.xml:1.8
phpdoc/en/reference/filesystem/functions/fgetss.xml:1.9
--- phpdoc/en/reference/filesystem/functions/fgetss.xml:1.8 Wed Jun 20
22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/fgetss.xml Sun Jul 1 21:31:16 2007
@@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
-<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
+<!-- $Revision: 1.9 $ -->
<refentry xmlns="http://docbook.org/ns/docbook"; xml:id="function.fgetss">
<refnamediv>
<refname>fgetss</refname>
<refpurpose>Gets line from file pointer and strip HTML tags</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+
+ <refsect1 role="description">
+ &reftitle.description;
<methodsynopsis>
<type>string</type><methodname>fgetss</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
@@ -15,30 +15,103 @@
<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>
- <parameter>allowable_tags</parameter> was added in PHP 3.0.13,
- PHP 4.0.0.
- </para>
- </note>
+ Identical to <function>fgets</function>, except that
+ <function>fgetss</function> attempts to strip any HTML and PHP tags from
+ the text it reads.
</para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
<para>
- Parameter <parameter>length</parameter> is optional since PHP 5.
+ <variablelist>
+ <varlistentry>
+ <term><parameter>handle</parameter></term>
+ <listitem>
+ &fs.validfp.all;
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>length</parameter></term>
+ <listitem>
+ <para>
+ Length of the data to be retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>allowable_tags</parameter></term>
+ <listitem>
+ <para>
+ You can use the optional third parameter to specify tags which should
+ not be stripped.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Returns a string of up to <parameter>length</parameter> - 1 bytes read from
+ the file pointed to by <parameter>handle</parameter>, with all HTML and PHP
+ code striped.
+ </para>
+ <para>
+ If an error occurs, returns &false;.
+ </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>5.0.0</entry>
+ <entry>
+ The <parameter>length</parameter> parameter is optional
+ </entry>
+ </row>
+ <row>
+ <entry>3.0.13 and 4.0.0</entry>
+ <entry>
+ The <parameter>allowable_tags</parameter> parameter was added,
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
¬e.line-endings;
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- See also <function>fgets</function>, <function>fopen</function>,
- <function>fsockopen</function>, <function>popen</function>, and
- <function>strip_tags</function>.
+ <simplelist>
+ <member><function>fgets</function></member>
+ <member><function>fopen</function></member>
+ <member><function>popen</function></member>
+ <member><function>fsockopen</function></member>
+ <member><function>strip_tags</function></member>
+ </simplelist>
</para>
</refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/fileatime.xml?r1=1.9&r2=1.10&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/fileatime.xml
diff -u phpdoc/en/reference/filesystem/functions/fileatime.xml:1.9
phpdoc/en/reference/filesystem/functions/fileatime.xml:1.10
--- phpdoc/en/reference/filesystem/functions/fileatime.xml:1.9 Wed Jun 20
22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/fileatime.xml Sun Jul 1
21:31:16 2007
@@ -1,36 +1,48 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
-<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
+<!-- $Revision: 1.10 $ -->
<refentry xmlns="http://docbook.org/ns/docbook"; xml:id="function.fileatime">
<refnamediv>
<refname>fileatime</refname>
<refpurpose>Gets last access time of file</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+
+ <refsect1 role="description">
+ &reftitle.description;
<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.
+ Gets the last access time of the given file.
</simpara>
+ </refsect1>
- ¬e.clearstatcache;
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>filename</parameter></term>
+ <listitem>
+ <para>
+ Path to the file.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
- &tip.fopen-wrapper.stat;
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Returns the time the file was last accessed, or &false; in case of
+ an error. The time is returned as a Unix timestamp.
+ </para>
+ </refsect1>
+ <refsect1 role="examples">
+ &reftitle.examples;
<para>
<example>
<title><function>fileatime</function> example</title>
@@ -50,12 +62,38 @@
</programlisting>
</example>
</para>
- <simpara>
- See also <function>filemtime</function>,
- <function>fileinode</function>, and
- <function>date</function>.
- </simpara>
</refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
+ <note>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ </note>
+ ¬e.clearstatcache;
+ &tip.fopen-wrapper.stat;
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><function>filemtime</function></member>
+ <member><function>fileinode</function></member>
+ <member><function>date</function></member>
+ </simplelist>
+ </para>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/filetype.xml?r1=1.12&r2=1.13&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/filetype.xml
diff -u phpdoc/en/reference/filesystem/functions/filetype.xml:1.12
phpdoc/en/reference/filesystem/functions/filetype.xml:1.13
--- phpdoc/en/reference/filesystem/functions/filetype.xml:1.12 Wed Jun 20
22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/filetype.xml Sun Jul 1
21:31:16 2007
@@ -1,18 +1,41 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.12 $ -->
-<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
+<!-- $Revision: 1.13 $ -->
<refentry xmlns="http://docbook.org/ns/docbook"; xml:id="function.filetype">
<refnamediv>
<refname>filetype</refname>
<refpurpose>Gets file type</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+
+ <refsect1 role="description">
+ &reftitle.description;
<methodsynopsis>
<type>string</type><methodname>filetype</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
+ Returns the type of the given file.
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>filename</parameter></term>
+ <listitem>
+ <para>
+ Path to the file.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
Returns the type of the file. Possible values are fifo, char,
dir, block, link, file, and unknown.
</para>
@@ -21,11 +44,10 @@
produce an <constant>E_NOTICE</constant> message if the stat call fails
or if the file type is unknown.
</para>
+ </refsect1>
- ¬e.clearstatcache;
-
- &tip.fopen-wrapper.stat;
-
+ <refsect1 role="examples">
+ &reftitle.examples;
<para>
<example>
<title><function>filetype</function> example</title>
@@ -41,12 +63,28 @@
</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>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
+ ¬e.clearstatcache;
+ &tip.fopen-wrapper.stat;
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><function>is_dir</function></member>
+ <member><function>is_file</function></member>
+ <member><function>is_link</function></member>
+ <member><function>file_exists</function></member>
+ <member><function>stat</function></member>
+ <member><function>mime_content_type</function></member>
+ </simplelist>
+ </para>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/flock.xml?r1=1.14&r2=1.15&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/flock.xml
diff -u phpdoc/en/reference/filesystem/functions/flock.xml:1.14
phpdoc/en/reference/filesystem/functions/flock.xml:1.15
--- phpdoc/en/reference/filesystem/functions/flock.xml:1.14 Wed Jun 20
22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/flock.xml Sun Jul 1 21:31:16 2007
@@ -1,78 +1,127 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.14 $ -->
-<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
+<!-- $Revision: 1.15 $ -->
<refentry xmlns="http://docbook.org/ns/docbook"; xml:id="function.flock">
<refnamediv>
<refname>flock</refname>
<refpurpose>Portable advisory file locking</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+
+ <refsect1 role="description">
+ &reftitle.description;
<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>
+ <para>
+ <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).
+ </para>
+ <para>
+ The lock is released also by <function>fclose</function> (which is also
+ called automatically when script finished).
+ </para>
+ <para>
+ 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).
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>handle</parameter></term>
+ <listitem>
+ <para>
+ An open file pointer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>operation</parameter></term>
+ <listitem>
+ <para>
+ <parameter>operation</parameter> is one of the following:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <constant>LOCK_SH</constant> to acquire a shared lock (reader).
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <constant>LOCK_EX</constant> to acquire an exclusive lock (writer).
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <constant>LOCK_UN</constant> to release a lock (shared or exclusive).
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <constant>LOCK_NB</constant> if you don't want
+ <function>flock</function> to block while locking.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>wouldblock</parameter></term>
+ <listitem>
+ <para>
+ The optional third argument is set to &true; if the lock would block
+ (EWOULDBLOCK errno condition).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
&return.success;
- </simpara>
+ </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>4.0.1</entry>
+ <entry>
+ The <literal>LOCK_XXX</literal> constants were added. Prior to that
+ you must use 1 for <constant>LOCK_SH</constant>, 2 for
+ <constant>LOCK_EX</constant>, 3 for <constant>LOCK_UN</constant> and
+ 4 for <constant>LOCK_NB</constant>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
<para>
<example>
<title><function>flock</function> example</title>
@@ -96,6 +145,15 @@
</programlisting>
</example>
</para>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
+ <note>
+ <para>
+ <function>flock</function> is mandatory under Windows.
+ </para>
+ </note>
<note>
<para>
Because <function>flock</function> requires a file pointer, you may have
@@ -125,6 +183,7 @@
</para>
</warning>
</refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/fnmatch.xml?r1=1.12&r2=1.13&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/fnmatch.xml
diff -u phpdoc/en/reference/filesystem/functions/fnmatch.xml:1.12
phpdoc/en/reference/filesystem/functions/fnmatch.xml:1.13
--- phpdoc/en/reference/filesystem/functions/fnmatch.xml:1.12 Wed Jun 20
22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/fnmatch.xml Sun Jul 1
21:31:16 2007
@@ -1,12 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.12 $ -->
+<!-- $Revision: 1.13 $ -->
<refentry xmlns="http://docbook.org/ns/docbook"; xml:id="function.fnmatch">
<refnamediv>
<refname>fnmatch</refname>
<refpurpose>Match filename against a pattern</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+
+ <refsect1 role="description">
+ &reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>fnmatch</methodname>
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
@@ -17,42 +18,122 @@
<function>fnmatch</function> checks if the passed
<parameter>string</parameter> would
match the given shell wildcard <parameter>pattern</parameter>.
</para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem>
+ <para>
+ The shell wildcard patter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem>
+ <para>
+ The tested string. This function is especially useful for filenames,
+ but may also be used on regular strings.
+ </para>
+ <para>
+ 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>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter></term>
+ <listitem>
+ <para>
+ See the Unix manpage on <literal>fnmatch(3)</literal> for flag names
+ (as long as they are not documented here<!-- TODO hartmut -->).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Returns &true; if there is a match, &false; otherwise.
+ </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
<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">
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>4.1.0</entry>
+ <entry>
+ The <parameter>suffix</parameter> parameter was added
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Checking a color name against a shell wildcard pattern</title>
+ <programlisting role="php">
<![CDATA[
<?php
if (fnmatch("*gr[ae]y", $color)) {
echo "some form of gray ...";
}
-?>
]]>
- </programlisting>
- </example>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
<warning>
<para>
For now this function is not available on Windows or other non-POSIX
compliant systems.
</para>
</warning>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<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 -->).
+ <simplelist>
+ <member><function>glob</function></member>
+ <member><function>ereg</function></member>
+ <member><function>preg_match</function></member>
+ <member><function>sscanf</function></member>
+ <member><function>printf</function></member>
+ <member><function>sprintf</function></member>
+ </simplelist>
</para>
</refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/filesystem/functions/fpassthru.xml?r1=1.12&r2=1.13&diff_format=u
Index: phpdoc/en/reference/filesystem/functions/fpassthru.xml
diff -u phpdoc/en/reference/filesystem/functions/fpassthru.xml:1.12
phpdoc/en/reference/filesystem/functions/fpassthru.xml:1.13
--- phpdoc/en/reference/filesystem/functions/fpassthru.xml:1.12 Wed Jun 20
22:24:27 2007
+++ phpdoc/en/reference/filesystem/functions/fpassthru.xml Sun Jul 1
21:31:16 2007
@@ -1,56 +1,64 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.12 $ -->
-<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
+<!-- $Revision: 1.13 $ -->
<refentry xmlns="http://docbook.org/ns/docbook"; xml:id="function.fpassthru">
<refnamediv>
<refname>fpassthru</refname>
<refpurpose>Output all remaining data on a file pointer</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+
+ <refsect1 role="description">
+ &reftitle.description;
<methodsynopsis>
<type>int</type><methodname>fpassthru</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
</methodsynopsis>
- <simpara>
+ <para>
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>
+ </para>
+ <para>
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>
+ </para>
+ <para>
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>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>handle</parameter></term>
+ <listitem>
+ &fs.validfp.all;
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
<para>
- <example>
- <title>Using <function>fpassthru</function> with binary files</title>
- <programlisting role="php">
+ 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.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Using <function>fpassthru</function> with binary files</title>
+ <programlisting role="php">
<