Debian Codegraph @

upstream/debian-unstable/man2/rt_sigqueueinfo.2

raw
1 .\" Copyright 2002-2011, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH rt_sigqueueinfo 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 rt_sigqueueinfo, rt_tgsigqueueinfo \- queue a signal and data
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <linux/signal.h>" " /* Definition of " SI_* " constants */"
15 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
16 .B #include <unistd.h>
17 .P
18 .BI "int syscall(SYS_rt_sigqueueinfo, pid_t " tgid ,
19 .BI " int " sig ", siginfo_t *" info );
20 .BI "int syscall(SYS_rt_tgsigqueueinfo, pid_t " tgid ", pid_t " tid ,
21 .BI " int " sig ", siginfo_t *" info );
22 .fi
23 .P
24 .IR Note :
25 There are no glibc wrappers for these system calls;
26 see NOTES.
27 .SH DESCRIPTION
28 The
29 .BR rt_sigqueueinfo ()
30 and
31 .BR rt_tgsigqueueinfo ()
32 system calls are the low-level interfaces used to send a signal plus data
33 to a process or thread.
34 The receiver of the signal can obtain the accompanying data
35 by establishing a signal handler with the
36 .BR sigaction (2)
37 .B SA_SIGINFO
38 flag.
39 .P
40 These system calls are not intended for direct application use;
41 they are provided to allow the implementation of
42 .BR sigqueue (3)
43 and
44 .BR pthread_sigqueue (3).
45 .P
46 The
47 .BR rt_sigqueueinfo ()
48 system call sends the signal
49 .I sig
50 to the thread group with the ID
51 .IR tgid .
52 (The term "thread group" is synonymous with "process", and
53 .I tgid
54 corresponds to the traditional UNIX process ID.)
55 The signal will be delivered to an arbitrary member of the thread group
56 (i.e., one of the threads that is not currently blocking the signal).
57 .P
58 The
59 .I info
60 argument specifies the data to accompany the signal.
61 This argument is a pointer to a structure of type
62 .IR siginfo_t ,
63 described in
64 .BR sigaction (2)
65 (and defined by including
66 .IR <sigaction.h> ).
67 The caller should set the following fields in this structure:
68 .TP
69 .I si_code
70 This should be one of the
71 .B SI_*
72 codes in the Linux kernel source file
73 .IR include/asm\-generic/siginfo.h .
74 If the signal is being sent to any process other than the caller itself,
75 the following restrictions apply:
76 .RS
77 .IP \[bu] 3
78 The code can't be a value greater than or equal to zero.
79 In particular, it can't be
80 .BR SI_USER ,
81 which is used by the kernel to indicate a signal sent by
82 .BR kill (2),
83 and nor can it be
84 .BR SI_KERNEL ,
85 which is used to indicate a signal generated by the kernel.
86 .IP \[bu]
87 The code can't (since Linux 2.6.39) be
88 .BR SI_TKILL ,
89 which is used by the kernel to indicate a signal sent using
90 .\" tkill(2) or
91 .BR tgkill (2).
92 .RE
93 .TP
94 .I si_pid
95 This should be set to a process ID,
96 typically the process ID of the sender.
97 .TP
98 .I si_uid
99 This should be set to a user ID,
100 typically the real user ID of the sender.
101 .TP
102 .I si_value
103 This field contains the user data to accompany the signal.
104 For more information, see the description of the last
105 .RI ( "union sigval" )
106 argument of
107 .BR sigqueue (3).
108 .P
109 Internally, the kernel sets the
110 .I si_signo
111 field to the value specified in
112 .IR sig ,
113 so that the receiver of the signal can also obtain
114 the signal number via that field.
115 .P
116 The
117 .BR rt_tgsigqueueinfo ()
118 system call is like
119 .BR rt_sigqueueinfo (),
120 but sends the signal and data to the single thread
121 specified by the combination of
122 .IR tgid ,
123 a thread group ID,
124 and
125 .IR tid ,
126 a thread in that thread group.
127 .SH RETURN VALUE
128 On success, these system calls return 0.
129 On error, they return \-1 and
130 .I errno
131 is set to indicate the error.
132 .SH ERRORS
133 .TP
134 .B EAGAIN
135 The limit of signals that may be queued has been reached.
136 (See
137 .BR signal (7)
138 for further information.)
139 .TP
140 .B EINVAL
141 .IR sig ,
142 .IR tgid ,
143 or
144 .I tid
145 was invalid.
146 .TP
147 .B EPERM
148 The caller does not have permission to send the signal to the target.
149 For the required permissions, see
150 .BR kill (2).
151 .TP
152 .B EPERM
153 .I tgid
154 specifies a process other than the caller and
155 .I info\->si_code
156 is invalid.
157 .TP
158 .B ESRCH
159 .BR rt_sigqueueinfo ():
160 No thread group matching
161 .I tgid
162 was found.
163 .P
164 .BR rt_tgsigqueinfo ():
165 No thread matching
166 .I tgid
167 and
168 .I tid
169 was found.
170 .SH STANDARDS
171 Linux.
172 .SH HISTORY
173 .TP
174 .BR rt_sigqueueinfo ()
175 Linux 2.2.
176 .TP
177 .BR rt_tgsigqueueinfo ()
178 Linux 2.6.31.
179 .SH NOTES
180 Since these system calls are not intended for application use,
181 there are no glibc wrapper functions;
182 use
183 .BR syscall (2)
184 in the unlikely case that you want to call them directly.
185 .P
186 As with
187 .BR kill (2),
188 the null signal (0) can be used to check if the specified process
189 or thread exists.
190 .SH SEE ALSO
191 .BR kill (2),
192 .BR pidfd_send_signal (2),
193 .BR sigaction (2),
194 .BR sigprocmask (2),
195 .BR tgkill (2),
196 .BR pthread_sigqueue (3),
197 .BR sigqueue (3),
198 .BR signal (7)