man3/pthread_kill.3

   1 '\" t
   2 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH pthread_kill 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 pthread_kill \- send a signal to a thread
  10 .SH LIBRARY
  11 POSIX threads library
  12 .RI ( libpthread ", " \-lpthread )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <signal.h>
  16 .P
  17 .BI "int pthread_kill(pthread_t " thread ", int " sig );
  18 .fi
  19 .P
  20 .RS -4
  21 Feature Test Macro Requirements for glibc (see
  22 .BR feature_test_macros (7)):
  23 .RE
  24 .P
  25 .BR pthread_kill ():
  26 .nf
  27     _POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500
  28 .fi
  29 .SH DESCRIPTION
  30 The
  31 .BR pthread_kill ()
  32 function sends the signal
  33 .I sig
  34 to
  35 .IR thread ,
  36 a thread in the same process as the caller.
  37 The signal is asynchronously directed to
  38 .IR thread .
  39 .P
  40 If
  41 .I sig
  42 is 0, then no signal is sent, but error checking is still performed.
  43 .SH RETURN VALUE
  44 On success,
  45 .BR pthread_kill ()
  46 returns 0;
  47 on error, it returns an error number, and no signal is sent.
  48 .SH ERRORS
  49 .TP
  50 .B EINVAL
  51 An invalid signal was specified.
  52 .SH ATTRIBUTES
  53 For an explanation of the terms used in this section, see
  54 .BR attributes (7).
  55 .TS
  56 allbox;
  57 lbx lb lb
  58 l l l.
  59 Interface       Attribute       Value
  60 T{
  61 .na
  62 .nh
  63 .BR pthread_kill ()
  64 T}      Thread safety   MT-Safe
  65 .TE
  66 .SH VERSIONS
  67 The glibc implementation of
  68 .BR pthread_kill ()
  69 gives an error
  70 .RB ( EINVAL )
  71 on attempts to send either of the real-time signals
  72 used internally by the NPTL threading implementation.
  73 See
  74 .BR nptl (7)
  75 for details.
  76 .P
  77 POSIX.1-2008 recommends that if an implementation detects the use
  78 of a thread ID after the end of its lifetime,
  79 .BR pthread_kill ()
  80 should return the error
  81 .BR ESRCH .
  82 The glibc implementation returns this error in the cases where
  83 an invalid thread ID can be detected.
  84 But note also that POSIX says that an attempt to use a thread ID whose
  85 lifetime has ended produces undefined behavior,
  86 and an attempt to use an invalid thread ID in a call to
  87 .BR pthread_kill ()
  88 can, for example, cause a segmentation fault.
  89 .SH STANDARDS
  90 POSIX.1-2008.
  91 .SH HISTORY
  92 POSIX.1-2001.
  93 .SH NOTES
  94 Signal dispositions are process-wide:
  95 if a signal handler is installed,
  96 the handler will be invoked in the thread
  97 .IR thread ,
  98 but if the disposition of the signal is "stop", "continue", or "terminate",
  99 this action will affect the whole process.
 100 .SH SEE ALSO
 101 .BR kill (2),
 102 .BR sigaction (2),
 103 .BR sigpending (2),
 104 .BR pthread_self (3),
 105 .BR pthread_sigmask (3),
 106 .BR raise (3),
 107 .BR pthreads (7),
 108 .BR signal (7)