cvs: phpdoc /en/reference/misc/functions connection-aborted.xml connection-status.xml connection-timeout.xml constant.xml define.xml defined.xml
die.xml eval.xml exit.xml get-browser.xml halt-compiler.xml highlight-file.xml highlight-string.xml ignore-user-abort.xml pack.xml
php-check-syntax.xml php-strip-whitespace.xml show-source.xml sleep.xml sys-getloadavg.xml time-nanosleep.xml time-sleep-until.xml uniqid.xml
unpack.xml usleep.xml

From:	Mehdi Achour	Date:	Mon, 19 Feb 2007 00:03:13 +0000
Subject:	cvs: phpdoc /en/reference/misc/functions connection-aborted.xml connection-status.xml connection-timeout.xml constant.xml define.xml defined.xml die.xml eval.xml exit.xml get-browser.xml halt-compiler.xml highlight-file.xml highlight-string.xml ignore-user-abort.xml pack.xml php-check-syntax.xml php-strip-whitespace.xml show-source.xml sleep.xml sys-getloadavg.xml time-nanosleep.xml time-sleep-until.xml uniqid.xml unpack.xml usleep.xml
Groups:	php.doc
Request:	Send a blank email to phpdoc+get-969375516@lists.php.net to get a copy of this message

didou Mon Feb 19 00:03:13 2007 UTC Modified files: /phpdoc/en/reference/misc/functions connection-aborted.xml connection-status.xml connection-timeout.xml constant.xml define.xml defined.xml die.xml eval.xml exit.xml get-browser.xml halt-compiler.xml highlight-file.xml highlight-string.xml ignore-user-abort.xml pack.xml php-check-syntax.xml php-strip-whitespace.xml show-source.xml sleep.xml sys-getloadavg.xml time-nanosleep.xml time-sleep-until.xml uniqid.xml unpack.xml usleep.xml Log: ref.misc: switch to new docstyle

http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/misc/functions/connection-aborted.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/misc/functions/connection-aborted.xml diff -u phpdoc/en/reference/misc/functions/connection-aborted.xml:1.5 phpdoc/en/reference/misc/functions/connection-aborted.xml:1.6 --- phpdoc/en/reference/misc/functions/connection-aborted.xml:1.5 Mon Feb 19 00:02:49 2007 +++ phpdoc/en/reference/misc/functions/connection-aborted.xml Mon Feb 19 00:03:13 2007 @@ -1,28 +1,43 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <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>  - + <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>  - + <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>  - + <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 @@ </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>  - + <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 @@ </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>  - + <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 @@ </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>  - + <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>  - + <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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/misc/functions/exit.xml?r1=1.12&r2=1.13&diff_format=u Index: phpdoc/en/reference/misc/functions/exit.xml diff -u phpdoc/en/reference/misc/functions/exit.xml:1.12 phpdoc/en/reference/misc/functions/exit.xml:1.13 --- phpdoc/en/reference/misc/functions/exit.xml:1.12 Mon Feb 19 00:02:49 2007 +++ phpdoc/en/reference/misc/functions/exit.xml Mon Feb 19 00:03:13 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <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 >= 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 >= 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 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> - <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>. - </simpara> + </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>  - + <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> + <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> + </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> - 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. - </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> + <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 @@ </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 @@ </para> </note> </refsect1> + </refentry>  + <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 @@ </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>  - + <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>  - + <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 @@ </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>  - + <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>  +  <refentry id="function.pack"> <refnamediv> @@ -16,59 +16,160 @@ </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 - </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> + 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> + 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> <programlisting role="php"> @@ -84,23 +185,17 @@ </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>  + <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>  - </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 @@ </screen> </para> </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <para> @@ -129,6 +140,7 @@ </simplelist> </para> </refsect1> + </refentry>  + <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 @@ </example> </para> </refsect1> + </refentry>  - + <refentry id="function.show-source"> <refnamediv> <refname>show_source</refname> @@ -14,6 +13,7 @@ <function>highlight_file</function>. </simpara> </refsect1> + </refentry>  - + <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 @@ </screen> </example> </para> - <simpara> - See also <function>usleep</function> and + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <function>usleep</function>, <function>set_time_limit</function> - </simpara> + </para> </refsect1> + </refentry>  + <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 @@ </example> </para> </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + &note.no-windows; + </refsect1> + </refentry>  + <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 @@ </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>  + <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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/misc/functions/uniqid.xml?r1=1.10&r2=1.11&diff_format=u Index: phpdoc/en/reference/misc/functions/uniqid.xml diff -u phpdoc/en/reference/misc/functions/uniqid.xml:1.10 phpdoc/en/reference/misc/functions/uniqid.xml:1.11 --- phpdoc/en/reference/misc/functions/uniqid.xml:1.10 Mon Feb 19 00:02:49 2007 +++ phpdoc/en/reference/misc/functions/uniqid.xml Mon Feb 19 00:03:13 2007 @@ -1,50 +1,76 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <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 @@ ?> ]]> </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>  - + <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 @@ </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 @@ 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>  - + <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 @@ ?> ]]> </programlisting> - <para> - This script will output : - </para> + &example.outputs; <screen> <![CDATA[ 11:13:28 @@ -47,16 +95,18 @@ </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