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

ref.misc: switch to new docstyle

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@230198 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Mehdi Achour 2007-02-19 00:04:49 +00:00
parent 87176f4374
commit b530ac7a60
25 changed files with 1289 additions and 491 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
reference/misc/functions/connection-aborted.xml
View file

@ -1,28 +1,43 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.2 -->
<!-- $Revision: 1.6 $ -->
<refentry id="function.connection-aborted">
<refnamediv>
<refname>connection_aborted</refname>
<refpurpose>Returns &true; if client disconnected</refpurpose>
<refpurpose>Check whether if client disconnected</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>connection_aborted</methodname>
<void/>
</methodsynopsis>
<simpara>
Returns &true; if client disconnected. See the <link
linkend="features.connection-handling">Connection Handling</link>
description in the <link linkend="features">Features</link>
chapter for a complete explanation.
</simpara>
<para>
See also <function>connection_status</function>, and
<function>ignore_user_abort</function>.
Checks whether if the client disconnected.
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns 1 if client disconnected, 0 otherwise.
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>connection_status</function></member>
<member><function>ignore_user_abort</function></member>
<member>
<link linkend="features.connection-handling">Connection Handling</link>
for a complete description of connection handling in PHP.
</member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

41
reference/misc/functions/connection-status.xml
View file

@ -1,28 +1,45 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.2 -->
<!-- $Revision: 1.6 $ -->
<refentry id="function.connection-status">
<refnamediv>
<refname>connection_status</refname>
<refpurpose>Returns connection status bitfield</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>connection_status</methodname>
<void/>
</methodsynopsis>
<simpara>
Returns the connection status bitfield. See the <link
linkend="features.connection-handling">Connection Handling</link>
description in the <link linkend="features">Features</link>
chapter for a complete explanation.
</simpara>
<para>
See also <function>connection_aborted</function>, and
<function>ignore_user_abort</function>.
Gets the connection status bitfield.
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the connection status bitfield, which can be used against the
<literal>CONNECTION_XXX</literal> constants to determine the connection
status.
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>connection_aborted</function></member>
<member><function>ignore_user_abort</function></member>
<member>
<link linkend="features.connection-handling">Connection Handling</link>
for a complete description of connection handling in PHP.
</member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

47
reference/misc/functions/connection-timeout.xml
View file

@ -1,20 +1,31 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.2 -->
<!-- $Revision: 1.5 $ -->
<refentry id="function.connection-timeout">
<refnamediv>
<refname>connection_timeout</refname>
<refpurpose>Return &true; if script timed out</refpurpose>
<refpurpose>Check if the script timed out</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>connection_timeout</methodname>
<type>int</type><methodname>connection_timeout</methodname>
<void/>
</methodsynopsis>
<simpara>
Returns &true; if script timed out.
</simpara>
<para>
Determines whether if the script timed out.
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns 1 if the script timed out, 0 otherwise.
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<warning>
<title>Deprecated</title>
<simpara>
@ -25,17 +36,21 @@
TODO: correct connection handling. Any volunteers?
-->
</warning>
</refsect1>
<simpara>
See the <link
linkend="features.connection-handling">Connection Handling</link>
description in the <link linkend="features">Features</link>
chapter for a complete explanation.
</simpara>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>connection_status</function>.
<simplelist>
<member><function>connection_status</function></member>
<member>
<link linkend="features.connection-handling">Connection Handling</link>
for a complete description of connection handling in PHP.
</member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

53
reference/misc/functions/constant.xml
View file

@ -1,20 +1,20 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.38 -->
<!-- $Revision: 1.7 $ -->
<refentry id="function.constant">
<refnamediv>
<refname>constant</refname>
<refpurpose>Returns the value of a constant</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>constant</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>constant</function> will return the value of the
constant indicated by <parameter>name</parameter>.
Return the value of the constant indicated by
<parameter>name</parameter>.
</simpara>
<simpara>
<function>constant</function> is useful if you need to retrieve
@ -25,6 +25,34 @@
This function works also with <link
linkend="language.oop5.constants">class constants</link>.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
The constant name.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the value of the constant, or &null; if the constant is not
defined.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>constant</function> example</title>
@ -42,12 +70,19 @@ echo constant("MAXSIZE"); // same thing as the previous line
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>define</function>,
<function>defined</function> and the section on <link
linkend="language.constants">Constants</link>.
<simplelist>
<member><function>define</function></member>
<member><function>defined</function></member>
<member>The section on <link linkend="language.constants">Constants</link></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

78
reference/misc/functions/define.xml
View file

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.2 -->
<!-- $Revision: 1.8 $ -->
<refentry id="function.define">
<refnamediv>
<refname>define</refname>
<refpurpose>Defines a named constant</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>define</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
@ -15,22 +15,54 @@
<methodparam choice="opt"><type>bool</type><parameter>case_insensitive</parameter></methodparam>
</methodsynopsis>
<para>
Defines a named constant at runtime. See the
<link linkend="language.constants">section on constants</link>
for more details.
Defines a named constant at runtime.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
The name of the constant is given by <parameter>name</parameter>;
the value is given by <parameter>value</parameter>.
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
The name of the constant.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
The value of the constant.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>case_insensitive</parameter></term>
<listitem>
<para>
If set to &true;, the constant will be defined case-insensitive.
The default behaviour is case-sensitive; i.e.
<literal>CONSTANT</literal> and <literal>Constant</literal> represent
different values.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The optional third parameter
<parameter>case_insensitive</parameter> is also available. If the
value &true; is given, then the constant will be
defined case-insensitive. The default behaviour is
case-sensitive; i.e. CONSTANT and Constant represent different
values.
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Defining Constants</title>
@ -50,15 +82,19 @@ echo Greeting; // outputs "Hello you."
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
&return.success;
</para>
<para>
See also <function>defined</function>,
<function>constant</function> and the section on <link
linkend="language.constants">Constants</link>.
<simplelist>
<member><function>defined</function></member>
<member><function>constant</function></member>
<member>The section on <link linkend="language.constants">Constants</link></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

74
reference/misc/functions/defined.xml
View file

@ -1,22 +1,56 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.2 -->
<!-- $Revision: 1.10 $ -->
<refentry id="function.defined">
<refnamediv>
<refname>defined</refname>
<refpurpose>Checks whether a given named constant exists</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>defined</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if the named constant given by
<parameter>name</parameter> has been defined,
&false; otherwise.
Checks whether the given constant exists and is defined.
</para>
<note>
<para>
If you want to see if a variable exists, use <function>isset</function>
as <function>defined</function> only applies to <link
linkend="language.constants">constants</link>. If you want to see if a
function exists, use <function>function_exists</function>.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>
The constant name.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; if the named constant given by <parameter>name</parameter>
has been defined, &false; otherwise.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Checking Constants</title>
@ -33,23 +67,21 @@ if (defined('CONSTANT')) {
</programlisting>
</example>
</para>
<note>
<para>
If you want to see if a variable exists, use
<function>isset</function> as <function>defined</function> only
applies to <link linkend="language.constants">constants</link>.
If you want to see if a function exists, use
<function>function_exists</function>.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>define</function>,
<function>constant</function>,
<function>get_defined_constants</function>,
<function>function_exists</function>, and the section on
<link linkend="language.constants">Constants</link>.
<simplelist>
<member><function>define</function></member>
<member><function>constant</function></member>
<member><function>get_defined_constants</function></member>
<member><function>function_exists</function></member>
<member>The section on <link linkend="language.constants">Constants</link></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

9
reference/misc/functions/die.xml
View file

@ -1,17 +1,18 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.57 -->
<!-- $Revision: 1.5 $ -->
<refentry id="function.die">
<refnamediv>
<refname>die</refname>
<refpurpose>Equivalent to <function>exit</function></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<para>
This language construct is equivalent to <function>exit</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

114
reference/misc/functions/eval.xml
View file

@ -1,54 +1,77 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.17 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.58 -->
<!-- $Revision: 1.18 $ -->
<refentry id="function.eval">
<refnamediv>
<refname>eval</refname>
<refpurpose>Evaluate a string as PHP code</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>eval</methodname>
<methodparam><type>string</type><parameter>code_str</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>eval</function> evaluates the string given in
<parameter>code_str</parameter> as PHP code. Among other things,
this can be useful for storing code in a database text field for
later execution. <parameter>code_str</parameter> does not have to
contain <link linkend="language.basic-syntax.phpmode">PHP Opening
tags</link>.
</simpara>
<simpara>
<para>
Evaluates the string given in <parameter>code_str</parameter> as PHP code.
Among other things, this can be useful for storing code in a database text
field for later execution.
</para>
<para>
There are some factors to keep in mind when using
<function>eval</function>. Remember that the string passed must
be valid PHP code, including things like terminating statements
with a semicolon so the parser doesn't die on the line after the
<function>eval</function>, and properly escaping things in
<parameter>code_str</parameter>. To mix HTML output and PHP code
you can use a closing PHP tag to leave PHP mode.
</simpara>
<simpara>
Also remember that variables given values under
<function>eval</function> will retain these values in the main
script afterwards.
</simpara>
<simpara>
A <literal>return</literal> statement will terminate the evaluation of
the string immediately. As of PHP 4, <function>eval</function> returns
&null; unless <literal>return</literal> is called in the evaluated
code, in which case the value passed to <literal>return</literal> is
returned. In case of a parse error in the evaluated code,
<function>eval</function> returns &false;.
In case of a fatal error in the evaluated code, the whole script exits.
<function>eval</function>. Remember that the string passed must be valid
PHP code, including things like terminating statements with a semicolon so
the parser doesn't die on the line after the <function>eval</function>,
and properly escaping things in <parameter>code_str</parameter>. To mix
HTML output and PHP code you can use a closing PHP tag to leave PHP mode.
</para>
<para>
Also remember that variables given values under <function>eval</function>
will retain these values in the main script afterwards.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>code_str</parameter></term>
<listitem>
<para>
The code string to be avaluated.
<parameter>code_str</parameter> does not have to contain <link
linkend="language.basic-syntax.phpmode">PHP Opening tags</link>.
</para>
<para>
A <literal>return</literal> statement will immediately terminate the
evaluation of the string .
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
As of PHP 4, <function>eval</function> returns &null; unless
<literal>return</literal> is called in the evaluated code, in which case
the value passed to <literal>return</literal> is returned. In case of a
parse error in the evaluated code, <function>eval</function> returns
&false;.
</para>
<para>
In PHP 3, <function>eval</function> does not return a value.
</simpara>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>
<function>eval</function> example - simple text merge
</title>
<title><function>eval</function> example - simple text merge</title>
<programlisting role="php">
<![CDATA[
<?php
@ -70,9 +93,24 @@ This is a cup with my coffee in it.
</screen>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
&tip.ob-capture;
<note>
<para>
In case of a fatal error in the evaluated code, the whole script exits.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>call_user_func</function>.
<simplelist>
<member><function>call_user_func</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

97
reference/misc/functions/exit.xml
View file

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.2 -->
<!-- $Revision: 1.13 $ -->
<refentry id="function.exit">
<refnamediv>
<refname>exit</refname>
<refpurpose>Output a message and terminate the current script</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>exit</methodname>
<methodparam choice="opt"><type>string</type><parameter>status</parameter></methodparam>
@ -16,27 +16,50 @@
<type>void</type><methodname>exit</methodname>
<methodparam><type>int</type><parameter>status</parameter></methodparam>
</methodsynopsis>
<note>
<simpara>
This is not a real function, but a language construct.
</simpara>
</note>
<note>
<simpara>
PHP &gt;= 4.2.0 does NOT print the <parameter>status</parameter>
if it is an <type>integer</type>.
</simpara>
</note>
<simpara>
The <function>exit</function> function terminates execution of
the script. It prints <parameter>status</parameter> just before exiting.
</simpara>
<simpara>
If <parameter>status</parameter> is an <type>integer</type>, that value
will also be used as the exit status. Exit statuses should be in the
range 0 to 254, the exit status 255 is reserved by PHP and shall not be
used. The status 0 is used to terminate the program successfully.
</simpara>
<para>
Terminates execution of the script.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>status</parameter></term>
<listitem>
<para>
If <parameter>status</parameter> is a string, this function prints the
<parameter>status</parameter>, if set as a string just before exiting.
</para>
<para>
If <parameter>status</parameter> is an <type>integer</type>, that
value will also be used as the exit status. Exit statuses should be in
the range 0 to 254, the exit status 255 is reserved by PHP and shall
not be used. The status 0 is used to terminate the program
successfully.
</para>
<note>
<simpara>
PHP &gt;= 4.2.0 does NOT print the <parameter>status</parameter>
if it is an <type>integer</type>.
</simpara>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.void;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>exit</function> example</title>
@ -74,15 +97,31 @@ exit(0376); //octal
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<simpara>
This language construct is equivalent to <function>die</function>.
</simpara>
<para>
This is not a real function, but a language construct.
</para>
</note>
<note>
<para>
This language construct is equivalent to <function>die</function>.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also: <function>register_shutdown_function</function>.
<simplelist>
<member><function>register_shutdown_function</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

126
reference/misc/functions/get-browser.xml
View file

@ -1,43 +1,98 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.15 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.2 -->
<!-- $Revision: 1.16 $ -->
<refentry id="function.get-browser">
<refnamediv>
<refname>get_browser</refname>
<refpurpose>Tells what the user's browser is capable of</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>get_browser</methodname>
<methodparam choice="opt"><type>string</type><parameter>user_agent</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>return_array</parameter></methodparam>
</methodsynopsis>
<para>
<function>get_browser</function> attempts to determine the
capabilities of the user's browser. This is done by looking up
the browser's information in the <filename>browscap.ini</filename>
Attempts to determine the capabilities of the user's browser, by looking
up the browser's information in the <filename>browscap.ini</filename>
file.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
By default, the value of HTTP User-Agent header is
used; however, you can alter this (i.e., look up another browser's
info) by passing the optional <parameter>user_agent</parameter> parameter to
<function>get_browser</function>. You can bypass <parameter>user_agent</parameter>
parameter with &null; value.
<variablelist>
<varlistentry>
<term><parameter>user_agent</parameter></term>
<listitem>
<para>
The User Agent to be analyzed. By default, the value of HTTP
User-Agent header is used; however, you can alter this (i.e., look up
another browser's info) by passing this parameter.
</para>
<para>
You can bypass this parameter with a &null; value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>return_array</parameter></term>
<listitem>
<para>
If set to &true;, this function will return an <type>array</type>
instead of an <type>object</type>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<simpara>
The information is returned in an <type>object</type>, which will contain
various data elements representing, for instance, the browser's
major and minor version numbers and ID string; &true;/&false; values
for features such as frames, JavaScript, and cookies; and so
forth.
</simpara>
<simpara>
As of PHP 4.3.2, if the optional parameter
<parameter>return_array</parameter> is &true;, this function will return an
<type>array</type> instead of an <type>object</type>.
</simpara>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The information is returned in an object or an array which will contain
various data elements representing, for instance, the browser's major and
minor version numbers and ID string; &true;/&false; values for features
such as frames, JavaScript, and cookies; and so forth.
</para>
<para>
The <literal>cookies</literal> value simply means that the browser
itself is capable of accepting cookies and does not mean the user has
enabled the browser to accept cookies or not. The only way to test if
cookies are accepted is to set one with <function>setcookie</function>,
reload, and check for the value.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>4.3.2</entry>
<entry>
The optional parameter <parameter>return_array</parameter> was added.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Listing all information about the users browser</title>
@ -89,23 +144,21 @@ Array
</screen>
</example>
</para>
<para>
The <literal>cookies</literal> value simply means that the browser
itself is capable of accepting cookies and does not mean the user has
enabled the browser to accept cookies or not. The only way to test if
cookies are accepted is to set one with <function>setcookie</function>,
reload, and check for the value.
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
In order for this to work, your <link linkend="ini.browscap">browscap</link>
configuration setting in &php.ini; must point to the correct location of the
In order for this to work, your <link
linkend="ini.browscap">browscap</link> configuration setting in
&php.ini; must point to the correct location of the
<filename>browscap.ini</filename> file on your system.
</para>
<para>
<filename>browscap.ini</filename> is not bundled with PHP, but you
may find an <ulink url="&url.browscap.download;">up-to-date php_browscap.ini</ulink>
file here.
<filename>browscap.ini</filename> is not bundled with PHP, but you may
find an up-to-date <ulink
url="&url.browscap.download;">php_browscap.ini</ulink> file here.
</para>
<para>
While <filename>browscap.ini</filename> contains information on
@ -114,6 +167,7 @@ Array
</para>
</note>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

32
reference/misc/functions/halt-compiler.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<refentry id="function.halt-compiler">
<refnamediv>
<refname>__halt_compiler</refname>
@ -14,19 +14,22 @@
<void/>
</methodsynopsis>
<para>
This function halts the execution of the compiler. This can be useful to
embed data in PHP scripts, like the installation files.
Halts the execution of the compiler. This can be useful to embed data in
PHP scripts, like the installation files.
</para>
<para>
Byte position of the data start can be determined by the
<constant>__COMPILER_HALT_OFFSET__</constant> constant which is defined
only if there is a <function>__halt_compiler</function> presented in the
file.
</para>
<note>
<para>
<function>__halt_compiler</function> can only be used from the outermost
scope.
</para>
</note>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.void;
</para>
</refsect1>
<refsect1 role="examples">
@ -54,6 +57,17 @@ __halt_compiler();the installation data (eg. tar, gz, PHP, etc.)
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
<function>__halt_compiler</function> can only be used from the outermost
scope.
</para>
</note>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

140
reference/misc/functions/highlight-file.xml
View file

@ -1,53 +1,23 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.22 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.22 -->
<!-- $Revision: 1.23 $ -->
<refentry id="function.highlight-file">
<refnamediv>
<refname>highlight_file</refname>
<refpurpose>Syntax highlighting of a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>highlight_file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>return</parameter></methodparam>
</methodsynopsis>
<simpara>
The <function>highlight_file</function> function prints out a syntax
highlighted version of the code contained in <parameter>filename</parameter>
using the colors defined in the built-in syntax highlighter for PHP.
</simpara>
<simpara>
If the second parameter <parameter>return</parameter> is set to &true;
then <function>highlight_file</function> will return the highlighted
code as a string instead of printing it out. If the second parameter is
not set to &true; then <function>highlight_file</function> will
return &true; on success, &false; on failure.
</simpara>
&note.uses-ob;
<note>
<simpara>
The <parameter>return</parameter> parameter became available in PHP
4.2.0. Before this time it behaved like the default, which is &false;
</simpara>
</note>
<note>
<simpara>
Since PHP 4.2.1 this function is also affected by <link
linkend="ini.safe-mode">safe_mode</link> and <link
linkend="ini.open-basedir">open_basedir</link>.
</simpara>
</note>
<caution>
<simpara>
Care should be taken when using the
<function>highlight_file</function> function to make sure that
you do not inadvertently reveal sensitive information such as
passwords or any other type of information that might create a
potential security risk.
</simpara>
</caution>
<para>
Prints out or return a syntax highlighted version of the code contained
in <parameter>filename</parameter> using the colors defined in the
built-in syntax highlighter for PHP.
</para>
<para>
Many servers are configured to automatically highlight files
with a <emphasis>phps</emphasis> extension. For example,
@ -60,10 +30,96 @@
AddType application/x-httpd-php-source .phps
]]>
</screen>
<simpara>
See also <function>highlight_string</function>.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
<para>
Path to the PHP file to be highlighted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>return</parameter></term>
<listitem>
<para>
Set this parameter to &true; to make this function return the
highlighted code.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
If <parameter>return</parameter> is set to &true;, returns the highlighted
code as a string instead of printing it out. Otherwise, it will return
&true; on success, &false; on failure.
</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.2.1</entry>
<entry>
This function is now also affected by <link
linkend="ini.safe-mode">safe_mode</link> and <link
linkend="ini.open-basedir">open_basedir</link>.
</entry>
</row>
<row>
<entry>4.2.0</entry>
<entry>
The <parameter>return</parameter> parameter was added.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<caution>
<para>
Care should be taken when using the <function>highlight_file</function>
function to make sure that you do not inadvertently reveal sensitive
information such as passwords or any other type of information that might
create a potential security risk.
</para>
</caution>
&note.uses-ob;
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>highlight_string</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

107
reference/misc/functions/highlight-string.xml
View file

@ -1,31 +1,84 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.22 -->
<!-- $Revision: 1.8 $ -->
<refentry id="function.highlight-string">
<refnamediv>
<refname>highlight_string</refname>
<refpurpose>Syntax highlighting of a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>highlight_string</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>return</parameter></methodparam>
</methodsynopsis>
<simpara>
The <function>highlight_string</function> function outputs a syntax
highlighted version of <parameter>str</parameter> using the colors defined
in the built-in syntax highlighter for PHP.
Outputs or returns a syntax highlighted version of the given PHP code
using the colors defined in the built-in syntax highlighter for PHP.
</simpara>
<simpara>
If the second parameter <parameter>return</parameter> is set to &true;
then <function>highlight_string</function> will return the highlighted
code as a string instead of printing it out. If the second parameter is
not set to &true; then <function>highlight_string</function> will
return &true; on success, &false; on failure.
</simpara>
&note.uses-ob;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>str</parameter></term>
<listitem>
<para>
The PHP code to be highligthed. This should include the opening tag.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>return</parameter></term>
<listitem>
<para>
Set this parameter to &true; to make this function return the
highlighted code.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
If <parameter>return</parameter> is set to &true;, returns the highlighted
code as a string instead of printing it out. Otherwise, it will return
&true; on success, &false; on failure.
</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.2.0</entry>
<entry>
The <parameter>return</parameter> parameter was added.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>highlight_string</function> example</title>
@ -60,16 +113,22 @@ highlight_string('<?php phpinfo(); ?>');
</screen>
</example>
</para>
<note>
<simpara>
The <parameter>return</parameter> parameter became available in PHP
4.2.0. Before this time it behaved like the default, which is &false;
</simpara>
</note>
<simpara>
See also <function>highlight_file</function>.
</simpara>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
&note.uses-ob;
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>highlight_file</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

58
reference/misc/functions/ignore-user-abort.xml
View file

@ -1,31 +1,59 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.2 -->
<!-- $Revision: 1.5 $ -->
<refentry id="function.ignore-user-abort">
<refnamediv>
<refname>ignore_user_abort</refname>
<refpurpose>Set whether a client disconnect should abort script execution</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>ignore_user_abort</methodname>
<methodparam choice="opt"><type>bool</type><parameter>setting</parameter></methodparam>
</methodsynopsis>
<simpara>
This function sets whether a client disconnect should cause a
script to be aborted. It will return the previous setting and
can be called without an argument to not change the current
setting and only return the current setting. See the <link
linkend="features.connection-handling">Connection Handling</link>
section in the <link linkend="features">Features</link> chapter
for a complete description of connection handling in PHP.
</simpara>
<para>
See also <function>connection_aborted</function>, and
<function>connection_status</function>.
Sets whether a client disconnect should cause a script to be aborted.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>setting</parameter></term>
<listitem>
<para>
If not set, the function will only return the current setting.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the previous setting, as a boolean.
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>connection_aborted</function></member>
<member><function>connection_status</function></member>
<member>
<link linkend="features.connection-handling">Connection Handling</link>
for a complete description of connection handling in PHP.
</member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

219
reference/misc/functions/pack.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.4 -->
<refentry id="function.pack">
<refnamediv>
@ -16,58 +16,159 @@
</methodsynopsis>
<para>
Pack given arguments into binary string according to
<parameter>format</parameter>. Returns binary string containing
data.
<parameter>format</parameter>.
</para>
<para>
The idea to this function was taken from Perl and all formatting
codes work the same as there, however, there are some formatting
codes that are missing such as Perl's "u" format code. The format
string consists of format codes followed by an optional repeater
argument. The repeater argument can be either an integer value or
* for repeating to the end of the input data. For a, A, h, H the
repeat count specifies how many characters of one data argument
are taken, for @ it is the absolute position where to put the
next data, for everything else the repeat count specifies how
many data arguments are consumed and packed into the resulting
binary string. Currently implemented are
The idea to this function was taken from Perl and all formatting codes
work the same as there, however, there are some formatting codes that are
missing such as Perl's "u" format code.
</para>
<para>
<table>
<title><function>pack</function> format characters</title>
<tgroup cols="2">
<thead>
<row>
<entry>Code</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row><entry>a</entry><entry>NUL-padded string</entry></row>
<row><entry>A</entry><entry>SPACE-padded string</entry></row>
<row><entry>h</entry><entry>Hex string, low nibble first</entry></row>
<row><entry>H</entry><entry>Hex string, high nibble first</entry></row>
<row><entry>c</entry><entry>signed char</entry></row>
<row><entry>C</entry><entry>unsigned char</entry></row>
<row><entry>s</entry><entry>signed short (always 16 bit, machine byte order)</entry></row>
<row><entry>S</entry><entry>unsigned short (always 16 bit, machine byte order)</entry></row>
<row><entry>n</entry><entry>unsigned short (always 16 bit, big endian byte order)</entry></row>
<row><entry>v</entry><entry>unsigned short (always 16 bit, little endian byte order)</entry></row>
<row><entry>i</entry><entry>signed integer (machine dependent size and byte order)</entry></row>
<row><entry>I</entry><entry>unsigned integer (machine dependent size and byte order)</entry></row>
<row><entry>l</entry><entry>signed long (always 32 bit, machine byte order)</entry></row>
<row><entry>L</entry><entry>unsigned long (always 32 bit, machine byte order)</entry></row>
<row><entry>N</entry><entry>unsigned long (always 32 bit, big endian byte order)</entry></row>
<row><entry>V</entry><entry>unsigned long (always 32 bit, little endian byte order)</entry></row>
<row><entry>f</entry><entry>float (machine dependent size and representation)</entry></row>
<row><entry>d</entry><entry>double (machine dependent size and representation)</entry></row>
<row><entry>x</entry><entry>NUL byte</entry></row>
<row><entry>X</entry><entry>Back up one byte</entry></row>
<row><entry>@</entry><entry>NUL-fill to absolute position</entry></row>
</tbody>
</tgroup>
</table>
Note that the distinction between signed and unsigned values only
affects the function <function>unpack</function>, where as
function <function>pack</function> gives the same result for
signed and unsigned format codes.
</para>
<para>
Also note that PHP internally stores <type>integer</type> values as
signed values of a machine dependent size. If you give it an unsigned
integer value too large to be stored that way it is converted to a
<type>float</type> which often yields an undesired result.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
The <parameter>format</parameter> string consists of format codes
followed by an optional repeater argument. The repeater argument can
be either an integer value or <literal>*</literal> for repeating to
the end of the input data. For a, A, h, H the repeat count specifies
how many characters of one data argument are taken, for @ it is the
absolute position where to put the next data, for everything else the
repeat count specifies how many data arguments are consumed and packed
into the resulting binary string.
</para>
<para>
Currently implemented formats are:
<table>
<title><function>pack</function> format characters</title>
<tgroup cols="2">
<thead>
<row>
<entry>Code</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>a</entry>
<entry>NUL-padded string</entry>
</row>
<row>
<entry>A</entry>
<entry>SPACE-padded string</entry></row>
<row>
<entry>h</entry>
<entry>Hex string, low nibble first</entry></row>
<row>
<entry>H</entry>
<entry>Hex string, high nibble first</entry></row>
<row><entry>c</entry><entry>signed char</entry></row>
<row>
<entry>C</entry>
<entry>unsigned char</entry></row>
<row>
<entry>s</entry>
<entry>signed short (always 16 bit, machine byte order)</entry>
</row>
<row>
<entry>S</entry>
<entry>unsigned short (always 16 bit, machine byte order)</entry>
</row>
<row>
<entry>n</entry>
<entry>unsigned short (always 16 bit, big endian byte order)</entry>
</row>
<row>
<entry>v</entry>
<entry>unsigned short (always 16 bit, little endian byte order)</entry>
</row>
<row>
<entry>i</entry>
<entry>signed integer (machine dependent size and byte order)</entry>
</row>
<row>
<entry>I</entry>
<entry>unsigned integer (machine dependent size and byte order)</entry>
</row>
<row>
<entry>l</entry>
<entry>signed long (always 32 bit, machine byte order)</entry>
</row>
<row>
<entry>L</entry>
<entry>unsigned long (always 32 bit, machine byte order)</entry>
</row>
<row>
<entry>N</entry>
<entry>unsigned long (always 32 bit, big endian byte order)</entry>
</row>
<row>
<entry>V</entry>
<entry>unsigned long (always 32 bit, little endian byte order)</entry>
</row>
<row>
<entry>f</entry>
<entry>float (machine dependent size and representation)</entry>
</row>
<row>
<entry>d</entry>
<entry>double (machine dependent size and representation)</entry>
</row>
<row>
<entry>x</entry>
<entry>NUL byte</entry>
</row>
<row>
<entry>X</entry>
<entry>Back up one byte</entry>
</row>
<row>
<entry>@</entry>
<entry>NUL-fill to absolute position</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>args</parameter></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a binary string containing data.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>pack</function> example</title>
@ -84,23 +185,17 @@ $binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66);
</para>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
Note that the distinction between signed and unsigned values only
affects the function <function>unpack</function>, where as
function <function>pack</function> gives the same result for
signed and unsigned format codes.
</para>
<para>
Also note that PHP internally stores <type>integer</type> values as
signed values of a machine dependent size. If you give it an unsigned
integer value too large to be stored that way it is converted to a
<type>float</type> which often yields an undesired result.
</para>
<para>
See also
<function>unpack</function>.
<simplelist>
<member><function>unpack</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

52
reference/misc/functions/php-check-syntax.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.11 $ -->
<!-- $Revision: 1.12 $ -->
<refentry id="function.php-check-syntax">
<refnamediv>
<refname>php_check_syntax</refname>
@ -11,34 +11,41 @@
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>php_check_syntax</methodname>
<methodparam><type>string</type><parameter>file_name</parameter></methodparam>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter role="reference">error_message</parameter></methodparam>
</methodsynopsis>
<simpara>
For technical reasons, this function is deprecated and removed from PHP.
Instead, use <literal>php -l somefile.php</literal> from the
<link linkend="features.commandline">commandline</link>.
</simpara>
<simpara>
The <function>php_check_syntax</function> function performs a syntax
(lint) check on the specified <parameter>filename</parameter> testing
for scripting errors. This is similar to using <command>php -l</command>
from the <link linkend="features.commandline">commandline</link> except
<function>php_check_syntax</function> will execute (but not output)
the checked <parameter>file_name</parameter>. For example, if a function
is defined in <parameter>file_name</parameter>, this defined function will
be available to the file that executed
<para>
Performs a syntax (lint) check on the specified
<parameter>filename</parameter> testing for scripting errors.
</para>
<para>
This is similar to using <command>php -l</command> from the <link
linkend="features.commandline">commandline</link> except that this
function will execute (but not output) the checked
<parameter>filename</parameter>.
</para>
<para>
For example, if a function is defined in <parameter>filename</parameter>,
this defined function will be available to the file that executed
<function>php_check_syntax</function>, but output from
<parameter>file_name</parameter> will be suppressed.
<parameter>filename</parameter> will be suppressed.
</para>
<note>
<!-- See PHP bug #27406 for details on this suppression -->
</simpara>
<para>
For technical reasons, this function is deprecated and removed from PHP.
Instead, use <literal>php -l somefile.php</literal> from the
<link linkend="features.commandline">commandline</link>.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>file_name</parameter></term>
<term><parameter>filename</parameter></term>
<listitem>
<para>
The name of the file being checked.
@ -59,13 +66,15 @@
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; if the lint check passed, and &false; if the link check
failed or if <parameter>file_name</parameter> cannot be opened.
failed or if <parameter>filename</parameter> cannot be opened.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
@ -102,6 +111,7 @@
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
@ -120,6 +130,7 @@ PHP Parse error: unexpected T_STRING in /tmp/somefile.php on line 81
</screen>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
@ -129,6 +140,7 @@ PHP Parse error: unexpected T_STRING in /tmp/somefile.php on line 81
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

40
reference/misc/functions/php-strip-whitespace.xml
View file

@ -1,11 +1,12 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<refentry id="function.php-strip-whitespace">
<refnamediv>
<refname>php_strip_whitespace</refname>
<refpurpose>Return source with stripped comments and whitespace</refpurpose>
</refnamediv>
<refsect1>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>php_strip_whitespace</methodname>
@ -18,6 +19,30 @@
This is similar to using <command>php -w</command> from the
<link linkend="features.commandline">commandline</link>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
<para>
Path to the PHP file.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The stripped source code will be returned on success, or an empty string
on failure.
</para>
<note>
<para>
This function works as described as of PHP 5.0.1. Before this it would
@ -27,14 +52,8 @@
</para>
</note>
</refsect1>
<refsect1>
&reftitle.returnvalues;
<para>
The stripped source code will be returned on success, or an empty string
on failure.
</para>
</refsect1>
<refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
@ -68,6 +87,7 @@ do_nothing();
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

4
reference/misc/functions/show-source.xml
View file

@ -1,6 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.24 -->
<!-- $Revision: 1.7 $ -->
<refentry id="function.show-source">
<refnamediv>
<refname>show_source</refname>
@ -14,6 +13,7 @@
<function>highlight_file</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

60
reference/misc/functions/sleep.xml
View file

@ -1,21 +1,56 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.2 -->
<!-- $Revision: 1.10 $ -->
<refentry id="function.sleep">
<refnamediv>
<refname>sleep</refname>
<refpurpose>Delay execution</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>sleep</methodname>
<methodparam><type>int</type><parameter>seconds</parameter></methodparam>
</methodsynopsis>
<simpara>
The <function>sleep</function> function delays program execution for the
given number of <parameter>seconds</parameter>.
Delays the program execution for the given number of
<parameter>seconds</parameter>.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>seconds</parameter></term>
<listitem>
<para>
Halt time in seconds.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns zero on success, or &false; on errors.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
If the specified number of <parameter>seconds</parameter> is negative,
this function will generate a <constant>E_WARNING</constant>.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>sleep</function> example</title>
@ -46,11 +81,16 @@ echo date('h:i:s') . "\n";
</screen>
</example>
</para>
<simpara>
See also <function>usleep</function> and
<function>set_time_limit</function>
</simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<function>usleep</function>,
<function>set_time_limit</function>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

15
reference/misc/functions/sys-getloadavg.xml
View file

@ -1,11 +1,9 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sys-getloadavg">
<refnamediv>
<refname>sys_getloadavg</refname>
<refpurpose>
get average system load
</refpurpose>
<refpurpose>Gets system load average</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
@ -14,11 +12,10 @@
<void/>
</methodsynopsis>
<para>
This function returns three samples representing the average system load
Returns three samples representing the average system load
(the number of processes in the system run queue) over the last 1, 5 and 15
minutes, respectively.
</para>
&note.no-windows;
</refsect1>
<refsect1 role="returnvalues">
@ -48,6 +45,12 @@ if ($load[0] > 80) {
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
&note.no-windows;
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

58
reference/misc/functions/time-nanosleep.xml
View file

@ -1,11 +1,12 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<refentry id="function.time-nanosleep">
<refnamediv>
<refname>time_nanosleep</refname>
<refpurpose>Delay for a number of seconds and nanoseconds</refpurpose>
</refnamediv>
<refsect1>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>time_nanosleep</methodname>
@ -16,13 +17,33 @@
Delays program execution for the given number of
<parameter>seconds</parameter> and <parameter>nanoseconds</parameter>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<parameter>seconds</parameter> must be a positive integer, and
<parameter>nanoseconds</parameter> must be a positive integer less than
1 billion.
<variablelist>
<varlistentry>
<term><parameter>seconds</parameter></term>
<listitem>
<para>
Must be a positive integer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>nanoseconds</parameter></term>
<listitem>
<para>
Must be a positive integer less than 1 billion.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
@ -46,15 +67,8 @@
</itemizedlist>
</para>
</refsect1>
<refsect1>
&reftitle.seealso;
<para>
<function>sleep</function>,
<function>usleep</function>,
<function>set_time_limit</function>
</para>
</refsect1>
<refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
@ -90,8 +104,22 @@ if ($nano === true) {
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
&note.no-windows;
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<function>sleep</function>,
<function>usleep</function>,
<function>set_time_limit</function>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

34
reference/misc/functions/time-sleep-until.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<refentry id="function.time-sleep-until">
<refnamediv>
<refname>time_sleep_until</refname>
@ -7,6 +7,7 @@
Make the script sleep until the specified time
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
@ -14,13 +15,9 @@
<methodparam><type>float</type><parameter>timestamp</parameter></methodparam>
</methodsynopsis>
<para>
This function will make the script sleep until the specified
<parameter>timestamp</parameter>. If the specified
<parameter>timestamp</parameter> is in the past,
<function>time_sleep_until</function> will generate a
<constant>E_WARNING</constant> and return &false;.
Makes the script sleep until the specified
<parameter>timestamp</parameter>.
</para>
&note.no-windows;
</refsect1>
<refsect1 role="parameters">
@ -37,11 +34,6 @@
</varlistentry>
</variablelist>
</para>
<note>
<simpara>
All signals will be delivered after the script wakes up.
</simpara>
</note>
</refsect1>
<refsect1 role="returnvalues">
@ -51,6 +43,14 @@
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
If the specified <parameter>timestamp</parameter> is in the past, this
function will generate a <constant>E_WARNING</constant>.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
@ -73,6 +73,16 @@ var_dump(time_sleep_until(time()+0.2));
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<simpara>
All signals will be delivered after the script wakes up.
</simpara>
</note>
&note.no-windows;
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>

124
reference/misc/functions/uniqid.xml
View file

@ -1,50 +1,76 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.2 -->
<!-- $Revision: 1.11 $ -->
<refentry id="function.uniqid">
<refnamediv>
<refname>uniqid</refname>
<refpurpose>Generate a unique ID</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>uniqid</methodname>
<methodparam choice="opt"><type>string</type><parameter>prefix</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>more_entropy</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>uniqid</function> returns a prefixed unique identifier
based on the current time in microseconds. <parameter>prefix</parameter>
became optional in PHP 5 but can be useful, for instance, if you generate identifiers
simultaneously on several hosts that might happen to generate the
identifier at the same microsecond. Up until PHP 4.3.1,
<parameter>prefix</parameter> could only be a maximum of 114
characters long.
</simpara>
<simpara>
If the optional <parameter>more_entropy</parameter> parameter is
&true;, <function>uniqid</function> will add additional entropy (using
the combined linear congruential generator) at the end of the return
value, which should make the results more unique.
</simpara>
<simpara>
With an empty <parameter>prefix</parameter>, the returned string
will be 13 characters long. If <parameter>more_entropy</parameter> is
&true;, it will be 23 characters.
</simpara>
<note>
<simpara>
The <parameter>prefix</parameter> parameter is required before PHP 5.
</simpara>
</note>
<para>
Gets a prefixed unique identifier based on the current time in
microseconds.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>prefix</parameter></term>
<listitem>
<para>
Can be useful, for instance, if you generate identifiers
simultaneously on several hosts that might happen to generate the
identifier at the same microsecond.
</para>
<para>
With an empty <parameter>prefix</parameter>, the returned string will
be 13 characters long. If <parameter>more_entropy</parameter> is
&true;, it will be 23 characters.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>more_entropy</parameter></term>
<listitem>
<para>
If set to &true;, <function>uniqid</function> will add additional
entropy (using the combined linear congruential generator) at the end
of the return value, which should make the results more unique.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the unique identifier, as a string.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
If you need a unique identifier or token and you intend to give
out that token to the user via the network (i.e. session cookies),
it is recommended that you use something along these lines:
</para>
<para>
<informalexample>
This will create a 32 character identifier (a 128 bit hex number)
that is extremely difficult to predict.
<example>
<title><function>uniqid</function> Example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -57,13 +83,41 @@ $better_token = md5(uniqid(rand(), true));
?>
]]>
</programlisting>
</informalexample>
</example>
</para>
<simpara>
This will create a 32 character identifier (a 128 bit hex number)
that is extremely difficult to predict.
</simpara>
</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>prefix</parameter> parameter was made optional.
</entry>
</row>
<row>
<entry>4.3.1</entry>
<entry>
The limit of 114 characters long for <parameter>prefix</parameter>
was raised.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

65
reference/misc/functions/unpack.xml
View file

@ -1,28 +1,65 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.22 -->
<!-- $Revision: 1.6 $ -->
<refentry id="function.unpack">
<refnamediv>
<refname>unpack</refname>
<refpurpose>Unpack data from binary string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>unpack</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
</methodsynopsis>
<para>
<function>unpack</function> from binary string into array
according to <parameter>format</parameter>. Returns array
containing unpacked elements of binary string.
Unpacks from a binary string into an array according to the given
<parameter>format</parameter>.
</para>
<para>
<function>unpack</function> works slightly different from Perl as
the unpacked data is stored in an associative array. To
accomplish this you have to name the different format codes and
separate them by a slash /.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
See <function>pack</function> for an explanation of the format codes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
The packed data.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an associative array containing unpacked elements of binary
string.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>unpack</function> example</title>
<programlisting role="php">
@ -38,6 +75,10 @@ $array = unpack("c2chars/nint", $binarydata);
</para>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<caution>
<para>
Note that PHP internally stores integral values as signed. If you
@ -46,11 +87,17 @@ $array = unpack("c2chars/nint", $binarydata);
even though unsigned unpacking was specified.
</para>
</caution>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>pack</function> for an explanation of the format
codes.
<simplelist>
<member><function>pack</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

92
reference/misc/functions/usleep.xml
View file

@ -1,22 +1,72 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- splitted from ./en/functions/misc.xml, last change in rev 1.14 -->
<!-- $Revision: 1.10 $ -->
<refentry id="function.usleep">
<refnamediv>
<refname>usleep</refname>
<refpurpose>Delay execution in microseconds</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>usleep</methodname>
<methodparam><type>int</type><parameter>micro_seconds</parameter></methodparam>
</methodsynopsis>
<simpara>
The <function>usleep</function> function delays program execution
for the given number of <parameter>micro_seconds</parameter>. A
microsecond is one millionth of a second.
</simpara>
<para>
Delays program execution for the given number of micro seconds.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>micro_seconds</parameter></term>
<listitem>
<para>
Halt time in micro seconds. A micro second is one millionth of a
second.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.void;
</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>
This function now works on Windows systems.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>usleep</function> example</title>
@ -36,9 +86,7 @@ echo date('h:i:s') . "\n";
?>
]]>
</programlisting>
<para>
This script will output :
</para>
&example.outputs;
<screen>
<![CDATA[
11:13:28
@ -47,16 +95,18 @@ echo date('h:i:s') . "\n";
</screen>
</example>
</para>
<note>
<simpara>
This function did not work on Windows systems until PHP 5.0.0
</simpara>
</note>
<simpara>
See also <function>sleep</function> and
<function>set_time_limit</function>.
</simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>sleep</function></member>
<member><function>set_time_limit</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file