NuttxUserGuide.html

</pre>

<H3><a name="schedunlock">2.3.2 sched_unlock</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;sched.h&gt;
    STATUS sched_unlock( void );
</pre>

<p>
<b>Description:</b> This function decrements the preemption lock
count. Typically this is paired with sched_lock() and concludes
a critical section of code. Preemption will not be unlocked until
sched_unlock() has been called as many times as sched_lock().
When the lockCount is decremented to zero, any tasks that were
eligible to preempt the current task will execute.
<p>
<b>Input Parameters:</b> None.
<p>
<b>Returned Values:</b> 
<ul>
<li>OK or ERROR.
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> This is a NON-POSIX interface.
VxWorks provides the comparable interface:
<pre>
    STATUS taskUnlock( void );
</pre>

<H3><a name="schedlockcount">2.3.3 sched_lockcount</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;sched.h&gt;
    sint32 sched_lockcount( void )
</pre>

<p>
<b>Description:</b> This function returns the current value of
the lockCount. If zero, preemption is enabled; if non-zero, this
value indicates the number of times that sched_lock() has been called
on this thread of execution.
<p>
<b>Input Parameters:</b> None.
<p>
<b>Returned Values:</b> 
<ul>
<li>The current value of the lockCount.
</ul>

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

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="Message_Queue"><h2>2.4 Named Message Queue Interfaces</h2></a>
  </td>
  </tr>
</table>

<p>
  NuttX supports POSIX named message queues for inter-task 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 <a href="#ErrnoAccess"><code>errno</code></a> 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 <a href="#ErrnoAccess"><code>errno</code></a> 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 <a href="#ErrnoAccess"><code>errno</code></a> 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 <a href="#ErrnoAccess"><code>errno</code></a> 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 SIGEV_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.
</p>

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="Semaphores"><h2>2.5 Counting Semaphore Interfaces</h2></a>
  </td>
  </tr>
</table>

<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>
  <a name="priorityinversion"><b>Priority Inversion</b></a>.
  Proper use of semaphores avoids the issues of <code>sched_lock()</code>.
  However, consider the following example:
  <OL>
    <li>Some low-priority task, <I>Task C</I>, acquires a semaphore 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
  supports this behavior, but only if <code>CONFIG_PRIORITY_INHERITANCE</code>
  is defined in your OS configuration file.  If <code>CONFIG_PRIORITY_INHERITANCE</code>
  is not defined, then 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 semaphore-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>
  <a name="priorityinheritance"><b>Priority Inheritance</b></a>.
  As mentioned, NuttX does support <i>priority inheritance</i> provided that
  <code>CONFIG_PRIORITY_INHERITANCE</code> is defined in your OS configuration file.
  However, the implementation and configuration of the priority inheritance feature
  is sufficiently complex that more needs to be said.
  How can a feature that can be described by a single, simple sentence require such
  a complex implementation:
</p>
<ul>
  <li>
    <b><code>CONFIG_SEM_PREALLOCHOLDERS</code>.</b>
    First of all, in NuttX priority inheritance is implement on POSIX counting
    semaphores.  The reason for this is that these semaphores are the most
    primitive waiting mechanism in NuttX; Most other waiting facilities are
    based on semaphores.  So if priority inheritance is implemented for POSIX
    counting semaphores, then most NuttX waiting mechanisms will have this
    capability.
    <p>
      Complexity arises because counting semaphores can have numerous
      holders of semaphore counts.  Therefore, in order to implement
      priority inheritance across all holders, then internal data
      structures must be allocated to manage the various holders associated
      with a semaphore.
      The setting <code>CONFIG_SEM_PREALLOCHOLDERS</code> defines the maximum
      number of different threads (minus one per semaphore instance) that can
      take counts on a semaphore with priority inheritance support.
      This setting defines the size of a single pool of pre-allocated structures.
      It may be set to zero if priority inheritance is disabled OR if you
      are only using semaphores as mutexes (only one holder) OR if no more
      than two threads participate using a counting semaphore.
    </p>
    <p>
      The cost associated with setting <code>CONFIG_SEM_PREALLOCHOLDERS</code>
      is slightly increased code size and around 6-12 bytes times the value
      of <code>CONFIG_SEM_PREALLOCHOLDERS</code>.
    </p>
  </li>
  <li>
    <b><code>CONFIG_SEM_NNESTPRIO</code>:</b>
    In addition, there may be multiple threads of various priorities that
    need to wait for a count from the semaphore.
    These, the lower priority thread holding the semaphore may have to
    be boosted numerous time and, to make things more complex, will have
    to keep track of all of the boost priorities values in in order to
    correctly restore the priorities after a count has been handed out
    to the higher priority thread.
    The <code>CONFIG_SEM_NNESTPRIO</code> defines the size of an array,
    one array per active thread.
    This setting is the maximum number of higher priority threads (minus
    1) than can be waiting for another thread to release a count on a semaphore.
    This value may be set to zero if no more than one thread is expected to
    wait for a semaphore.
    <p>
      The cost associated with setting <code>CONFIG_SEM_NNESTPRIO</code>
      is slightly increased code size and (<code>CONFIG_SEM_PREALLOCHOLDERS</code> + 1)
      times the maximum number of active threads.
    </p>
  </li>
  <li>
    <b>Increased Susceptibility to Bad Thread Behavior</b>.
    These various structures tie the semaphore implementation more tightly to
    the behavior of the implementation.  For examples, if a thread executes while
    holding counts on a semaphore, or if a thread exits without call <code>sem_destroy()</code>
    then.  Or what if the thread with the boosted priority re-prioritizes itself?
    The NuttX implement of priority inheritance attempts to handle all of these
    types of corner cases, but it is very likely that some are missed.
    The worst case result is that memory could by stranded within the priority
    inheritance logic.
  </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>