NAME
mq_notify() — register or cancel a notification request with a message queue
SYNOPSIS
#include <sys/mqueue.h>
int mq_notify(mqd_t mqdes, const struct sigevent *notification);
DESCRIPTION
If the argument
notification
is not NULL,
the
mq_notify()
system call registers the calling process to be notified of message arrival
at an empty message queue associated with the message queue descriptor
mqdes.
The notification specified by the
notification
argument will be sent to the process when the message queue transitions from
the empty state to the non-empty state.
If the type of notification specified in
notification->sigev_notify
is
SIGEV_SIGNAL,
then the signal
specified in
notification->sigev_signo
will be sent to the process.
If the
SA_SIGINFO
flag is set for that signal number, then the
value specified in
notification->sigev_value
will be the
si_value
component of the
siginfo_t
structure passed to the signal catching function at the time of signal
delivery.
At any time, only one process can be
registered for notification with a message queue.
If the calling process, or
any other process has already registered for notification with the specified
message queue, subsequent attempts to register with that queue will fail.
If
notification
is NULL
and the process is currently registered for notification with the specified
message queue, the existing registration is canceled.
When the notification is sent to the registered process, its registration
is removed.
The message queue is then available for registration.
If there is some process blocked in
mq_receive()
waiting to receive a message from a message queue, the arrival of a message
on the queue will satisfy the
mq_receive(),
even if the queue has a registered notification request.
The resulting behavior
is as if the message queue remains empty, and no notification is sent.
To use this function, link in the realtime library by specifying
-lrt
on the compiler or linker command line.
RETURN VALUE
mq_notify()
returns the following values:
- 0
Successful completion.
- -1
Failure.
errno
is set to indicate the error.
ERRORS
If
mq_notify()
fails,
errno
is set to one of the following values:
- EAGAIN
The system lacks sufficient signal queuing resources to honor the request.
- EBADF
The
mqdes
argument is not a valid message queue descriptor.
- EBUSY
A process is already registered for notification with the message queue.
- EINVAL
An attempt was made to cancel a non-existent notification request, or
notification
points to an invalid address.
- ENOSYS
mq_notify()
is not supported by the implementation.
STANDARDS CONFORMANCE
mq_notify(): POSIX 1003.1b
Printable version
