man2/rt_sigqueueinfo.2

   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 2019-10-10 "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 *" info );
  31 .PP
  32 .BI "int rt_tgsigqueueinfo(pid_t " tgid ", pid_t " tid ", int " sig ,
  33 .BI "                      siginfo_t *" info );
  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 info
  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 should be one of the
  82 .B SI_*
  83 codes in the Linux kernel source file
  84 .IR include/asm-generic/siginfo.h .
  85 If the signal is being sent to any process other than the caller itself,
  86 the following restrictions apply:
  87 .RS
  88 .IP * 3
  89 The code can't be a value greater than or equal to zero.
  90 In particular, it can't be
  91 .BR SI_USER ,
  92 which is used by the kernel to indicate a signal sent by
  93 .BR kill (2),
  94 and nor can it be
  95 .BR SI_KERNEL ,
  96 which is used to indicate a signal generated by the kernel.
  97 .IP *
  98 The code can't (since Linux 2.6.39) be
  99 .BR SI_TKILL ,
 100 which is used by the kernel to indicate a signal sent using
 101 .\" tkill(2) or
 102 .BR tgkill (2).
 103 .RE
 104 .TP
 105 .I si_pid
 106 This should be set to a process ID,
 107 typically the process ID of the sender.
 108 .TP
 109 .I si_uid
 110 This should be set to a user ID,
 111 typically the real user ID of the sender.
 112 .TP
 113 .I si_value
 114 This field contains the user data to accompany the signal.
 115 For more information, see the description of the last
 116 .RI ( "union sigval" )
 117 argument of
 118 .BR sigqueue (3).
 119 .PP
 120 Internally, the kernel sets the
 121 .I si_signo
 122 field to the value specified in
 123 .IR sig ,
 124 so that the receiver of the signal can also obtain
 125 the signal number via that field.
 126 .PP
 127 The
 128 .BR rt_tgsigqueueinfo ()
 129 system call is like
 130 .BR rt_sigqueueinfo (),
 131 but sends the signal and data to the single thread
 132 specified by the combination of
 133 .IR tgid ,
 134 a thread group ID,
 135 and
 136 .IR tid ,
 137 a thread in that thread group.
 138 .SH RETURN VALUE
 139 On success, these system calls return 0.
 140 On error, they return \-1 and
 141 .I errno
 142 is set to indicate the error.
 143 .SH ERRORS
 144 .TP
 145 .B EAGAIN
 146 The limit of signals which may be queued has been reached.
 147 (See
 148 .BR signal (7)
 149 for further information.)
 150 .TP
 151 .B EINVAL
 152 .IR sig ,
 153 .IR tgid ,
 154 or
 155 .IR tid
 156 was invalid.
 157 .TP
 158 .B EPERM
 159 The caller does not have permission to send the signal to the target.
 160 For the required permissions, see
 161 .BR kill (2).
 162 .TP
 163 .B EPERM
 164 .I tgid
 165 specifies a process other than the caller and
 166 .I info->si_code
 167 is invalid.
 168 .TP
 169 .B ESRCH
 170 .BR rt_sigqueueinfo ():
 171 No thread group matching
 172 .I tgid
 173 was found.
 174 .PP
 175 .BR rt_tgsigqueinfo ():
 176 No thread matching
 177 .I tgid
 178 and
 179 .I tid
 180 was found.
 181 .SH VERSIONS
 182 The
 183 .BR rt_sigqueueinfo ()
 184 system call was added to Linux in version 2.2.
 185 The
 186 .BR rt_tgsigqueueinfo ()
 187 system call was added to Linux in version 2.6.31.
 188 .SH CONFORMING TO
 189 These system calls are Linux-specific.
 190 .SH NOTES
 191 Since these system calls are not intended for application use,
 192 there are no glibc wrapper functions; use
 193 .BR syscall (2)
 194 in the unlikely case that you want to call them directly.
 195 .PP
 196 As with
 197 .BR kill (2),
 198 the null signal (0) can be used to check if the specified process
 199 or thread exists.
 200 .SH SEE ALSO
 201 .BR kill (2),
 202 .BR pidfd_send_signal (2),
 203 .BR sigaction (2),
 204 .BR sigprocmask (2),
 205 .BR tgkill (2),
 206 .BR pthread_sigqueue (3),
 207 .BR sigqueue (3),
 208 .BR signal (7)