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>
30a first-in-first-out policy for scheduling thread wakeup.
31     <p>
32  <dt> SYNC_POLICY_FIXED_PRIORITY
33<dd>
34a 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>
43The <strong>semaphore_create</strong> function creates a new semaphore, associates the
44created semaphore with the specified task, and returns a send right
45naming the new semaphore.  In order to support a robust
46producer/consumer communication service, Interrupt Service Routines
47(ISR) must be able to signal semaphores. The semaphore synchronizer
48service is designed to allow user-level device drivers to perform
49signal operations, eliminating the need for event counters.  Device
50drivers which utilize semaphores are responsible for creating (via
51<strong>semaphore_create</strong>) and exporting (via <strong>device_get_status</strong>)
52semaphores for
53user level access. Device driver semaphore creation is done at device
54initialization 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>
60The 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>
65The kernel could not allocate the semaphore.
66     <p>
67<dt> <strong>KERN_SUCCESS</strong>
68<dd>
69The semaphore was successfully created.
70</dl>
71<h3>RELATED INFORMATION</h3>
72<p>
73Functions:
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>.
79