man3/sigqueue.3

   1 '\" t
   2 .\" Copyright (c) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" added note on self-signaling, aeb, 2002-06-07
   7 .\" added note on CAP_KILL, mtk, 2004-06-16
   8 .\"
   9 .TH sigqueue 3 (date) "Linux man-pages (unreleased)"
  10 .SH NAME
  11 sigqueue \- queue a signal and data to a process
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <signal.h>
  18 .P
  19 .BI "int sigqueue(pid_t " pid ", int " sig ", const union sigval " value );
  20 .fi
  21 .P
  22 .RS -4
  23 Feature Test Macro Requirements for glibc (see
  24 .BR feature_test_macros (7)):
  25 .RE
  26 .P
  27 .BR sigqueue ():
  28 .nf
  29     _POSIX_C_SOURCE >= 199309L
  30 .fi
  31 .SH DESCRIPTION
  32 .BR sigqueue ()
  33 sends the signal specified in
  34 .I sig
  35 to the process whose PID is given in
  36 .IR pid .
  37 The permissions required to send a signal are the same as for
  38 .BR kill (2).
  39 As with
  40 .BR kill (2),
  41 the null signal (0) can be used to check if a process with a given
  42 PID exists.
  43 .P
  44 The
  45 .I value
  46 argument is used to specify an accompanying item of data (either an integer
  47 or a pointer value) to be sent with the signal, and has the following type:
  48 .P
  49 .in +4n
  50 .EX
  51 union sigval {
  52     int   sival_int;
  53     void *sival_ptr;
  54 };
  55 .EE
  56 .in
  57 .P
  58 If the receiving process has installed a handler for this signal using the
  59 .B SA_SIGINFO
  60 flag to
  61 .BR sigaction (2),
  62 then it can obtain this data via the
  63 .I si_value
  64 field of the
  65 .I siginfo_t
  66 structure passed as the second argument to the handler.
  67 Furthermore, the
  68 .I si_code
  69 field of that structure will be set to
  70 .BR SI_QUEUE .
  71 .SH RETURN VALUE
  72 On success,
  73 .BR sigqueue ()
  74 returns 0, indicating that the signal was successfully
  75 queued to the receiving process.
  76 Otherwise, \-1 is returned and
  77 .I errno
  78 is set to indicate the error.
  79 .SH ERRORS
  80 .TP
  81 .B EAGAIN
  82 The limit of signals which may be queued has been reached.
  83 (See
  84 .BR signal (7)
  85 for further information.)
  86 .TP
  87 .B EINVAL
  88 .I sig
  89 was invalid.
  90 .TP
  91 .B EPERM
  92 The process does not have permission to send the signal
  93 to the receiving process.
  94 For the required permissions, see
  95 .BR kill (2).
  96 .TP
  97 .B ESRCH
  98 No process has a PID matching
  99 .IR pid .
 100 .SH ATTRIBUTES
 101 For an explanation of the terms used in this section, see
 102 .BR attributes (7).
 103 .TS
 104 allbox;
 105 lbx lb lb
 106 l l l.
 107 Interface       Attribute       Value
 108 T{
 109 .na
 110 .nh
 111 .BR sigqueue ()
 112 T}      Thread safety   MT-Safe
 113 .TE
 114 .SH VERSIONS
 115 .SS C library/kernel differences
 116 On Linux,
 117 .BR sigqueue ()
 118 is implemented using the
 119 .BR rt_sigqueueinfo (2)
 120 system call.
 121 The system call differs in its third argument, which is the
 122 .I siginfo_t
 123 structure that will be supplied to the receiving process's
 124 signal handler or returned by the receiving process's
 125 .BR sigtimedwait (2)
 126 call.
 127 Inside the glibc
 128 .BR sigqueue ()
 129 wrapper, this argument,
 130 .IR uinfo ,
 131 is initialized as follows:
 132 .P
 133 .in +4n
 134 .EX
 135 uinfo.si_signo = sig;      /* Argument supplied to sigqueue() */
 136 uinfo.si_code = SI_QUEUE;
 137 uinfo.si_pid = getpid();   /* Process ID of sender */
 138 uinfo.si_uid = getuid();   /* Real UID of sender */
 139 uinfo.si_value = val;      /* Argument supplied to sigqueue() */
 140 .EE
 141 .in
 142 .SH STANDARDS
 143 POSIX.1-2008.
 144 .SH HISTORY
 145 Linux 2.2.
 146 POSIX.1-2001.
 147 .SH NOTES
 148 If this function results in the sending of a signal to the process
 149 that invoked it, and that signal was not blocked by the calling thread,
 150 and no other threads were willing to handle this signal (either by
 151 having it unblocked, or by waiting for it using
 152 .BR sigwait (3)),
 153 then at least some signal must be delivered to this thread before this
 154 function returns.
 155 .SH SEE ALSO
 156 .BR kill (2),
 157 .BR rt_sigqueueinfo (2),
 158 .BR sigaction (2),
 159 .BR signal (2),
 160 .BR pthread_sigqueue (3),
 161 .BR sigwait (3),
 162 .BR signal (7)