<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
 <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
    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>
   <para>
    The following list of signals are supported by the Process Control
    functions.  Please see your systems signal(7) man page for details
    of the default behavior of these signals.
   <table>
    <title>Supported Signals</title>
    <tgroup cols="2">
     <tbody>
      <row>
       <entry><literal>SIGFPE</literal></entry>
       <entry><literal>SIGCONT</literal></entry>
       <entry><literal>SIGKILL</literal></entry>
      </row>
      <row>
       <entry><literal>SIGSTOP</literal></entry>
       <entry><literal>SIGUSR1</literal></entry>
       <entry><literal>SIGTSTP</literal></entry>
      </row>
      <row>
       <entry><literal>SIGHUP</literal></entry>
       <entry><literal>SIGUSR2</literal></entry>
       <entry><literal>SIGTTIN</literal></entry>
      </row>
      <row>
       <entry><literal>SIGINT</literal></entry>
       <entry><literal>SIGSEGV</literal></entry>
       <entry><literal>SIGTTOU</literal></entry>
      </row>
      <row>
       <entry><literal>SIGQUIT</literal></entry>
       <entry><literal>SIGPIPE</literal></entry>
       <entry><literal>SIGURG</literal></entry>
      </row>
      <row>
       <entry><literal>SIGILL</literal></entry>
       <entry><literal>SIGALRM</literal></entry>
       <entry><literal>SIGXCPU</literal></entry>
      </row>
      <row>
       <entry><literal>SIGTRAP</literal></entry>
       <entry><literal>SIGTERM</literal></entry>
       <entry><literal>SIGXFSZ</literal></entry>
      </row>
      <row>
       <entry><literal>SIGABRT</literal></entry>
       <entry><literal>SIGSTKFLT</literal></entry>
       <entry><literal>SIGVTALRM</literal></entry>
      </row>
      <row>
       <entry><literal>SIGIOT</literal></entry>
       <entry><literal>SIGCHLD</literal></entry>
       <entry><literal>SIGPROF</literal></entry>
      </row>
      <row>
       <entry><literal>SIGBUS</literal></entry>
       <entry><literal>SIGCLD</literal></entry>
       <entry><literal>SIGWINCH</literal></entry>
      </row>
      <row>
       <entry><literal>SIGPOLL</literal></entry>
       <entry><literal>SIGIO</literal></entry>
       <entry><literal>SIGPWR</literal></entry>
      </row>
      <row>
       <entry><literal>SIGSYS</literal></entry>
       <entry><literal></literal></entry>
       <entry><literal></literal></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   </para>

   <sect1 id="pcntl-example">
    <title>Process Control Example</title>
    <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>
   </sect1>
  </partintro>


 <refentry id="function.pcntl-fork">
  <refnamediv>
   <refname>pcntl_fork</refname>
   <refpurpose>Forks the currently running process</refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>int</type><methodname>pcntl_fork</methodname>
     <void/>
    </methodsynopsis>
   <para>
    The <function>pcntl_fork</function> function creates a child
    process that differs from the parent process only in it's PID and
    PPID. Please see your system's fork(2) man page for specific details as to
    how fork works on your system.
   </para>
   <para>
    On success, the PID of the child process is returned in the
    parent's thread of execution, and a 0 is returned in the child's
    thread of execution.  On failure, a -1 will be returned in the
    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">
<![CDATA[
<?php

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

?>
]]>
    </programlisting>
   </example>
   <para>
    See also <function>pcntl_waitpid</function> and
    <function>pcntl_signal</function>.
   </para>
  </refsect1>
 </refentry>


 <refentry id="function.pcntl-signal">
  <refnamediv>
   <refname>pcntl_signal</refname>
   <refpurpose>Installs a signal handler</refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>bool</type><methodname>pcntl_signal</methodname>
     <methodparam><type>int</type><parameter>signo</parameter></methodparam>
     <methodparam><type>mixed</type><parameter>handle</parameter></methodparam>
    </methodsynopsis>
   <para>
    The <function>pcntl_signal</function> function installs a new
    signal handler for the signal indicated by
    <parameter>signo</parameter>.  The signal handler is set to
    <parameter>handler</parameter> which may be the name of a user
    created function, or either of the two global constants SIG_IGN
    or SIG_DFL.
   </para>
   <para>
    <function>pcntl_signal</function> returns &true; on success or
    &false; on failure.
   </para>
   <example>
    <title><function>pcntl_signal</function> Example</title>
    <programlisting role="php">
<![CDATA[
<?php

// signal handler function
function sig_handler($signo) {

     switch($signo) {
         case SIGTERM:
             // handle shutdown tasks
             exit;
             break;
         case SIGHUP:
             // handle restart tasks
             break;
         case SIGUSR1:
             print "Caught SIGUSR1...\n";
             break;
         default:
             // handle all other signals
     }

}


print "Installing signal handler...\n";

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

print "Generating signal SIGTERM to self...\n";

// send SIGUSR1 to current process id
posix_kill(posix_getpid(), SIGUSR1);

print "Done\n"

?>
]]>
    </programlisting>
   </example>
   <para>
    See also <function>pcntl_fork</function> and
    <function>pcntl_waitpid</function>.
   </para>
  </refsect1>
 </refentry>


 <refentry id="function.pcntl-waitpid">
  <refnamediv>
   <refname>pcntl_waitpid</refname>
   <refpurpose>Waits on or returns the status of a forked child</refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>int</type><methodname>pcntl_waitpid</methodname>
     <methodparam><type>int</type><parameter>pid</parameter></methodparam>
     <methodparam><type>int</type><parameter>status</parameter></methodparam>
     <methodparam><type>int</type><parameter>options</parameter></methodparam>
    </methodsynopsis>
   <para>
    The <function>pcntl_waitpid</function> function suspends execution
    of the current process until a child as specified by the
    <parameter>pid</parameter> argument has exited, or until a signal
    is delivered whose action is to terminate the current process or
    to call a signal handling function.  If a child as requested by
    <parameter>pid</parameter> has already exited by the time of the
    call (a so-called "zombie" process), the function returns
    immediately.  Any system resources used by the child are
    freed. Please see your system's waitpid(2) man page for specific
    details as to how waitpid works on your system.
   </para>
   <para>
    <function>pcntl_waitpid</function> returns the process ID of the
    child which exited, -1 on error or zero if WNOHANG was used and no
    child was available
   </para>
   <para>
    The value of <parameter>pid</parameter> can be one of the following:
    <table>
     <title>possible values for <parameter>pid</parameter></title>
     <tgroup cols="2">
      <tbody>
       <row>
	<entry><literal>&lt; -1</literal></entry>
	<entry>
	 wait for any child process whose process group ID is equal to
	 the absolute value of <parameter>pid</parameter>.
	</entry>
       </row>
       <row>
	<entry><literal>-1</literal></entry>
	<entry>
	 wait for any child process; this is the same behaviour that
	 the wait function exhibits.
	</entry>
       </row>
       <row>
        <entry><literal>0</literal></entry>
        <entry>
	 wait for any child process whose process group ID is equal to
	 that of the calling process.
        </entry>
       </row>
       <row>
        <entry><literal>&gt; 0</literal></entry>
        <entry>
	 wait for the child whose process ID is equal to the value of
	 <parameter>pid</parameter>.
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
   <para>
    <function>pcntl_waitpid</function> will store status information
    in the <parameter>status</parameter> parameter which can be
    evaluated using the following functions:
    <function>pcntl_wifexited</function>,
    <function>pcntl_wifstopped</function>,
    <function>pcntl_wifsignaled</function>,
    <function>pcntl_wexitstatus</function>,
    <function>pcntl_wtermsig</function> and
    <function>pcntl_wstopsig</function>.
   </para>
   <para>
    The value of <parameter>options</parameter> is the value of zero
    or more of the following two global constants
    <literal>OR</literal>'ed together:
    <table>
     <title>possible values for <parameter>options</parameter></title>
     <tgroup cols="2">
      <tbody>
       <row>
        <entry><literal>WNOHANG</literal></entry>
        <entry>
	 return immediately if no child has exited.
	</entry>
       </row>
       <row>
        <entry><literal>WUNTRACED</literal></entry>
        <entry>
	 return for children which are stopped, and whose status has
	 not been reported.
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
   <para>
    See also <function>pcntl_fork</function>,
    <function>pcntl_signal</function>,
    <function>pcntl_wifexited</function>,
    <function>pcntl_wifstopped</function>,
    <function>pcntl_wifsignaled</function>,
    <function>pcntl_wexitstatus</function>,
    <function>pcntl_wtermsig</function> and
    <function>pcntl_wstopsig</function>.
   </para>
  </refsect1>
 </refentry>


 <refentry id="function.pcntl-wexitstatus">
  <refnamediv>
   <refname>pcntl_wexitstatus</refname>
   <refpurpose>
    Returns the return code of a terminated child
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>int</type><methodname>pcntl_wexitstatus</methodname>
     <methodparam><type>int</type><parameter>status</parameter></methodparam>      
    </methodsynopsis>
   <para>
    Returns the return code of a terminated child.  This function is
    only useful if <function>pcntl_wifexited</function> returned
    &true;.
   </para>
   <para>
    The parameter <parameter>status</parameter> is the status
    parameter supplied to a successfull call to
    <function>pcntl_waitpid</function>.
   </para>
   <para>
    See also <function>pcntl_waitpid</function> and
    <function>pcntl_wifexited</function>.
   </para>
  </refsect1>
 </refentry>


 <refentry id="function.pcntl-wifexited">
  <refnamediv>
   <refname>pcntl_wifexited</refname>
   <refpurpose>
    Returns &true; if status code represents a successful exit
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>int</type><methodname>pcntl_wifexited</methodname>
     <methodparam><type>int</type><parameter>status</parameter></methodparam>
    </methodsynopsis>
   <para>
    Returns &true; if the child status code represents a successful
    exit.
   </para>
   <para>
    The parameter <parameter>status</parameter> is the status
    parameter supplied to a successfull call to
    <function>pcntl_waitpid</function>.
   </para>
   <para>
    See also <function>pcntl_waitpid</function> and
    <function>pcntl_wexitstatus</function>.
   </para>
  </refsect1>
 </refentry>


 <refentry id="function.pcntl-wifsignaled">
  <refnamediv>
   <refname>pcntl_wifsignaled</refname>
   <refpurpose>
    Returns &true; if status code represents a termination due to a
    signal
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>int</type><methodname>pcntl_wifsignaled</methodname>
     <methodparam><type>int</type><parameter>status</parameter></methodparam>
    </methodsynopsis>
   <para>
    Returns &true; if the child process exited because of a signal
    which was not caught.
   </para>
   <para>
    The parameter <parameter>status</parameter> is the status
    parameter supplied to a successfull call to
    <function>pcntl_waitpid</function>.
   </para>
   <para>
    See also <function>pcntl_waitpid</function> and
    <function>pcntl_signal</function>.
   </para>
  </refsect1>
 </refentry>


 <refentry id="function.pcntl-wifstopped">
  <refnamediv>
   <refname>pcntl_wifstopped</refname>
   <refpurpose>
    Returns &true; if child process is currently stopped
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>int</type><methodname>pcntl_wifstopped</methodname>
     <methodparam><type>int</type><parameter>status</parameter></methodparam>
    </methodsynopsis>
   <para>
    Returns &true; if the child process which caused the return is
    currently stopped; this is only possible if the call to
    <function>pcntl_waitpid</function> was done using the option
    <literal>WUNTRACED</literal>.
   </para>
   <para>
    The parameter <parameter>status</parameter> is the status
    parameter supplied to a successfull call to
    <function>pcntl_waitpid</function>.
   </para>
   <para>
    See also <function>pcntl_waitpid</function>.
   </para>
  </refsect1>
 </refentry>


 <refentry id="function.pcntl-wstopsig">
  <refnamediv>
   <refname>pcntl_wstopsig</refname>
   <refpurpose>
    Returns the signal which caused the child to stop
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>int</type><methodname>pcntl_wstopsig</methodname>
     <methodparam><type>int</type><parameter>status</parameter></methodparam>
    </methodsynopsis>
   <para>
    Returns the number of the signal which caused the child to stop.
    This function is only useful if
    <function>pcntl_wifstopped</function> returned &true;.
   </para>
   <para>
    The parameter <parameter>status</parameter> is the status
    parameter supplied to a successfull call to
    <function>pcntl_waitpid</function>.
   </para>
   <para>
    See also <function>pcntl_waitpid</function> and
    <function>pcntl_wifstopped</function>.
   </para>
  </refsect1>
 </refentry>


 <refentry id="function.pcntl-wtermsig">
  <refnamediv>
   <refname>pcntl_wtermsig</refname>
   <refpurpose>
    Returns the signal which caused the child to terminate
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>int</type><methodname>pcntl_wtermsig</methodname>
     <methodparam><type>int</type><parameter>status</parameter></methodparam>
    </methodsynopsis>
   <para>
    Returns the number of the signal that caused the child process to
    terminate. This function is only useful if
    <function>pcntl_wifsignaled</function> returned &true;.
   </para>
   <para>
    The parameter <parameter>status</parameter> is the status
    parameter supplied to a successfull call to
    <function>pcntl_waitpid</function>.
   </para>
   <para>
    See also <function>pcntl_waitpid</function>,
    <function>pcntl_signal</function> and
    <function>pcntl_wifsignaled</function>.
   </para>
  </refsect1>
 </refentry>

  <refentry id='function.pcntl-exec'>
   <refnamediv>
    <refname>pcntl_exec</refname>
    <refpurpose>
     Executes specified program in current process space
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>pcntl_exec</methodname>
      <methodparam><type>string</type><parameter>path</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>args</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>envs</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </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
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
-->