mq_notify(3)mq_notify(3)NAMEmq_notify - Attaches a request for asynchronous signal notification to
a message queue (P1003.1b)
SYNOPSIS
#include <mqueue.h>
int mq_notify ( mqd_t mqdes, const struct sigevent *notification);
LIBRARY
Realtime Library (librt.so, librt.a)
PARAMETERS
Specifies a message queue descriptor. Specifies a signal to be sent
when the specified queue accepts a message. If the notification argu‐
ment is NULL, and the process has previously attached a notification
request to the message queue with this mqdes argument, the notification
request is detached and the queue is available for another process to
attach a notification request.
DESCRIPTION
The mq_notify function attaches a request for asynchronous signal noti‐
fication to a message queue for the calling process. Following a call
to this function, the specified signal is sent to the calling process
when the queue transitions from empty to non-empty. Two or more pro‐
cesses cannot attach notification requests to the same queue at the
same time.
If a process has attached a notification request and any process is
blocked in the execution of the mq_receive function waiting to receive
a message when a message arrives at the queue, then the appropriate
mq_receive function is completed and the notification remains pending.
When the notification has been sent, the registration is canceled. In
effect, it is a one-shot notification and must be re-registered if
required.
Note that the POSIX IPC functions are not reentrant with respect to
signals. For example, if your application were to use a signal to
notify it that a queue has become non-empty and then attempt to call
mq_receive from the signal handler, the signal handler must reside in a
thread other than the tread that called mq_send. Otherwise, a deadlock
on internal locks would occur.
RETURN VALUES
On successful completion, the function returns the value 0 (zero); oth‐
erwise, the function returns the value -1 and sets errno to indicate
the error.
ERRORS
The mq_notify function fails under the following conditions: The mqdes
argument is not a valid message queue descriptor. A process has
already attached to this message queue for asynchronous notification,
or the calling process attempted to cancel a request that was attached
by another process. The requested signo is invalid, or the
sigev_notify field of the notification structure does not equal
SIGEV_SIGNAL.
SEE ALSO
Functions: mq_open(3), mq_send(3)
Guide to Realtime Programming
mq_notify(3)
