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