International PHP Conference Berlin 2025

proc_get_status

(PHP 5, PHP 7, PHP 8)

proc_get_status Получает информацию о процессе, который открыли функцией proc_open()

Описание

proc_get_status(resource $process): array

Функция proc_get_status() получает данные о процессе, который открыли через функцию proc_open().

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

process

Дескриптор типа resource, который открыли функцией proc_open() и который исследует функция.

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

Функция возвращает массив (array) с полученной информацией. Получаемый массив содержит следующие элементы:

элементтипописание
command string Строка с командой, которую передали в функцию proc_open().
pid int идентификатор процесса
running bool Значение элемента равняется true, если процесс всё ещё запущен, false, если процесс завершился.
signaled bool Значение элемента равняется true, если дочерний процесс завершился неперехваченным сигналом. В Windows независимо от условия завершения дочернего процесса значение элемента равняется false.
stopped bool Значение элемента равняется true, если дочерний процесс остановился сигналом. В Windows независимо от условия остановки дочернего процесса значение элемента равняется false.
exitcode int Код завершения, который возвращается процессом и который несёт смысл, только если значение элемента running равно false. До PHP 8.3.0 только первый вызов функции возвращал реальное значение, очередные вызовы возвращали значение -1.
cached bool С PHP 8.3.0 значение элемента равно true, когда код завершения закешировался. Кеширование гарантирует, что код завершения не потеряется при очередных вызовах к API-интерфейсу процесса.
termsig int Номер сигнала, который заставил дочерний процесс завершить выполнение и который несёт смысл, только если значение элемента signaled равно true.
stopsig int Номер сигнала, который заставил дочерний процесс остановить выполнение и который несёт смысле, только если значение элемента stopped равно true.

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

Версия Описание
8.3.0 В массив возврата добавили запись "cached". До PHP 8.3.0 только первый вызов возвращал реальной код завершения. Запись "cached" указывает на то, что код завершения закешировался.

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

  • proc_open() - Выполняет команду и открывает указатель на файл для ввода или вывода

Добавить

Примечания пользователей 9 notes

up
47
Mark Seecof
15 years ago
On Unix/Linux, if you change the command line you pass to proc_open() just slightly then proc_get_status() will give you the actual process-id (pid) of your child.

Suppose you wish to run the external command /usr/bin/compress to create a BSD foo.Z file. Rather than proc_open("/usr/bin/compress /tmp/foo",...) you may invoke proc_open("exec /usr/bin/compress /tmp/foo",...) and then proc_get_status()['pid'] will be the actual pid of /usr/bin/compress.

Why? Because the way proc_open() actually works on Unix/Linux is by starting "/bin/sh -c usercmd userargs...", e.g., "/bin/sh -c /usr/bin/compress /tmp/foo".[Note 1] That means normally your command is the child of the shell, so the pid you retrieve with proc_get_status() is the pid of the shell (PHP's child), and you have to fumble around trying to find the pid of your command (PHP's grandchild). But if you put "exec" in front of your command, you tell the shell to *replace itself* with your command without starting another process (technically, to exec your command without forking first). That means your command will inherit the pid of the shell, which is the pid that proc_get_status() returns.

So if you would like the actual pid of the process running your command, just prepend "exec " to your proc_open() command argument then retrieve the pid using proc_get_status().

This also makes proc_terminate() and proc_close() work more like you might prefer, since they will affect the actual process running your command (which will be a child process rather than a grandchild process).

[Note 1] My guess is that the PHP developers want the shell to expand wildcards in path/filenames.
up
12
php dot net at crazedsanity dot com
15 years ago
For clarification, the "exitcode" is only valid the FIRST TIME IT IS CALLED after the process exits.

If you have a method that polls a spawned process for its status, you *MUST* have that same method capture the exitcode: if the method is called a second time (after realizing the pid is dead) and it hasn't cached that exitcode, it will receive the -1 mentioned.
up
10
Lachlan Mulcahy
13 years ago
It is worth noting that proc_get_status will continue to indicate the process that you spawned is running (because it is!) until that process has been able to write everything it wants to write to the STDOUT and STDERR streams.

PHP seems to use a buffer for this and so the spawned process can can get it's write calls to return immediately.

However, once this buffer is full the write call will block until you read out some of the information from the stream/pipe.

This can manifest itself in many ways but generally the called process will still be running, but just not doing anything as it is blocking on being able to write more to STDERR or STDOUT -- whichever stream buffer is full.

To work around this you should include in your loop of checking proc_get_status' running element a "stream_get_contents" on the relevant pipes.

I generally use stream_set_blocking($pipies[2], 0) kind of calls to make sure that the stream_get_contents call will not block if there is no data in the stream.

This one had me stumped for a while, so hopefully it helps someone!
up
3
webmaster at rouen dot fr
16 years ago
The following function takes an array of shell commands and executes them. It is able to execute up to $nb_max_process at the same time. As soon as one process is terminated, another one is executed. Quite useful if you want to batch process commands on a multi-processor or multi-core environment.

The example below tries to convert to PNG a list of SVG files submitted on the command line (using Inkscape).

(it's quick and dirty but works very well for me)

#!/usr/bin/php
<?php
function pool_execute($commandes,$nb_max_process) {
$pool=array();
for(
$i=0;$i<$nb_max_process;$i++) {
$pool[$i]=FALSE;
}

while(
count($commandes)>0) {
$commande=array_shift($commandes);

$commande_lancee=FALSE;
while(
$commande_lancee==FALSE) {
usleep(50000);

for(
$i=0;$i<$nb_max_process and $commande_lancee==FALSE;$i++) {
if(
$pool[$i]===FALSE) {
$pool[$i]=proc_open($commande,array(),$foo);
$commande_lancee=TRUE;
} else {
$etat=proc_get_status($pool[$i]);
if(
$etat['running']==FALSE) {
proc_close($pool[$i]);
$pool[$i]=proc_open($commande,array(),$foo);
$commande_lancee=TRUE;
}
}
}
}
}
}

$fichiers=$argv;
array_shift($fichiers);
$commandes=array();
foreach(
$fichiers as $fichier) {
$entree=$fichier;
$sortie=basename($fichier,'.svg').".png";
$commandes[]='inkscape --file='.escapeshellarg($entree).' --export-area-canvas --export-png='.escapeshellarg($sortie);
}

pool_execute($commandes,4);
up
1
strrev xc.noxeh@ellij
16 years ago
You can NOT rely on pid+1.
You could prefix exec to the command string, this will replace the /bin/sh script with the real thing you want to exec (use only if you don't do 'scary things' like pipes, output redirection, multiple commands, however if you know how they work, go ahead).
If you prefix exec, the /bin/sh process will only start your process, and the PID will be the same.
up
0
marco dot marsala at live dot it
1 year ago
If launching a GNU screen with proc_open, subsequents proc_get_status always return (wrongly) running = false

$descriptorspec = array(
0 => array("pipe", "r"), // stdin
1 => array("pipe", "w"), // stdout
2 => array("pipe", "w") // stderr
);
$p = proc_open('screen ...', $descriptorspec, $pipes);
var_dump(proc_get_status($p)['running']); // false (wrong)
up
0
damien at cyg dot net
17 years ago
Alternatively, if you're calling a subsequent php script using proc_open, you can have that process echo its own actual PID in the output.
Also, if you go through the /proc filesystem on linux, you can read through /proc/12345 where 12345 is the pid returned by proc_get_status (the pid of the /bin/sh instance) and it will list its child processes within.
up
-1
andy dot shellam at mailnetwork dot co dot uk
17 years ago
Further to my previous note, I've found out the PID returned is the PID of the shell (/bin/sh) that then runs the actual command requested.

I've raised this as bug #41003.
up
-3
andy dot shellam at mailnetwork dot co dot uk
17 years ago
To the poster above, same here on FreeBSD 6.1, PHP 5.2.1.

To get the correct PID to use for posix_kill I have to add 1 to the PID returned from proc_get_status.
To Top