mq_notify()
Ask to be notified when there's a message in the queue
Synopsis:
#include <mqueue.h>
int mq_notify(
mqd_t mqdes,
const struct sigevent* notification );
Arguments:
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
If notification isn't NULL, the mq_notify() function registers the caller for notification when the queue identified by mqdes transitions from an empty to non-empty state. When this happens, the sigevent pointed to by notification is delivered to the caller. Once the caller has been notified about the queue's transition, the notification is removed.
- The message queue manager needs to be running. For more information, see the entry mqueue in the Utilities Reference.
- This function accepts registered events (see MsgRegisterEvent()), but for compatibility with POSIX, it also accepts unregistered events.
We recommend that you use the following event types in this case:
- SIGEV_SIGNAL
- SIGEV_SIGNAL_CODE
- SIGEV_SIGNAL_THREAD
- SIGEV_PULSE
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.
If a process has registered for notification, and another process is blocked on mq_receive(), then 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, then the existing registration is removed.
Returns:
-1 if an error occurred (errno is set). Any other value indicates success.
Errors:
- EBADF
- The message-queue descriptor mqdes is invalid.
- EBUSY
- A process has already registered for notification for the given queue.
- EINVAL
- The caller requested to remove the existing notification, but the notification was registered by a different process.
Classification:
| Safety: | |
|---|---|
| Cancellation point | No |
| Signal handler | No |
| Thread | Yes |