Debian Codegraph @

upstream/debian-trixie/man2/tkill.2

raw
1 .\" Copyright (C) 2008 Michael Kerrisk <[email protected]>
2 .\" and Copyright 2003 Abhijit Menon-Sen <[email protected]>
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 2024-05-02 "Linux man-pages 6.9.1"
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 <[email protected]>:
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)