'\"macro stdmacro
.TH SIGQUEUE 3 
.SH NAME
sigqueue \- queue a signal to a process  (\s-1POSIX\s+1)
.Op c p a
.SH C SYNOPSIS
.nf
.B #include <signal.h>
.PP
.B "int sigqueue(pid_t pid, int signo, const union sigval value);
.fi
.PP
.Op
.SH DESCRIPTION
.PP
The function
.I sigqueue()
causes the signal specified by 
.I signo
to be sent with the value specified by
.I value
to the process specified by
.I pid.
If
.I signo
is zero (the null signal), error checking is performed, but no signal is actually sent. The null signal can be used to check the validity of
.I pid.
.sp
The conditions required for a process to have permission to queue a signal to another process are the same as for the
.IR kill (2)
function.
.sp
If the signal specified in 
.I signo
is currently blocked for the receiving process,
.I sigqueue()
shall return immediately and, if SA_SIGINFO is set for 
.I signo
and if the resources were available to queue the signal, the signal shall be left queued and pending. Furthermore, when the signal handler for
.I signo
is delivered, the field 
.I si_code
of the passed in
.I siginfo
structure will be set to SI_QUEUE (see \f4sigaction\fP(2), \f4signal\fP(5)).
If SA_SIGINFO is not set for
\f2signo\fP, then
.I signo,
but not necessarily
.I value,
shall be sent at least once to the receiving process.
.sp
If the value of
.I pid
causes
.I signo
to be generated for the sending process, and if 
.I signo
is not blocked for the calling thread and if no other thread
has
.I signo
unblocked or is waiting in a
.I sigwait
function for
.IR signo ,
at least one pending unblocked signal shall be delivered to the
calling thread before the
.IR sigqueue()
function returns.
.SH "SEE ALSO"
\f4kill\fP(2),
\f4sigaction\fP(2),
\f4sigwait\fP(3),
\f4signal\fP(5).
.SH "DIAGNOSTICS"
.PP
Upon successful completion, the 
.I sigqueue()
function returns a value of 0 indicating that the specified signal has been queued. Otherwise a value of -1 is returned and 
.I errno
is set to indicate the error.
If any of the conditions below occur, the 
.I sigqueue()
function shall return -1 and set
.I errno
to the corresponding value:
.TP 15
.SM
\%[EAGAIN]
No resources available to queue the signal.
The process has already queued SIGQUEUE_MAX signals that are still
pending at the receivers, or a system wide resource limit has been exceeded.
.TP 15
.SM
\%[EINVAL]
The value of the 
.I sig
argument is an invalid or unsupported signal number.
.TP 15
.SM
\%[EPERM]
The process does not have the appropriate privilege to send the signal
to the receiving process.
.TP 15
.SM
\%[EPERM]
The process
.I pid
does not exist.
.SH "WARNING"
The \s-1POSIX\s+1 and System V signal facilities have different semantics.
Using both facilities in the same program is \f3strongly discouraged\fP
and will result in unpredictable behavior.