sigqueue() -- queue a signal to a process

SYNOPSIS

#include <sys/types.h>

#include <signal.h>

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

The sigqueue() function sends a signal to a process or a group of processes that pid specifies along with the value specified by value. The signal to be sent is specified by sig, and is either one of the signals specified in signal.h, or 0. If sig 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 pid.

The conditions under which a process has permission to queue a signal to another process with sigqueue() are the same as for the kill() function.

The sigqueue() function returns immediately. If the receiving process has SA_SIGINFO set for the signal sig, the signal is queued for the receiving process. If SA_SIGINFO is not set for the receiving process, the signal is delivered via the usual signal delivery mechanisms (if the signal is not already pending for the process, it is added to the list of pending signals; otherwise, no action is taken). If the value of pid causes sig to be generated for the sending process and if sig is not blocked, either sig or at least one pending unblocked signal is delivered to the sending process before the sigqueue() function returns.

sigqueue() is successful if the process has permission to send sig to any of the processes that pid specified. If sigqueue() fails, no signal is sent.

PARAMETERS

pid: Is a process ID or process group ID.
sig: Specifies the signal to be sent.
value: Is a user-specified value to be passed along with the signal to the receiving process. The receiving process can find the value by examining the si_value field of the siginfo_t structure.

RETURN VALUES

On success, sigqueue() returns a value of zero. On failure, it returns a value of -1, does not send a signal, and sets errno to one of the following values:

EAGAIN: There are not enough 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.
EINVAL: The value of sig is an invalid or unsupported signal number.
EPERM: The user ID of the sending process is not privileged; its real or effective user ID does not match the real or saved user ID of the receiving process. Or, the process does not have permission to send the signal to any receiving process.
ESRCH: No process or process group can be found that corresponds to the one that pid specifies.

CONFORMANCE

POSIX Realtime Extensions.

MULTITHREAD SAFETY LEVEL

Async-signal-safe.

PORTING ISSUES

The determination of whether the sending process has permission to send a signal to the receiving process ignores any uid or gid settings that have been specified with calls to setuid() or setgid(), The determination is done by comparing the uids of each of the two processes at the time that they were created.

Using sigqueue() to send the SIGTERM or SIGHUP signal to a non-NuTCRACKER Platform attempts to post a close message to a window owned by the process specified by pid. If the process calling sigqueue() does not have sufficient privileges to perform this function, or if no window could be found to which to post the close message, kill() returns -1 with errno set to EPERM.

Sending the SIGKILL signal to non-NuTCRACKER Platform processes also attempts to post a close message to a window owned by the process specified by pid. In cases where it is not possible to post this message, or where the process does not exit in a timely fashion, sigqueue() attempts to use the Win32 TerminateProcess() function to kill the process specified by pid. If the process calling sigqueue() does not have sufficient privileges to perform this function, sigqueue() returns -1 with errno set to EPERM.

Sending any other signal to a non-NuTCRACKER Platform process fails with errno set to EPERM.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

sigqueue()
queue a signal to a process

Function