mq_notify(3c)

NAME
     mq_notify - register message notification request

C SYNOPSIS
     #include <mqueue.h>

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

DESCRIPTION
     mq_notify registers a message notification request with the message queue
     named by mqd. A message notification is an asynchronous event which
     informs a process of a message that has arrived on a previously empty
     queue.  A message queue transition from empty to non-empty will result in
     a notification delivery to the process that registered the request.

     There can be only one message notification registered with a queue at any
     given time.

     If the sigev_notify member of notification is SIGEV_THREAD then the
     function sigev_notify_function will be called by a new thread (see
     pthreads(5)) with sigev_value as the argument.  This thread is created
     when the event arrives with the attributes specified in
     sigev_notify_attributes except that it is automatically detached.  The
     calling process should ensure there are sufficient resources to create
     the thread.

     If the notification argument is NULL and the calling process already has
     a pending notification request, then the pending request will be cleared.
     The message queue will then be available for notification registration.

     Once a message notification is delivered to a process, or the requesting
     process exits before receiving the notification, then the request is
     cleared.  The message queue will then be available for notification
     registration.

     If a message arrives at an empty queue, and a process is blocked in
     mq_receive waiting for a message, then the waiting process will receive
     the message.  In this case, the notification request registered with the
     queue will have no effect.

     mq_notify will fail if one or more of the following conditions are true:

     [EBADF]        The message queue descriptor, mqd, is not valid.

     [EBUSY]        A notification request is already registered with the
                    queue.

     [EINTR]        A signal interrupted the mq_notify function call.

     [EAGAIN]       Insufficient memory to implement the SIGEV_THREAD service
                    for notification.
SEE ALSO
     mq_open(3c), intro(3c), mq_unlink(3c), mq_receive(3c), mq_send(3c),
     mq_getattr(3c)

DIAGNOSTICS
     Upon successful completion, a value of 0 is returned.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.