Ref/pcntl-Phpdoc专题

参考一下 POSIX functions 对有助于理解使用。

pcntl_alarm

为进程设置一个alarm闹钟信号

说明

int pcntl_alarm ( int $seconds )

创建一个计时器，在指定的秒数后向进程发送一个SIGALRM信号。每次对 pcntl_alarm的调用都会取消之前设置的alarm信号。

参数

seconds
等待的秒数。如果seconds设置为0,将不会创建alarm信号。

返回值

返回上次alarm调度（离alarm信号发送）剩余的秒数，或者之前没有alarm调度（译注：或者之前调度已完成）时返回0。

pcntl_async_signals

Enable/disable asynchronous signal handling or return the old setting

说明

bool pcntl_async_signals ([ bool $on = null ] )

If the on parameter is omitted, pcntl_async_signals returns whether asynchronous signal handling is enabled. Otherwise, asynchronous signal handling is enabled or disabled.

参数

on
Whether asynchronous signal handling should be enabled.

返回值

When used as getter (that is without the optional parameter) it returns whether asynchronous signal handling is enabled. When used as setter (that is with the optional parameter given), it returns whether asynchronous signal handling was enabled before the function call.

参见

declare

pcntl_errno

别名 pcntl_get_last_error

说明

此函数是该函数的别名： pcntl_get_last_error

pcntl_exec

在当前进程空间执行指定程序

说明

void pcntl_exec ( string $path [, array $args [, array $envs ]] )

以给定参数执行程序。

参数

path
path必须时可执行二进制文件路径或一个在文件第一行指定了一个可执行文件路径标头的脚本（比如文件第一行是#!/usr/local/bin/perl的perl脚本）。更多的信息请查看您系统的execve（2）手册。

args
args是一个要传递给程序的参数的字符串数组。

envs
envs是一个要传递给程序作为环境变量的字符串数组。这个数组是 key => value格式的，key代表要传递的环境变量的名称，value代表该环境变量值。

返回值

当发生错误时返回 false ，没有错误时没有返回。

pcntl_fork

在当前进程当前位置产生分支（子进程）。译注：fork是创建了一个子进程，父进程和子进程都从fork的位置开始向下继续执行，不同的是父进程执行过程中，得到的fork返回值为子进程号，而子进程得到的是0。

说明

int pcntl_fork ( void )

pcntl_fork函数创建一个子进程，这个子进程仅PID（进程号）和PPID（父进程号）与其父进程不同。fork怎样在您的系统工作的详细信息请查阅您的系统的fork（2）手册。

返回值

成功时，在父进程执行线程内返回产生的子进程的PID，在子进程执行线程内返回0。失败时，在父进程上下文返回-1，不会创建子进程，并且会引发一个PHP错误。

范例

示例 #1 pcntl_fork 示例

<?php

$pid = pcntl_fork();
//父进程和子进程都会执行下面代码
if ($pid == -1) {
    //错误处理：创建子进程失败时返回-1.
     die('could not fork');
} else if ($pid) {
     //父进程会得到子进程号，所以这里是父进程执行的逻辑
     pcntl_wait($status); //等待子进程中断，防止子进程成为僵尸进程。
} else {
     //子进程得到的$pid为0, 所以这里是子进程执行的逻辑。
}

?>

参见

pcntl_waitpid
pcntl_signal

pcntl_get_last_error

Retrieve the error number set by the last pcntl function which failed

说明

int pcntl_get_last_error ( void )

Warning

本函数还未编写文档，仅有参数列表。

参数

此函数没有参数。

返回值

Returns error code.

参见

pcntl_strerror

pcntl_getpriority

获取任意进程的优先级

说明

int pcntl_getpriority ([ int $pid = getmypid() [, int $process_identifier = PRIO_PROCESS ]] )

pcntl_getpriority 获取进程号为 pid的进程的优先级。由于不同的系统类型以及内核版本下优先级可能不同，因此请参考您系统的getpriority（2）手册以获取详细的规范。

参数

pid
如果没有指定，默认是当前进程的进程号。

process_identifier
PRIO_PGRP（译注：获取进程组优先级）, PRIO_USER （译注：获取用户进程优先级）或 PRIO_PROCESS（译注：默认值;获取进程优先级）三者之一。

返回值

pcntl_getpriority 返回进程的优先级或在错误时返回 false 。值越小代表优先级越高。

Warning

此函数可能返回布尔值 false，但也可能返回等同于 false 的非布尔值。请阅读布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

参见

pcntl_setpriority

pcntl_setpriority

修改任意进程的优先级

说明

bool pcntl_setpriority ( int $priority [, int $pid = getmypid() [, int $process_identifier = PRIO_PROCESS ]] )

pcntl_setpriority 设置进程号为 pid的进程的优先级。

参数

priority
priority 通常时-20至20这个范围内的值。默认优先级是0,值越小代表优先级越高。由于不同的系统类型以及内核版本下优先级可能不同，因此请参考您系统的setpriority（2）手册以获取详细的规范。

pid
如果没有指定，默认是当前进程的进程号。

返回值

成功时返回 true，或者在失败时返回 false。

参见

pcntl_getpriority

pcntl_signal_dispatch

调用等待信号的处理器

说明

bool pcntl_signal_dispatch ( void )

函数pcntl_signal_dispatch调用每个等待信号通过pcntl_signal 安装的处理器。

返回值

成功时返回 true，或者在失败时返回 false。

范例

示例 #1 pcntl_signal_dispatch 示例

<?php
echo "安装信号处理器...\n";
pcntl_signal(SIGHUP,  function($signo) {
     echo "信号处理器被调用\n";
});

echo "为自己生成SIGHUP信号...\n";
posix_kill(posix_getpid(), SIGHUP);

echo "分发...\n";
pcntl_signal_dispatch();

echo "完成\n";

?>

以上例程的输出类似于：

安装信号处理器...
为自己生成SIGHUP信号...
分发...
信号处理器被调用
完成

参见

pcntl_signal
pcntl_sigprocmask
pcntl_sigwaitinfo
pcntl_sigtimedwait

pcntl_signal_get_handler

Get the current handler for specified signal

说明

mixed pcntl_signal_get_handler ( int $signo )

The pcntl_signal_get_handler function will get the current handler for the specified signo.

参数

signo
The signal number.

返回值

This function may return an integer value that refers to SIG_DFL or SIG_IGN. If you set a custom handler a string value containing the function name is returned.

更新日志

版本	说明
7.1.0	pcntl_signal_get_handler has been added.

范例

示例 #1 pcntl_signal_get_handler example

<?php
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: int(0)

function pcntl_test($signo) {}
pcntl_signal(SIGUSR1, 'pcntl_test');
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: string(10) "pcntl_test"

pcntl_signal(SIGUSR1, SIG_DFL);
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: int(0)

pcntl_signal(SIGUSR1, SIG_IGN);
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: int(1)
?>

参见

pcntl_signal

pcntl_signal

安装一个信号处理器

说明

bool pcntl_signal ( int $signo , callback $handler [, bool $restart_syscalls = true ] )

函数pcntl_signal为signo指定的信号安装一个新的信号处理器。

参数

signo
信号编号。

handler
信号处理器可以是用户创建的函数或方法的名字，也可以是系统常量 SIG_IGN（译注：忽略信号处理程序）或SIG_DFL（默认信号处理程序）.

Note:

注意当你使用一个对象方法的时候，该对象的引用计数回增加使得它在你改变为其他处理或脚本结束之前是持久存在的。

restart_syscalls
指定当信号到达时系统调用重启是否可用。（译注：经查资料，此参数意为系统调用被信号打断时，系统调用是否从开始处重新开始，但根据http://bugs.php.net/bug.php?id=52121，此参数存在bug无效。）

返回值

成功时返回 true，或者在失败时返回 false。

更新日志

版本	说明
4.3.0	增加参数`restart_syscalls`。
4.3.0	对象方法可以作为回调被使用。
4.3.0	PCNTL现在使用了ticks作为信号处理的回调机制，ticks在速度上远远超过了之前的处理机制。这个变化与“用户ticks”遵循了相同的语义。您可以使用declare 语句在程序中指定允许发生回调的位置。这使得我们对异步事件处理的开销最小化。在编译PHP时启用pcntl将始终承担这种开销，不论您的脚本中是否真正使用了pcntl。 PHP 4.3.0使用ticks作为信号处理回调机制，这比以前的机制快了很多。这个变化与 "用户ticks" 遵循了相同的语义。您可以使用declare() 语句在程序中指定允许发生回调的位置。

范例

示例 #1 pcntl_signal示例

<?php
//使用ticks需要PHP 4.3.0以上版本
declare(ticks = 1);

//信号处理函数
function sig_handler($signo)
{

     switch ($signo) {
         case SIGTERM:
             // 处理SIGTERM信号
             exit;
             break;
         case SIGHUP:
             //处理SIGHUP信号
             break;
         case SIGUSR1:
             echo "Caught SIGUSR1...\n";
             break;
         default:
             // 处理所有其他信号
     }

}

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

//安装信号处理器
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGHUP,  "sig_handler");
pcntl_signal(SIGUSR1, "sig_handler");

// 或者在PHP 4.3.0以上版本可以使用对象方法
// pcntl_signal(SIGUSR1, array($obj, "do_something");

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

//向当前进程发送SIGUSR1信号
posix_kill(posix_getpid(), SIGUSR1);

echo "Done\n"

?>

参见

pcntl_fork
pcntl_waitpid

pcntl_sigprocmask

设置或检索阻塞信号

说明

bool pcntl_sigprocmask ( int $how , array $set [, array &$oldset ] )

函数pcntl_sigprocmask用来增加，删除或设置阻塞信号，具体行为依赖于参数how。

参数

how
设置pcntl_sigprocmask函数的行为。可选值:

SIG_BLOCK: 把信号加入到当前阻塞信号中。
SIG_UNBLOCK: 从当前阻塞信号中移出信号。
SIG_SETMASK: 用给定的信号列表替换当前阻塞信号列表。

set
信号列表。

oldset
oldset是一个输出参数，用来返回之前的阻塞信号列表数组。

返回值

成功时返回 true，或者在失败时返回 false。

范例

示例 #1 pcntl_sigprocmask 示例

<?php
//将SIGHUP信号加入到阻塞信号中
pcntl_sigprocmask(SIG_BLOCK, array(SIGHUP));
$oldset = array();
//将SIGHUP从阻塞信号列表中移除并返回之前的阻塞信号列表。
pcntl_sigprocmask(SIG_UNBLOCK, array(SIGHUP), $oldset);
?>

参见

pcntl_sigwaitinfo
pcntl_sigtimedwait

pcntl_sigtimedwait

带超时机制的信号等待

说明

int pcntl_sigtimedwait ( array $set [, array &$siginfo [, int $seconds = 0 [, int $nanoseconds = 0 ]]] )

函数pcntl_sigtimedwait实际上与pcntl_sigwaitinfo 的行为一致，不同在于它多了两个增强参数seconds和 nanoseconds，这使得脚本等待的事件有了一个时间的上限。

参数

set
要等待的信号列表数组。

siginfo
siginfo是一个输出参数，用来返回信号的信息。更详细情况参见 pcntl_sigwaitinfo。

seconds
超时秒数。

nanoseconds
超时纳秒数。

返回值

成功时，函数pcntl_sigtimedwait返回信号编号。

参见

pcntl_sigprocmask
pcntl_sigwaitinfo

pcntl_sigwaitinfo

等待信号

说明

int pcntl_sigwaitinfo ( array $set [, array &$siginfo ] )

pcntl_sigwaitinfo函数暂停调用脚本的执行直到接收到set 参数中列出的某个信号。只要其中的一个信号已经在等待状态(比如：通过 pcntl_sigprocmask函数阻塞)，函数pcntl_sigwaitinfo就回立刻返回。

参数

set
要等待的信号数组。

siginfo
siginfo是一个输出参数，用来返回信号的信息。

以下元素会为所有信号设置：

signo: 信号编号
errno: 错误编号
code: 信号代码

下面元素可能会为SIGCHLD信号设置:

status: 退出的值或信号
utime: 用户消耗的时间
stime: 系统（内核）消耗的时间
pid: 发送进程ID
uid: 发送进程的实际用户ID

信号SIGILL, SIGFPE, SIGSEGV 和 SIGBUS 可能会被设置的元素:

addr: 发生故障的内存位置

可能会为SIGPOLL 信号设置的元素：

band: Band event
fd: 文件描述符

返回值

成功时，函数pcntl_sigwaitinfo返回一个信号编号。

范例

示例 #1 pcntl_sigwaitinfo example

<?php
echo "Blocking SIGHUP signal\n";
pcntl_sigprocmask(SIG_BLOCK, array(SIGHUP));

echo "Sending SIGHUP to self\n";
posix_kill(posix_getpid(), SIGHUP);

echo "Waiting for signals\n";
$info = array();
pcntl_sigwaitinfo(array(SIGHUP), $info);
?>

参见

pcntl_sigprocmask
pcntl_sigtimedwait

pcntl_strerror

Retrieve the system error message associated with the given errno

说明

stringfalse pcntl_strerror ( int $errno )

Warning

本函数还未编写文档，仅有参数列表。

参数

errno

返回值

Returns error description on success 或者在失败时返回 false.

参见

pcntl_get_last_error

pcntl_wait

等待或返回 fork 的子进程状态

说明

int pcntl_wait ( int &$status [, int $options = 0 [, array &$rusage ]] )

wait函数挂起当前进程的执行直到一个子进程退出或接收到一个信号要求中断当前进程或调用一个信号处理函数。如果一个子进程在调用此函数时已经退出（俗称僵尸进程），此函数立刻返回。子进程使用的所有系统资源将被释放。关于 wait 在您系统上工作的详细规范请查看您系统的 wait（2）手册。

Note:

这个函数等同于以 -1 作为参数 pid 的值并且没有 options 参数来调用 pcntl_waitpid 函数。

参数

status
pcntl_wait 将会存储状态信息到 status 参数上，这个通过 status 参数返回的状态信息可以用以下函数 pcntl_wifexited, pcntl_wifstopped, pcntl_wifsignaled, pcntl_wexitstatus, pcntl_wtermsig 以及 pcntl_wstopsig 获取其具体的值。

options
如果您的操作系统（多数BSD类系统）允许使用 wait3，您可以提供可选的options 参数。如果这个参数没有提供，wait将会被用作系统调用。如果wait3不可用，提供参数 options 不会有任何效果。options 的值可以是0 或者以下两个常量或两个常量“或运算”结果（即两个常量代表意义都有效）。


WNOHANG	如果没有子进程退出立刻返回。
WUNTRACED	子进程已经退出并且其状态未报告时返回。

返回值

pcntl_wait 返回退出的子进程进程号，发生错误时返回 -1,如果提供了 WNOHANG 作为 option（wait3可用的系统）并且没有可用子进程时返回 0。

参见

pcntl_fork
pcntl_signal
pcntl_wifexited
pcntl_wifstopped
pcntl_wifsignaled
pcntl_wexitstatus
pcntl_wtermsig
pcntl_wstopsig
pcntl_waitpid

pcntl_waitpid

等待或返回fork的子进程状态

说明

int pcntl_waitpid ( int $pid , int &$status [, int $options = 0 ] )

挂起当前进程的执行直到参数pid指定的进程号的进程退出，或接收到一个信号要求中断当前进程或调用一个信号处理函数。

如果pid指定的子进程在此函数调用时已经退出（俗称僵尸进程），此函数将立刻返回。关于waitpid更详细的规范请参见您系统的waitpid（2）手册。

参数

pid
参数pid的值可以是以下之一：


\< -1	等待任意进程组ID等于参数`pid`给定值的绝对值的进程。
-1	等待任意子进程;与pcntl_wait函数行为一致。
0	等待任意与调用进程组ID相同的子进程。
> 0	等待进程号等于参数`pid`值的子进程。

Note:

指定-1作为pid的值等同于pcntl_wait 提供(负的options)。

status
pcntl_waitpid将会存储状态信息到status 参数上，这个通过status参数返回的状态信息可以用以下函数 pcntl_wifexited, pcntl_wifstopped, pcntl_wifsignaled, pcntl_wexitstatus, pcntl_wtermsig以及 pcntl_wstopsig获取其具体的值。

options
如果您的操作系统（多数BSD类系统）允许使用wait3，您可以提供可选的options 参数。如果这个参数没有提供，wait将会被用作系统调用。如果wait3不可用，提供参数 options不会有任何效果。options的值可以是0 或者以下两个常量或两个常量“或运算”结果（即两个常量代表意义都有效）。


WNOHANG	如果没有子进程退出立刻返回。
WUNTRACED	子进程已经退出并且其状态未报告时返回。

返回值

pcntl_waitpid返回退出的子进程进程号，发生错误时返回-1,如果提供了 WNOHANG作为option（wait3可用的系统）并且没有可用子进程时返回0。

参见

pcntl_fork
pcntl_signal
pcntl_wifexited
pcntl_wifstopped
pcntl_wifsignaled
pcntl_wexitstatus
pcntl_wtermsig
pcntl_wstopsig

pcntl_wexitstatus

返回一个中断的子进程的返回代码

说明

int pcntl_wexitstatus ( int $status )

返回一个中断的子进程的返回代码。这个函数仅在函数pcntl_wifexited返回 true.时有效。

参数

status
参数 status 是提供给成功调用 pcntl_waitpid 时的状态参数。

返回值

返回整形的子进程返回代码。

参见

pcntl_waitpid
pcntl_wifexited

pcntl_wifexited

检查状态代码是否代表一个正常的退出。

说明

bool pcntl_wifexited ( int $status )

检查子进程状态代码是否代表正常退出。

参数

status
参数 status 是提供给成功调用 pcntl_waitpid 时的状态参数。

返回值

当子进程状态代码代表正常退出时返回 true ，其他情况返回 false。

参见

pcntl_waitpid
pcntl_wexitstatus

pcntl_wifsignaled

检查子进程状态码是否代表由于某个信号而中断

说明

bool pcntl_wifsignaled ( int $status )

检查子进程是否是由于某个未捕获的信号退出的。

参数

status
参数 status 是提供给成功调用 pcntl_waitpid 时的状态参数。

返回值

如果子进程是由于某个未捕获的信号退出的返回 true ，其他情况返回 false 。

参见

pcntl_waitpid
pcntl_signal

pcntl_wifstopped

检查子进程当前是否已经停止

说明

bool pcntl_wifstopped ( int $status )

仅查子进程当前是否停止; 此函数只有作用于使用了WUNTRACED作为 option的pcntl_waitpid函数调用产生的status时才有效。

参数

status
参数 status 是提供给成功调用 pcntl_waitpid 时的状态参数。

返回值

如果子进程当前是停止的返回 true ，其他情况返回 false 。

参见

pcntl_waitpid

pcntl_wstopsig

返回导致子进程停止的信号

说明

int pcntl_wstopsig ( int $status )

返回导致子进程停止的信号编号。这个函数仅在pcntl_wifstopped返回 true 时有效。

参数

status
参数 status 是提供给成功调用 pcntl_waitpid 时的状态参数。

返回值

返回信号编号。

参见

pcntl_waitpid
pcntl_wifstopped

pcntl_wtermsig

返回导致子进程中断的信号

说明

int pcntl_wtermsig ( int $status )

返回导致子进程中断的信号编号。这个函数仅在pcntl_wifsignaled 返回 true 时有效。

参数

status
参数 status 是提供给成功调用 pcntl_waitpid 时的状态参数。

返回值

返回整型的信号编号。

参见

pcntl_waitpid
pcntl_signal
pcntl_wifsignaled

pcntl_alarm — 为进程设置一个alarm闹钟信号
pcntl_async_signals — Enable/disable asynchronous signal handling or return the old setting
pcntl_errno — 别名 pcntl_get_last_error
pcntl_exec — 在当前进程空间执行指定程序
pcntl_fork — 在当前进程当前位置产生分支（子进程）。译注：fork是创建了一个子进程，父进程和子进程都从fork的位置开始向下继续执行，不同的是父进程执行过程中，得到的fork返回值为子进程号，而子进程得到的是0。
pcntl_get_last_error — Retrieve the error number set by the last pcntl function which failed
pcntl_getpriority — 获取任意进程的优先级
pcntl_setpriority — 修改任意进程的优先级
pcntl_signal_dispatch — 调用等待信号的处理器
pcntl_signal_get_handler — Get the current handler for specified signal
pcntl_signal — 安装一个信号处理器
pcntl_sigprocmask — 设置或检索阻塞信号
pcntl_sigtimedwait — 带超时机制的信号等待
pcntl_sigwaitinfo — 等待信号
pcntl_strerror — Retrieve the system error message associated with the given errno
pcntl_wait — 等待或返回 fork 的子进程状态
pcntl_waitpid — 等待或返回fork的子进程状态
pcntl_wexitstatus — 返回一个中断的子进程的返回代码
pcntl_wifexited — 检查状态代码是否代表一个正常的退出。
pcntl_wifsignaled — 检查子进程状态码是否代表由于某个信号而中断
pcntl_wifstopped — 检查子进程当前是否已经停止
pcntl_wstopsig — 返回导致子进程停止的信号
pcntl_wtermsig — 返回导致子进程中断的信号