<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
 <reference id="ref.pcntl">
  <title>Process Control Functions</title>
  <titleabbrev>PCNTL</titleabbrev>

  <partintro>
   <section id="pcntl.intro">
    &reftitle.intro;
    <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 Advanced Programming in the
     UNIX Environment by W. Richard Stevens (Addison-Wesley).
   </para>
   </section>

   <section id="pcntl.requirements">
    &reftitle.required;
    &no.requirement;
   </section>

   <section id="pcntl.installation">
    &reftitle.install;
    <para>
     Process Control support in PHP is not enabled by default. You will need
     to use the <link
     linkend="install.configure.enable-pcntl">--enable-pcntl</link>
     configuration option when compiling PHP to enable Process Control
     support.
    </para>
    <note>
     <para>
      Currently, this module will not function on non-Unix platforms
      (Windows).
     </para>
    </note>
   </section>

   <section id="pcntl.configuration">
    &reftitle.runtime;
    &no.config;
   </section>

   <section id="pcntl.resources">
    &reftitle.resources;
    &no.resource;
   </section>

   &reference.pcntl.constants;

   <section id="pcntl.example">
    &reftitle.examples;
    <para>
     This example forks off a daemon process with a signal handler.
    </para>
    <example>
     <title>Process Control Example</title>
     <programlisting role="php">
<![CDATA[
<?php

$pid = pcntl_fork();
if ($pid == -1) {
     die("could not fork"); 
} else if ($pid) {
     exit(); // we are the parent 
} else {
     // we are the child
}

// detatch from the controlling terminal
if (!posix_setsid()) {
    die("could not detach from terminal");
}

// setup signal handlers
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGHUP, "sig_handler");

// loop forever performing tasks
while(1) {

    // do something interesting here

}

function sig_handler($signo) {

     switch($signo) {
         case SIGTERM:
             // handle shutdown tasks
             exit;
             break;
         case SIGHUP:
             // handle restart tasks
             break;
         default:
             // handle all other signals
     }

}

?>
]]>
     </programlisting>
    </example>
   </section>

   <section id="pcntl.seealso">
    &reftitle.seealso;
    <para>
     A look at the section about
     <link linkend="ref.posix">POSIX functions</link>
     may be useful.
    </para>
   </section>

  </partintro>

&reference.pcntl.functions;

 </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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->