]>
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 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
5 | .\" |
6 | .\" 2004-05-31, added tgkill, ahu, aeb | |
9d8d2b61 | 7 | .\" 2008-01-15 mtk -- rewrote DESCRIPTION |
fea681da | 8 | .\" |
4c1c5274 | 9 | .TH tkill 2 (date) "Linux man-pages (unreleased)" |
fea681da | 10 | .SH NAME |
a0d39abb | 11 | tkill, tgkill \- send a signal to a thread |
c94c1b95 AC |
12 | .SH LIBRARY |
13 | Standard C library | |
8fc3b2cf | 14 | .RI ( libc ", " \-lc ) |
fea681da MK |
15 | .SH SYNOPSIS |
16 | .nf | |
d96a43d4 AC |
17 | .BR "#include <signal.h>" " /* Definition of " SIG* " constants */" |
18 | .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" | |
19 | .B #include <unistd.h> | |
c6d039a3 | 20 | .P |
ba8a0d11 | 21 | .BI "[[deprecated]] int syscall(SYS_tkill, pid_t " tid ", int " sig ); |
c6d039a3 | 22 | .P |
d96a43d4 | 23 | .B #include <signal.h> |
c6d039a3 | 24 | .P |
85ac0753 | 25 | .BI "int tgkill(pid_t " tgid ", pid_t " tid ", int " sig ); |
fea681da | 26 | .fi |
c6d039a3 | 27 | .P |
45c99e3e | 28 | .IR Note : |
d96a43d4 AC |
29 | glibc provides no wrapper for |
30 | .BR tkill (), | |
31 | necessitating the use of | |
32 | .BR syscall (2). | |
fea681da | 33 | .SH DESCRIPTION |
60a90ecd | 34 | .BR tgkill () |
a0d39abb MK |
35 | sends the signal |
36 | .I sig | |
37 | to the thread with the thread ID | |
38 | .I tid | |
39 | in the thread group | |
40 | .IR tgid . | |
41 | (By contrast, | |
42 | .BR kill (2) | |
33a0ccb2 | 43 | can be used to send a signal only to a process (i.e., thread group) |
a0d39abb MK |
44 | as a whole, and the signal will be delivered to an arbitrary |
45 | thread within that process.) | |
c6d039a3 | 46 | .P |
60a90ecd | 47 | .BR tkill () |
a0d39abb MK |
48 | is an obsolete predecessor to |
49 | .BR tgkill (). | |
33a0ccb2 | 50 | It allows only the target thread ID to be specified, |
a0d39abb MK |
51 | which may result in the wrong thread being signaled if a thread |
52 | terminates and its thread ID is recycled. | |
53 | Avoid using this system call. | |
bea08fec | 54 | .\" FIXME Maybe say something about the following: |
c4b7c8da | 55 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12889 |
36127c0e | 56 | .\" |
eec5c0d0 | 57 | .\" Quoting Rich Felker <bugdal@aerifal.cx>: |
36127c0e | 58 | .\" |
eec5c0d0 MK |
59 | .\" There is a race condition in pthread_kill: it is possible that, |
60 | .\" between the time pthread_kill reads the pid/tid from the target | |
61 | .\" thread descriptor and the time it makes the tgkill syscall, | |
62 | .\" the target thread terminates and the same tid gets assigned | |
63 | .\" to a new thread in the same process. | |
36127c0e | 64 | .\" |
eec5c0d0 MK |
65 | .\" (The tgkill syscall was designed to eliminate a similar race |
66 | .\" condition in tkill, but it only succeeded in eliminating races | |
67 | .\" where the tid gets reused in a different process, and does not | |
68 | .\" help if the same tid gets assigned to a new thread in the | |
69 | .\" same process.) | |
70 | .\" | |
71 | .\" The only solution I can see is to introduce a mutex that ensures | |
72 | .\" that a thread cannot exit while pthread_kill is being called on it. | |
73 | .\" | |
74 | .\" Note that in most real-world situations, like almost all race | |
75 | .\" conditions, this one will be extremely rare. To make it | |
76 | .\" measurable, one could exhaust all but 1-2 available pid values, | |
77 | .\" possibly by lowering the max pid parameter in /proc, forcing | |
78 | .\" the same tid to be reused rapidly. | |
c6d039a3 | 79 | .P |
fea681da MK |
80 | These are the raw system call interfaces, meant for internal |
81 | thread library use. | |
47297adb | 82 | .SH RETURN VALUE |
c13182ef MK |
83 | On success, zero is returned. |
84 | On error, \-1 is returned, and \fIerrno\fP | |
f6a4078b | 85 | is set to indicate the error. |
fea681da MK |
86 | .SH ERRORS |
87 | .TP | |
f5a0865d JH |
88 | .B EAGAIN |
89 | The | |
90 | .B RLIMIT_SIGPENDING | |
91 | resource limit was reached and | |
92 | .I sig | |
93 | is a real-time signal. | |
94 | .TP | |
95 | .B EAGAIN | |
96 | Insufficient kernel memory was available and | |
97 | .I sig | |
98 | is a real-time signal. | |
49a2a105 MK |
99 | .TP |
100 | .B EINVAL | |
101 | An invalid thread ID, thread group ID, or signal was specified. | |
102 | .TP | |
103 | .B EPERM | |
104 | Permission denied. | |
105 | For the required permissions, see | |
106 | .BR kill (2). | |
107 | .TP | |
108 | .B ESRCH | |
109 | No process with the specified thread ID (and thread group ID) exists. | |
3113c7f3 | 110 | .SH STANDARDS |
4131356c AC |
111 | Linux. |
112 | .SH HISTORY | |
113 | .TP | |
60a90ecd | 114 | .BR tkill () |
4131356c AC |
115 | Linux 2.4.19 / 2.5.4. |
116 | .TP | |
60a90ecd | 117 | .BR tgkill () |
4131356c AC |
118 | Linux 2.5.75, |
119 | glibc 2.30. | |
c12fd10d | 120 | .SH NOTES |
a0d39abb MK |
121 | See the description of |
122 | .B CLONE_THREAD | |
123 | in | |
124 | .BR clone (2) | |
125 | for an explanation of thread groups. | |
47297adb | 126 | .SH SEE ALSO |
a0d39abb MK |
127 | .BR clone (2), |
128 | .BR gettid (2), | |
4a19d2ac MK |
129 | .BR kill (2), |
130 | .BR rt_sigqueueinfo (2) |