PHP: pcntl_waitid

説明

pcntl_waitid(
    int $idtype = P_ALL,
    ?int $id = null,
    array &$info = [],
    int $flags = WEXITED,
    array &$resource_usage = []
): bool

呼び出し元の子プロセスにおける終了、停止、および/または継続イベントに関連するステータス情報を取得します。

WNOHANG フラグを渡さない限り、呼び出し元のプロセスはエラーが発生するか、以下を全て満たすステータス情報が利用できるようになるまでブロックします。

idtype と id で指定された一連の子プロセスのうちの、いずれかの子プロセスのステータス情報であること
ステータス情報の状態変化が、 flags で設定した状態変化フラグのひとつにマッチすること

マッチしたステータス情報が、pcntl_waitid() の呼び出し前に利用可能になった場合、呼び出しは直ぐに返ります。マッチしたステータス情報がふたつ以上の子プロセスで利用可能になった場合、それらのステータスの順番は不定です。

注意:
このドキュメントは waitid 関数の POSIX 仕様を満たしていますし、 Linux, NetBSD, FreeBSD に特有の追加パラメータもいくつか満たしています。システムで waitid がどのように動作するかの詳細は、システムの waitid(2) のマニュアルを参照ください。

パラメータ

idtype

id

idtype と id は、どの子プロセスを待つのかを指定するのに使います。

**POSIX 標準の `idtype` と `id`**
`idtype` が `P_ALL` の場合	全ての子プロセスを待ちます。`id` は無視されます。
`idtype` が `P_PID` の場合	プロセスID が `id` に等しい子プロセスを待ちます。
`idtype` が `P_PGID` の場合	プロセスグループID が `id` に等しいすべての子プロセスを待ちます。

**Linux 特有の `idtype` と `id`**
`idtype` が `P_PIDFD` の場合(Linux 5.4 以降)	`id` で指定した PID ファイルディスクリプタで参照している子プロセスを待ちます。 (PID ファイルディスクリプタに関する詳しい情報は、 Linux の `pidfd_open(2)` man ページを参照ください)

**NetBSD と FreeBSD に特有の `idtype` と `id`**
`idtype` が `P_UID` の場合	実効ユーザーID が `id` に等しいプロセスを待ちます。
`idtype` が `P_GID` の場合	実効グループID が `id` に等しいプロセスを待ちます。
`idtype` が `P_SID` の場合	セッションID が `id` に等しいプロセスを待ちます。子プロセスが自分自身のセッションを開始していた場合、そのセッションIDはプロセスIDと等しくなります。そうでない場合、子プロセスのセッションIDは、呼び出し側のセッションIDとマッチします。

**FreeBSD に特有の `idtype` と `id`**
`idtype` が `P_JAILID` の場合	jail の識別子が `id` に等しい jail 中のプロセスを待ちます。

info

info には、シグナルに関する情報を含めた情報を設定します。

info 配列には、以下のキーが含まれています:

signo: Signal number
errno: System error number
code: Signal code
status: Exit value or signal
pid: Sending process ID
uid: Real user ID of sending process
utime: User time consumed
stime: System time consumed

flags

flags は、以下の定数を0個以上 OR で結んだ値です。　

**`flags` に設定できる値**
`WCONTINUED`	以下にあてはまる任意の子プロセスについて、その状態が返されます: ジョブの制御停止から動作が継続して以降、そのステータスが報告されていないか、 pcntl_waitid() を `WNOWAIT` フラグ付きで呼び出したことによってのみステータスが報告された子プロセス。
`WEXITED`	終了したプロセスを待つ
`WNOHANG`	ステータスが利用可能でない場合でもハングしない。つまり、すぐに制御を戻します。
`WNOWAIT`	`info` で返されたプロセスの状態が waitable な状態であってもそのままにする。これはプロセスの状態に影響しません。つまり、この関数呼び出しが完了した後、プロセスを再度待つことができるということです。
`WSTOPPED`	シグナルを受け取って停止した子プロセスについて、そのステータスが報告されていないか、 pcntl_waitid() を `WNOWAIT` フラグ付きで呼び出したことによってのみに報告された場合、その子プロセスの状態が返されます。

resource_usage

resource_usage には、子プロセスからリソース利用状況の統計を含めた配列を設定します。この情報は、(FreeBSD のように)wait6 システムコールが利用可能な場合か、生の waitid システムコールを利用できる Linux でサポートされています。

戻り値

WNOHANG が指定されており、かつ idtype と id で指定された任意のプロセスでステータスが利用できない場合 pcntl_waitid() は true を返します。

子プロセスのうちのひとつで、状態が変化した場合、 pcntl_waitid() は true を返します。

上記以外の場合、false が返され、エラー番号 errno を取得するために pcntl_get_last_error() が使えます。

注意:
エラー番号 errno が取得できた場合、それに関連付けられたテキストメッセージを取得するために pcntl_strerror() が使えます。

エラー / 例外

**エラー番号 (`errno`) の値**
`ECHILD`	呼び出し側のプロセスには、待っていない子プロセスはありません。
`EINTR`	pcntl_waitid() がシグナルで割り込まれました。
`EINVAL`	`flags` に不正な値が指定されたか、 `idtype` と `id` で不正なプロセスのセットを指定しました。

参考

pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
pcntl_wait() - 待つかフォークした子プロセスのステータスを返す
pcntl_fork() - 現在実行中のプロセスをフォークする
pcntl_signal() - シグナルハンドラを設定する
pcntl_wifexited() - ステータスコードが正常終了を表しているかどうかを調べる
pcntl_wifstopped() - 子プロセスが現在停止しているかどうかを調べる
pcntl_wifsignaled() - ステータスコードがシグナルによる終了を表しているかどうかを調べる
pcntl_wexitstatus() - 終了した子プロセスのリターンコードを返す
pcntl_wtermsig() - 子プロセスを終了させたシグナルを返す
pcntl_wstopsig() - 子プロセスを停止させたシグナルを返す

pcntl_waitid

説明

パラメータ

戻り値

エラー / 例外

参考

Found A Problem?

User Contributed Notes