Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

pthread_sigqueue(3C)

Name

pthread_sigqueue, pthread_sigqueue_wait - queue a signal to a thread

Synopsis

#include <signal.h>

int pthread_sigqueue(pthread_t thread, int sig,
     const union sigval value);
int pthread_sigqueue_wait(pthread_t thread, int sig,
     const union sigval value, const struct timespec *timeout);

Description

The pthread_sigqueue() and pthread_sigqueue_wait() functions cause the signal specified by sig to be sent with the value specified by value to the thread specified by thread. The thread argument must be a member of the same process as the calling thread. The sig argument must be one of the signals listed in siginfo.h(3HEAD), with the exception of SIGCANCEL being reserved and off limits. If sig is 0, a validity check is performed for the existence of the target thread; no signal is sent.

The pthread_sigqueue() function returns immediately. In contrast, pthread_sigqueue_wait() will wait for resources to become available to queue the signal if the caller's process already has the maximum number of queued signals allowed per process pending. If the timeout argument is not NULL, pthread_sigqueue_wait() will wait up to the specified time interval for the necessary resources to become available. If the timeout argument is NULL , pthread_sigqueue_wait() will wait as long as necessary.

If SA_SIGINFO is set for sig and if the resources were available to queue the signal, the signal is queued and sent to the target thread. If SA_SIGINFO is not set for sig, then sig is sent at least once to the target thread; it is unspecified whether value will be sent to the target thread as a result of this call.

If the value of thread causes sig to be generated for the calling thread, and if sig is not blocked for the calling thread, either sig or at least another pending, unblocked signal will be delivered to the calling thread before the pthread_sigqueue() or pthread_sigqueue_wait() function returns. Should any of multiple pending signals in the range SIGRTMIN to SIGRTMAX be selected for delivery, it will be the lowest numbered one. The selection order between realtime and non-realtime signals, or between multiple pending non-realtime signals, is unspecified.

Return Values

Upon successful completion, for either pthread_sigqueue() or pthread_sigqueue_wait(), the specified signal will have been sent and the function returns 0. Otherwise, no signal is sent and the function returns an error number. It is not an error for the target thread to be a zombie thread.

Errors

The pthread_sigqueue() and pthread_sigqueue_wait() functions will fail if:

EAGAIN

No resources are available to queue the signal within the specified time, if any. The process has already queued its maximum number of signals that are still pending at the receiver(s), or a system wide resource limit has been exceeded. The maximum number of outstanding queued signals that a process can have is defined by its process.max-siqueue-size resource control.

EINVAL

The value of sig is an invalid or unsupported signal number or the timeout argument specifies an invalid time.

ESRCH

The target thread does not exist.

The pthread_sigqueue_wait() function will fail if:

EFAULT

The timeout argument to pthread_sigqueue_wait() is not NULL and is an invalid address.

EINTR

The pthread_sigqueue_wait() function was interrupted while waiting.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Async-Signal-Safe

See Also

kill(2), pthread_kill(3C), pthread_sigmask(3C), sigqueue(3C), siginfo.h(3HEAD), signal.h(3HEAD), attributes(7), resource-controls(7)