pthread_kill() — Send a signal to a thread

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.4a Single UNIX Specification, Version 3	both	POSIX(ON)

Format

#define _OPEN_THREADS
#include <pthread.h>
#include <signal.h>

int pthread_kill(pthread_t thread, int sig);

SUSV3:

#define _UNIX03_THREADS
#include <signal.h> 

int pthread_kill(pthread_t thread, int sig);

General description

Directs a signal sig to the thread thread. The value of sig must be either 0 or one of the symbols defined in signal.h. (See Table 1 for a list of signals.) If sig is 0, pthread_kill() performs error checking but does not send a signal.

pthread_t is the data type used to uniquely identify a thread. It is returned by pthread_create() and used by the application in function calls that require a thread identifier.

Special behavior for C++: If a thread is sent a signal using pthread_kill() and that thread does not handle the signal, then destructors for local objects may not be executed.

Usage notes

The SIGTHSTOP and SIGTHCONT signals can be issued by this function. pthread_kill() is the only function that can issue SIGTHSTOP or SIGTHCONT.

Returned value

If successful, pthread_kill() returns 0.

If unsuccessful, pthread_kill() returns -1 sends no signal, and sets errno to one of the following values:

Error Code

Description

EINVAL

One of the following error conditions exists:

The thread ID specified by thread is not valid.
The value of sig is incorrect or is not the number of a supported signal.

ESRCH

No thread could be found corresponding to that specified by the given thread ID.

Special behavior for Single UNIX Specification, Version 3: If unsuccessful, pthread_kill() returns an error number to indicate the error.

Example

CELEBP35

/* CELEBP35 */                                   
#define _OPEN_THREADS                                                           
                                                                                
#include <errno.h>                                                              
#include <pthread.h>                                                            
#include <signal.h>                                                             
#include <stdio.h>                                                              
#include <unistd.h>                                                             
                                                                                
void            *threadfunc(void *parm)                                         
{                                                                               
 int        threadnum;                                                          
 int        *tnum;                                                              
 sigset_t   set;                                                                
                                                                                
 tnum = parm;                                                                   
 threadnum = *tnum;                                                             
                                                                                
 printf("Thread %d executing\n", threadnum);                                    
 sigemptyset(&set);                                                             
 if(sigaddset(&set, SIGUSR1) == -1) {                                           
    perror("Sigaddset error");                                                  
    pthread_exit((void *)1);                                                    
 }                                                                              
                                                                                
 if(sigwait(&set) != SIGUSR1) {                                                 
    perror("Sigwait error");                                                    
    pthread_exit((void *)2);                                                    
 }                                                                              
                                                                                
 pthread_exit((void *)0);                                                       
}                                                                               
                                                                                
main() {                                                                        
 int          status;                                                           
 int          threadparm = 1;                                                   
 pthread_t    threadid;                                                         
 int          thread_stat;                                                      
                                                                                
 status = pthread_create( &threadid,                                            
                          NULL,                                                 
                          threadfunc,                                           
                          (void *)&threadparm);                                 
 if ( status <  0) {                                                            
    perror("pthread_create failed");                                            
    exit(1);                                                                    
 }                                                                              
                                                                                
 sleep(5);                                                                      
                                                                                
 status = pthread_kill( threadid, SIGUSR1);                                     
 if ( status <  0)                                                              
    perror("pthread_kill failed");                                              
                                                                                
 status = pthread_join( threadid, (void *)&thread_stat);                        
 if ( status <  0)                                                              
    perror("pthread_join failed");                                              
                                                                                
 exit(0);                                                                       
}