php-doc-en/functions/misc.xml

 <reference id="ref.misc">
  <title>Miscellaneous functions</title>
  <titleabbrev>Misc.</titleabbrev>

  <partintro>
   <para>
    These functions were placed here because none of the other
    categories seemed to fit.
   </para>
  </partintro>

  <refentry id="function.create-function">
   <refnamediv>
    <refname>create_function</refname>
    <refpurpose>Create an anonymous (lambda-style) function</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>create_function</function></funcdef>
      <paramdef>string <parameter>args</parameter></paramdef>
      <paramdef>string <parameter>code</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Creates an anonymous function from the parameters passed, and
     returns a unique name for it. Usually the
     <parameter>args</parameter> will be passed as a single quote
     delimited string, and this is also recommended for the
     <parameter>code</parameter>. The reason for using single quoted
     strings, is to protect
     the variable names from parsing, otherwise, if you use double
     quotes there will be a need to escape the variable names, e.g. 
     <literal>\$avar</literal>.
    </para>
    <para>
     You can use this function, to (for example) create a function
     from information gathered at run time:
     <example>
      <title>
       Creating an anonymous function with <function>create_function</function>
      </title>
      <programlisting role="php">
$newfunc = create_function('$a,$b','return "ln($a) + ln($b) = ".log($a * $b);');
echo "New anonymous function: $newfunc\n";
echo $newfunc(2,M_E)."\n";
// outputs
// New anonymous function: lambda_1
// ln(2) + ln(2.718281828459) = 1.6931471805599
      </programlisting>
     </example>
     Or, perhaps to have general handler function that can apply a set
     of operations to a list of parameters:
     <example>
      <title>
       Making a general processing function with
       <function>create_function</function>
      </title>
      <programlisting role="php">
function process($var1, $var2, $farr) {
    for ($f=0; $f &lt; count($farr); $f++)
    echo $farr[$f]($var1,$var2)."\n";
}

// create a bunch of math functions
$f1 = 'if ($a &gt;=0) {return "b*a^2 = ".$b*sqrt($a);} else {return false;}';
$f2 = "return \"min(b^2+a, a^2,b) = \".min(\$a*\$a+\$b,\$b*\$b+\$a);";
$f3 = 'if ($a &gt; 0 &amp;&amp; $b != 0) {return "ln(a)/b = ".log($a)/$b;} else {return false;}';
$farr = array(
    create_function('$x,$y', 'return "some trig: ".(sin($x) + $x*cos($y));'),
    create_function('$x,$y', 'return "a hypotenuse: ".sqrt($x*$x + $y*$y);'),
    create_function('$a,$b', $f1),
    create_function('$a,$b', $f2),
    create_function('$a,$b', $f3)
    );

echo "\nUsing the first array of anonymous functions\n";
echo "parameters: 2.3445, M_PI\n";
process(2.3445, M_PI, $farr);

// now make a bunch of string processing functions
$garr = array(
    create_function('$b,$a','if (strncmp($a,$b,3) == 0) return "** \"$a\" '.
    'and \"$b\"\n** Look the same to me! (looking at the first 3 chars)";'),
    create_function('$a,$b','; return "CRCs: ".crc32($a)." , ".crc32(b);'),
    create_function('$a,$b','; return "similar(a,b) = ".similar_text($a,$b,&$p)."($p%)";')
    );
echo "\nUsing the second array of anonymous functions\n";
process("Twas brilling and the slithy toves", "Twas the night", $garr);
      </programlisting>
     </example>
     and when you run the code above, the output will be:
     <informalexample>
      <programlisting>
Using the first array of anonymous functions
parameters: 2.3445, M_PI
some trig: -1.6291725057799
a hypotenuse: 3.9199852871011
b*a^2 = 4.8103313314525
min(b^2+a, a^2,b) = 8.6382729035898
ln(a/b) = 0.27122299212594

Using the second array of anonymous functions
** "Twas the night" and "Twas brilling and the slithy toves"
** Look the same to me! (looking at the first 3 chars)
CRCs: -725381282 , 1908338681
similar(a,b) = 11(45.833333333333%)
      </programlisting>
     </informalexample>
    But perhaps the most common use for of lambda-style (anonymous) functions
    is to create callback functions, for example when using
    <function>array_walk</function> or <function>usort</function>
    <example>
     <title>Using anonymous functions as callback functions</title>
     <programlisting role="php">
$av = array("the ","a ","that ","this ");
array_walk($av, create_function('&$v,$k','$v = $v."mango";'));
print_r($av);  // for PHP3 use var_dump()
// outputs:
// Array
// (
//   [0] =&gt; the mango
//   [1] =&gt; a mango
//   [2] =&gt; that mango
//   [3] =&gt; this mango
// )

// an array of strings ordered from shorter to longer
$sv = array("small","larger","a big string","it is a string thing");
print_r($sv);
// outputs:
// Array
// (
//   [0] =&gt; small
//   [1] =&gt; larger
//   [2] =&gt; a big string
//   [3] =&gt; it is a string thing
// )

// sort it from longer to shorter
usort($sv, create_function('$a,$b','return strlen($b) - strlen($a);'));
print_r($sv);
// outputs:
// Array
// (
//   [0] =&gt; it is a string thing
//   [1] =&gt; a big string
//   [2] =&gt; larger
//   [3] =&gt; small
// )
     </programlisting>
    </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.connection-aborted">
   <refnamediv>
    <refname>connection_aborted</refname>
    <refpurpose>Returns true if client disconnected</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>connection_aborted</function></funcdef>
      <paramdef>void <parameter></parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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>
   </refsect1>
  </refentry>

  <refentry id="function.connection-status">
   <refnamediv>
    <refname>connection_status</refname>
    <refpurpose>Returns connection status bitfield</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>connection_status</function></funcdef>
      <paramdef>void <parameter></parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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>
   </refsect1>
  </refentry>

  <refentry id="function.connection-timeout">
   <refnamediv>
    <refname>connection_timeout</refname>
    <refpurpose>Return true if script timed out</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>connection_timeout</function></funcdef>
      <paramdef>void <parameter></parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     Returns true if script timed out.    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>
  </refentry>

  <refentry id="function.define">
   <refnamediv>
    <refname>define</refname>
    <refpurpose>Defines a named constant.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>define</function></funcdef>
      <paramdef>string <parameter>name</parameter></paramdef>
      <paramdef>mixed <parameter>value</parameter></paramdef>
      <paramdef>int 
       <parameter><optional>case_insensitive</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Defines a named constant, which is similar to a variable except:
     <itemizedlist>
      <listitem>
       <simpara>
    Constants do not have a dollar sign '$' before them;
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    Constants may be accessed anywhere without regard to variable
    scoping rules;
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    Constants may not be redefined or undefined once they have
    been set; and
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    Constants may only evaluate to scalar values.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     The name of the constant is given by <parameter>name</parameter>;
     the value is given by <parameter>value</parameter>.
    </para>
    <para>
     The optional third parameter
     <parameter>case_insensitive</parameter> is also available. If the
     value <emphasis>1</emphasis> is given, then the constant will be
     defined case-insensitive. The default behaviour is
     case-sensitive; i.e. CONSTANT and Constant represent different
     values.
    </para>
    <para>
     <example>
      <title>Defining Constants</title>
      <programlisting role="php">
&lt;?php
define ("CONSTANT", "Hello world.");
echo CONSTANT; // outputs "Hello world."
?&gt;
      </programlisting>
     </example>
    </para>
    <para>
     <function>Define</function> returns TRUE on success and FALSE if
     an error occurs.
    </para>
    <para>
     See also <function>defined</function> and the section on <link
     linkend="language.constants">Constants</link>.
    </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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>defined</function></funcdef>
      <paramdef>string <parameter>name</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Returns true if the named constant given by
     <parameter>name</parameter> has been defined, false otherwise.
    </para>
    <para>
     See also <function>define</function> and the section on <link
     linkend="language.constants">Constants</link>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.die">
   <refnamediv>
    <refname>die</refname>
    <refpurpose>
     Output a message and terminate the current script
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>die</function></funcdef>
      <paramdef>string <parameter>message</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     This language construct outputs a message and terminates parsing
     of the script.  It does not return anything.
    </simpara>
    <para>
     <example>
      <title>die example</title>
      <programlisting role="php">
&lt;?php
$filename = '/path/to/data-file';
$file = fopen ($filename, 'r')
    or die("unable to open file ($filename)");
?&gt;
      </programlisting>
     </example>
    </para>
    <simpara>
     See also <function>exit</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.eval">
   <refnamediv>
    <refname>eval</refname>
    <refpurpose>Evaluate a string as PHP code</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>mixed <function>eval</function></funcdef>
      <paramdef>string <parameter>code_str</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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.
    </simpara>
    <simpara>
     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>.
    </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 immediatley. In PHP4 you may use <literal>return</literal>
     to return a value that will become the result of the 
     <function>eval</function> function while in PHP3 
     <function>eval</function> was of type <literal>void</literal> and did 
     never return anything.
    </simpara>
    <para>
     <example>
      <title>
       <function>Eval</function> example - simple text merge
      </title>
      <programlisting role="php">
&lt;?php
$string = 'cup';
$name = 'coffee';
$str = 'This is a $string with my $name in it.&lt;br&gt;';
echo $str;
eval ("\$str = \"$str\";");
echo $str;
?&gt;
      </programlisting>
     </example>
    </para>
    <para>
     The above example will show:
     <programlisting>
This is a $string with my $name in it.
This is a cup with my coffee in it.
     </programlisting>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.exit">
   <refnamediv>
    <refname>exit</refname>
    <refpurpose>Terminate current script</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>exit</function></funcdef>
      <void/>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     This language construct terminates parsing of the script.    It
     does not return.
    </simpara>
    <simpara>
     See also <function>die</function>.
    </simpara>
   </refsect1>
  </refentry> 

  <refentry id="function.func-get-arg">
   <refnamediv>
    <refname>func_get_arg</refname>
    <refpurpose>Return an item from the argument list</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>mixed <function>func_get_arg</function></funcdef>
      <paramdef>int <parameter>arg_num</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     Returns the argument which is at the
     <parameter>arg_num</parameter>'th offset into a user-defined
     function's argument list. Function arguments are counted starting
     from zero. <function>Func_get_arg</function> will generate a
     warning if called from outside of a function definition.
    </simpara>
    <simpara>
     If <parameter>arg_num</parameter> is greater than the number of
     arguments actually passed, a warning will be generated and
     <function>func_get_arg</function> will return FALSE.
    </simpara>
    <para>
     <informalexample>
      <programlisting role="php">
&lt;?php
function foo() {
     $numargs = func_num_args();
     echo "Number of arguments: $numargs&lt;br&gt;\n";
     if ($numargs &gt;= 2) {
     echo "Second argument is: " . func_get_arg (1) . "&lt;br&gt;\n";
     }
} 

foo (1, 2, 3);
?&gt;
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     <function>Func_get_arg</function> may be used in conjunction with
     <function>func_num_args</function> and
     <function>func_get_args</function> to allow user-defined
     functions to accept variable-length argument lists.
    </simpara>
    <note>
     <simpara>
      This function was added in PHP 4.
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.func-get-args">
   <refnamediv>
    <refname>func_get_args</refname>
    <refpurpose>
     Returns an array comprising a function's argument list
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>array <function>func_get_args</function></funcdef>
      <paramdef>void <parameter></parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     Returns an array in which each element is the corresponding
     member of the current user-defined function's argument
     list. <function>Func_get_args</function> will generate a warning
     if called from outside of a function definition.
    </simpara>
    <para>
     <informalexample>
      <programlisting role="php">
&lt;?php
function foo() {
    $numargs = func_num_args();
    echo "Number of arguments: $numargs&lt;br&gt;\n";
    if ($numargs &gt;= 2) {
    echo "Second argument is: " . func_get_arg (1) . "&lt;br&gt;\n";
    }
    $arg_list = func_get_args();
    for ($i = 0; $i &lt; $numargs; $i++) {
    echo "Argument $i is: " . $arg_list[$i] . "&lt;br&gt;\n";
    }
} 

foo (1, 2, 3);
?&gt;
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     <function>Func_get_args</function> may be used in conjunction
     with <function>func_num_args</function> and
     <function>func_get_arg</function> to allow user-defined functions
     to accept variable-length argument lists.
    </simpara>
    <note>
     <simpara>
      This function was added in PHP 4.
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.func-num-args">
   <refnamediv>
    <refname>func_num_args</refname>
    <refpurpose>
     Returns the number of arguments passed to the function
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>func_num_args</function></funcdef>
      <paramdef>void <parameter></parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     Returns the number of arguments passed into the current
     user-defined function. <function>Func_num_args</function> will
     generate a warning if called from outside of a function
     definition.
    </simpara>
    <para>
     <informalexample>
      <programlisting role="php">
&lt;?php
function foo() {
    $numargs = func_num_args();
    echo "Number of arguments: $numargs\n";
} 

foo (1, 2, 3);    // Prints 'Number of arguments: 3'
?&gt;
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     <function>Func_num_args</function> may be used in conjunction
     with <function>func_get_arg</function> and
     <function>func_get_args</function> to allow user-defined
     functions to accept variable-length argument lists.
    </simpara>
    <note>
     <simpara>
      This function was added in PHP 4.
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.function-exists">
   <refnamediv>
    <refname>function_exists</refname>
    <refpurpose>
     Return true if the given function has been defined
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>function_exists</function></funcdef>
      <paramdef>string <parameter>function_name</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     Checks the list of defined functions for
     <parameter>function_name</parameter>.    Returns true if the given
     function name was found, false otherwise.
    </simpara>
   </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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>object <function>get_browser</function></funcdef>
      <paramdef>string 
       <parameter><optional>user_agent</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     <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> file. By default, the value of
     $HTTP_USER_AGENT 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>.
    </simpara>
    <simpara>
     The information is returned in an object, 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>
     While <filename>browscap.ini</filename> contains information on
     many browsers, it relies on user updates to keep the database
     current. The format of the file is fairly self-explanatory.
    </simpara>
    <para>
     The following example shows how one might list all available
     information retrieved about the user's browser.
     <example>
      <title><function>Get_browser</function> example</title>
      <programlisting role="php">
&lt;?php
function list_array ($array) {
    while (list ($key, $value) = each ($array)) {
    $str .= "&lt;b&gt;$key:&lt;/b&gt; $value&lt;br&gt;\n";
    }
    return $str;
}
echo "$HTTP_USER_AGENT&lt;hr&gt;\n";
$browser = get_browser();
echo list_array ((array) $browser);
?&gt;
      </programlisting>
     </example>
    </para>
    <simpara>
     The output of the above script would look something like this:
    </simpara>
    <programlisting>
Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)&lt;hr&gt;
&lt;b&gt;browser_name_pattern:&lt;/b&gt; Mozilla/4\.5.*&lt;br&gt;
&lt;b&gt;parent:&lt;/b&gt; Netscape 4.0&lt;br&gt;
&lt;b&gt;platform:&lt;/b&gt; Unknown&lt;br&gt;
&lt;b&gt;majorver:&lt;/b&gt; 4&lt;br&gt;
&lt;b&gt;minorver:&lt;/b&gt; 5&lt;br&gt;
&lt;b&gt;browser:&lt;/b&gt; Netscape&lt;br&gt;
&lt;b&gt;version:&lt;/b&gt; 4&lt;br&gt;
&lt;b&gt;frames:&lt;/b&gt; 1&lt;br&gt;
&lt;b&gt;tables:&lt;/b&gt; 1&lt;br&gt;
&lt;b&gt;cookies:&lt;/b&gt; 1&lt;br&gt;
&lt;b&gt;backgroundsounds:&lt;/b&gt; &lt;br&gt;
&lt;b&gt;vbscript:&lt;/b&gt; &lt;br&gt;
&lt;b&gt;javascript:&lt;/b&gt; 1&lt;br&gt;
&lt;b&gt;javaapplets:&lt;/b&gt; 1&lt;br&gt;
&lt;b&gt;activexcontrols:&lt;/b&gt; &lt;br&gt;
&lt;b&gt;beta:&lt;/b&gt; &lt;br&gt;
&lt;b&gt;crawler:&lt;/b&gt; &lt;br&gt;
&lt;b&gt;authenticodeupdate:&lt;/b&gt; &lt;br&gt;
&lt;b&gt;msn:&lt;/b&gt; &lt;br&gt;
    </programlisting>
    <simpara>
     In order for this to work, your <link
     linkend="ini.sect.browscap">browscap</link> configuration file
     setting must point to the correct location of the
     <filename>browscap.ini</filename> file.
    </simpara>
    <simpara>
     For more information (including locations from which you may
     obtain a <filename>browscap.ini</filename> file), check the PHP
     FAQ at <ulink
     url="&url.php.faq;">&url.php.faq;</ulink>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.highlight-file">
   <refnamediv>
    <refname>highlight_file</refname>
    <refpurpose>Syntax highlighting of a file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>highlight_file</function></funcdef>
      <paramdef>string <parameter>filename</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     The <function>highlight_file</function> function prints out a syntax
     higlighted version of the code contained in <parameter>filename</parameter> 
     using the colors defined in the built-in syntax highlighter for PHP.
    </simpara>
   <para>
     <example>
      <title>Creating a source highlighting URL</title>
      <simpara>
       To setup a URL that can code hightlight any script that you pass to
       it, we will make use of the &quot;ForceType&quot; directive in
       Apache to generate a nice URL pattern, and use the 
       function <function>highlight_file</function> to show a nice looking
       code list.
      </simpara>
      <simpara>
       In your httpd.conf you can add the following:
      </simpara>
      <para>
       <informalexample><programlisting>
&lt;Location /source&gt;
    ForceType application/x-httpd-php
&lt;/Location&gt;
       </programlisting></informalexample>
      </para>
      <simpara>
       And then make a file named &quot;source&quot; and put it in your
       web root directory.
      </simpara>
      <para>
       <programlisting role="php">
&lt;HTML&gt;
&lt;HEAD&gt;
&lt;TITLE&gt;Source Display&lt;/TITLE&gt;
&lt;/HEAD&gt;
&lt;BODY BGCOLOR=&quot;white&quot;&gt;
&lt;?php
    $script = getenv (&quot;PATH_TRANSLATED&quot;);
    if(!$script) {
    echo &quot;&lt;BR&gt;&lt;B&gt;ERROR: Script Name needed&lt;/B&gt;&lt;BR&gt;&quot;;
    } else {
    if (ereg(&quot;(\.php|\.inc)$&quot;,$script)) {
    echo &quot;&lt;H1&gt;Source of: $PATH_INFO&lt;/H1&gt;\n&lt;HR&gt;\n&quot;;
    highlight_file($script);
    } else {
    echo &quot;&lt;H1&gt;ERROR: Only PHP or include script names are allowed&lt;/H1&gt;&quot;; 
    }
    }
    echo &quot;&lt;HR&gt;Processed: &quot;.date(&quot;Y/M/d H:i:s&quot;,time());
?&gt;
&lt;/BODY&gt;
&lt;/HTML&gt;
       </programlisting>
      </para>
      <simpara>
       Then you can use an URL like the one below to display a colorized
       version of a script located in &quot;/path/to/script.php&quot; 
       in your web site.
      </simpara>
      <para>
       <informalexample>
    <programlisting>
http://your.server.com/source/path/to/script.php
    </programlisting>
       </informalexample>
      </para>
     </example>
    </para>
    <simpara>
     See also <function>highlight_string</function>,
     <function>show_source</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.highlight-string">
   <refnamediv>
    <refname>highlight_string</refname>
    <refpurpose>Syntax highlighting of a string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>highlight_string</function></funcdef>
      <paramdef>string <parameter>str</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     The <function>highlight_string</function> function prints out a syntax
     highlighted version of <parameter>str</parameter> using the colors defined 
     in the built-in syntax highlighter for PHP.
    </simpara>
    <simpara>
     See also <function>highlight_file</function>,
     <function>show_source</function>.
    </simpara>
   </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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>ignore_user_abort</function></funcdef>
      <paramdef>int 
       <parameter><optional>setting</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <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>
   </refsect1>
  </refentry> 
    
  <refentry id="function.iptcparse">
   <refnamediv>
    <refname>iptcparse</refname>
    <refpurpose>
     Parse a binary IPTC <ulink url="&url.iptc;">&url.iptc;</ulink>
     block into single tags.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>array <function>iptcparse</function></funcdef>
      <paramdef>string <parameter>iptcblock</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     This function parses a binary IPTC block into its single tags. It
     returns an array using the tagmarker as an index and the value as
     the value. It returns false on error or if no IPTC data was
     found.  See <function>GetImageSize</function> for a sample.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.leak">
   <refnamediv>
    <refname>leak</refname>
    <refpurpose>Leak memory</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>leak</function></funcdef>
      <paramdef>int <parameter>bytes</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     <function>Leak</function> leaks the specified amount of memory.
    </simpara>
    <simpara>
     This is useful when debugging the memory manager, which
     automatically cleans up "leaked" memory when each request is
     completed.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.pack">
   <refnamediv>
    <refname>pack</refname>
    <refpurpose>Pack data into binary string.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>pack</function></funcdef>
      <paramdef>string <parameter>format</parameter></paramdef>
      <paramdef>mixed 
       <parameter><optional>args</optional></parameter> ...
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Pack given arguments into binary string according to
     <parameter>format</parameter>. Returns binary string containing
     data.
    </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
     <itemizedlist>
      <listitem>
       <simpara>
    a NUL-padded string
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    A SPACE-padded string
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    h Hex string, low nibble first
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    H Hex string, high nibble first
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    c signed char
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    C unsigned char
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    s signed short (always 16 bit, machine byte order)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    S unsigned short (always 16 bit, machine byte order)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    n unsigned short (always 16 bit, big endian byte order)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    v unsigned short (always 16 bit, little endian byte order)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    i signed integer (machine dependent size and byte order)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    I unsigned integer (machine dependent size and byte order)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    l signed long (always 32 bit, machine byte order)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    L unsigned long (always 32 bit, machine byte order)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    N unsigned long (always 32 bit, big endian byte order)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    V unsigned long (always 32 bit, little endian byte order)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    f float (machine dependent size and representation)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    d double (machine dependent size and representation)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    x NUL byte
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    X Back up one byte
       </simpara>
      </listitem>
      <listitem>
       <simpara>
    @ NUL-fill to absolute position
       </simpara>
      </listitem>
     </itemizedlist>
     <example>
      <title><function>Pack</function> format string</title>
      <programlisting role="php">
$binarydata = pack ("nvc*", 0x1234, 0x5678, 65, 66);
      </programlisting>
      <para>
       The resulting binary string will be 6 bytes long and contain
       the byte sequence 0x12, 0x34, 0x78, 0x56, 0x41, 0x42.
      </para>
     </example>
    </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 integral values as signed
     values of a machine dependent size. If you give it an unsigned
     integral value too large to be stored that way it is converted to
     a double which often yields an undesired result.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.register-shutdown-function">
   <refnamediv>
    <refname>register_shutdown_function</refname>
    <refpurpose>
     Register a function for execution on shutdown
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int 
       <function>register_shutdown_function</function>
      </funcdef>
      <paramdef>string <parameter>func</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     Registers the function named by <parameter>func</parameter> to be
     executed when script processing is complete.</simpara>
    <para>
     Common Pitfalls:
    </para>
    <simpara>
     Since no output is allowed to the browser in this function, you
     will be unable to debug it using statements such as print or
     echo.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.restore-error-handler">
   <refnamediv>
    <refname>restore_error_handler</refname>
    <refpurpose>
     Restores the previous error handler function
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>restore_error_handler</function></funcdef>
      <paramdef>void</paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Used after changing the error handler function using
     <function>set_error_handler</function>, to revert to the previous error
     handler (which could be the built-in or a user defined function)
    </para>
    <para>
     See also <function>error_reporting</function>,
     <function>set_error_handler</function>,
     <function>trigger_error</function>, <function>user_error</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.serialize">
   <refnamediv>
    <refname>serialize</refname>
    <refpurpose>
     Generates a storable representation of a value
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>serialize</function></funcdef>
      <paramdef>mixed <parameter>value</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     <function>Serialize</function> returns a string containing a
     byte-stream representation of <parameter>value</parameter> that
     can be stored anywhere.
    </simpara>
    <simpara>
     This is useful for storing or passing PHP values around without
     losing their type and structure.
    </simpara>
    <simpara>
     To make the serialized string into a PHP value again, use
     <function>unserialize</function>.    <function>Serialize</function>
     handles the types <type>integer</type>, <type>double</type>,
     <type>string</type>, <type>array</type> (multidimensional) and
     <type>object</type> (object properties will be serialized, but
     methods are lost).
    </simpara>
    <para>
     <example>
      <title><function>Serialize</function> example</title>
      <programlisting role="php">
// $session_data contains a multi-dimensional array with session
// information for the current user.  We use serialize() to store
// it in a database at the end of the request.

$conn = odbc_connect ("webdb", "php", "chicken");
$stmt = odbc_prepare ($conn,
      "UPDATE sessions SET data = ? WHERE id = ?");
$sqldata = array (serialize($session_data), $PHP_AUTH_USER);
if (!odbc_execute ($stmt, &amp;$sqldata)) {
    $stmt = odbc_prepare($conn,
     "INSERT INTO sessions (id, data) VALUES(?, ?)");
    if (!odbc_execute($stmt, &amp;$sqldata)) {
    /* Something went wrong.  Bitch, whine and moan. */
    }
}
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.set-error-handler">
   <refnamediv>
    <refname>set_error_handler</refname>
    <refpurpose>
     Sets a user-defined error handler function.  
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>set_error_handler</function></funcdef>
      <paramdef>string <parameter>error_handler</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Sets a user function (<parameter>error_handler</parameter>) to handle
     errors in a script.  Returns the previously defined error handler (if
     any), or false on error.  This function can be used for defining your own
     way of handling errors during runtime, for example in applications in
     which you need to do cleanup of data/files when a critical error happens,
     or when you need to trigger an error under certain conditions (using
     <function>trigger_error</function>)
    </para>
    <para>
     The user function needs to accept 2 parameters: the error code, and a
     string describing the error. The example below shows the handling of 
     internal execptions by triggering errors and handling them with a user
     defined function:
     <example>
      <title>
       Error handling with <function>set_error_handler</function> and
       <function>trigger_error</function>
      </title>
      <programlisting role="php">
&lt;?php

// redefine the user error constants - PHP4 only
define(FATAL,E_USER_ERROR);
define(ERROR,E_USER_WARNING);
define(WARNING,E_USER_NOTICE);

// set the error reporting level for this script
error_reporting(FATAL + ERROR + WARNING);

// error handler function
function myErrorHandler ($errno, $errstr) {
    switch ($errno) {
    case FATAL:
    echo &quot;&lt;b&gt;FATAL&lt;/b&gt; [$errno] $errstr&lt;br&gt;\n&quot;;
    echo &quot;  Fatal error in line &quot;.__LINE__.&quot; of file &quot;.__FILE__;
    echo &quot;, PHP &quot;.PHP_VERSION.&quot; (&quot;.PHP_OS.&quot;)&lt;br&gt;\n&quot;;
    echo &quot;Aborting...&lt;br&gt;\n&quot;;
    exit -1;
    break;
    case ERROR:
    echo &quot;&lt;b&gt;ERROR&lt;/b&gt; [$errno] $errstr&lt;br&gt;\n&quot;;
    break;
    case WARNING:
    echo &quot;&lt;b&gt;WARNING&lt;/b&gt; [$errno] $errstr&lt;br&gt;\n&quot;;
    break;
    default:
    echo &quot;Unkown error type: [$errno] $errstr&lt;br&gt;\n&quot;;
    break;
    }
}

// function to test the error handling
function scale_by_log ($vect, $scale) {
    if ( !is_numeric($scale) || $scale &lt;= 0 )
    trigger_error(&quot;log(x) for x &lt;= 0 is undefined, you used: scale = $scale&quot;, 
      FATAL);
    if (!is_array($vect)) {
    trigger_error(&quot;Incorrect input vector, array of values expected&quot;, ERROR);
    return null;
    }
    for ($i=0; $i&lt;count($vect); $i++) {
    if (!is_numeric($vect[$i]))
    trigger_error(&quot;Value at position $i is not a number, using 0 (zero)&quot;, 
      WARNING);
    $temp[$i] = log($scale) * $vect[$i];
    }
    return $temp;
}

// set to the use defined error handler
$old_error_handler = set_error_handler(&quot;myErrorHandler&quot;);

// trigger some errors, first define a mixed array with a non-numeric item
echo &quot;vector a\n&quot;;
$a = array(2,3,&quot;foo&quot;,5.5,43.3,21.11);
print_r($a);

// now generate second array, generating a warning
echo &quot;----\nvector b - a warning (b = log(PI) * a)\n&quot;;
$b = scale_by_log($a, M_PI);
print_r($b);

// this is trouble, we pass a string instead of an array
echo &quot;----\nvector c - an error\n&quot;;
$c = scale_by_log(&quot;not array&quot;,2.3);
var_dump($c);

// this is a critical error, log of zero or negative number is undefined
echo &quot;----\nvector d - fatal error\n&quot;;
$d = scale_by_log($a, -2.5);

?&gt;
      </programlisting>
     </example>
     And when you run this sample script, the output will be
     <informalexample>
      <programlisting>
vector a
Array
(
    [0] =&gt; 2
    [1] =&gt; 3
    [2] =&gt; foo
    [3] =&gt; 5.5
    [4] =&gt; 43.3
    [5] =&gt; 21.11
)
----
vector b - a warning (b = log(PI) * a)
&lt;b&gt;WARNING&lt;/b&gt; [1024] Value at position 2 is not a number, using 0 (zero)&lt;br&gt;
Array
(
    [0] =&gt; 2.2894597716988
    [1] =&gt; 3.4341896575482
    [2] =&gt; 0
    [3] =&gt; 6.2960143721717
    [4] =&gt; 49.566804057279
    [5] =&gt; 24.165247890281
)
----
vector c - an error
&lt;b&gt;ERROR&lt;/b&gt; [512] Incorrect input vector, array of values expected&lt;br&gt;
NULL
----
vector d - fatal error
&lt;b&gt;FATAL&lt;/b&gt; [256] log(x) for x &lt;= 0 is undefined, you used: scale = -2.5&lt;br&gt;
  Fatal error in line 16 of file trigger_error.php, PHP 4.0.1pl2 (Linux)&lt;br&gt;
Aborting...&lt;br&gt;
      </programlisting>
     </informalexample>
    </para>
    <para>
     See also <function>error_reporting</function>,
     <function>restore_error_handler</function>,
     <function>trigger_error</function>, <function>user_error</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.show-source">
   <refnamediv>
    <refname>show_source</refname>
    <refpurpose>Syntax highlighting of a file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>show_source</function></funcdef>
      <paramdef>string <parameter>filename</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     The <function>show_source</function> function prints out a syntax
     higlighted version of the code contained in <parameter>filename</parameter> 
     using the colors defined in the built-in syntax highlighter for PHP.
    </simpara>
    <note>
     <simpara>
      This function is an alias for the function
      <function>highlight_file</function>
     </simpara>
    </note>
    <simpara>
     See also <function>highlight_string</function>,
     <function>highlight_file</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.sleep">
   <refnamediv>
    <refname>sleep</refname>
    <refpurpose>Delay execution</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>sleep</function></funcdef>
      <paramdef>int <parameter>seconds</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     The sleep function delays program execution for the given number
     of <parameter>seconds</parameter>.
    </simpara>
    <simpara>
     See also <function>usleep</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.trigger-error">
   <refnamediv>
    <refname>trigger_error</refname>
    <refpurpose>
     Generates a user-level error/warning/notice message
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>trigger_error</function></funcdef>
      <paramdef>string <parameter>error_msg</parameter></paramdef>
      <paramdef>int
       <parameter><optional>error_type</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Used to trigger a user error condition, it can be used by in conjunction
     with the built-in error handler, or with a user defined function that has
     been set as the new error handler
     (<function>set_error_handler</function>). This function is useful when
     you need to generate a particular response to an exception at runtime.
     For example:
     <informalexample>
      <programlisting>
if (assert($divisor == 0))
   trigger_error("Cannot divide by zero", E_USER_ERROR);
      </programlisting>
     </informalexample>
     <note>
     <para>
     See <function>set_error_handler</function> for a more extensive example.
     </para>
     </note>
    </para>
    <para>
     See also <function>error_reporting</function>,
     <function>set_error_handler</function>,
     <function>restore_error_handler</function>, 
     <function>user_error</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.uniqid">
   <refnamediv>
    <refname>uniqid</refname>
    <refpurpose>Generate a unique id</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>uniqid</function></funcdef>
      <paramdef>string <parameter>prefix</parameter></paramdef>
      <paramdef>boolean 
       <parameter><optional>lcg</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     <function>Uniqid</function> returns a prefixed unique identifier
     based on the current time in microseconds. The prefix can be
     useful for instance if you generate identifiers simultaneously on
     several hosts that might happen to generate the identifier at the
     same microsecond.    <parameter>Prefix</parameter> can be up to 114
     characters long.
    </simpara>
    <simpara>
     If the optional <parameter>lcg</parameter> parameter is true,
     <function>uniqid</function> will add additional "combined LCG"
     entropy 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>lcg</parameter> is
     true, it will be 23 characters.
    </simpara>
    <note>
     <simpara>
      The <parameter>lcg</parameter> parameter is only available in
      PHP 4 and PHP 3.0.13 and later.
     </simpara>
    </note>
    <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 the lines of
     <informalexample>
      <programlisting role="php">
$token = md5 (uniqid ("")); // no random portion
$better_token = md5 (uniqid (rand())); // better, difficult to guess
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     This will create a 32 character identifier (a 128 bit hex number)
     that is extremely difficult to predict.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.unpack">
   <refnamediv>
    <refname>unpack</refname>
    <refpurpose>Unpack data from binary string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>array <function>unpack</function></funcdef>
      <paramdef>string <parameter>format</parameter></paramdef>
      <paramdef>string <parameter>data</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>Unpack</function> from binary string into array
     according to <parameter>format</parameter>. Returns array
     containing unpacked elements of binary string.
    </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 /.
     <example>
      <title><function>Unpack</function> format string</title>
      <programlisting role="php">
$array = unpack ("c2chars/nint", $binarydata);
      </programlisting>
      <para>
       The resulting array will contain the entries "chars1",
       "chars2" and "int".
      </para>
     </example>
    </para>
    <para>
     For an explanation of the format codes see also:
     <function>pack</function>
    </para>
    <para>
     Note that PHP internally stores integral values as signed. If you
     unpack a large unsigned long and it is of the same size as PHP
     internally stored values the result will be a negative number
     even though unsigned unpacking was specified.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.unserialize">
   <refnamediv>
    <refname>unserialize</refname>
    <refpurpose>
     Creates a PHP value from a stored representation
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>mixed <function>unserialize</function></funcdef>
      <paramdef>string <parameter>str</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     <function>unserialize</function> takes a single serialized
     variable (see <function>serialize</function>) and converts it
     back into a PHP value.  The converted value is returned, and can
     be an <type>integer</type>, <type>double</type>,
     <type>string</type>, <type>array</type> or <type>object</type>.
     If an object was serialized, its methods are not preserved in the
     returned value.
    </simpara>
    <para>
     <example>
      <title><function>Unserialize</function> example</title>
      <programlisting role="php">
// Here, we use unserialize() to load session data from a database
// into $session_data.    This example complements the one described
// with <function>serialize</function>.

$conn = odbc_connect ("webdb", "php", "chicken");
$stmt = odbc_prepare ($conn, "SELECT data FROM sessions WHERE id = ?");
$sqldata = array ($PHP_AUTH_USER);
if (!odbc_execute ($stmt, &amp;$sqldata) || !odbc_fetch_into ($stmt, &amp;$tmp)) {
    // if the execute or fetch fails, initialize to empty array
    $session_data = array();
} else {
    // we should now have the serialized data in $tmp[0].
    $session_data = unserialize ($tmp[0]);
    if (!is_array ($session_data)) {
    // something went wrong, initialize to empty array
    $session_data = array();
    }
}
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.user-error">
   <refnamediv>
    <refname>user_error</refname>
    <refpurpose>
     Generates a user-level error/warning/notice message
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>user_error</function></funcdef>
      <paramdef>string <parameter>error_msg</parameter></paramdef>
      <paramdef>int
       <parameter><optional>error_type</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     This is an alias for the function <function>trigger_error</function>.
    </para>
    <para>
     See also <function>error_reporting</function>,
     <function>set_error_handler</function>,
     <function>restore_error_handler</function>, 
     <function>trigger_error</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.usleep">
   <refnamediv>
    <refname>usleep</refname>
    <refpurpose>Delay execution in microseconds</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>usleep</function></funcdef>
      <paramdef>int <parameter>micro_seconds</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <simpara>
     The <function>usleep</function> function delays program execution
     for the given number of <parameter>micro_seconds</parameter>.
    </simpara>
    <simpara>
     See also <function>sleep</function>.
    </simpara>
    <note>
     <simpara>
      This function does not work on Windows systems.
     </simpara>
    </note>
   </refsect1>
  </refentry>

 </reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->