PHP 5.4.31 Released

pcntl_signal

(PHP 4 >= 4.1.0, PHP 5)

pcntl_signalInstalle un gestionnaire de signaux

Description

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

pcntl_signal() installe un nouveau gestionnaire de signaux ou remplace le gestionnaire de signaux courant pour le signal indiqué par le paramètre signo.

Liste de paramètres

signo

Le numéro du signal.

handler

Le gestionnaire de signaux. Peut être un callable, qui sera appelé pour gérer le signal, ou bien l'une des deux constantes globales SIG_IGN ou SIG_DFL, qui vont, respectivement, ignorer le signal ou restaurer le gestionnaire de signaux par défaut.

Si un callable est fourni, il doit implémenter la signature suivante :

void handler ( int $signo )
signo
Le signal à gérer.

Note:

Notez que lorsque vous configurez le gestionnaire avec une méthode d'objet, le compteur de référence de l'objet est incrémenté, ce qui le rend persistant jusqu'à ce que vous changiez le gestionnaire de signaux pour un autre, ou que le script se termine.

restart_syscalls

Le paramètre optionnel restart_syscalls spécifie si l'appel système de redémarrage (restarting) doit être utilisé lorsque ce signal arrive.

Valeurs de retour

Cette fonction retourne TRUE en cas de succès ou FALSE si une erreur survient.

Historique

Version Description
4.3.0 Le paramètre restart_syscalls a été ajouté.
4.3.0 Utiliser une méthode d'un objet en tant que fonction de rappel est devenu possible.
4.3.0 Depuis PHP 4.3.0, PCNTL utilise les ticks comme mécanisme de signaux de traitement des rappels qui est plus rapide que l'ancien mécanisme. Ce changement suit les mêmes règles que l'utilisation des "user ticks". Vous devriez utiliser la requête declare() pour spécifier l'endroit dans votre programme où les rappels sont autorisés à être utilisés pour le traitement du signal de la fonction proprement dite (comme utilisé dans l'exemple suivant).

Exemples

Exemple #1 Exemple avec pcntl_signal()

<?php
// l'usage des ticks est nécessaire depuis PHP 4.3.0
declare(ticks 1);

// gestionnaire de signaux système
function sig_handler($signo)
{

     switch (
$signo) {
         case 
SIGTERM:
             
// gestion de l'extinction
             
exit;
             break;
         case 
SIGHUP:
             
// gestion du redémarrage
             
break;
         case 
SIGUSR1:
             echo 
"Reçu le signe SIGUSR1...\n";
             break;
         default:
             
// gestion des autres signaux
     
}

}

echo 
"Installation du gestionnaire de signaux...\n";

// Installation des gestionnaires de signaux
pcntl_signal(SIGTERM"sig_handler");
pcntl_signal(SIGHUP,  "sig_handler");
pcntl_signal(SIGUSR1"sig_handler");

// ou bien utilisez un objet (disponible depuis PHP 4.3.0)
// pcntl_signal(SIGUSR1, array($obj, "faire_quelque_chose"));

echo"Génération d'un signal SIGTERM à moi-même...\n";

// envoi de SIGUSR1 à l'identifiant de processus courant
posix_kill(posix_getpid(), SIGUSR1);

echo 
"Fait\n";

?>

Notes

La fonction pcntl_signal() ne place pas dans une pile les gestionnaires de signaux, mais les remplace.

Voir aussi

add a note add a note

User Contributed Notes 22 notes

up
10
Zsolt Szilagyi
1 year ago
Remember that declaring a tick handler can become really expensive in terms of CPU cycles: Every n ticks the signal handling overhead will be executed.

So instead of declaring tick=1, test if tick=100 can do the job. If so, you are likely to gain fivefold speed.

As your script might always might miss some signals due to blocking operations like cURL downloads, call pcntl_signal_dispatch() on vital spots, e.g. at the beginning of your main loop.
up
6
webmaster at ajeux dot com
4 years ago
For PHP >= 5.3.0, instead of declare(ticks = 1), you should now use pcntl_ signal_ dispatch().
up
1
S. Kr@cK
2 years ago
static class method to get the name of a process signal as string:

(self::$processSignalDescriptions is used to cache the results)

<?php
   
public static function getPOSIXSignalText($signo) {

        try {
            if (
is_null(self::$processSignalDescriptions)) {

               
self::$processSignalDescriptions = array();

               
$signal_list = explode(" ", trim(shell_exec("kill -l")));
                foreach (
$signal_list as $key => $value) {
                   
self::$processSignalDescriptions[$key+1] = "SIG".$value;
                }
            }

            return isset(
self::$processSignalDescriptions[$signo])?self::$processSignalDescriptions[$signo]:"UNKNOWN";

        } catch (
Exception $e) {}

        return
"UNKNOWN";
    }
?>
up
2
rbotzer at yahoo dot com
6 years ago
You cannot assign a signal handler for SIGKILL (kill -9).
up
1
rob at robertjohnkaper dot com
7 years ago
Tip: when using objects, don't set the signal handler from the constructor or even a method called from the constructor - your internal variables will be uninitialised.
up
1
frustrated at outdated docs
4 months ago
Please be aware that declaring ticks or calling pcntl_signal_dispatch() in 5.3 and later is required to make pcntl_signal do anything useful. I wish the documentation made this more clear.
up
1
benjamin at josefus dot /NO+SPAM/ net
5 years ago
Since php >= 5.3 handles Closures, you are now able to define the Callback directly.
Try this:

<?php
declare(ticks = 1);

pcntl_signal(SIGUSR1, function ($signal) {
            echo
'HANDLE SIGNAL ' . $signal . PHP_EOL;
});

posix_kill(posix_getpid(), SIGUSR1);

die;
?>
up
0
Aurelien Marchand
3 years ago
I was having some issues with processing a signal using an object method I use for something else as well. In particular, I wanted to handle SIGCHLD with my own method "do_reap()" which I also call after a stream_select timeout and that uses a non-blocking pcntl_waitpid function.

The method was called when the signal was received but it couldn't reap the child.

The only way it worked was by creating a new handler that itself called do_reap().

So in other words, the following does not work:

<?php
class Parent {
 
/* ... */
 
private function do_reap(){
   
$p = pcntl_waitpid(-1,$status,WNOHANG);
    if(
$p > 0){
      echo
"\nReaped zombie child " . $p;
    }

   public function
run(){
   
/* ... */
   
pcntl_signal(SIGCHLD,array(&$this,"do_reap"));
   
$readable = @stream_select($read,$null,$null,5); // 5 sec timeout
   
if($readable === 0){
     
// we got a timeout
     
$this->do_reap();
   }
}
?>

But this work:

<?php
class Parent {
 
/* ... */
 
private function do_reap(){
   
$p = pcntl_waitpid(-1,$status,WNOHANG);
    if(
$p > 0){
      echo
"\nReaped zombie child " . $p;
    }

   public function
run(){
   
/* ... */
   
pcntl_signal(SIGCHLD,array(&$this,"child_died"));
   
$readable = @stream_select($read,$null,$null,5); // 5 sec timeout
   
if($readable === 0){
     
// we got a timeout
     
$this->do_reap();
   }

    private function
child_died(){
     
$this->do_reap();
    }
}
?>
up
0
ewout dot NOSPAM dot zigterman at custosys dot nl
5 years ago
I found out then when you use pcntl_signal in a 'deamon' script and you run it before you fork childs it does not work as expected.

instead you need to use pcntl_signal in the child code of the child you are forking

and if you want to cach signals for the 'deamon' part you should use pcntl_signal in the parent code.
up
0
seong at respice dot net
5 years ago
Be careful, when using an object in your callback. It seems this elevates the reference count. You may not want it to happen in repeated child processes.
up
0
Anonymous
6 years ago
Multiple children return less than the number of children exiting at a given moment SIGCHLD signals is normal behavior for Unix (POSIX) systems.  SIGCHLD might be read as "one or more children changed status -- go examine your children and harvest their status values".  Signals are implemented as bit masks in most Unix systems, so there can only be 1 SIGCHLD bit set in any given kernel tick for a process.
up
0
anxious2006
6 years ago
Under my setup (FreeBSD 6.2-RELEASE / PHP 5.2.4 CLI) I've noticed that when a child exits the SIGCHLD handler in the parent is not always invoked. It seems to happen when two children exit near simultaneously.

In this instance the child prints "EXIT" and the parent prints "SIGCHLD received":

- EXIT
- SIGCHLD received

This works as expected, but now look what happens when three exit in quick succession:

- EXIT
- EXIT
- EXIT
- SIGCHLD received
- SIGCHLD received

Because of this quirk any code which tries to limit the maximum number of children by incrementing on fork and decrementing on SIGCHLD will eventually end up with a single child (or no further forks), since the "active children" count is always above the maximum. I've noticed similar behaviour with using decrement after pcntl_wait(). Hopefully there's a workaround for this.
up
0
nate at example dot com
7 years ago
If you have a script that needs certain sections to not be interrupted by a signal (especially SIGTERM or SIGINT), but want to make your script ready to process that signal ASAP, there's only one way to do it. Flag the script as having received the signal, and wait for your script to say its ready to process it.

Here's a sample script:

<?
    $allow_exit = true;  // are we permitting exit?
    $force_exit = false; // do we need to exit?

    declare(ticks = 1);
    register_tick_function('check_exit');
    pcntl_signal(SIGTERM, 'sig_handler');
    pcntl_signal(SIGINT, 'sig_handler');

    function sig_handler () {
        global $allow_exit, $force_exit;

        if ($allow_exit)
            exit;
        else
            $force_exit = true;
    }

    function check_exit () {
        global $allow_exit, $force_exit;

        if ($force_exit && $allow_exit)
            exit;
    }

    $allow_exit = false;

    $i = 0;
    while (++$i) {
        echo "still going (${i})\n";
        if ($i == 10)
            $allow_exit = true;

        sleep(2);
    }
?>

You set $allow_exit to true at all times when it is perfectly acceptable that your script could exit without warning. In sections where you really need the script to continue running, you set $allow_exit to false. Any signals received while $allow_exit is false will not take effect until you set $allow_exit to true.

<?
    $allow_exit = true;

    // unimportant stuff here. exiting will not harm anything

    $allow_exit = false;

    // really important stuff not to be interrupted

    $allow_exit = true;

    // more unimportant stuff. if signal was received during
    // important processing above, script will exit here
?>
up
0
imslushie at hotmaildotcom dot com
7 years ago
I have been having trouble reaping my child process. It seemed most of the time, children were reaped properly but *sometimes* they would stay as zombies. I was catching the CHLD signal to reap child processes with the following code:

<?php

function childFinished($signal)
{
  global
$kids;
 
$kids--;
 
pcntl_waitpid(-1, $status);
}

$kids = 0;
pcntl_signal(SIGCHLD, "childFinished");
for (
$i = 0; $i < 1000; $i++)
{
  while (
$kids >= 50) sleep(1);
 
 
$pid = pcntl_fork();
  if (
$pid == -1) die('failed to fork :(');

 
/* child process */
 
if ($pid == 0)
  {
   
/* do something */
   
exit(0);
  }

 
/* parent */
 
else { $kids++; }
}

/* when finished, just clean up the children */
print "Reaping $kids children...\n";
while (
$kids) sleep(1);

print
"Finished.\n";
?>

The problem was, $kids never became zero so it would effectively wait forever. After wracking my brains (UNIX forks are new to me) I finally read the Perl IPC docs and viola, a solution! It turns out that because signal handlers are not re-entrant, my handler will not be called again while it is in use. The scenario that caused me trouble was that one child would exit and call the signal handler, which would pcntl_waitpid() it and decrement the counter. Meanwhile, another child would exit while the first child was still being reaped,  so the second would never get to notify the parent!

The solution was to continually reap children from the SIGCHLD handler, so long as there were children to reap. Here is the *fixed* childFinished function:

<?php

function childFinished($signal)
{
  global
$kids;

  while(
pcntl_waitpid(-1, $status, WNOHANG) > 0 )
   
$kids--;
}

?>
up
0
aeolianmeson at NOSPAXM dot blitzeclipse dot com
8 years ago
This issue occurs in at least PHP 5.1.2.

When a SIGINT is sent via CTRL+C or CTRL+BREAK, the handler is called. If this handler sends a SIGTERM to other children, the signals are not received.

SIGINT can be sent via posix_kill() and it work exactly as expected-- This only applies when initiated via a hard break.
up
0
aeolianmeson at NOSPAM dot blitzeclipse dot com
8 years ago
In at least version 5.1.4, the parameter passed to the handler is not a strict integer.

I have had such problems as trying to add the signal to an array, but the array is completely screwed up when viewed (but not viewed immediately after being added). This occurs when the handler is a method (array($this, 'methodname')), or a traditional functions.

To avoid this bug, typecast the parameter to an integer:
(note that each newline may appear to just be 'n'.)

<?php
print("pid= " . posix_getpid() . "\n");
declare(
ticks=1);
$arrsignals = array();

function
handler($nsig)
{
    global
$arrsignals;
   
$arrsignals[] = (int)$nsig;
    print(
"Signal caught and registered.\n");
   
var_dump($arrsignals);
}

pcntl_signal(SIGTERM, 'handler');

// Wait for signals from the command-line (just a simple 'kill (pid)').
$n = 15;
while(
$n)
{
   
sleep(1);
   
$n--;
}

print(
"terminated.\n\n");
var_dump($arrsignals);
?>

Dustin
up
0
zenyatta22 at hotmail
8 years ago
Process handling is not available when using a blocking socket! Bear this in mind.
up
0
wm161 at wm161 dot net
8 years ago
When you are running a script inside of a loop that checks a socket, and it hangs on that checking (Either by flaw or design), it can't handle signals until some data is received.

A suggested workaround would be to use the stream_set_blocking function, or stream_select on the offending reads.
up
0
codeslinger at compsalot dot com
9 years ago
I ran into an interesting problem. CLI 4.3.10 Linux

The parent forked a child.  The child did a bunch of stuff, and when it was done it sent SIGUSR1 to the parent and immediately exited.

Result:
The child turned into a zombie process waiting for the parent to harvest it, as it should.

But the parent was unable to harvest the child because it was receiving an endless barrage of SIGUSR1s.  In fact, it logged over 200000 before I shut it down (SIGKILL).  The parent was not able to do anything else (respond to other events) during that time.

No, it wasn't a bug in my child code.  Apparently, after sending a signal there is some "behind the covers" work that needs to occur to acknowledge signal completion, and when you exit immediately it is not able to happen, so the system just keeps trying.

Solution:  I introduced a small delay in the child, after sending the signal, and before exiting. 
No more Sig loops...

----------

P.S.  With respect to the note below.  The whole point of the sleep function is to enable the processing of other events.  So, yes, your non-renterent code, will suddenly get re-entered when you do a sleep, because you have just handed off control to the next pending event.

Ignoring the signal is only an option if the signal is unimportant to your program....   The better way to approach it, is to not do lengthy processing inside of the signal event.  Instead set a global flag and get the heck out of there as fast as possible.  Allow another part of your program to check the flag and do the processing outside of the signal event.  Usually your program is in some kind of loop when it is receiving signals, so checking a flag regularly shouldn't be a problem.
up
0
ieure at php dot net
9 years ago
Some weird signal interactions going on here. I'm running PHP 4.3.9.

sleep() calls seem to be interrupted when any signal is received by the PHP script. But things get weird when you sleep() inside a signal handler.

Ordinarily, signal handlers are non-reentrant. That is, if the signal handler is running, sending another signal has no effect. However, sleep() seems to override PHP's signal handling. If you sleep() inside a signal handler, the signal is received and the sleep() is interrupted.

This can be worked around like this:

function handler($signal)
{
    // Ignore this signal
    pcntl_signal($signal, SIG_IGN);

    sleep(10);

    // Reinstall signal handler
    pcntl_signal($signal, __FUNCTION__);
}

I don't see any mention of this behavior in the documentation.
up
0
daniel[at]lorch.cc
12 years ago
There are two documents I consider reading:

  Unix Signals Programming
  http://users.actcom.co.il/~choo/lupg/tutorials/

  Beej's Guide to Unix Interprocess Communication
  http://www.ecst.csuchico.edu/~beej/guide/ipc/

Also, have a look at the manpage:

  http://www.mcsr.olemiss.edu/cgi-bin/man-cgi?signal+5
up
-1
Holger Hees
6 years ago
you should use following code to prevent situation described by anxious2006 (children exit near simultaneously)

public function sig_handler($signo){
  switch ($signo) {
    case SIGCLD:
      while( ( $pid = pcntl_wait ( $signo, WNOHANG ) ) > 0 ){
        $signal = pcntl_wexitstatus ( $signo );
      }
      break;
  }
}
To Top