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);
#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.
- 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 */
#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);
}
Related information
- pthread.h — Thread interfaces
- signal.h — Exception handling
- bsd_signal() — BSD version of signal()
- kill() — Send a signal to a process
- killpg() — Send a signal to a process group
- pthread_self() — Get the caller
- raise() — Raise signal
- sigaction() — Examine or change a signal action
- sighold() — Add a signal to a thread
- sigignore() — Set disposition to ignore a signal
- signal() — Handle interrupts
- sigprocmask() — Examine or change a thread
- sigrelse() — Remove a signal from a thread
- sigset() — Change a signal action or a thread