Debian Codegraph @

upstream/debian-unstable/man2/tkill.2

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