pthread_kill()--Send Signal to Thread

 #include <pthread.h>
 #include <signal.h>
 int pthread_kill(pthread_t thread, int sig);   

The pthread_kill() function requests that the signal sig be delivered to the specified thread. The signal to be sent is specified by sig and is either zero or one of the signals from the list of defined signals in the <signal.h> header file. If sig is zero, error checking is performed, but no signal is sent to the target thread.

A thread can use pthread_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 pthread_kill() returns. If there are no other pending unblocked signals, the delivered signal is sig.

The pthread_kill() API in no way changes the effect or scope of a signal. Even though a signal can be sent to a specific thread using the pthread_kill() API, the behavior that occurs when the signal is delivered is unchanged.

For example, sending a SIGKILL signal to a thread using pthread_kill() ends the entire process, not simply the target thread. SIGKILL is defined to end the entire process, regardless of the thread it is delivered to, or how it is sent.

Authorities and Locks

None.

Parameters

thread

(Input) Pthread handle of the target thread

sig

(Input) The signal number to be delivered or zero to validate the pthread_t

Return Value

0

pthread_kill() was successful.

value

pthread_kill() was not successful. value is set to indicate the error condition.

Error Conditions

If pthread_kill() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

[ESRCH]

No thread could be found that matched the thread ID specified.

[EINVAL]

The value specified for the argument is not correct.

[ENOTSIGINIT]

The process is not enabled for signals.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_sigmask()--Set or Get Signal Mask
  
  
• pthread_signal_to_cancel_np()--Convert Signals to Cancel Requests

Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#define _MULTI_THREADED
#include <pthread.h>
#include <stdio.h>
#include <signal.h>
#include "check.h"

#define NUMTHREADS 3
void sighand(int signo);

void *threadfunc(void *parm)
{
  pthread_t             self = pthread_self();
  pthread_id_np_t       tid;
  int                   rc;

  pthread_getunique_np(&self, &tid);
  printf("Thread 0x%.8x %.8x entered\n", tid);
  errno = 0;
  rc = sleep(30);
  if (rc != 0 && errno == EINTR) {
    printf("Thread 0x%.8x %.8x got a signal delivered to it\n",
           tid);
    return NULL;
  }
  printf("Thread 0x%.8x %.8x did not get expected results! rc=%d, errno=%d\n",
         tid, rc, errno);
  return NULL;
}

int main(int argc, char **argv)
{
  int                     rc;
  int                     i;
  struct sigaction        actions;
  pthread_t               threads[NUMTHREADS];

  printf("Enter Testcase - %s\n", argv[0]);
 
  printf("Set up the alarm handler for the process\n");
  memset(&actions, 0, sizeof(actions));
  sigemptyset(&actions.sa_mask);
  actions.sa_flags = 0;
  actions.sa_handler = sighand;

  rc = sigaction(SIGALRM,&actions,NULL);
  checkResults("sigaction\n", rc);

  for(i=0; i<NUMTHREADS; ++i) {
    rc = pthread_create(&threads[i], NULL, threadfunc, NULL);
    checkResults("pthread_create()\n", rc);
  }

  sleep(3);
  for(i=0; i<NUMTHREADS; ++i) {
    rc = pthread_kill(threads[i], SIGALRM);
    checkResults("pthread_kill()\n", rc);
  }

  for(i=0; i<NUMTHREADS; ++i) {
    rc = pthread_join(threads[i], NULL);
    checkResults("pthread_join()\n", rc);
  }
  printf("Main completed\n");
  return 0;
}

void sighand(int signo)
{
  pthread_t             self = pthread_self();
  pthread_id_np_t       tid;
 
  pthread_getunique_np(&self, &tid);
  printf("Thread 0x%.8x %.8x in signal handler\n",
         tid);
  return;
}

Output:

Enter Testcase - QP0WTEST/TPKILL0
Set up the alarm handler for the process
Thread 0x00000000 0000000c entered
Thread 0x00000000 0000000d entered
Thread 0x00000000 0000000e entered
Thread 0x00000000 0000000c in signal handler
Thread 0x00000000 0000000c got a signal delivered to it
Thread 0x00000000 0000000d in signal handler
Thread 0x00000000 0000000d got a signal delivered to it
Thread 0x00000000 0000000e in signal handler
Thread 0x00000000 0000000e got a signal delivered to it
Main completed

[ Back to top | Pthread APIs | APIs by category ]