114 lines
2.7 KiB
Groff
114 lines
2.7 KiB
Groff
'\"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.
|