kill() — Send a signal to a process

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.1 XPG4 XPG4.2 Single UNIX Specification, Version 3	both	POSIX(ON)

Format

#define _POSIX_SOURCE
#include <signal.h>

int kill(pid_t pid, int sig);

General description

Sends a signal to a process or process group. A process has permission to send a signal if the real or effective user ID of the sender is the same as the real or effective user ID of the intended recipient. A process can also send signals if it has appropriate privileges. If _POSIX_SAVED_IDS is defined in the unistd.h header file, the saved set user ID of the intended recipient is checked instead of its effective user ID.

Regardless of user ID, a process can always send a SIGCONT signal to a process that is a member of the same session (same session ID) as the sender.

You can use either signal() or sigaction() to specify how a signal will be handled when kill() is invoked.

A process can use kill() to send a signal to itself. If the signal is not blocked or ignored, at least one pending unblocked signal is delivered to the sender before kill() returns. If there are no other pending unblocked signals, the delivered signal is sig.

pid can be used to specify these processes:

pid_t pid;

Specifies the processes that the caller wants to send a signal to:

If pid is greater than 0, kill() sends its signal to the process whose ID is equal to pid.
If pid is equal to 0, kill() sends its signal to all processes whose process group ID is equal to that of the sender, except for those that the sender does not have appropriate privileges to send a signal to.
If pid is -1, kill() returns -1.
Special behavior for XPG4.2: If pid is -1, kill() sends the signal, sig, to all processes, except for those to which the sender does not have appropriate privileges to send a signal.
If pid is less than -1, kill() sends its signal to all processes whose process group ID is equal to the absolute value of pid, except for those that the sender does not have appropriate privileges to send a signal to.

int sig;

The signal that should be sent to the processes specified by pid. (For a list of signals, see Table 1.) This must be 0 or one of the signals defined in the signal.h header file. If sig is 0, kill() performs error checking but does not send a signal. You can code sig as 0 to check whether the pid argument is valid.

This function is supported only in a POSIX program. You can use it to pass SIGIOERR.

Usage notes

The use of the SIGTHSTOP and SIGTHCONT signal is not supported with this function.

Returned value

kill() returns 0 if it has permission to send sig to any of the processes specified by pid.

If kill() fails to send a signal, it returns -1 and sets errno to one of the following values:

Error Code: Description
EINVAL: The value of sig is incorrect or is not the number of a supported signal.
EPERM: The caller does not have permission to send the signal to any process specified by pid.
ESRCH: There are no processes or process groups corresponding to pid.

Example

CELEBK01

⁄* CELEBK01 *⁄
#define _POSIX_SOURCE
#include <signal.h>
#include <stdio.h>
#include <sys⁄types.h>
#include <unistd.h>
#include <sys⁄wait.h> ⁄*FIX: used to be <wait.h>*⁄

main() {
  sigset_t sigset;
  int    p[2], status;
  char   c='z';
  pid_t  pid;

  if (pipe(p) != 0)
    perror("pipe() error");
  else {
    if ((pid = fork()) == 0) {
      sigemptyset(&sigset);
      puts("child is letting parent know he's ready for signal");
      write(p[1], &c, 1);
      puts("child is waiting for signal");
      sigsuspend(&sigset);
      exit(0);
    }

    puts("parent is waiting for child to say he's ready for signal");
    read(p[0], &c, 1);
    puts("child has told parent he's ready for signal");

    kill(pid, SIGTERM);

    wait(&status);
    if (WIFSIGNALED(status))
      if (WTERMSIG(status) == SIGTERM)
        puts("child was ended with a SIGTERM");
      else
        printf("child was ended with a %d signal\n", WTERMSIG(status));
    else puts("child was not ended with a signal");

    close(p[0]);
    close(p[1]);
  }
}

Output

parent is waiting for child to say he's ready for signal
child is letting parent know he's ready for signal
child is waiting for signal
child has told parent he's ready for signal
child was ended with a SIGTERM