osfmk/man/semaphore_wait.html

   1 <h2>semaphore_wait</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Wait on the specified semaphore.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   semaphore_wait</strong>
   8                 <strong>(semaphore_t</strong>                          <var>semaphore</var><strong>);</strong>
   9 </pre>
  10 <h3>PARAMETERS</h3>
  11 <dl>
  12 <p>
  13 <dt> <var>semaphore</var>
  14 <dd>
  15 [in send right] The port naming the semaphore that the wait operation is being performed upon.
  16 </dl>
  17 <h3>DESCRIPTION</h3>
  18 <p>
  19 The <strong>semaphore_wait</strong> function decrements the semaphore count. If the
  20 semaphore count is negative after decrementing, the calling thread
  21 blocks.  Device driver interrupt service routines (ISR) should never
  22 execute <strong>semaphore_wait</strong>, since waiting on a semaphore at the ISR level
  23 may, and often will, lead to a deadlock.
  24 <h3>RETURN VALUES</h3>
  25 <dl>
  26 <p>
  27 <dt> <strong>KERN_INVALID_ARGUMENT</strong>
  28 <dd>
  29 The specified semaphore is invalid.
  30 <p>
  31 <dt> <strong>KERN_TERMINATED</strong>
  32 <dd>
  33 The specified semaphore has been destroyed.
  34 <p>
  35 <dt> <strong>KERN_ABORTED</strong>
  36 <dd>
  37 The caller was blocked due to a negative count on the semaphore, and was
  38      awoken for a reason not related to the semaphore subsystem
  39      (e.g. <strong>thread_terminate</strong>).
  40 <p>
  41 <dt> <strong>KERN_SUCCESS</strong>
  42 <dd>
  43 The semaphore wait operation was successful.
  44 </dl>
  45 <h3>RELATED INFORMATION</h3>
  46 <p>
  47 Functions:
  48 <a href="semaphore_create.html"><strong>semaphore_create</strong></a>,
  49 <a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>,
  50 <a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>,
  51 <a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>,
  52 <a href="device_get_status.html"><strong>device_get_status</strong></a>.