mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 17:08:54 +00:00
7839d91186
removing the others git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@78562 c90b9560-bf6c-de11-be94-00142212c4b1
653 lines
19 KiB
XML
653 lines
19 KiB
XML
<!-- D O N O T E D I T T H I S F I L E ! ! !
|
|
|
|
it is still here for historical reasons only
|
|
(as translators may need to check old revision diffs)
|
|
|
|
if you want to change things documented in this file
|
|
you should now edit the files found under en/reference
|
|
instead -->
|
|
|
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.12 $ -->
|
|
<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 Advanced Programming in the
|
|
UNIX Environment by W. Richard Stevens (Addison-Wesley).
|
|
</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>< -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>> 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
|
|
-->
|
|
|