lib/libc/sys/sigqueue.2

   1 .\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  17 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
  20 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  23 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  24 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  25 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  26 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd March 10, 2012
  31 .Dt SIGQUEUE 2
  32 .Os
  33 .Sh NAME
  34 .Nm sigqueue
  35 .Nd "queue a signal to a process (REALTIME)"
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In signal.h
  40 .Ft int
  41 .Fn sigqueue "pid_t pid" "int signo" "const union sigval value"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn sigqueue
  45 system call causes the signal specified by
  46 .Fa signo
  47 to be sent with the value specified by
  48 .Fa value
  49 to the process specified by
  50 .Fa pid .
  51 If
  52 .Fa signo
  53 is zero (the null signal), error checking is performed but
  54 no signal is actually sent.
  55 The null signal can be used to check the
  56 validity of PID.
  57 .Pp
  58 The conditions required for a process to have permission to queue a
  59 signal to another process are the same as for the
  60 .Xr kill 2
  61 system call.
  62 The
  63 .Fn sigqueue
  64 system call queues a signal to a single process specified by the
  65 .Fa pid
  66 argument.
  67 .Pp
  68 The
  69 .Fn sigqueue
  70 system call returns immediately.
  71 If the resources were
  72 available to queue the signal, the signal will be queued and sent to
  73 the receiving process.
  74 .Pp
  75 If the value of
  76 .Fa pid
  77 causes
  78 .Fa signo
  79 to be generated for the sending process, and if
  80 .Fa signo
  81 is not blocked for the calling thread and if no other thread has
  82 .Fa signo
  83 unblocked or is waiting in a
  84 .Fn sigwait
  85 system call for
  86 .Fa signo ,
  87 either
  88 .Fa signo
  89 or at least the pending, unblocked signal will be delivered to the
  90 calling thread before
  91 .Fn sigqueue
  92 returns.
  93 Should any multiple pending signals in the range
  94 .Dv SIGRTMIN
  95 to
  96 .Dv SIGRTMAX
  97 be selected for delivery, it is the lowest numbered
  98 one.
  99 The selection order between realtime and non-realtime signals, or
 100 between multiple pending non-realtime signals, is unspecified.
 101 .Sh RETURN VALUES
 102 .Rv -std
 103 .Sh ERRORS
 104 The
 105 .Fn sigqueue
 106 system call
 107 will fail if:
 108 .Bl -tag -width Er
 109 .It Bq Er EAGAIN
 110 No resources are available to queue the signal.
 111 The process has already
 112 queued
 113 .Brq Dv SIGQUEUE_MAX
 114 signals that are still pending at the receiver(s),
 115 or a system-wide resource limit has been exceeded.
 116 .It Bq Er EINVAL
 117 The value of the
 118 .Fa signo
 119 argument is an invalid or unsupported signal number.
 120 .It Bq Er EPERM
 121 The process does not have the appropriate privilege to send the signal
 122 to the receiving process.
 123 .It Bq Er ESRCH
 124 The process
 125 .Fa pid
 126 does not exist.
 127 .El
 128 .Sh SEE ALSO
 129 .Xr kill 2 ,
 130 .Xr sigaction 2 ,
 131 .Xr sigpending 2 ,
 132 .Xr sigqueue 2 ,
 133 .Xr sigsuspend 2 ,
 134 .Xr sigtimedwait 2 ,
 135 .Xr sigwait 2 ,
 136 .Xr sigwaitinfo 2 ,
 137 .Xr pause 3 ,
 138 .Xr pthread_sigmask 3 ,
 139 .Xr siginfo 3
 140 .Sh STANDARDS
 141 The
 142 .Fn sigqueue
 143 system call conforms to
 144 .St -p1003.1-2004 .
 145 .Sh HISTORY
 146 Support for
 147 .Tn POSIX
 148 realtime signal queue first appeared in
 149 .Fx 7.0 .