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 April 21, 2024 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.Pp 100As a 101.Fx 102extension, the value of 103.Fa signo 104can be or-ed with the following flags: 105.Bl -tag -width __SIGQUEUE_TID 106.It Dv __SIGQUEUE_TID 107The 108.Fa pid 109parameter is the thread identifier of a thread in the current process, 110and the specified signal is queued into the specified thread' queue. 111.El 112.Sh RETURN VALUES 113.Rv -std 114.Sh ERRORS 115The 116.Fn sigqueue 117system call 118will fail if: 119.Bl -tag -width Er 120.It Bq Er EAGAIN 121No resources are available to queue the signal. 122The process has already 123queued 124.Brq Dv SIGQUEUE_MAX 125signals that are still pending at the receiver(s), 126or a system-wide resource limit has been exceeded. 127.It Bq Er EINVAL 128The value of the 129.Fa signo 130argument is an invalid or unsupported signal number. 131.It Bq Er EPERM 132The process does not have the appropriate privilege to send the signal 133to the receiving process. 134.It Bq Er ESRCH 135The process 136.Fa pid 137does not exist. 138.It Bq Er ESRCH 139The thread with id 140.Fa pid 141does not exist in the current process. 142.El 143.Sh SEE ALSO 144.Xr kill 2 , 145.Xr sigaction 2 , 146.Xr sigpending 2 , 147.Xr sigsuspend 2 , 148.Xr sigtimedwait 2 , 149.Xr sigwait 2 , 150.Xr sigwaitinfo 2 , 151.Xr pause 3 , 152.Xr pthread_sigmask 3 , 153.Xr siginfo 3 154.Sh STANDARDS 155The 156.Fn sigqueue 157system call conforms to 158.St -p1003.1-2004 . 159.Sh HISTORY 160Support for 161.Tn POSIX 162realtime signal queue first appeared in 163.Fx 7.0 . 164.Sh CAVEATS 165When using 166.Nm 167to send signals to a process which might have a different ABI 168(for instance, one is 32-bit and the other 64-bit), 169the 170.Va sival_int 171member of 172.Fa value 173can be delivered reliably, but the 174.Va sival_ptr 175may be truncated in endian dependent ways and must not be relied on. 176Further, many pointer integrity schemes disallow sending pointers to other 177processes, and this technique should not be used in programs intended to 178be portable. 179