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(). Порядок, в котором функция сообщит о статусе дочерних процессов, не определили, если доступ к информации об изменении статуса появился для двух или большего количества дочерних процессов.

Замечание:
Документация касается POSIX-спецификации функции waitid, и ряд дополнительных параметров, которые характерны для реализации функции в системах Linux, NetBSD и FreeBSD. Подробнее о работе функции waitid в текущей системе рассказывает man-страница руководства к функции waitid(2) конкретной системы.

Список параметров

idtype

id

Через аргументы idtype и id указывают, какие дочерние процессы ожидать.

**Аргументы `idtype` и `id` POSIX-стандарта**
Значение аргумента `idtype` равно `P_ALL`	Функция игнорирует аргумент `id` и ожидает изменения состояния каждого дочернего процесса.
Значение аргумента `idtype` равно `P_PID`	Функция ожидает изменения состояния дочернего процесса, идентификатор которого равен значению аргумента `id`.
Значение аргумента `idtype` равно `P_PGID`	Функция ожидает изменения состояния каждого дочернего процесса, идентификатор группы которого равен значению аргумента `id`.

**Аргументы `idtype` и `id`, характерные для Linux-систем**
Значение аргумента `idtype` равно `P_PIDFD` (с Linux 5.4)	Функция ожидает изменения состояния дочернего процесса, на который ссылается PID-идентификатор дескриптора файла, который указали в аргументе `id`. Подробнее о PID-идентификаторе дескриптора файла рассказывает man-страница руководства к функции `pidfd_open(2)`.

**Аргументы `idtype` и `id`, характерные для ОС NetBSD и FreeBSD**
Значение аргумента `idtype` равно `P_UID`	Функция ожидает процессы, эффективный идентификатор пользователя которых равен значению аргумента `id`.
Значение аргумента `idtype` равно `P_GID`	Функция ожидает процессы, эффективный идентификатор группы которых равен значению аргумента `id`.
Значение аргумента `idtype` равно `P_SID`	Функция ожидает процессы, идентификатор сессии которых равен значению аргумента `id`. Идентификатор сессии дочернего процесса и идентификатор дочернего процесса совпадут, если дочерний процесс запустил свою сессию, иначе идентификатор сессии дочернего процесса совпадёт с идентификатором сессии родительского процесса.

**Аргументы `idtype` и `id`, характерные для ОС FreeBSD**
Значение аргумента `idtype` равно `P_JAILID`	Функция ожидает процессы внутри изоляции, чей идентификатор равен значению аргумента `id`.

info

Функция заполнит параметр info массивом, который одержит информацию о сигнале.

Массив info содержит следующие ключи:

signo: Номер сигнала
errno: Номер системной ошибки
code: Код сигнала
status: Значение, которое процесс вернул при выходе, или сигнал, который изменил состояние процесса
pid: Идентификатор процесса, который отправил сигнал
uid: Реальный идентификатор пользователя процесса, который отправил сигнал
utime: Время, которое затратил пользователь
stime: Время, которое затратила система

flags

Значение аргумента flags состоит из нуля или большего количества следующих констант, которые объединили побитовым оператором ИЛИ:

**Возможные значения аргумента `flags`**
`WCONTINUED`	Возвращать статус дочернего процесса, который продолжает работу и о статусе которого либо не сообщалось, поскольку процесс продолжился после остановки управления заданием, либо сообщалось только через вызовы функции pcntl_waitid() с флагом `WNOWAIT`.
`WEXITED`	Ожидать процессы, которые сообщили о выходе.
`WNOHANG`	Не зависать, если статус недоступен; немедленно вернуть результат.
`WNOWAIT`	Сохранять процесс, статус которого возвращается в параметре `info`, в состоянии ожидания. Это не влияет на состояние процесса; процесс разрешается ожидать снова после завершения этого вызова.
`WSTOPPED`	Возвращать статус дочернего процесса, который остановился после получения сигнала и статус которого либо не сообщался с момента остановки процесса, либо о статусе сообщалось только через вызовы функции pcntl_waitid() с флагом `WNOWAIT`.

resource_usage

Функция заполнит переменную resource_usage массивом со статистикой потребления ресурсов дочерним процессом. Функция заполняет переменную, только если в системах наподобие FreeBSD доступен системный вызов wait6 или в ОС Linux при доступности прямого системного вызова waitid.

Возвращаемые значения

Функция pcntl_waitid() возвращает true, если указали флаг WNOHANG и статус недоступен ни для одного процесса, который определили аргументами idtype и id.

Функция pcntl_waitid() возвращает true при изменении состояния дочернего процесса.

В остальных случаях возвращается false, а номер ошибки errno получают функцией pcntl_get_last_error().

Замечание:
Текстовое описание номера ошибки errno получают функцией pcntl_strerror().

Ошибки

**Значения номера ошибки `errno`**
`ECHILD`	У родительского процесса нет дочерних процессов, которые бы не ожидала функция.
`EINTR`	Выполнение функции pcntl_waitid() прервал сигнал.
`EINVAL`	В аргументе `flags` передали недопустимое значение или через аргументы `idtype` и `id` указали недопустимый набор процессов.

Список изменений

Версия	Описание
8.5.0	Добавили параметр `resource_usage`.

Смотрите также

pcntl_waitpid() - Ожидает или возвращает статус порождённого дочернего процесса
pcntl_wait() - Ожидает или возвращает статус порождённого дочернего процесса
pcntl_fork() - Разветвить (fork) текущий запущенный процесс
pcntl_signal() - Устанавливает обработчик сигнала
pcntl_wifexited() - Проверяет, соответствует ли код завершения процесса нормальному завершению
pcntl_wifstopped() - Проверяет, остановлен ли дочерний процесс
pcntl_wifsignaled() - Проверить, соответствует ли код завершения процесса завершению по сигналу
pcntl_wexitstatus() - Получить код возврата завершённого дочернего процесса
pcntl_wtermsig() - Получить сигнал, из-за которого был принудительно завершён дочерний процесс
pcntl_wstopsig() - Получить сигнал, из-за которого был остановлен дочерний процесс

pcntl_waitid