NAME    [Toc]    [Back]

       mq_notify  -  Attaches  a  request for asynchronous signal
       notification to a message queue (P1003.1b)

SYNOPSIS    [Toc]    [Back]

       #include <mqueue.h>

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

LIBRARY    [Toc]    [Back]

       Realtime Library (librt.so, librt.a)

PARAMETERS    [Toc]    [Back]

       Specifies  a message queue descriptor.  Specifies a signal
       to be sent when the specified queue accepts a message.  If
       the  notification  argument  is  NULL, and the process has
       previously attached a notification request to the  message
       queue  with  this mqdes argument, the notification request
       is detached and the queue is available for another process
       to attach a notification request.

DESCRIPTION    [Toc]    [Back]

       The mq_notify function attaches a request for asynchronous
       signal notification to a message  queue  for  the  calling
       process.  Following a call to this function, the specified
       signal is sent to the calling process when the queue transitions
  from  empty  to  non-empty. Two or more processes
       cannot attach notification requests to the same  queue  at
       the same time.

       If  a  process has attached a notification request and any
       process is blocked in  the  execution  of  the  mq_receive
       function  waiting  to  receive  a  message  when a message
       arrives at the  queue,  then  the  appropriate  mq_receive
       function  is  completed and the notification remains pending.


       When the notification has been sent, the  registration  is
       canceled.  In  effect,  it  is a one-shot notification and
       must be re-registered if required.

       Note that the POSIX IPC functions are not  reentrant  with
       respect to signals.  For example, if your application were
       to use a signal to notify it that a queue has become  nonempty
  and then attempt to call mq_receive from the signal
       handler, the signal handler must reside in a thread  other
       than  the tread that called mq_send. Otherwise, a deadlock
       on internal locks would occur.

RETURN VALUES    [Toc]    [Back]

       On successful completion, the function returns the value 0
       (zero);  otherwise,  the function returns the value -1 and
       sets errno to indicate the error.

ERRORS    [Toc]    [Back]

       The mq_notify function fails under  the  following  conditions:
  The  mqdes  argument  is not a valid message queue
       descriptor.  A process has already attached to  this  message
  queue  for asynchronous notification, or the calling
       process attempted to cancel a request that was attached by
       another  process.   The requested signo is invalid, or the
       sigev_notify field of the notification structure does  not
       equal SIGEV_SIGNAL.

SEE ALSO    [Toc]    [Back]

       Functions: mq_open(3), mq_send(3)

       Guide to Realtime Programming



                                                     mq_notify(3)