mq_notify Subroutine

Purpose

Notifies a process that a message is available.

Library

Standard C Library (libc.a)

Syntax

#include <mqueue.h>

int mq_notify (mqdes, notification)
mqd_t mqdes;
const struct sigevent *notification;

Description

If the notification parameter is not NULL, the mq_notify subroutine registers the calling process to be notified of message arrival at an empty message queue associated with the specified message queue descriptor, mqdes. The notification specified by the notification parameter is sent to the process when the message queue transitions from empty to non-empty. At any time only one process may be registered for notification by a message queue. If the calling process or any other process has already registered for notification of message arrival at the specified message queue, subsequent attempts to register for that message queue fails.

If notification is NULL and the process is currently registered for notification by the specified message queue, the existing registration is removed.

When the notification is sent to the registered process, its registration is removed. The message queue is then available for registration.

If a process has registered for notification of message arrival at a message queue and a thread is blocked in the mq_receive or mq_timedreceive subroutines waiting to receive a message, the arriving message satisfies the appropriate mq_receive or mq_timedreceive subroutine respectively. The resulting behavior is as if the message queue remains empty, and no notification is sent.

Parameters

Item Description
mqdes Specifies a message queue descriptor.
notification Points to the sigevent structure.

Return Values

Upon successful completion, the mq_notify subroutine returns a zero. Otherwise, it returns a value of -1 and sets errno to indicate the error.

Error Codes

The mq_notify subroutine fails if:
Item Description
EBADF The mqdes parameter is not a valid message queue descriptor.
EBUSY A process is already registered for notification by the message queue.
EFAULT Invalid used address.
ENOMEM Insufficient memory for the required operation.
ENOTSUP This function is not supported with processes that have been checkpoint-restart'ed.
EINVAL The current process is not registered for notification for the specified message queue and registration removal was requested.