original/man2/sigqueue.2

   1 .\" Copyright (c) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" added note on self-signaling, aeb, 2002-06-07
  24 .\" added note on CAP_KILL, mtk, 2004-06-16
  25 .\"
  26 .TH SIGQUEUE 2 2007-07-26 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 sigqueue, rt_sigqueueinfo \- queue a signal and data to a process
  29 .SH SYNOPSIS
  30 .B #include <signal.h>
  31 .sp
  32 .BI "int sigqueue(pid_t " pid ", int " sig ", const union sigval " value );
  33 .sp
  34 .in -4n
  35 Feature Test Macro Requirements for glibc (see
  36 .BR feature_test_macros (7)):
  37 .in
  38 .sp
  39 .BR sigqueue ():
  40 _POSIX_C_SOURCE\ >=\ 199309L
  41 .SH DESCRIPTION
  42 .BR sigqueue ()
  43 sends the signal specified in
  44 .I sig
  45 to the process whose PID is given in
  46 .IR pid .
  47 The permissions required to send a signal are the same as for
  48 .BR kill (2).
  49 As with
  50 .BR kill (2),
  51 the null signal (0) can be used to check if a process with a given
  52 PID exists.
  53 .PP
  54 The
  55 .I value
  56 argument is used to specify an accompanying item of data (either an integer
  57 or a pointer value) to be sent with the signal, and has the following type:
  58 .sp
  59 .in +4n
  60 .nf
  61 union sigval {
  62     int   sival_int;
  63     void *sival_ptr;
  64 };
  65 .fi
  66 .in
  67
  68 If the receiving process has installed a handler for this signal using the
  69 .B SA_SIGINFO
  70 flag to
  71 .BR sigaction (2),
  72 then it can obtain this data via the
  73 .I si_value
  74 field of the
  75 .I siginfo_t
  76 structure passed as the second argument to the handler.
  77 Furthermore, the
  78 .I si_code
  79 field of that structure will be set to
  80 .BR SI_QUEUE .
  81 .SH "RETURN VALUE"
  82 On success,
  83 .BR sigqueue ()
  84 returns 0, indicating that the signal was successfully
  85 queued to the receiving process.
  86 Otherwise \-1 is returned and
  87 .I errno
  88 is set to indicate the error.
  89 .SH ERRORS
  90 .TP
  91 .B EAGAIN
  92 The limit of signals which may be queued has been reached.
  93 (See
  94 .BR signal (7)
  95 for further information.)
  96 .TP
  97 .B EINVAL
  98 .I sig
  99 was invalid.
 100 .TP
 101 .B EPERM
 102 The process does not have permission to send the signal
 103 to the receiving process.
 104 For the required permissions, see
 105 .BR kill (2).
 106 .TP
 107 .B ESRCH
 108 No process has a PID matching
 109 .IR pid .
 110 .SH VERSIONS
 111 This system call first appeared in Linux 2.2.
 112 .SH "CONFORMING TO"
 113 POSIX.1-2001.
 114 .SH NOTES
 115 If this function results in the sending of a signal to the process
 116 that invoked it, and that signal was not blocked by the calling thread,
 117 and no other threads were willing to handle this signal (either by
 118 having it unblocked, or by waiting for it using
 119 .BR sigwait (3)),
 120 then at least some signal must be delivered to this thread before this
 121 function returns.
 122
 123 On Linux, the underlying system call is actually named
 124 .BR rt_sigqueueinfo (),
 125 and differs in its third argument, which is the
 126 .I siginfo_t
 127 structure that will be supplied to the receiving process's
 128 signal handler or returned by the receiving process's
 129 .BR sigtimedwait (2)
 130 call.
 131 Inside the glibc
 132 .BR sigqueue ()
 133 wrapper, this argument,
 134 .IR info ,
 135 is initialized as follows:
 136 .in +4n
 137 .nf
 138
 139 info.si_signo = sig;      /* argument supplied to sigqueue() */
 140 info.si_code = SI_QUEUE;
 141 info.si_pid = getpid();   /* Process ID of sender */
 142 info.si_uid = getuid();   /* Real UID of sender */
 143 info.si_value = val;      /* argument supplied to sigqueue() */
 144 .fi
 145 .in
 146 .SH "SEE ALSO"
 147 .BR kill (2),
 148 .BR sigaction (2),
 149 .BR signal (2),
 150 .BR pthread_sigqueue (3),
 151 .BR sigwait (3),
 152 .BR signal (7)