osfmk/man/MP_request_notification.html

   1 <h2>mach_port_request_notification</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Request notification of the specified port event type.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   mach_port_request_notification</strong>
   8                 <strong>(ipc_space_t</strong>                               <var>task</var>,
   9                  <strong>mach_port_name_t</strong>                          <var>name</var>,
  10                  <strong>mach_msg_id_t</strong>                          <var>variant</var>,
  11                  <strong>mach_port_mscount_t</strong>                       <var>sync</var>,
  12                  <strong>mach_port_send_once_t</strong>                   <var>notify</var>,
  13                  <strong>mach_msg_type_name_t</strong>               <var>notify_type</var>,
  14                  <strong>mach_port_send_once_t</strong>                <var>*previous</var><strong>);</strong>
  15 </pre>
  16 <h3>PARAMETERS</h3>
  17 <dl>
  18 <p>
  19 <dt> <var>task</var>
  20 <dd>
  21 [in task send right]
  22 The task holding the specified right.
  23 <p>
  24 <dt> <var>name</var>
  25 <dd>
  26 [in scalar]
  27 The task's name for the right.
  28 <p>
  29 <dt> <var>variant</var>
  30 <dd>
  31 [in scalar]
  32 The type of notification.
  33 <p>
  34 <dt> <var>sync</var>
  35 <dd>
  36 [in scalar]
  37 Some variants use this value to overcome race conditions.
  38 <p>
  39 <dt> <var>notify</var>
  40 <dd>
  41 [in notify send-once or receive (to be converted to send-once) right]
  42 A
  43 send-once right, to which the notification will be sent.
  44 <p>
  45 <dt> <var>notify_type</var>
  46 <dd>
  47 [in scalar]
  48 IPC type of the <var>notify</var> right; either
  49 <strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or <strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>.
  50 <p>
  51 <dt> <var>previous</var>
  52 <dd>
  53 [out notify send-once right]
  54 The previously registered send-once right.
  55 </dl>
  56 <h3>DESCRIPTION</h3>
  57 <p>
  58 The <strong>mach_port_request_notification</strong> function registers a request for a
  59 notification and supplies a send-once right that the notification
  60 will use.  It is an atomic
  61 swap, returning the previously registered send-once right (or
  62 <strong>MACH_PORT_NULL</strong> for none).  A notification request may be
  63 cancelled by providing <strong>MACH_PORT_NULL</strong>.
  64 <p>
  65 The <var>variant</var> argument takes the following values:
  66 <dl>
  67 <dt> <strong>MACH_NOTIFY_PORT_DESTROYED</strong>
  68 <dd>
  69 <var>sync</var> must be zero.  The <var>name</var> must specify a receive right,
  70 and the call requests a port-destroyed notification for the receive
  71 right.  If the receive right were to have been destroyed, for instance
  72 by <strong>mach_port_destroy</strong>, then instead the receive right will be
  73 sent in a port-destroyed notification to the registered send-once right.
  74 <p>
  75 <dt> <strong>MACH_NOTIFY_DEAD_NAME</strong>
  76 <dd>
  77 The call requests a dead-name notification.  <var>name</var> specifies send,
  78 receive, or send-once rights for a port.  If the port is destroyed (and the
  79 right remains, becoming a dead name), then a dead-name notification
  80 which carries the name of the right will be sent to the registered
  81 send-once right.  If <var>sync</var> is non-zero,
  82 the <var>name</var> may specify a dead name, and
  83 a dead-name notification is immediately generated.
  84 <p>
  85 Whenever a dead-name notification is generated, the user reference
  86 count of the dead name is incremented.  For example, a send right with
  87 two user refs has a registered dead-name request.  If the port is
  88 destroyed, the send right turns into a dead name with three user refs
  89 (instead of two), and a dead-name notification is generated.
  90 <p>
  91 If the name is made available for reuse, perhaps because of
  92 <strong>mach_port_destroy</strong> or <strong>mach_port_mod_refs</strong>,
  93 or the name denotes a
  94 send-once right which has a message sent to it, then the registered send-once
  95 right is used to generate a port-deleted notification instead.
  96 <p>
  97 <dt> <strong>MACH_NOTIFY_NO_SENDERS</strong>
  98 <dd>
  99 The call requests a no-senders notification.  <var>name</var> must specify a
 100 receive right.  If the receive right's make-send count is greater than or
 101 equal to the sync value, and it has no extant send rights, than an
 102 immediate no-senders notification is generated.  Otherwise the notification is
 103 generated when the receive right next loses its last extant send right.  In
 104 either case, any previously registered send-once right is returned.
 105 <p>
 106 The no-senders notification carries the value the port's make-send
 107 count had when it was generated.  The make-send count is incremented
 108 whenever a send right is made directly from a receive right.  The
 109 make-send count is reset to zero when the receive right is carried in a
 110 message.
 111 <p>
 112 When moving a receive right, no-senders notifications are canceled,
 113 with a send-once notification sent to indicate the cancelation.
 114 </dl>
 115 <h3>NOTES</h3>
 116 <p>
 117 This interface is machine word length specific because of the port name
 118 parameter.
 119 <h3>RETURN VALUES</h3>
 120 <dl>
 121 <p>
 122 <dt> <strong>KERN_INVALID_NAME</strong>
 123 <dd>
 124 <var>name</var> did not denote a right.
 125 <p>
 126 <dt> <strong>KERN_INVALID_RIGHT</strong>
 127 <dd>
 128 <var>name</var> denoted an invalid right.
 129 <p>
 130 <dt> <strong>KERN_INVALID_CAPABILITY</strong>
 131 <dd>
 132 <var>notify</var> was invalid.
 133 </dl>
 134 <p>
 135 When using <strong>MACH_NOTIFY_DEAD_NAME</strong>:
 136 <dl>
 137 <p>
 138 <dt> <strong>KERN_UREFS_OVERFLOW</strong>
 139 <dd>
 140 <var>name</var> denotes a dead name, but generating an immediate dead-name
 141 notification would overflow the name's user-reference count.
 142 </dl>
 143 <h3>RELATED INFORMATION</h3>
 144 <p>
 145 Functions:
 146 <a href="mach_msg.html"><strong>mach_msg</strong></a>,
 147 <a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.