1.\" $NetBSD: sigqueue.2,v 1.3 2013/02/14 09:31:48 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.Nd queue a signal to a process (REALTIME) 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In signal.h 41.Ft int 42.Fn sigqueue "pid_t pid" "int signo" "const union sigval value" 43.Ft int 44.Fn sigqueueinfo "pid_t pid" "const siginfo_t *info" 45.Sh DESCRIPTION 46The 47.Fn sigqueue 48system call causes the signal specified by 49.Fa signo 50to be sent with the value specified by 51.Fa value 52to the process specified by 53.Fa pid . 54If 55.Fa signo 56is zero (the null signal), error checking is performed but 57no signal is actually sent. 58The null signal can be used to check the 59validity of PID. 60.Pp 61The conditions required for a process to have permission to queue a 62signal to another process are the same as for the 63.Xr kill 2 64system call. 65The 66.Fn sigqueue 67system call queues a signal to a single process specified by the 68.Fa pid 69argument. 70.Pp 71The 72.Fn sigqueue 73system call is implemented using 74.Fn sigqueueinfo 75and passing the appropriate information in the 76.Fa info 77argument. 78.Pp 79The 80.Fn sigqueue 81system call returns immediately. 82If the resources were 83available to queue the signal, the signal will be queued and sent to 84the receiving process. 85.Pp 86If the value of 87.Fa pid 88causes 89.Fa signo 90to be generated for the sending process, and if 91.Fa signo 92is not blocked for the calling thread and if no other thread has 93.Fa signo 94unblocked or is waiting in a 95.Fn sigwait 96system call for 97.Fa signo , 98either 99.Fa signo 100or at least the pending, unblocked signal will be delivered to the 101calling thread before 102.Fn sigqueue 103returns. 104Should any multiple pending signals in the range 105.Dv SIGRTMIN 106to 107.Dv SIGRTMAX 108be selected for delivery, it is the lowest numbered 109one. 110The selection order between realtime and non-realtime signals, or 111between multiple pending non-realtime signals, is unspecified. 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 queued 123.Brq Dv SIGQUEUE_MAX 124signals that are still pending at the receiver(s), 125or a system-wide resource limit has been exceeded. 126.It Bq Er EINVAL 127The value of the 128.Fa signo 129argument is an invalid or unsupported signal number. 130.It Bq Er EPERM 131The process does not have the appropriate privilege to send the signal 132to the receiving process. 133.It Bq Er ESRCH 134The process 135.Fa pid 136does not exist. 137.El 138.Sh SEE ALSO 139.Xr sigaction 2 , 140.Xr siginfo 2 , 141.Xr sigpending 2 , 142.Xr sigsuspend 2 , 143.Xr sigtimedwait 2 , 144.Xr sigwait 2 , 145.Xr sigwaitinfo 2 , 146.Xr pause 3 , 147.Xr pthread_sigmask 3 148.Sh STANDARDS 149The 150.Fn sigqueue 151system call conforms to 152.St -p1003.1-2004 . 153.Sh HISTORY 154Support for 155.Tn POSIX 156realtime signal queue first appeared in 157.Nx 6.0 . 158