array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'pt_BR', ), 'this' => array ( 0 => 'function.pcntl-waitid.php', 1 => 'pcntl_waitid', 2 => 'Aguarda que um processo filho mude de estado', ), 'up' => array ( 0 => 'ref.pcntl.php', 1 => 'Funções PCNTL', ), 'prev' => array ( 0 => 'function.pcntl-wait.php', 1 => 'pcntl_wait', ), 'next' => array ( 0 => 'function.pcntl-waitpid.php', 1 => 'pcntl_waitpid', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'pt_BR', 'path' => 'reference/pcntl/functions/pcntl-waitid.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

pcntl_waitid

(PHP 8 >= 8.4.0)

pcntl_waitid — Aguarda que um processo filho mude de estado

Descrição

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

Obtém informações de status referentes a eventos de término, parada e/ou continuação em um dos processos filhos do chamador.

A menos que o sinalizador WNOHANG seja passado, o processo de chamada ficará bloqueado até que ocorra um erro ou informações de status fiquem disponíveis, satisfazendo todos os seguintes:

Se informações de status correspondentes estiverem disponíveis antes da chamada a pcntl_waitid(), o retorno será imediato. Se informações de status correspondentes estiverem disponíveis para dois ou mais processos filhos, a ordem em que seus status são relatados não é especificada.

Nota:

Esta documentação abrange a especificação POSIX da função waitid, juntamente com alguns parâmetros adicionais específicos para implementações em Linux, NetBSD e FreeBSD. Consulte a página de manual waitid(2) do sistema operacional para obter detalhes específicos sobre como waitid funciona.

Parâmetros

idtype
id
Os argumentos idtype e id são usados ​​para especificar quais filhos esperar.
Padrão POSIX para argumentos idtype e id
Se idtype for P_ALL espera por qualquer processo filho, id é ignorado.
Se idtype for P_PID espera pelo processo filho com ID de processo igual a id.
Se idtype for P_PGID espera por qualquer processo filho com ID de grupo de processo igual a id.
Argumentos idtype e id específicos para Linux
Se idtype for P_PIDFD (desde o Linux 5.4) espera pelo processo filho referido pelo descritor de arquivo PID especificado em id. (Consulte a página de manual do Linux pidfd_open(2) para obter mais informações sobre descritores de arquivo PID.)
Argumentos idtype e id específicos do NetBSD e FreeBSD
Se idtype for P_UID aguarda processos cujo ID de usuário efetivo seja igual a id.
Se idtype for P_GID aguarda processos cujo ID de grupo efetivo seja igual a id.
Se idtype for P_SID aguarda processos cujo ID de sessão seja igual a id. Se o processo filho iniciou sua própria sessão, seu ID de sessão será o mesmo que seu ID de processo. Caso contrário, o ID de sessão de um processo filho corresponderá ao ID de sessão do chamador.
Argumentos idtype e id específicos do FreeBSD
Se idtype for P_JAILID aguarda processos dentro de uma "jail" cujo identificador de "jail" seja igual a id.
info

O parâmetro info é definido como um array contendo informações sobre o sinal.

O array info pode conter as seguintes chaves:

  • signo: Número do sinal
  • errno: Número do erro do sistema
  • code: Código do sinal
  • status: Valor ou sinal de saída
  • pid: ID do processo que envia
  • uid: ID do usuário real do processo que envia
  • utime: Tempo do usuário consumido
  • stime: Tempo do sistema consumido

flags

O valor de flags é o valor de zero ou mais das seguintes constantes combinadas com OR:
Valores possíveis para flags
WCONTINUED O status deve ser retornado para qualquer processo filho continuado cujo status não tenha sido relatado desde que continuou a partir de uma parada de controle de tarefa ou tenha sido relatado apenas por chamadas a pcntl_waitid() com o sinalizador WNOWAIT definido.
WEXITED Aguarda processos que foram encerrados.
WNOHANG Não trava se nenhum status estiver disponível; retorna imediatamente.
WNOWAIT Mantém o processo cujo status é retornado em info em um estado de espera. Isso não deve afetar o estado do processo; o processo pode ser aguardado novamente após a conclusão desta chamada.
WSTOPPED O status deve ser retornado para qualquer processo filho que tenha parado ao receber um sinal e cujo status não tenha sido relatado desde sua parada ou tenha sido relatado apenas por chamadas a pcntl_waitid() com o sinalizador WNOWAIT definido.

resource_usage

O parâmetro resource_usage é definido como um array que contém estatística de uso de recursos do processo filho. Isto é suportado se a chamada de sistema wait6 estiver disponível (por exemplo no FreeBSD), ou também no Linux através da chamada de sistema waitid.

Valor Retornado

pcntl_waitid() retorna true se WNOHANG foi especificado e o status não está disponível para qualquer processo especificado por idtype e id.

pcntl_waitid() retorna true devido à mudança de estado de um de seus filhos.

Caso contrário, false é retornado e pcntl_get_last_error() pode ser usado para obter o número do erro errno.

Nota:

Uma vez obtido um número de erro errno, pcntl_strerror() pode ser usada para obter a mensagem de texto associada a ele.

Erros/Exceções

Valores de número de erro (errno)
ECHILD O processo de chamada não possui processos filho existentes não aguardados.
EINTR pcntl_waitid() foi interrompido por um sinal.
EINVAL Um valor inválido foi especificado para flags, ou idtype e id especificam um conjunto inválido de processos.

Registro de Alterações

Versão Descrição
8.5.0 resource_usage foi adicionado.

Veja Também