man2/rt_sigqueueinfo.2

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