lib/librt/mq_notify.2

   1 .\"     $NetBSD: mq_notify.3,v 1.1 2009/01/05 21:19:49 rmind Exp $
   2 .\"
   3 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   4 .\"
   5 .Dd August 19, 2009
   6 .Dt MQ_NOTIFY 2
   7 .Os
   8 .Sh NAME
   9 .Nm mq_notify
  10 .Nd notify process that a message is available (REALTIME)
  11 .Sh LIBRARY
  12 .Lb librt
  13 .Sh SYNOPSIS
  14 .In mqueue.h
  15 .Ft int
  16 .Fn mq_notify "mqd_t mqdes" "const struct sigevent *notification"
  17 .Sh DESCRIPTION
  18 If the argument
  19 .Fa notification
  20 is not
  21 .Dv NULL ,
  22 this function will register the calling process to be notified of
  23 message arrival at an empty message queue associated with the
  24 specified message queue descriptor,
  25 .Fa mqdes .
  26 The notification specified by the
  27 .Fa notification
  28 argument will be sent to the process when the message queue
  29 transitions from empty to non-empty.
  30 At any time, only one process may be registered for notification
  31 by a message queue.
  32 If the calling process or any other process has already registered
  33 for notification of message arrival at the specified message queue,
  34 subsequent attempts to register for that message queue fails.
  35 .Pp
  36 If
  37 .Fa notification
  38 is
  39 .Dv NULL
  40 and the process is currently registered for notification by the
  41 specified message queue, the existing registration will be removed.
  42 .Pp
  43 When the notification is sent to the registered process,
  44 its registration will be removed.
  45 The message queue will then be available for registration.
  46 .Pp
  47 If a process has registered for notification of message arrival
  48 at a message queue and some thread is blocked in
  49 .Fn mq_receive
  50 waiting to receive a message when a message arrives at the queue,
  51 the arriving message will satisfy the appropriate
  52 .Fn mq_receive .
  53 The resulting behavior is as if the message queue remains empty,
  54 and no notification will be sent.
  55 .Sh RETURN VALUES
  56 .Rv -std mq_notify
  57 .Sh ERRORS
  58 The
  59 .Fn mq_notify
  60 function fails if:
  61 .Bl -tag -width Er
  62 .It Bq Er EBADF
  63 The
  64 .Fa mqdes
  65 argument is not a valid message queue descriptor.
  66 .It Bq Er EBUSY
  67 A process is already registered for notification by the message queue.
  68 .El
  69 .Sh SEE ALSO
  70 .Xr mq_close 2 ,
  71 .Xr mq_getattr 2 ,
  72 .Xr mq_open 2 ,
  73 .Xr mq_receive 2 ,
  74 .Xr mq_send 2 ,
  75 .Xr mq_setattr 2 ,
  76 .Xr mq_unlink 2
  77 .Sh STANDARDS
  78 This function conforms to the
  79 .St -p1003.1-2001
  80 standard.
  81 .Sh HISTORY
  82 This function first appeared in
  83 .Dx 2.5 .
  84 .Sh COPYRIGHT
  85 Portions of this text are reprinted and reproduced in electronic form
  86 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
  87 -- Portable Operating System Interface (POSIX), The Open Group Base
  88 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
  89 Electrical and Electronics Engineers, Inc and The Open Group.
  90 In the
  91 event of any discrepancy between this version and the original IEEE and
  92 The Open Group Standard, the original IEEE and The Open Group Standard
  93 is the referee document.
  94 The original Standard can be obtained online at
  95 http://www.opengroup.org/unix/online.html .