pcntl_signal

Installs a signal handler

&reftitle.description; `bool` `pcntl_signal` `int` `signal` ``callable``int```handler` `bool` `restart_syscalls`&true;

The `pcntl_signal` function installs a new signal handler or replaces the current signal handler for the signal indicated by `signal`.

&reftitle.parameters;

`signal`

- The signal number.

`handler`

- The signal handler. This may be either a `callable`, which will be invoked to handle the signal, or either of the two global constants `SIG_IGN` or `SIG_DFL`, which will ignore the signal or restore the default signal handler respectively.

  If a `callable` is given, it must implement the following signature:

  `void```handler`` `int` `signo` `mixed` `siginfo`

  `signal`

- The signal being handled.

`siginfo`

- If operating systems supports siginfo_t structures, this will be an array of signal information dependent on the signal.

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.

`restart_syscalls`

- Specifies whether system call restarting should be used when this signal arrives.

&reftitle.returnvalues;

&return.success;

&reftitle.changelog;

&Version; | &Description;
7.1.0 | As of PHP 7.1.0 the handler callback is given a second argument containing the siginfo of the specific signal. This data is only supplied if the operating system has the siginfo_t structure. If the OS does not implement siginfo_t NULL is supplied.

&reftitle.examples;

### `pcntl_signal` example

    <?php
    // tick use required
    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
    // pcntl_signal(SIGUSR1, array($obj, "do_something"));

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

    // send SIGUSR1 to current process id
    // posix_* functions require the posix extension
    posix_kill(posix_getpid(), SIGUSR1);

    echo "Done\n";

    ?>

&reftitle.notes;

`pcntl_signal` doesn't stack the signal handlers, but replaces them.

&reftitle.seealso;

- `pcntl_fork`
- `pcntl_waitpid`