1.\" Copyright (c) 2005 David Xu <[email protected]> 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 May 5, 2017 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 43The 44.Fn sigqueue 45system call causes the signal specified by 46.Fa signo 47to be sent with the value specified by 48.Fa value 49to the process specified by 50.Fa pid . 51If 52.Fa signo 53is zero (the null signal), error checking is performed but 54no signal is actually sent. 55The null signal can be used to check the 56validity of PID. 57.Pp 58The conditions required for a process to have permission to queue a 59signal to another process are the same as for the 60.Xr kill 2 61system call. 62The 63.Fn sigqueue 64system call queues a signal to a single process specified by the 65.Fa pid 66argument. 67.Pp 68The 69.Fn sigqueue 70system call returns immediately. 71If the resources were 72available to queue the signal, the signal will be queued and sent to 73the receiving process. 74.Pp 75If the value of 76.Fa pid 77causes 78.Fa signo 79to be generated for the sending process, and if 80.Fa signo 81is not blocked for the calling thread and if no other thread has 82.Fa signo 83unblocked or is waiting in a 84.Fn sigwait 85system call for 86.Fa signo , 87either 88.Fa signo 89or at least the pending, unblocked signal will be delivered to the 90calling thread before 91.Fn sigqueue 92returns. 93Should any multiple pending signals in the range 94.Dv SIGRTMIN 95to 96.Dv SIGRTMAX 97be selected for delivery, it is the lowest numbered 98one. 99The selection order between realtime and non-realtime signals, or 100between multiple pending non-realtime signals, is unspecified. 101.Sh RETURN VALUES 102.Rv -std 103.Sh ERRORS 104The 105.Fn sigqueue 106system call 107will fail if: 108.Bl -tag -width Er 109.It Bq Er EAGAIN 110No resources are available to queue the signal. 111The process has already 112queued 113.Brq Dv SIGQUEUE_MAX 114signals that are still pending at the receiver(s), 115or a system-wide resource limit has been exceeded. 116.It Bq Er EINVAL 117The value of the 118.Fa signo 119argument is an invalid or unsupported signal number. 120.It Bq Er EPERM 121The process does not have the appropriate privilege to send the signal 122to the receiving process. 123.It Bq Er ESRCH 124The process 125.Fa pid 126does not exist. 127.El 128.Sh SEE ALSO 129.Xr kill 2 , 130.Xr sigaction 2 , 131.Xr sigpending 2 , 132.Xr sigsuspend 2 , 133.Xr sigtimedwait 2 , 134.Xr sigwait 2 , 135.Xr sigwaitinfo 2 , 136.Xr pause 3 , 137.Xr pthread_sigmask 3 , 138.Xr siginfo 3 139.Sh STANDARDS 140The 141.Fn sigqueue 142system call conforms to 143.St -p1003.1-2004 . 144.Sh HISTORY 145Support for 146.Tn POSIX 147realtime signal queue first appeared in 148.Fx 7.0 . 149.Sh CAVEATS 150When using 151.Nm 152to send signals to a process which might have a different ABI 153(for instance, one is 32-bit and the other 64-bit), 154the 155.Va sival_int 156member of 157.Fa value 158can be delivered reliably, but the 159.Va sival_ptr 160may be truncated in endian dependent ways and must not be relied on. 161Further, many pointer integrity schemes disallow sending pointers to other 162processes, and this technique should not be used in programs intended to 163be portable. 164