[Previous]
[Contents]
[Next]

mq_notify()

notify the calling process when the message queue isn't empty

Synopsis:

#include <mqueue.h>
int mq_notify( mqd_t mqdes, 
         const struct sigevent *notification );

Description:

If notification isn't NULL, this function requests the server to notify the calling process when the queue makes the transition from empty to nonempty. The means by which the server is to notify the process is passed in notification. Once the message queue server has notified the process of the transition, the notification is removed.

The sigevent structure pointed to by notification contains at least the following member:

int sigev_signo
If sigev_signo is positive, it's interpreted as a signal number to be sent to the calling process when the queue goes from empty to nonempty. If it's negative, it's interpreted as a proxy to trigger when the queue becomes nonempty.

Under normal operation, only one process may register for notification at a time. If a process attempts to attach a notification, and another process is already attached, an error is returned, and errno is set to EBUSY. However, if the QNX extended option MQ_MULT_NOTIFY is set in the mq_flags for the specified queue, multiple processes may be registered for notification. They're notified in FIFO order.

If a process has registered for notification, and another process is blocked on an mq_receive(), the mq_receive() call is satisfied by any arriving message. The resulting behavior is as if the message queue remained empty.

If notification is NULL, and the current process is currently registered for notification, the existing registration is removed.

If the MQ_NOTIFY_ALWAYS flag is set in the mq_flags field ( or the server is started with the -a option ), the caller is notified when a message is written to the queue even if the queue currently contains some messages.

Returns:

0
Success
-1
An error occurred. errno is set to indicate the error.

Errors:

EBADF
mqdes doesn't represent a valid message queue.
EBUSY
The QNX extended option MQ_MULT_NOTIFY hasn't been set, and a process has already registered for notification for the given queue.
ESRCH
The notification argument is NULL, but the current process isn't registered for notification.

Classification:

POSIX 1003.4 with extensions

Safety:
Interrupt handler No
Signal handler Yes, but modifies errno
Thread Yes

Caveats:

In order to use the mq_... functions, you must:

See also:

errno, mq_close(), mq_getattr(), mq_open(), mq_receive(), mq_send(), mq_setattr(), mq_unlink()

chapter on POSIX.4 message queues


[Previous]
[Contents]
[Next]