completed intro text, added a couple of function examples

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@58673 c90b9560-bf6c-de11-be94-00142212c4b1

functions/pcntl.xml

@@ -1,9 +1,25 @@
 <?xml encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
  <reference id="ref.pcntl">
   <title>Process Control Functions</title>
   <titleabbrev>PCNTL</titleabbrev>
   <partintro>
+   <para>
+    Process Control support in PHP implements the Unix style of
+    process creation, program execution, signal handling and process
+    termination.  Process Control should not be enabled within a
+    webserver environment and unexpected results may happen if any
+    Process Control functions are used within a webserver environment.
+   </para>
+   <para>
+    This documentation is intended to explain the general usage of
+    each of the Process Control functions.  For detailed information
+    about Unix process control you are encouraged to consult your
+    systems documentation including fork(2), waitpid(2) and signal(2)
+    or a comprehensive reference such as <citation>Advanced
+    Programming in the UNIX Environment by W. Richard Stevens
+    (Addison-Wesley)</citation>.
+   </para>
    <para>
     Process Control support in PHP is not enabled by default.  You
     will need to use the <link
@@ -89,7 +105,6 @@
    </table>
    </para>
 
-
    <sect1 id="pcntl-example">
     <title>Process Control Example</title>
     <para>
@@ -176,6 +191,23 @@ function sig_handler($signo) {
     parent's context, no child process will be created, and a PHP
     error is raised.
    </para>
+   <example>
+    <title><function>pcntl_fork</function> Example</title>
+    <programlisting role="php">
+&lt;?php
+
+$pid = pcntl_fork();
+if ($pid == -1) {
+     die("could not fork");
+} else if ($pid) {
+     // we are the parent
+} else {
+     // we are the child
+}
+
+?&gt;
+    </programlisting>
+   </example>
    <para>
     See also <function>pcntl_waitpid</function> and
     <function>pcntl_signal</function>.
@@ -210,6 +242,35 @@ function sig_handler($signo) {
     <function>pcntl_signal</function> returns &true; on success or
     &false; on failure.
    </para>
+   <example>
+    <title><function>pcntl_fork</function> Example</title>
+    <programlisting role="php">
+&lt;?php
+
+// setup signal handlers
+pcntl_signal(SIGTERM, "sig_handler");
+pcntl_signal(SIGHUP, "sig_handler");
+
+// signal handler function
+function sig_handler($signo) {
+
+     switch($signo) {
+         case SIGTERM:
+             // handle shutdown tasks
+             exit;
+             break;
+         case SIGHUP:
+             // handle restart tasks
+             break;
+         default:
+             // handle all other signals
+     }
+
+}
+
+?&gt;
+    </programlisting>
+   </example>
    <para>
     See also <function>pcntl_fork</function> and
     <function>pcntl_waitpid</function>.