NuttxUserGuide.html

<b>Returned Values:</b> 
<ul>
<li>The current value of the lockCount.
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> None.
<hr>

<H2>2.4 <A NAME="Message_Queue">Named Message Queue Interfaces</a></H2>

<p>
  NuttX supports POSIX named message queues for intertask communication.
  Any task may send or receive messages on named message queues.
  Interrupt handlers may send messages via named message queues.
</p>
<ul>
  <li><a href="#mqopen">2.4.1 mq_open</a></li>
  <li><a href="#mqclose">2.4.2 mq_close</a></li>
  <li><a href="#mqunlink">2.4.3 mq_unlink</a></li>
  <li><a href="#mqsend">2.4.4 mq_send</a></li>
  <li><a href="#mqtimedsend">2.4.5 mq_timedsend</a></li>
  <li><a href="#mqreceive">2.4.6 mq_receive</a></li>
  <li><a href="#mqtimedreceive">2.4.7 mq_timedreceive</a></li>
  <li><a href="#mqnotify">2.4.8 mq_notify</a></li>
  <li><a href="#mqsetattr">2.4.9 mq_setattr</a></li>
  <li><a href="#mqgetattr">2.4.10 mq_getattr</a></li>
</ul>

<H3><a name="mqopen">2.4.1 mq_open</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;mqueue.h&gt;
    mqd_t mq_open( const char *mqName, int oflags, ... );
</pre>

<p>
<b>Description:</b> This function establish a connection between
a named message queue and the calling task. After a successful
call of mq_open(), the task can reference the message queue using
the address returned by the call. The message queue remains usable
until it is closed by a successful call to mq_close().
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>mqName</I>. Name of the queue to open
<li><I>oflags</I>. Open flags. These may be any combination of:
<ul>
<li><I>O_RDONLY</I>. Open for read access.
<li><I>O_WRONLY</I>. Open for write access.
<li><I>O_RDWR</I>. Open for both read &amp; write access.
<li><I>O_CREAT</I>. Create message queue if it does not already
exist.
<li><I>O_EXCL</I>. Name must not exist when opened.
<li><I>O_NONBLOCK</I>. Don't wait for data.
</ul>

<li><I>... Optional parameters</I>.
When the O_CREAT flag is specified, POSIX requires that a third
and fourth parameter be supplied:
<ul>
<li><I>mode</I>.  The mode parameter is of type mode_t.  In the POSIX
specification, this mode value provides file permission bits for the
message queue.  This parameter is required but not used in the present
implementation.
<li><I>attr</I>.  A pointer to an mq_attr that is provided to initialize.
the message queue.  If attr is NULL, then the messages queue is created
with implementation-defined default message queue attributes.  If attr is
non-NULL, then the message queue mq_maxmsg attribute is set to the
corresponding value when the queue is created.  The mq_maxmsg attribute
determines the maximum number of messages that can be queued before
addition attempts to send messages on the message queue fail or cause the
sender to block; the mq_msgsize attribute determines the maximum size of a
message that can be sent or received.  Other elements of attr are ignored
(i.e, set to default message queue attributes).
</ul>
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>A message queue descriptor or -1 (ERROR)
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX interface
of the same name.
Differences from the full POSIX implementation include:
<ul>
<li>The mq_msgsize attributes determines the maximum size of a message that
may be sent or received.  In the present implementation, this maximum
message size is limited at 22 bytes.
</ul>

<H3><a name="mqclose">2.4.2 mq_close</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;mqueue.h&gt;
    int mq_close( mqd_t mqdes );
</pre>

<p>
<b>Description:</b> This function is used to indicate that the
calling task is finished with the specified message queued mqdes.
The mq_close() deallocates any system resources allocated by the
system for use by this task for its message queue.
<p>
If the calling task has attached a notification request to the message
queue via this <I>mqdes</I> (see mq_notify()), this attachment will be
removed and the message queue is available for another task to attach
for notification.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>mqdes</I>. Message queue descriptor.
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK) if the message queue is closed successfully, otherwise,
-1 (ERROR).
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<p>
<ul>
<li>The behavior of a task that is blocked on either a <code>mq_send()</code> or
<code>mq_receive()</code> is undefined when <code>mq_close()</code> is called.
<li>The result of using this message queue descriptor after successful
return from mq_close() is undefined.
</ul>
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX interface
of the same name.

<H3><a name="mqunlink">2.4.3 mq_unlink</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;mqueue.h&gt;
    int mq_unlink( const char *mqName );
</pre>

<p>
<b>Description:</b> This function removes the message queue named
by &quot;mqName.&quot; If one or more tasks have the message queue
open when mq_unlink() is called, removal of the message queue
is postponed until all references to the message queue have been
closed.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>mqName</I>. Name of the message queue
</ul>

<p>
<b>Returned Values:</b> None.
<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="mqsend">2.4.4 mq_send</a></H3>
<p>
<b>Function Prototype:</b> 
</p>
<pre>
    #include &lt;mqueue.h&gt;
    int mq_send(mqd_t mqdes, const void *msg, size_t msglen, int prio);
</pre>
<p>
<b>Description:</b>
  This function adds the specified message, <code>msg</code>,
  to the message queue, <code>mqdes</code>.
  The <code>msglen</code> parameter specifies the length of the message in bytes pointed to by <code>msg</code>.
  This length must not exceed the maximum message length from the <code>mq_getattr()</code>.
</p>
<p>
  If the message queue is not full, <code>mq_send()</code> will place the <code>msg</code>
  in the message queue at the position indicated by the <code>prio</code> argument.
  Messages with higher priority will be inserted before lower priority messages
  The value of <code>prio</code> must not exceed <code>MQ_PRIO_MAX</code>.
</p>
<p>
  If the specified message queue is full and <code>O_NONBLOCK</code> is not
  set in the message queue, then <code>mq_send()</code> will block until space
  becomes available to the queue the message.
</p>
<p>
  If the message queue is full and <code>NON_BLOCK</code> is set, the message
  is not queued and <code>ERROR</code> is returned.
</p>
<p>
  <b>Input Parameters:</b> 
</p>
<ul>
  <li><code>mqdes</code>. Message queue descriptor.</li>
  <li><code>msg</code>. Message to send.</li>
  <li><code>msglen</code>. The length of the message in bytes.</li>
  <li><code>prio</code>. The priority of the message.</li>
</ul>
<p>
  <b>Returned Values:</b>
  On success, <code>mq_send()</code> returns 0 (<code>OK</code>);
  on error, -1 (<code>ERROR</code>) is returned, with <code>errno</code> set
  to indicate the error:
</p>
<ul>
  <li>
    <code>EAGAIN</code>.
    The queue was empty, and the <code>O_NONBLOCK</code> flag was set for the message queue description referred to by <code>mqdes</code>.
  </li>
  <li>
    <code>EINVAL</code>.
    Either <code>msg</code> or <code>mqdes</code> is <code>NULL</code> or the value of <code>prio</code> is invalid.
  </li>
  <li>
    <code>EPERM</code>.
    Message queue opened not opened for writing.
  </li>
  <li>
    <code>EMSGSIZE</code>.
    <code>msglen</code> was greater than the <code>maxmsgsize</code> attribute of the message queue.
  </li>
  <li>
    <code>EINTR</code>.
    The call was interrupted by a signal handler.
  </li>
</ul>
<p>
  <b>Assumptions/Limitations:</b> 
</p>
<p>
  <b>POSIX  Compatibility:</b>
  Comparable to the POSIX interface of the same name.
</p>

<h3><a name="mqtimedsend">mq_timedsend</a></h3>
<b>Function Prototype:</b> 
</p>
<pre>
    #include &lt;mqueue.h&gt;
    int mq_timedsend(mqd_t mqdes, const char *msg, size_t msglen, int prio,
                     const struct timespec *abstime);
</pre>
<p>
<b>Description:</b>
  This function adds the specified message, <code>msg</code>,
  to the message queue, <code>mqdes</code>.
  The <code>msglen</code> parameter specifies the length of the message in bytes pointed to by <code>msg</code>.
  This length must not exceed the maximum message length from the <code>mq_getattr()</code>.
</p>
<p>
  If the message queue is not full, <code>mq_timedsend()</code> will place the <code>msg</code>
  in the message queue at the position indicated by the <code>prio</code> argument.
  Messages with higher priority will be inserted before lower priority messages
  The value of <code>prio</code> must not exceed <code>MQ_PRIO_MAX</code>.
</p>
<p>
  If the specified message queue is full and <code>O_NONBLOCK</code> is not
  set in the message queue, then <code>mq_send()</code> will block until space
  becomes available to the queue the message or until a timeout occurs.
</p>
<p>
  <code>mq_timedsend()</code> behaves just like <code>mq_send()</code>, except
  that if the queue is full and the <code>O_NONBLOCK</code> flag is not enabled
  for the message queue description, then <code>abstime</code> points to a
  structure which specifies a ceiling on the time for which the call will block.
  This ceiling is an absolute timeout in seconds and nanoseconds since the
  Epoch (midnight on the morning of 1 January 1970).
</p>
<p>
  If the message queue is full, and the timeout has already expired by the time
  of the call, <code>mq_timedsend()<code> returns immediately.
</p>
<p>
  <b>Input Parameters:</b> 
</p>
<ul>
  <li><code>mqdes</code>. Message queue descriptor.</li>
  <li><code>msg</code>. Message to send.</li>
  <li><code>msglen</code>. The length of the message in bytes.</li>
  <li><code>prio</code>. The priority of the message.</li>
</ul>
<p>
  <b>Returned Values:</b>
  On success, <code>mq_send()</code> returns 0 (<code>OK</code>);
  on error, -1 (<code>ERROR</code>) is returned, with <code>errno</code> set
  to indicate the error:
</p>
<ul>
  <li>
    <code>EAGAIN</code>.
    The queue was empty, and the <code>O_NONBLOCK</code> flag was set for the message queue description referred to by <code>mqdes</code>.
  </li>
  <li>
    <code>EINVAL</code>.
    Either <code>msg</code> or <code>mqdes</code> is <code>NULL</code> or the value of <code>prio</code> is invalid.
  </li>
  <li>
    <code>EPERM</code>.
    Message queue opened not opened for writing.
  </li>
  <li>
    <code>EMSGSIZE</code>.
    <code>msglen</code> was greater than the <code>maxmsgsize</code> attribute of the message queue.
  </li>
  <li>
    <code>EINTR</code>.
    The call was interrupted by a signal handler.
  </li>
</ul>
<p>
  <b>Assumptions/Limitations:</b> 
</p>
<p>
  <b>POSIX  Compatibility:</b>
  Comparable to the POSIX interface of the same name.
</p>

<h3><a name="mqreceive">2.4.5 mq_receive</a></h3>
<p>
  <b>Function Prototype:</b> 
</p>
<pre>
    #include &lt;mqueue.h&gt;
    ssize_t mq_receive(mqd_t mqdes, void *msg, size_t msglen, int *prio);
</pre>
<p>
  <b>Description:</b>
  This function receives the oldest of the highest priority messages from the message
  queue specified by <code>mqdes</code>.
  If the size of the buffer in bytes, <code>msgLen</code>, is less than the
  <code>mq_msgsize</code> attribute of the message queue, <code>mq_receive()</code> will
  return an error.
  Otherwise, the selected message is removed from the queue and copied to <code>msg</code>.
</p>
<p>
  If the message queue is empty and <code>O_NONBLOCK</code> was not set, <code>mq_receive()</code>
  will block until a message is added to the message queue.
  If more than one task is waiting to receive a message, only the task with the highest
  priority that has waited the longest will be unblocked.
</p>
<p>
  If the queue is empty and <code>O_NONBLOCK</code> is set, <code>ERROR</code> will be returned.
</p>
<p>
  <b>Input Parameters:</b> 
</p>
<ul>
  <li><code>mqdes</code>. Message Queue Descriptor.</li>
  <li><code>msg</code>. Buffer to receive the message.</li>
  <li><code>msglen</code>. Size of the buffer in bytes.</li>
  <li><code>prio</code>. If not NULL, the location to store message priority.
</ul>
<p>
  <b>Returned Values:</b>.
  One success, the length of the selected message in bytes is returned.
  On failure, -1 (<code>ERROR</code>) is returned and the <code>errno</code> is set appropriately:
</p>
<ul>
  <li>
    <code>EAGAIN</code>
    The queue was empty and the <code>O_NONBLOCK</code> flag was set for the message queue description referred to by <code>mqdes</code>.
  </li>
  <li>
    <code>EPERM</code>
    Message queue opened not opened for reading.
  </li>
  <li>
    <code>EMSGSIZE</code>
    <code>msglen</code> was less than the <code>maxmsgsize</code> attribute of the message queue.
  </li>
  <li>
    <code>EINTR</code>
    The call was interrupted by a signal handler.
  </li>
  <li>
    <code>EINVAL</code>
    Invalid <code>msg</code> or <code>mqdes</code>
  </li>
</ul>
<p>
  <b>Assumptions/Limitations:</b> 
</p>
<p>
  <b>POSIX  Compatibility:</b>
  Comparable to the POSIX interface of the same name.
</p>

<h3><a name="mqtimedreceive">2.4.6 mq_timedreceive</a></h3>
<p>
  <b>Function Prototype:</b> 
</p>
<pre>
    #include &lt;mqueue.h&gt;
    ssize_t mq_timedreceive(mqd_t mqdes, void *msg, size_t msglen,
                            int *prio, const struct timespec *abstime);
</pre>
<p>
  <b>Description:</b>
  This function receives the oldest of the highest priority messages from the message
  queue specified by <code>mqdes</code>.
  If the size of the buffer in bytes, <code>msgLen</code>, is less than the
  <code>mq_msgsize</code> attribute of the message queue, <code>mq_timedreceive()</code> will
  return an error.
  Otherwise, the selected message is removed from the queue and copied to <code>msg</code>.
</p>
<p>
  If the message queue is empty and <code>O_NONBLOCK</code> was not set, <code>mq_timedreceive()</code>
  will block until a message is added to the message queue (or until a timeout occurs).
  If more than one task is waiting to receive a message, only the task with the highest
  priority that has waited the longest will be unblocked.
</p>
<p>
  <code>mq_timedreceive()</code> behaves just like <code>mq_receive()<code>, except
  that if the queue is empty and the <code>O_NONBLOCK<c/ode> flag is not enabled
  for the message queue description, then <code>abstime</code> points to a structure
  which specifies a ceiling on the time for which the call will block.
  This ceiling is an absolute timeout in seconds and nanoseconds since the Epoch
  (midnight on the morning of 1 January 1970).
</p>
<p>
  If no message is available, and the timeout has already expired by the time of
  the call, <code>mq_timedreceive()</code> returns immediately.
</p>
<p>
  <b>Input Parameters:</b> 
</p>
<ul>
  <li><code>mqdes</code>. Message Queue Descriptor.</li>
  <li><code>msg</code>. Buffer to receive the message.</li>
  <li><code>msglen</code>. Size of the buffer in bytes.</li>
  <li><code>prio</code>. If not NULL, the location to store message priority.
  <li><code>abstime</code>. The absolute time to wait until a timeout is declared.
</ul>
<p>
  <b>Returned Values:</b>.
  One success, the length of the selected message in bytes is returned.
  On failure, -1 (<code>ERROR</code>) is returned and the <code>errno</code> is set appropriately:
</p>
<ul>
  <li>
    <code>EAGAIN</code>:
    The queue was empty and the <code>O_NONBLOCK</code> flag was set for the message queue description referred to by <code>mqdes</code>.
  </li>
  <li>
    <code>EPERM</code>:
    Message queue opened not opened for reading.
  </li>
  <li>
    <code>EMSGSIZE</code>:
    <code>msglen</code> was less than the <code>maxmsgsize</code> attribute of the message queue.
  </li>
  <li>
    <code>EINTR</code>:
    The call was interrupted by a signal handler.
  </li>
  <li>
    <code>EINVAL</code>:
    Invalid <code>msg</code> or <code>mqdes</code> or <code>abstime</code>
  </li>
  <li>
    <code>ETIMEDOUT</code>:
    The call timed out before a message could be transferred.
  </li>
</ul>
<p>
  <b>Assumptions/Limitations:</b> 
</p>
<p>
  <b>POSIX  Compatibility:</b>
  Comparable to the POSIX interface of the same name.
</p>

<h3><a name="mqnotify">2.4.7 mq_notify</a></h3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;mqueue.h&gt;
    int mq_notify(mqd_t mqdes, const struct sigevent *notification);
</pre>

<p>
<b>Description:</b> If the &quot;notification&quot; input parameter
is not NULL, this function connects the task with the message queue such
that the specified signal will be sent to the task whenever the message
changes from empty to non-empty. One notification can be attached
to a message queue.
<p>
If &quot;notification&quot; is NULL, the attached notification
is detached (if it was held by the calling task) and the queue
is available to attach another notification.
<p>
When the notification is sent to the registered task, its registration
will be removed.  The message queue will then be available for
registration.
<p>
<b>Input Parameters:</b>
<ul>
<li><I>mqdes</I>. Message queue descriptor
<li><I>notification</I>. Real-time signal structure containing:
<ul>
<li><I>sigev_notify</I>. Should be osSIGEV_SIGNAL (but actually
ignored)
<li><I>sigev_signo</I>. The signo to use for the notification
<li><I>sigev_value</I>. Value associated with the signal
</ul>

</ul>

<p>
<b>Returned Values:</b> None.
<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX interface
of the same name.
Differences from the full POSIX implementation include:
<ul>
<li>The notification signal will be sent to the registered task even if
another task is waiting for the message queue to become non-empty.  This is
inconsistent with the POSIX specification which states, &quot;If a process
has registered for notification of message arrival at a message queue and
some process is blocked in <I>mq_receive</I> waiting to receive a message
when a message arrives at the queue, the arriving message shall satisfy the
appropriate <I>mq_receive()</I> ... The resulting behavior is as if the
message queue remains empty, and no notification shall be sent.&quot;
</ul>

<H3><a name="mqsetattr">2.4.8 mq_setattr</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;mqueue.h&gt;
    int mq_setattr( mqd_t mqdes, const struct mq_attr *mqStat,
                     struct mq_attr *oldMqStat);
</pre>

<p>
<b>Description:</b> This function sets the attributes associated
with the specified message queue &quot;mqdes.&quot; Only the &quot;O_NONBLOCK&quot;
bit of the &quot;mq_flags&quot; can be changed.
<p>
If &quot;oldMqStat&quot; is non-null, mq_setattr() will store
the previous message queue attributes at that location (just as
would have been returned by mq_getattr()).
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>mqdes</I>. Message queue descriptor
<li><I>mqStat</I>. New attributes
<li><I>oldMqState</I>. Old attributes
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK) if attributes are set successfully, otherwise -1
(ERROR).
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="mqgetattr">2.4.9 mq_getattr</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;mqueue.h&gt;
    int mq_getattr( mqd_t mqdes, struct mq_attr *mqStat);
</pre>

<p>
<b>Description:</b> This functions gets status information and
attributes associated with the specified message queue.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>mqdes</I>. Message queue descriptor
<li><I>mqStat</I>. Buffer in which to return attributes. The returned
attributes include:
<ul>
<li><I>mq_maxmsg</I>. Max number of messages in queue.
<li><I>mq_msgsize</I>. Max message size.
<li><I>mq_flags</I>. Queue flags.
<li><I>mq_curmsgs</I>. Number of messages currently in queue.
</ul>

</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK) if attributes provided, -1 (ERROR) otherwise.
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H2>2.5 <A NAME="Semaphores">Counting Semaphore Interfaces</a></H2>

<p>
  <b>Semaphores</b>.  Semaphores are the basis for
  synchronization and mutual exclusion in NuttX. NuttX supports
  POSIX semaphores.
</p>
<p>
  Semaphores are the preferred mechanism for gaining exclusive access to a
  resource.  sched_lock() and sched_unlock() can also be used for this purpose.
  However, sched_lock() and sched_unlock() have other undesirable side-affects
  in the operation of the system:  sched_lock() also prevents higher-priority
  tasks from running that do not depend upon the semaphore-managed resource
  and, as a result, can adversely affect system response times.
</p>
<p>
  <b>Priority Inversion</b>.  Proper use of semaphores avoids the issues of
  sched_lock().  However, consider the following example:
  <OL>
    <li>Some low-priority task, <I>Task C</I>, acquires a semphore in order to
      get exclusive access to a protected resource.</li>
    <li><I>Task C</I> is suspended to allow some high-priority task,</li>
      <I>Task A</I>, to execute.</li>
    <li><I>Task A</I> attempts to acquire the semaphore held by <I>Task C</I> and
      gets blocked until <I>Task C</I> relinquishes the semaphore.</li>
    <li><I>Task C</I> is allowed to execute again, but gets suspended by some
      medium-priority <I>Task B</I>.</li>
  </OL>
<p>
  At this point, the high-priority <I>Task A</I> cannot execute until
  <I>Task B</I> (and possibly other medium-priority tasks) completes and until
  <I>Task C</I> relinquishes the semaphore.  In effect, the high-priority task,
  <I>Task A</I> behaves as though it were lower in priority than the
  low-priority task, <I>Task C</I>!  This phenomenon is called <I>priority
  inversion</I>.
</p>
<p>
  Some operating systems avoid priority inversion by <I>automatically</I>
  increasing the priority of the low-priority <I>Task C</I> (the operable
  buzz-word for this behavior is <I>priority inheritance</I>).  NuttX does not
  support this behavior.  As a consequence, it is left to the designer to
  provide implementations that will not suffer from priority inversion.
  The designer may, as examples:
</p>
<ul>
  <li>Implement all tasks that need the semphore-managed resources at the
    same priority level,</li>
  <li>Boost the priority of the low-priority task before the semaphore is
    acquired, or</li>
  <li>Use sched_lock() in the low-priority task.</li>
</ul>
<p>
  POSIX semaphore interfaces:
</p>
<ul>
  <li><a href="#seminit">2.5.1 sem_init</a></li>
  <li><a href="#semdestroy">2.5.2 sem_destroy</a></li>
  <li><a href="#semopen">2.5.3 sem_open</a></li>
  <li><a href="#semclose">2.5.4 sem_close</a></li>
  <li><a href="#semunlink">2.5.5 sem_unlink</a></li>
  <li><a href="#semwait">2.5.6 sem_wait</a></li>
  <li><a href="#semtrywait">2.5.7 sem_trywait</a></li>
  <li><a href="#sempost">2.5.8 sem_post</a></li>
  <li><a href="#semgetvalue">2.5.9 sem_getvalue</a></li>
</ul>

<H3><a name="seminit">2.5.1 sem_init</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    int sem_init ( sem_t *sem, int pshared, unsigned int value );
</pre>

<p>
<b>Description:</b> This function initializes the UN-NAMED semaphore
sem. Following a successful call to sem_init(), the semaphore
may be used in subsequent calls to sem_wait(), sem_post(), and
sem_trywait(). The semaphore remains usable until it is destroyed.
<p>
Only <I>sem</I> itself may be used for performing synchronization.  The
result of referring to copies of <I>sem</I> in calls to <I>sem_wait()</I>,
<I>sem_trywait()</I>, <I>sem_post()</I>, and <I>sem_destroy()</I>, is
not defined.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>sem</I>. Semaphore to be initialized
<li><I>pshared</I>. Process sharing (not used)
<li><I>value</I>. Semaphore initialization value 
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK), or -1 (ERROR) if unsuccessful.
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.
Differences from the full POSIX implementation include:
<ul>
<li>pshared is not used.
</ul>

<H3><a name="semdestroy">2.5.2 sem_destroy</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    int sem_destroy ( sem_t *sem );
</pre>

<p>
<b>Description:</b> This function is used to destroy the un-named semaphore
indicated by <I>sem</I>.  Only a semaphore that was created using
<I>sem_init()</I> may be destroyed using <I>sem_destroy()</I>.  The effect
of calling <I>sem_destroy()</I> with a named semaphore is undefined.  The
effect of subsequent use of the semaphore <I>sem</I> is undefined until
<I>sem</I> is re-initialized by another call to <I>sem_init()</I>.
<p>
The effect of destroying a semaphore upon which other tasks are currently
blocked is undefined.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>sem</I>. Semaphore to be destroyed.
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK), or -1 (ERROR) if unsuccessful.
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="semopen">2.5.3 sem_open</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    sem_t *sem_open ( const char *name, int oflag, ...);
</pre>

<p>
<b>Description:</b> This function establishes a connection between
named semaphores and a task. Following a call to sem_open() with
the semaphore name, the task may reference the semaphore associated
with name using the address returned by this call. The semaphore
may be used in subsequent calls to sem_wait(), sem_trywait(),
and sem_post(). The semaphore remains usable until the semaphore
is closed by a successful call to sem_close().
<p>
If a task makes multiple calls to sem_open() with the same name,
then the same semaphore address is returned (provided there have
been no calls to sem_unlink()).
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>name</I>. Semaphore name
<li><I>oflag</I>. Semaphore creation options. This may one of
the following bit settings:
<ul>
<li><I>oflag</I> = 0: Connect to the semaphore only if it already
exists.
<li><I>oflag</I> = O_CREAT: Connect to the semaphore if it exists,
otherwise create the semaphore.
<li><I>oflag</I> = O_CREAT with O_EXCL (O_CREAT|O_EXCL): Create
a new semaphore unless one of this name already exists.
</ul>
<li>... Optional parameters.
NOTE:  When the O_CREAT flag is specified, POSIX requires that a third
and fourth parameter be supplied:
<ul>
<li><I>mode</I>.  The mode parameter is of type mode_t.  
This parameter is required but not used in the present
implementation.
<li><I>value</I>.  The value parameter is type unsigned int.  The semaphore
is created with an initial value of <I>value</I>.  Valid initial values for
semaphores must be less than or equal to <I>SEM_VALUE_MAX</I> (defined in
<CODE>include/limits.h</CODE>).
</ul>
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>A pointer to sem_t or -1 (ERROR) if unsuccessful.
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.
Differences from the full POSIX implementation include:
<ul>
<li>Treatment of links/connections is highly simplified. It is
just a counting semaphore.
</ul>

<H3><a name="semclose">2.5.4 sem_close</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    int sem_close ( sem_t *sem );
</pre>

<p>
<b>Description:</b> This function is called to indicate that the
calling task is finished with the specified named semaphore, sem.
The sem_close() deallocates any system resources allocated by
the system for this named semaphore.
<p>
If the semaphore has not been removed with a call to sem_unlink(),
then sem_close() has no effect on the named semaphore. However,
when the named semaphore has been fully unlinked, the semaphore
will vanish when the last task closes it.
<p>
Care must be taken to avoid risking the deletion of a semaphore
that another calling task has already locked.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>sem</I>. Semaphore descriptor
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK), or -1 (ERROR) if unsuccessful.
</ul>

<p>
<b>Assumptions/Limitations:</b>
<ul>
<li>Care must be taken to avoid deletion of a semaphore that another task
has already locked.
<li>sem_close() must not be called with an un-named semaphore.
</ul>
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="semunlink">2.5.5 sem_unlink</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    int sem_unlink ( const char *name );
</pre>

<p>
<b>Description:</b> This function will remove the semaphore named by the
input name parameter.  If one or more tasks have the semaphore named by
name oepn when sem_unlink() is called, destruction of the semaphore will
be postponed until all references have been destroyed by calls to
sem_close().
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>name</I>. Semaphore name
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK), or -1 (ERROR) if unsuccessful.
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<ul>
<li>Care must be taken to avoid deletion of a semaphore that another task
has already locked.
<li>sem_unlink() must not be called with an un-named semaphore.
</ul>
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.
Differences from the full POSIX implementation include:
<ul>
<li>Treatment of links/connections is highly simplified. It is
just a counting semaphore.
<li>Calls to sem_open() to re-create or re-connect to the semaphore may
refer to the same semaphore; POSIX specifies that a new semaphore with the
same name should be created after sem_unlink() is called.
</ul>

<H3><a name="semwait">2.5.6 sem_wait</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    int sem_wait ( sem_t *sem );
</pre>

<p>
<b>Description:</b> This function attempts to lock the semaphore
referenced by sem. If the semaphore as already locked by another
task, the calling task will not return until it either successfully acquires
the lock or the call is interrupted by a signal.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>sem</I>. Semaphore descriptor.
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK), or -1 (ERROR) is unsuccessful
</ul>
<p>
If <I>sem_wait</I> returns -1 (ERROR) then the cause of the failure
will be indicated by the thread-specific <I>errno</I> value (a pointer
to this value can be obtained using <I>get_errno_ptr()</I>).  The following
lists the possible values for <I>errno</I>:
<p>
<ul>
<li><I>EINVAL</I>:  Indicates that the <I>sem</I> input parameter is
not valid.
<li><I>EINTR</I>:  Indicates that the wait was interrupt by a signal
received by this task.  In this case, the semaphore has not be acquired.
</ul>
<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="semtrywait">2.5.7 sem_trywait</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    int sem_trywait ( sem_t *sem );
</pre>

<p>
<b>Description:</b> This function locks the specified semaphore
only if the semaphore is currently not locked.  In any event, the call
returns without blocking.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>sem</I>. The semaphore descriptor
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK) or -1 (ERROR) if unsuccessful
</ul>
If <I>sem_wait</I> returns -1 (ERROR) then the cause of the failure
will be indicated by the thread-specific <I>errno</I> value (a pointer
to this value can be obtained using <I>get_errno_ptr()</I>).  The following
lists the possible values for <I>errno</I>:
<p>
<ul>
<li><I>EINVAL</I>:  Indicates that the <I>sem</I> input parameter is
not valid.
<li><I>EAGAIN</I>:  Indicates that the semaphore was not acquired.