pcntl_signal

Description

bool pcntl_signal ( int signo, callback handle [, bool restart_syscalls] )

The pcntl_signal() function installs a new signal handler for the signal indicated by signo. The signal handler is set to handler which may be the name of a user created function, or either of the two global constants SIG_IGN or SIG_DFL. The optional restart_syscalls specifies whether system call restarting should be used when this signal arrives and defaults to TRUE.

如果成功则返回 TRUE，失败则返回 FALSE。

注: The optional restart_syscalls parameter became available in PHP 4.3.0.

注: The ability to use an object method as a callback became available in PHP 4.3.0. Note that when you set a handler to an object method, that object's reference count is increased which makes it persist until you either change the handler to something else, or your script ends.

例子 1. pcntl_signal() example


<?php
// tick use required as of PHP 4.3.0
declare(ticks = 1);

// signal handler function
function sig_handler($signo) 
{

     switch ($signo) {
         case SIGTERM:
             // handle shutdown tasks
             exit;
             break;
         case SIGHUP:
             // handle restart tasks
             break;
         case SIGUSR1:
             echo "Caught SIGUSR1...\n";
             break;
         default:
             // handle all other signals
     }

}

echo "Installing signal handler...\n";

// setup signal handlers
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGHUP,  "sig_handler");
pcntl_signal(SIGUSR1, "sig_handler");

// or use an object, available as of PHP 4.3.0
// pcntl_signal(SIGUSR1, array($obj, "do_something");

echo"Generating signal SIGTERM to self...\n";

// send SIGUSR1 to current process id
posix_kill(posix_getpid(), SIGUSR1);

echo "Done\n"

?>

注: As of PHP 4.3.0 PCNTL uses ticks as the signal handle callback mechanism, which is much faster than the previous mechanism. This change follows the same semantics as using "user ticks". You must use the declare() statement to specify the locations in your program where callbacks are allowed to occur for the signal handler to function properly (as used in the above example).

add a note User Contributed Notes

aeolianmeson at NOSPAXM dot blitzeclipse dot com
09-Jun-2006 04:19


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.

aeolianmeson at NOSPAM dot blitzeclipse dot com
30-May-2006 11:43


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

zenyatta22 at hotmail
29-Mar-2006 06:26


Process handling is not available when using a blocking socket! Bear this in mind.

sezer yalcin
12-Jan-2006 04:29


You should pay attention to this issue.



I realized "some" files need specific declare() where some do not.



It is good idea to include in all "main" files, not in include files.



junkmail at konvergencia dot hu

06-May-2003 04:21

It seems like the scope of declare() when used in it's new global form e.g.

  declare(ticks = 1);



is restricted to the file it is used in and the one's include() -ed or require() -ed by the script. So you can NOT do this:

wm161 at wm161 dot net
11-Jan-2006 07:45


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.

erik at phpcastle dot com
27-Dec-2005 07:46


When you want to stop a CLI script by a keyboard interupt then you should use SIGINT.



Example script:

#!/usr/bin/php5

<?php



// tick use required as of PHP 4.3.0

declare(ticks = 1);



// signal handler function

function sig_handler($signo)

{



         switch ($signo) {

                 case SIGINT:

                         // handle shutdown tasks

                         echo "Keyboard pressed...\n";

                         exit;

                         break;

                 default:

                         // handle all other signals

         }



}



echo "Installing signal handler...\n";



// setup signal handlers

pcntl_signal(SIGINT, "sig_handler");



// or use an object, available as of PHP 4.3.0

// pcntl_signal(SIGUSR1, array($obj, "do_something");



// Just a stupid simple loop

for ($i = 1; $i <= 10; $i++){

    echo ".";

    sleep(1);

    

}



echo "Done\n"



?>

codeslinger at compsalot dot com
04-Feb-2005 01:23


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.

ieure at php dot net
20-Jan-2005 09:15


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.

cp at ltur dot de
09-Dec-2004 06:21


@spam at etcpasswd dot de



Yes it is possible to use a Handler inside of a Class:



<?php

declare(ticks = 1);



class SignalHandler

{

    function __construct() {

        $this->_init();

    }

    function _init() {

        pcntl_signal(SIGTERM, array(&$this,"handleSignals"));

    }

    function handleSignals($signal)

    {

        echo "$signal\n";

    }



}

$o = new SignalHandler();

posix_kill(getmypid(),SIGTERM);

// prints 15

?>



HTH

.Ape

junkmail at konvergencia dot hu
06-May-2003 07:21


It seems like the scope of declare() when used in it's new global form e.g.

  declare(ticks = 1);



is restricted to the file it is used in and the one's include() -ed or require() -ed by the script. So you can NOT do this:



main.php:

<?php

 

  include ('signals.php');

 

  do_something_here();



?>



signals.php:

<?php



 declare(ticks = 1);



  function sig_handler($signo) {

     handle_the_signal_here();

  }



  pcntl_signal (SIGINT, 'sig_handler');



?>



Your signal handler function will not be called. In the above examples you have to declare() in the main.php file.

daniel[at]lorch.cc
28-Feb-2002 10:17


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

add a note