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