sigqueue()

Updated: May 06, 2022

Queue a signal to a process

Synopsis:

#include <signal.h>

int sigqueue ( pid_t pid, 
               int signo, 
               const union sigval value );

Arguments:

pid
The ID of the process that you want to signal.
signo
Zero, or the number of the signal that you want to queue for the process. For more information, see POSIX and QNX Neutrino signals in the documentation for SignalAction().

If the signal terminates a process, the cleanup of the terminated process occurs by default at the priority of the thread that sent the signal. As a QNX Neutrino extension, if you OR the SIG_TERMER_NOINHERIT flag (defined in <signal.h>) into signo, the cleanup occurs at the priority of the thread that received the signal.

value
A value that you want to queue with the signal. It's stored in the si_value member of the siginfo_t structure.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The sigqueue() function causes the signal, signo to be sent with the specified value to the process, pid. If signo is zero, error checking is performed, but no signal is actually sent. This is one way of checking to see if pid is valid.

The condition required for a process to have permission to queue a signal to another process is the same as for the kill() function:

The sigqueue() function returns immediately. If SA_SIGINFO is set for signo and if the resources are available to queue the signal, the signal is queued and sent to the receiving process. If SA_SIGINFO isn't set for the signo, then signo is sent to the receiving process if the signal isn't already pending.

If pid causes signo to be generated for the sending process, and if signo isn't blocked for the calling thread and if no other thread has signo unblocked or is waiting in a sigwait() function for signo, then either signo or at least one pending unblocked signal is delivered to the calling thread before sigqueue() returns.

Should any of multiple pending signals in the range SIGRTMIN to SIGRTMAX be selected for delivery, the lowest numbered one is delivered. The selection order between realtime and nonrealtime signals, or between multiple pending nonrealtime signals, is undefined.

Returns:

0
Success.
-1
An error occurred; errno is set.

Errors:

EAGAIN
No resources were available to queue the signal. The process has already queued the maximum number of signals as returned by:

sysconf( _SC_SIGQUEUE_MAX )

that are still pending at the receiver(s), or a system-wide resource limit has been exceeded.

EINVAL
The value of the signo argument is an invalid or unsupported signal number.
ENOSYS
The function sigqueue() isn't supported by this implementation.
EPERM
The calling process doesn't have the required permission; see procmgr_ability().
ESRCH
The process pid doesn't exist.

Classification:

POSIX 1003.1

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes