]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright (C) 2008 Michael Kerrisk <tmk.manpages@gmail.com> | |
2 | .\" and Copyright 2003 Abhijit Menon-Sen <ams@wiw.org> | |
3 | .\" | |
4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft | |
5 | .\" | |
6 | .\" 2004-05-31, added tgkill, ahu, aeb | |
7 | .\" 2008-01-15 mtk -- rewrote DESCRIPTION | |
8 | .\" | |
9 | .TH tkill 2 (date) "Linux man-pages (unreleased)" | |
10 | .SH NAME | |
11 | tkill, tgkill \- send a signal to a thread | |
12 | .SH LIBRARY | |
13 | Standard C library | |
14 | .RI ( libc ", " \-lc ) | |
15 | .SH SYNOPSIS | |
16 | .nf | |
17 | .BR "#include <signal.h>" " /* Definition of " SIG* " constants */" | |
18 | .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" | |
19 | .B #include <unistd.h> | |
20 | .P | |
21 | .BI "[[deprecated]] int syscall(SYS_tkill, pid_t " tid ", int " sig ); | |
22 | .P | |
23 | .B #include <signal.h> | |
24 | .P | |
25 | .BI "int tgkill(pid_t " tgid ", pid_t " tid ", int " sig ); | |
26 | .fi | |
27 | .P | |
28 | .IR Note : | |
29 | glibc provides no wrapper for | |
30 | .BR tkill (), | |
31 | necessitating the use of | |
32 | .BR syscall (2). | |
33 | .SH DESCRIPTION | |
34 | .BR tgkill () | |
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) | |
43 | can be used to send a signal only to a process (i.e., thread group) | |
44 | as a whole, and the signal will be delivered to an arbitrary | |
45 | thread within that process.) | |
46 | .P | |
47 | .BR tkill () | |
48 | is an obsolete predecessor to | |
49 | .BR tgkill (). | |
50 | It allows only the target thread ID to be specified, | |
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. | |
54 | .\" FIXME Maybe say something about the following: | |
55 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12889 | |
56 | .\" | |
57 | .\" Quoting Rich Felker <bugdal@aerifal.cx>: | |
58 | .\" | |
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. | |
64 | .\" | |
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. | |
79 | .P | |
80 | These are the raw system call interfaces, meant for internal | |
81 | thread library use. | |
82 | .SH RETURN VALUE | |
83 | On success, zero is returned. | |
84 | On error, \-1 is returned, and \fIerrno\fP | |
85 | is set to indicate the error. | |
86 | .SH ERRORS | |
87 | .TP | |
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. | |
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. | |
110 | .SH STANDARDS | |
111 | Linux. | |
112 | .SH HISTORY | |
113 | .TP | |
114 | .BR tkill () | |
115 | Linux 2.4.19 / 2.5.4. | |
116 | .TP | |
117 | .BR tgkill () | |
118 | Linux 2.5.75, | |
119 | glibc 2.30. | |
120 | .SH NOTES | |
121 | See the description of | |
122 | .B CLONE_THREAD | |
123 | in | |
124 | .BR clone (2) | |
125 | for an explanation of thread groups. | |
126 | .SH SEE ALSO | |
127 | .BR clone (2), | |
128 | .BR gettid (2), | |
129 | .BR kill (2), | |
130 | .BR rt_sigqueueinfo (2) |