| blob | c2990b6211b3670a1fe17b7b69fdfa64f6f3955e |
1 .\" Copyright (c) 2002, 2011 Michael Kerrisk <mtk.manpages@gmail.com>
2 .\"
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
7 .\"
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
12 .\"
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
19 .\" professionally.
20 .\"
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" %%%LICENSE_END
24 .\"
25 .TH RT_SIGQUEUEINFO 2 2017-09-15 "Linux" "Linux Programmer's Manual"
26 .SH NAME
27 rt_sigqueueinfo, rt_tgsigqueueinfo \- queue a signal and data
28 .SH SYNOPSIS
29 .nf
30 .BI "int rt_sigqueueinfo(pid_t " tgid ", int " sig ", siginfo_t *" uinfo );
31 .PP
32 .BI "int rt_tgsigqueueinfo(pid_t " tgid ", pid_t " tid ", int " sig ,
33 .BI " siginfo_t *" uinfo );
34 .fi
35 .PP
36 .IR Note :
37 There are no glibc wrappers for these system calls; see NOTES.
38 .SH DESCRIPTION
39 The
40 .BR rt_sigqueueinfo ()
41 and
42 .BR rt_tgsigqueueinfo ()
43 system calls are the low-level interfaces used to send a signal plus data
44 to a process or thread.
45 The receiver of the signal can obtain the accompanying data
46 by establishing a signal handler with the
47 .BR sigaction (2)
48 .B SA_SIGINFO
49 flag.
50 .PP
51 These system calls are not intended for direct application use;
52 they are provided to allow the implementation of
53 .BR sigqueue (3)
54 and
55 .BR pthread_sigqueue (3).
56 .PP
57 The
58 .BR rt_sigqueueinfo ()
59 system call sends the signal
60 .I sig
61 to the thread group with the ID
62 .IR tgid .
63 (The term "thread group" is synonymous with "process", and
64 .I tid
65 corresponds to the traditional UNIX process ID.)
66 The signal will be delivered to an arbitrary member of the thread group
67 (i.e., one of the threads that is not currently blocking the signal).
68 .PP
69 The
70 .I uinfo
71 argument specifies the data to accompany the signal.
72 This argument is a pointer to a structure of type
73 .IR siginfo_t ,
74 described in
75 .BR sigaction (2)
76 (and defined by including
77 .IR <sigaction.h> ).
78 The caller should set the following fields in this structure:
79 .TP
80 .I si_code
81 This must be one of the
82 .B SI_*
83 codes in the Linux kernel source file
84 .IR include/asm-generic/siginfo.h ,
85 with the restriction that the code must be negative
86 (i.e., cannot be
87 .BR SI_USER ,
88 which is used by the kernel to indicate a signal sent by
89 .BR kill (2))
90 and cannot (since Linux 2.6.39) be
91 .BR SI_TKILL
92 (which is used by the kernel to indicate a signal sent using
93 .\" tkill(2) or
94 .BR tgkill (2)).
95 .TP
96 .I si_pid
97 This should be set to a process ID,
98 typically the process ID of the sender.
99 .TP
100 .I si_uid
101 This should be set to a user ID,
102 typically the real user ID of the sender.
103 .TP
104 .I si_value
105 This field contains the user data to accompany the signal.
106 For more information, see the description of the last
107 .RI ( "union sigval" )
108 argument of
109 .BR sigqueue (3).
110 .PP
111 Internally, the kernel sets the
112 .I si_signo
113 field to the value specified in
114 .IR sig ,
115 so that the receiver of the signal can also obtain
116 the signal number via that field.
117 .PP
118 The
119 .BR rt_tgsigqueueinfo ()
120 system call is like
121 .BR rt_sigqueueinfo (),
122 but sends the signal and data to the single thread
123 specified by the combination of
124 .IR tgid ,
125 a thread group ID,
126 and
127 .IR tid ,
128 a thread in that thread group.
129 .SH RETURN VALUE
130 On success, these system calls return 0.
131 On error, they return \-1 and
132 .I errno
133 is set to indicate the error.
134 .SH ERRORS
135 .TP
136 .B EAGAIN
137 The limit of signals which may be queued has been reached.
138 (See
139 .BR signal (7)
140 for further information.)
141 .TP
142 .B EINVAL
143 .IR sig ,
144 .IR tgid ,
145 or
146 .IR tid
147 was invalid.
148 .TP
149 .B EPERM
150 The caller does not have permission to send the signal to the target.
151 For the required permissions, see
152 .BR kill (2).
153 Or:
154 .I uinfo->si_code
155 is invalid.
156 .TP
157 .B ESRCH
158 .BR rt_sigqueueinfo ():
159 No thread group matching
160 .I tgid
161 was found.
162 .PP
163 .BR rt_tgsigqueinfo ():
164 No thread matching
165 .I tgid
166 and
167 .I tid
168 was found.
169 .SH VERSIONS
170 The
171 .BR rt_sigqueueinfo ()
172 system call was added to Linux in version 2.2.
173 The
174 .BR rt_tgsigqueueinfo ()
175 system call was added to Linux in version 2.6.31.
176 .SH CONFORMING TO
177 These system calls are Linux-specific.
178 .SH NOTES
179 Since these system calls are not intended for application use,
180 there are no glibc wrapper functions; use
181 .BR syscall (2)
182 in the unlikely case that you want to call them directly.
183 .PP
184 As with
185 .BR kill (2),
186 the null signal (0) can be used to check if the specified process
187 or thread exists.
188 .SH SEE ALSO
189 .BR kill (2),
190 .BR sigaction (2),
191 .BR sigprocmask (2),
192 .BR tgkill (2),
193 .BR pthread_sigqueue (3),
194 .BR sigqueue (3),
195 .BR signal (7)