sigqueue()

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 real or effective user ID of the sending process must match the real or effective user ID of the receiving process
Or:
the calling process must have the PROCMGR_AID_SIGNAL ability enabled. For more information, see procmgr_ability().

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