]>
Commit | Line | Data |
---|---|---|
a0d39abb MK |
1 | .\" Copyright (C) 2008 Michael Kerrisk <tmk.manpages@gmail.com> |
2 | .\" and Copyright 2003 Abhijit Menon-Sen <ams@wiw.org> | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" 2004-05-31, added tgkill, ahu, aeb | |
9d8d2b61 | 27 | .\" 2008-01-15 mtk -- rewrote DESCRIPTION |
fea681da | 28 | .\" |
63121bd4 | 29 | .TH TKILL 2 2019-08-02 "Linux" "Linux Programmer's Manual" |
fea681da | 30 | .SH NAME |
a0d39abb | 31 | tkill, tgkill \- send a signal to a thread |
fea681da MK |
32 | .SH SYNOPSIS |
33 | .nf | |
c12fd10d | 34 | .BI "int tkill(int " tid ", int " sig ); |
68e4db0a | 35 | .PP |
c12fd10d | 36 | .BI "int tgkill(int " tgid ", int " tid ", int " sig ); |
fea681da | 37 | .fi |
dbfe9c70 | 38 | .PP |
45c99e3e | 39 | .IR Note : |
4c63ee20 MK |
40 | There is no glibc wrapper for |
41 | .BR tkill (); | |
42 | see NOTES. | |
fea681da | 43 | .SH DESCRIPTION |
60a90ecd | 44 | .BR tgkill () |
a0d39abb MK |
45 | sends the signal |
46 | .I sig | |
47 | to the thread with the thread ID | |
48 | .I tid | |
49 | in the thread group | |
50 | .IR tgid . | |
51 | (By contrast, | |
52 | .BR kill (2) | |
33a0ccb2 | 53 | can be used to send a signal only to a process (i.e., thread group) |
a0d39abb MK |
54 | as a whole, and the signal will be delivered to an arbitrary |
55 | thread within that process.) | |
efeece04 | 56 | .PP |
60a90ecd | 57 | .BR tkill () |
a0d39abb MK |
58 | is an obsolete predecessor to |
59 | .BR tgkill (). | |
33a0ccb2 | 60 | It allows only the target thread ID to be specified, |
a0d39abb MK |
61 | which may result in the wrong thread being signaled if a thread |
62 | terminates and its thread ID is recycled. | |
63 | Avoid using this system call. | |
bea08fec | 64 | .\" FIXME Maybe say something about the following: |
c4b7c8da | 65 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12889 |
36127c0e | 66 | .\" |
eec5c0d0 | 67 | .\" Quoting Rich Felker <bugdal@aerifal.cx>: |
36127c0e | 68 | .\" |
eec5c0d0 MK |
69 | .\" There is a race condition in pthread_kill: it is possible that, |
70 | .\" between the time pthread_kill reads the pid/tid from the target | |
71 | .\" thread descriptor and the time it makes the tgkill syscall, | |
72 | .\" the target thread terminates and the same tid gets assigned | |
73 | .\" to a new thread in the same process. | |
36127c0e | 74 | .\" |
eec5c0d0 MK |
75 | .\" (The tgkill syscall was designed to eliminate a similar race |
76 | .\" condition in tkill, but it only succeeded in eliminating races | |
77 | .\" where the tid gets reused in a different process, and does not | |
78 | .\" help if the same tid gets assigned to a new thread in the | |
79 | .\" same process.) | |
80 | .\" | |
81 | .\" The only solution I can see is to introduce a mutex that ensures | |
82 | .\" that a thread cannot exit while pthread_kill is being called on it. | |
83 | .\" | |
84 | .\" Note that in most real-world situations, like almost all race | |
85 | .\" conditions, this one will be extremely rare. To make it | |
86 | .\" measurable, one could exhaust all but 1-2 available pid values, | |
87 | .\" possibly by lowering the max pid parameter in /proc, forcing | |
88 | .\" the same tid to be reused rapidly. | |
efeece04 | 89 | .PP |
fea681da MK |
90 | These are the raw system call interfaces, meant for internal |
91 | thread library use. | |
47297adb | 92 | .SH RETURN VALUE |
c13182ef MK |
93 | On success, zero is returned. |
94 | On error, \-1 is returned, and \fIerrno\fP | |
fea681da MK |
95 | is set appropriately. |
96 | .SH ERRORS | |
97 | .TP | |
f5a0865d JH |
98 | .B EAGAIN |
99 | The | |
100 | .B RLIMIT_SIGPENDING | |
101 | resource limit was reached and | |
102 | .I sig | |
103 | is a real-time signal. | |
104 | .TP | |
105 | .B EAGAIN | |
106 | Insufficient kernel memory was available and | |
107 | .I sig | |
108 | is a real-time signal. | |
49a2a105 MK |
109 | .TP |
110 | .B EINVAL | |
111 | An invalid thread ID, thread group ID, or signal was specified. | |
112 | .TP | |
113 | .B EPERM | |
114 | Permission denied. | |
115 | For the required permissions, see | |
116 | .BR kill (2). | |
117 | .TP | |
118 | .B ESRCH | |
119 | No process with the specified thread ID (and thread group ID) exists. | |
2dd578fd MK |
120 | .SH VERSIONS |
121 | .BR tkill () | |
122 | is supported since Linux 2.4.19 / 2.5.4. | |
123 | .BR tgkill () | |
124 | was added in Linux 2.5.75. | |
4c63ee20 MK |
125 | .PP |
126 | Library support for | |
127 | .BR tgkill () | |
128 | was added to glibc in version 2.30. | |
47297adb | 129 | .SH CONFORMING TO |
60a90ecd MK |
130 | .BR tkill () |
131 | and | |
132 | .BR tgkill () | |
8382f16d | 133 | are Linux-specific and should not be used |
fea681da | 134 | in programs that are intended to be portable. |
c12fd10d | 135 | .SH NOTES |
a0d39abb MK |
136 | See the description of |
137 | .B CLONE_THREAD | |
138 | in | |
139 | .BR clone (2) | |
140 | for an explanation of thread groups. | |
efeece04 | 141 | .PP |
4c63ee20 MK |
142 | Glibc does not provide a wrapper for |
143 | .BR tkill (); | |
144 | call it using | |
c12fd10d | 145 | .BR syscall (2). |
4c63ee20 MK |
146 | Before glibc 2.30, there was also no wrapper function for |
147 | .BR tgkill (). | |
47297adb | 148 | .SH SEE ALSO |
a0d39abb MK |
149 | .BR clone (2), |
150 | .BR gettid (2), | |
4a19d2ac MK |
151 | .BR kill (2), |
152 | .BR rt_sigqueueinfo (2) |