NuttxUserGuide.html

routine's value.  An attributes object may be used to
specify details about the kind of thread being created.
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_create()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreaddetach">2.9.12 pthread_detach</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_detach(pthread_t thread);
</pre>
<p>
<b>Description:</b>
A thread object may be "detached" to specify that the
return value and completion status will not be requested.
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_detach()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadexit">2.9.13 pthread_exit</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    void pthread_exit(pthread_addr_t pvValue);
</pre>
<p>
<b>Description:</b>
A thread may terminate it's own execution.
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_exit()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadcancel">2.9.14 pthread_cancel</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_cancel(pthread_t thread);
</pre>
<p>
<b>Description:</b>

<p>The  pthread_cancel() function shall request that thread
be canceled. The target thread's cancelability state determines
when the cancellation takes effect. When the
cancellation is acted on, thread shall be terminated.</p>

<p>When cancelability is disabled, all cancels are held pending
in the target thread until the thread changes the cancelability.
When cancelability is deferred, all cancels are held pending in
the target thread until the thread changes the cancelability or
calls pthread_testcancel().</p>

<p>Cancelability is asynchronous; all cancels are acted upon
immediately (when enable), interrupting the thread with its processing.</p>

<p>
<b>Input Parameters:</b>
<p>
<ul>
<li><I>thread</I>.
Identifies the thread to be canceled.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>ptnread_cancel()</I> function will return zero (<I>OK</I>).
Otherwise, an error number will be returned to indicate the error:
<p>
<ul>
<li><I>ESRCH</I>.
No thread could be found corresponding to that specified by the given thread ID.</li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.  Except:</p>
<ul>
<li>The thread-specific data destructor functions shall be called for thread.
However, these destructors are not currently supported.</li>
<li>Cancellation types are not supported.  The thread will be canceled
at the time that pthread_cancel() is called or, if cancelation is disabled, at
the time when cancelation is re-enabled.</li>
<li><tt>pthread_testcancel()</tt> is not supported.</li>
<li>Thread cancellation at <i>cancellation points</i> is not supported.</li>
</ul>

<H3><a name="pthreadsetcancelstate">2.9.15 pthread_setcancelstate</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_setcancelstate(int state, int *oldstate);
</pre>
<p>
<b>Description:</b>
<p>The <i>pthread_setcancelstate()</i> function atomically
sets both the calling thread's cancelability state to the indicated
state and returns the previous cancelability  state at the location
referenced by oldstate.
Legal values for state are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE.<.li>

<p>Any pending thread cancelation may occur at the time that the
cancelation state is set to PTHREAD_CANCEL_ENABLE.</p>

<b>Input Parameters:</b>
<p>
<ul>
<li><I>state</I> 
New cancelation state.  One of PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.<.li>
<li><I>oldstate</I>.
Location to return the previous cancelation state.
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_setcancelstate()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be returned to indicate the error:
<p>
<ul>
<li><I>ESRCH</I>.
No thread could be found corresponding to that specified by the given thread ID.</li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadtestcancelstate">2.9.16 pthread_testcancelstate</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_setcancelstate(void);
</pre>
<p>
<b>Description:</b>
<p><b>NOT SUPPORTED</b>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_setcancelstate()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadjoin">2.9.17 pthread_join</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_join(pthread_t thread, pthread_addr_t *ppvValue);
</pre>
<p>
<b>Description:</b>
A thread can await termination of another thread and retrieve
the return value of the thread.
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_join()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadyield">2.9.18 pthread_yield</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    void pthread_yield(void);
</pre>
<p>
<b>Description:</b>
A thread may tell the scheduler that its processor can be
made available.
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_yield()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadself">2.9.19 pthread_self</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    pthread_t pthread_self(void);
</pre>
<p>
<b>Description:</b>
A thread may obtain a copy of its own thread handle.
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_self()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadgetschedparam">2.9.20 pthread_getschedparam</a></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_getschedparam(pthread_t thread, int *policy,
                              struct sched_param *param);
</pre>
<p>
  <b>Description:</b>
  The <code>pthread_getschedparam()</code> functions will get the 
  scheduling policy and parameters of threads.
  For <code>SCHED_FIFO</code> and <code>SCHED_RR</code>, the only
  required member of the <code>sched_param</code> structure is the
  priority <code>sched_priority</code>.
</p>
<p>
  The <code>pthread_getschedparam()</code> function will retrieve the
  scheduling policy and scheduling parameters for the thread whose thread
  ID is given by <code>thread</code> and will store those values in
  <code>policy</code> and <code>param</code>, respectively.
  The priority value returned from <code>pthread_getschedparam()</code>
  will be the value specified by the most recent <code>pthread_setschedparam()</code>,
  <code>pthread_setschedprio()</code>, or <code>pthread_create()</code> call
  affecting the target thread.
  It will not reflect any temporary adjustments to its priority (such as might
  result of any priority inheritance, for example).
</p>
<p>
  The policy parameter may have the value <code>SCHED_FIFO</code> or <code>SCHED_RR</code>
  (<code>SCHED_OTHER</code> and <code>SCHED_SPORADIC</code>, in particular, are not supported).
  The <code>SCHED_FIFO</code> and <code>SCHED_RR<code> policies will have a single
  scheduling parameter, <code>sched_priority</code>.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li>
    <code>thread</code>.
    The ID of thread whose scheduling parameters will be queried.
  </li>
  <li>
    <code>policy</code>.
    The location to store the thread's scheduling policy.
  </li>
  <li>
    <code>param</code>.
    The location to store the thread's priority.
  </li>
</ul>
<p>
  <b>Returned Values:</b>
  0 (<code>OK</code>) if successful.
  Otherwise, the error code <code>ESRCH</code> if the value specified by
  <code>thread</code> does not refer to an existing thread.
</p>
<p>
  <b>Assumptions/Limitations:</b>
</p>
<p>
  <b>POSIX Compatibility:</b>
  Comparable to the POSIX interface of the same name.
</p>

<H3><a name="pthreadsetschedparam">2.9.21 pthread_setschedparam</a></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_setschedparam(pthread_t thread, int policy,
                              const struct sched_param *param);
</pre>
<p>
  <b>Description:</b>
  The <code>pthread_setschedparam()</code> functions will set the scheduling policy
  and parameters of threads.
  For <code>SCHED_FIFO</code> and <code>SCHED_RR</code>, the only required member
  of the <code>sched_param</code> structure is the priority <code>sched_priority</code>.
</p>
</p>
  The <code>pthread_setschedparam()</code> function will set the scheduling policy
  and associated scheduling parameters for the thread whose thread ID is given by
  <code>thread</code> to the policy and associated parameters provided in
  <code>policy</code> and <code>param</code>, respectively.
</p>
<p>
  The policy parameter may have the value <code>SCHED_FIFO</code> or <code>SCHED_RR</code>.
  (<code>SCHED_OTHER</code> and <code>SCHED_SPORADIC</code>, in particular, are not supported).
  The <code>SCHED_FIFO</code> and <code>SCHED_RR</code> policies will have a single
  scheduling parameter, <code>sched_priority</code>.
</p>
<p>
  If the <code>pthread_setschedparam()</code> function fails, the scheduling
  parameters will not be changed for the target thread.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li>
    <code>thread</code>.
    The ID of thread whose scheduling parameters will be modified.
  </li>
  <li>
    <code>policy</code>.
    The new scheduling policy of the thread.
    Either <code>SCHED_FIFO</code> or <code>SCHED_RR<code>.
    <code>SCHED_OTHER<code> and <code>SCHED_SPORADIC<code> are not supported.
  </li>
  <li>
    <code>param</code>.
    The location to store the thread's priority.
  </li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If successful, the <I>pthread_setschedparam()</I> function will return
  zero (<I>OK</I>).  Otherwise, an error number will be
  returned to indicate the error:
</p>
<ul>
  <li>
    <code>EINVAL</code>.
    The value specified by <code>policy</code> or one of the scheduling parameters
    associated with the scheduling policy <code>policy</code> is invalid.
  </li>
  <li>
    <code>ENOTSUP</code>.
    An attempt was made to set the policy or scheduling parameters to an unsupported
    value (<code>SCHED_OTHER</code> and <code>SCHED_SPORADIC</code> in particular are
    not supported)
  </li>
  <li>
    <code>EPERM</code>.
    The caller does not have the appropriate permission to set either the scheduling
    parameters or the scheduling policy of the specified thread.
    Or, the implementation does not allow the application to modify one of the
    parameters to the value specified.

  </li>
  <li>
    <code>ESRCH</code>.
    The value specified by thread does not refer to a existing thread.
  </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="pthreadkeycreate">2.9.22 pthread_key_create</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_key_create( pthread_key_t *key, void (*destructor)(void*) )
</pre>
<p>
<b>Description:</b>
<p>
This function creates a thread-specific data key visible
to all threads in the system.  Although the same key value
may be used by different threads, the values bound to
the key by <I>pthread_setspecific()</I> are maintained on a
per-thread basis and persist for the life of the calling
thread.
<p>
Upon key creation, the value <I>NULL</I> will be associated with
the the new key in all active threads.  Upon thread
creation, the value <I>NULL</I> will be associated with all
defined keys in the new thread.
<p>
<b>Input Parameters:</b>
<p>
<ul>
<li><I>key</I> is a pointer to the key to create.
<li><I>destructor</I> is an optional destructor() function that may
be associated with each key that is invoked when a
thread exits.  However, this argument is ignored in
the current implementation.
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_key_create()</I> function will
store the newly created key value at *<I>key</I> and return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
<li><I>EAGAIN</I>.  The system lacked sufficient resources
to create another thread-specific data key, or the
system-imposed limit on the total number of keys
per task {<I>PTHREAD_KEYS_MAX</I>} has been exceeded
<li><I>ENONMEM</I>  Insufficient memory exists to create the key.
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.
<ul>
<li>The present implementation ignores the destructor argument.
</ul>

<H3><a name="pthreadsetspecific">2.9.23 pthread_setspecific</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_setspecific( pthread_key_t key, void *value )
</pre>
<p>
<b>Description:</b>
<p>
The <I>pthread_setspecific()</I> function associates a thread-
specific value with a key obtained via a previous call
to <I>pthread_key_create()</I>.  Different threads may bind
different values to the same key.  These values are
typically pointers to blocks of dynamically allocated
memory that have been reserved for use by the calling
thread.
<p>
The effect of calling <I>pthread_setspecific()</I> with a key value
not obtained from <I>pthread_key_create()</I> or after a key has been
deleted with <I>pthread_key_delete()</I> is undefined.
<p>
<b>Input Parameters:</b>
<p>
<ul>
<li><I>key</I>.  The data key to set the binding for.
<li><I>value</I>. The value to bind to the key.
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, <I>pthread_setspecific()</I> will return zero (<I>OK</I>).
Otherwise, an error number will be returned:
<p>
<ul>
<li><I>ENOMEM</I>.  Insufficient memory exists to associate the value
with the key.
<li><I>EINVAL</I>.  The key value is invalid.
</ul>
<p>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.
<ul>
<li>pthread_setspecific() may be called from a thread-specific data
destructor function.
</ul>

<H3><a name="pthreadgetspecific">2.9.24 pthread_getspecific</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    void *pthread_getspecific( pthread_key_t key )
</pre>
<p>
<b>Description:</b>
<p>
The <I>pthread_getspecific()</I> function returns the value
currently bound to the specified key on behalf of the
calling thread.
<p>
The effect of calling <I>pthread_getspecific()</I> with a key value
not obtained from <I>pthread_key_create()</I> or after a key has been
deleted with <I>pthread_key_delete()</I> is undefined.
<p>
<b>Input Parameters:</b>
<p>
<ul>
<li><I>key</I>.  The data key to get the binding for.
</ul>
<p>
<b>Returned Values:</b>
<p>
The function <I>pthread_getspecific()</I> returns the thread-
specific data associated with the given key.  If no
thread specific data is associated with the key, then
the value <I>NULL</I> is returned.
<p>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.
<ul>
<li>pthread_getspecific() may be called from a thread-specific data
destructor function.
</ul>

<H3><a name="pthreadkeydelete">2.9.25 pthread_key_delete</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_key_delete( pthread_key_t key )
</pre>
<p>
<b>Description:</b>
<p>
This POSIX function should delete a thread-specific data
key previously returned by <I>pthread_key_create()</I>.  However,
this function does nothing in the present implementation.
<p>
<b>Input Parameters:</b>
<p>
<ul>
<li><I>key</I>.  The key to delete
</ul>
<p>
<b>Returned Values:</b>
<p>
<ul>
<li>Always returns <I>EINVAL</I>.
</ul>
<p>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadmutexattrinit">2.9.26 pthread_mutexattr_init</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_mutexattr_init(pthread_mutexattr_t *attr);
</pre>
<p>
<b>Description:</b>
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_mutexattr_init()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadmutexattrdestroy">2.9.27 pthread_mutexattr_destroy</a></H3>
<p>
<b>Function Protoype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
</pre>
<p>
<b>Description:</b>
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_mutexattr_destroy()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadmutexattrgetpshared">2.9.28 pthread_mutexattr_getpshared</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_mutexattr_getpshared(pthread_mutexattr_t *attr,
					int *pshared);
</pre>
<p>
<b>Description:</b>
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_mutexattr_getpshared()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadmutexattrsetpshared">2.9.29 pthread_mutexattr_setpshared</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
   int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
					int pshared);
</pre>
<p>
<b>Description:</b>
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_mutexattr_setpshared()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<h3><a name="pthreadmutexattrgettype">2.9.30 pthread_mutexattr_gettype</a></h3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
#ifdef CONFIG_MUTEX_TYPES
    int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type);
#endif
</pre>
<p>
<b>Description:</b> Return the mutex type from the mutex attributes.
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>attr</code>. The mutex attributes to query</li>
  <li><code>type</code>.  Location to return the mutex type.  See
    <a href="#pthreadmutexattrsettype"><code>pthread_mutexattr_setttyp()</code></a>
    for a description of possible mutex types that may be returned.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_mutexattr_settype()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>EINVAL</code>. Parameters <code>attr</code> and/or <code>attr</code> are invalid.</li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.

<h3><a name="pthreadmutexattrsettype">2.9.31 pthread_mutexattr_settype</a></h3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
#ifdef CONFIG_MUTEX_TYPES
    int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);
#endif
</pre>
<p>
<b>Description:</b> Set the mutex type in the mutex attributes.
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>attr</code>. The mutex attributes in which to set the mutex type.</li>
  <li><code>type</code>. The mutex type value to set.  The following values are supported:
  <ul>
    <li><code>PTHREAD_MUTEX_NORMAL</code>.  This type of mutex does not detect deadlock. A thread
      attempting to relock this mutex without first unlocking it will deadlock.
      Attempting to unlock a mutex locked by a different thread results in undefined
      behavior. Attempting to unlock an unlocked mutex results in undefined behavior. </li>
    <li><code>PTHREAD_MUTEX_ERRORCHECK</code>.  This type of mutex provides error checking.
      A thread attempting to relock this mutex without first unlocking it will return with an error.
      A thread attempting to unlock a mutex which another thread has locked will return with an error.
      A thread attempting to unlock an unlocked mutex will return with an error.</li>
    <li><code>PTHREAD_MUTEX_RECURSIVE</code>.  A thread attempting to relock this mutex without first
      unlocking it will succeed in locking the mutex. The relocking deadlock which can occur with mutexes
      of type PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this mutex
      require the same number of unlocks to release the mutex before another thread can acquire the mutex.
      A thread attempting to unlock a mutex which another thread has locked will return with an error.
      A thread attempting to unlock an unlocked mutex will return with an error.</li>
    <li><code>PTHREAD_MUTEX_DEFAULT</code>.  The default mutex type (PTHREAD_MUTEX_NORMAL).</li>
  </ul>
  <p>
    In NuttX, <code>PTHREAD_MUTEX_NORMAL</code> is not implemented.  Rather, the behavior described
    for <code>PTHREAD_MUTEX_ERRORCHECK</code> is the <i>normal</i> behavior.
  </p>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_mutexattr_settype()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>EINVAL</code>. Parameters <code>attr</code> and/or <code>attr</code> are invalid.</li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.

<H3><a name="pthreadmutexinit">2.9.32 pthread_mutex_init</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_mutex_init(pthread_mutex_t *mutex,
			      pthread_mutexattr_t *attr);
</pre>
<p>
<b>Description:</b>
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_mutex_init()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadmutexdestrory">2.9.33 pthread_mutex_destroy</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_mutex_destroy(pthread_mutex_t *mutex);
</pre>
<p>
<b>Description:</b>
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_mutex_destroy()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadmutexlock">2.9.34 pthread_mutex_lock</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>
    #include &lt;pthread.h&gt;
    int pthread_mutex_lock(pthread_mutex_t *mutex);
</pre>
<p>
<b>Description:</b>
   The mutex object referenced by mutex is locked by calling <code>pthread_mutex_lock()</code>.
   If the mutex is already locked, the calling thread blocks until the mutex
   becomes available. This operation returns with the mutex object referenced
   by mutex in the locked state with the calling thread as its owner.
</p>
<p>
   If the mutex type is <code>PTHREAD_MUTEX_NORMAL</code>, deadlock detection is not provided.
   Attempting to relock the mutex causes deadlock. If a thread attempts to unlock
   a mutex that it has not locked or a mutex which is unlocked, undefined behavior
   results.
</p>
<p>
   In NuttX, <code>PTHREAD_MUTEX_NORMAL</code> is not implemented.  Rather, the behavior described
   for <code>PTHREAD_MUTEX_ERRORCHECK</code> is the <i>normal</i> behavior.
</p>
<p>
   If the mutex type is <code>PTHREAD_MUTEX_ERRORCHECK</code>, then error checking is provided.
   If a thread attempts to relock a mutex that it has already locked, an error
   will be returned. If a thread attempts to unlock a mutex that it has not
   locked or a mutex which is unlocked, an error will be returned.
</p>
<p>
   If the mutex type is <code>PTHREAD_MUTEX_RECURSIVE</code>, then the mutex maintains the concept
   of a lock count. When a thread successfully acquires a mutex for the first time,
   the lock count is set to one. Every time a thread relocks this mutex, the lock count
   is incremented by one. Each time the thread unlocks the mutex, the lock count is
   decremented by one. When the lock count reaches zero, the mutex becomes available
   for other threads to acquire. If a thread attempts to unlock a mutex that it has
   not locked or a mutex which is unlocked, an error will be returned.
</p>
<p>
   If a signal is delivered to a thread waiting for a mutex, upon return from
   the signal handler the thread resumes waiting for the mutex as if it was
   not interrupted.
</p>
<p>
<b>Input Parameters:</b>
<p>
<ul>
  <li><code>mutex</code>.  A reference to the mutex to be locked.</li>
</ul>
<p>
<b>Returned Values:</b>
<p>
If successful, the <I>pthread_mutex_lock()</I> function will return zero (<I>OK</I>).
Otherwise, an error number will be returned to indicate the error:
<p>
<ul>
  <li><code>To be provided</code>. </li>
</ul>
<p>Note that this function will never return the error EINTR.</p>
<b>Assumptions/Limitations:</b>
<p>
<b>POSIX Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadmutextrylock">2.9.35 pthread_mutex_trylock</a></H3>
<p>
<b>Function Prototype:</b>
<p>
<pre>