NAME

mq_notify − Attaches a request for asynchronous signal notification to a message queue (P1003.1b)

SYNOPSIS

#include <mqueue.h>

int ∗Lmq_notify (
mqd_t mqdes,
const struct sigevent ∗notification);

PARAMETERS

mqdes Specifies a message queue descriptor. 

∗notification
Specifies a signal to be sent when the specified  queue accepts a message. If the notification argument is NULL, and the process has previously attached a notification request to the message queue with this mqdes argument, notification request is detached and the queue is available for another process to attach a notification request. 

DESCRIPTION

Attaches a request for asynchronous signal notification 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 processes 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; otherwise, the function returns the value −1 and sets errno to indicate the error. 

ERRORS

[EBADF] The mqdes argument is not a valid message queue descriptor. 

[EBUSY] 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. 

[EINVAL] The requested signo is invalid, or the sigev_notify field of the notification structure does not equal SIGEV_SIGNAL. 

[ENOSYS] The function mq_notify is not supported by this implementation. 

RELATED INFORMATION

Functions: mq_open(3), mq_send(3)