osfmk/man/semaphore_create.html

   1 <h2>semaphore_create</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Create a new semaphore.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   semaphore_create</strong>
   8                 <strong>(task_t</strong>                   <var>task</var>,
   9                  <strong>semaphore_t</strong>        <var>*semaphore</var>,
  10                  <strong>int</strong>                    <var>policy</var>,
  11                  <strong>int</strong>                     <var>value</var><strong>);</strong>
  12 </pre>
  13 <h3>PARAMETERS</h3>
  14 <dl>
  15 <dt> <var>task</var>
  16 <dd>
  17 [in task port] The task receiving the send right of the newly created semaphore.
  18 <p>
  19 <dt> <var>semaphore</var>
  20 <dd>
  21 [out send right] The port naming the created semaphore.
  22 <p>
  23 <dt> <var>policy</var>
  24 <dd>
  25 [in scalar] The blocked thread wakeup policy for the newly created semaphore. Valid policies are:
  26 <dl>
  27 <p>
  28   <dt> SYNC_POLICY_FIFO
  29 <dd>
  30 a first-in-first-out policy for scheduling thread wakeup.
  31      <p>
  32   <dt> SYNC_POLICY_FIXED_PRIORITY
  33 <dd>
  34 a fixed priority policy for scheduling thread wakeup.
  35      </dl>
  36      <p>
  37 <dt> <var>value</var>
  38 <dd>
  39 [in scalar] The initial value of the semaphore count.
  40 </dl>
  41 <h3>DESCRIPTION</h3>
  42 <p>
  43 The <strong>semaphore_create</strong> function creates a new semaphore, associates the
  44 created semaphore with the specified task, and returns a send right
  45 naming the new semaphore.  In order to support a robust
  46 producer/consumer communication service, Interrupt Service Routines
  47 (ISR) must be able to signal semaphores. The semaphore synchronizer
  48 service is designed to allow user-level device drivers to perform
  49 signal operations, eliminating the need for event counters.  Device
  50 drivers which utilize semaphores are responsible for creating (via
  51 <strong>semaphore_create</strong>) and exporting (via <strong>device_get_status</strong>)
  52 semaphores for
  53 user level access. Device driver semaphore creation is done at device
  54 initialization time. Device drivers may support multiple semaphores.
  55 <h3>RETURN VALUES</h3>
  56 <dl>
  57   <p>
  58 <dt> <strong>KERN_INVALID_ARGUMENT</strong>
  59 <dd>
  60 The task argument or the policy argument was invalid,
  61      or the initial value of the semaphore was invalid.
  62      <p>
  63 <dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
  64 <dd>
  65 The kernel could not allocate the semaphore.
  66      <p>
  67 <dt> <strong>KERN_SUCCESS</strong>
  68 <dd>
  69 The semaphore was successfully created.
  70 </dl>
  71 <h3>RELATED INFORMATION</h3>
  72 <p>
  73 Functions:
  74 <a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>,
  75 <a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>,
  76 <a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>,
  77 <a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>,
  78 <a href="device_get_status.html"><strong>device_get_status</strong></a>.