NuttxUserGuide.html

<P>
<B>Returned Values:</B> 
<UL>
<LI>Signal number that cause the wait to be terminated, otherwise
-1 (ERROR) is returned.
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.
Differences from the POSIX interface include:
<UL>
<LI>Values for si_codes differ
<LI>No mechanism to return cause of ERROR. (It can be inferred
from si_code in a non-standard way).
<LI>POSIX states that &quot;If no signal is pending at the time of the
call, the calling task shall be suspended until one or more signals
in set become pending or until it is interrupted by an unblocked,
<I>caught</I> signal.&quot;  The present implementation does not require
that the unblocked signal be caught; the task will be resumed even if
the unblocked signal is ignored.
</UL>

<H3><a name="sigqueue">2.8.12 sigqueue</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int sigqueue (int tid, int signo, const union sigval value);
</PRE>

<P>
<B>Description:</B> This function sends the signal specified by
signo with the signal parameter value to the task specified
by tid.
<P>
If the receiving task has the signal blocked via its sigprocmask,
the signal will pend until it is unmasked.  Only one pending signal
(for a given signo) is retained by the system.  This is consistent with
POSIX which states:  &quot;If a subsequent occurrence of a pending signal
is generated, it is implementation defined as to whether the signal
is delivered more than once.&quot;
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>tid</I>. ID of the task to receive signal
<LI><I>signo</I>. Signal number
<LI><I>value</I>. Value to pass to task with signal
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>
  On  success (at least one signal was sent), zero (OK) is returned.
  On error, -1 (ERROR) is returned, and errno is set appropriately.
  <ul>
    <li><code>EGAIN</code>. The limit of signals which may be queued has been reached.</li>
    <li><code>EINVAL</code>. signo was invalid.</li>
    <li><code>EPERM</code>.  The task does not have permission to send the signal to the receiving process.</li>
    <li><code>ESRCH</code>. No process has a PID matching pid.</li>
  </ul>
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.
Differences from the POSIX interface include:
<UL>
<LI>Default action is to ignore signals.
<LI>Signals are processed one at a time in order
<LI>POSIX states that, &quot;If signo is zero (the null signal), error
checking will be performed but no signal is actually sent.&quot;
There is no null signal in the present implementation; a zero signal will
be sent.
</UL>

<H3><a name="kill">2.8.13 kill</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
   #include &lt;sys/types.h&gt;
   #include &ltsignal.h&gt;
   int kill(pid_t pid, int sig);
</PRE>

<P>
<B>Description:</B> 
  The kill() system call can be used to send any signal to
  any task.
</p>
<p>
  If the receiving task has the signal blocked via its sigprocmask,
  the signal will pend until it is unmasked.  Only one pending signal
  (for a given signo) is retained by the system.  This is consistent with
  POSIX which states:  &quot;If a subsequent occurrence of a pending signal
  is generated, it is implementation defined as to whether the signal
  is delivered more than once.&quot;
</p>
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>pid</I>. The id of the task to receive the signal.
  The POSIX <code>kill()</code> specification encodes process group
  information as zero and negative pid values.
  Only positive, non-zero values of pid are supported by this
  implementation. ID of the task to receive signal
<LI><I>signo</I>. The signal number to send.
  If signo is zero, no signal is sent, but all error checking is performed.
</UL>

<p>
  <B>Returned Values:</B> 
  <UL>
    <LI>OK or ERROR
  </UL>
</p>

<p>
  <B>Assumptions/Limitations:</B> 
</p>
<p>
  <b>POSIX  Compatibility:</b>
    Comparable to the POSIX interface of the same name.
    Differences from the POSIX interface include:
</p>
<ul>
  <li>Default action is to ignore signals.</li>
  <li>Signals are processed one at a time in order </li>
  <li>Sending of signals to 'process groups' is not supported in NuttX.</li>
</ul>

<H2>2.9 <A NAME="Pthread">Pthread Interfaces</A></H2>
<p>
  NuttX does not support <i>processes</i> in the way that, say, Linux does.
  NuttX only supports simple threads or tasks running within the same address space.
  For the most part, threads and tasks are interchangeable and differ primarily
  only in such things as the inheritance of file descriptors.
  Basically, threads are initialized and uninitialized differently and share a
  few more resources than tasks.
<p>
  The following pthread interfaces are supported in some form by NuttX:
</p>
<ul>
  <li><a href="#pthreadattrinit">2.9.1 pthread_attr_init</a></li>
  <li><a href="#pthreadattrdestroy">2.9.2 pthread_attr_destroy</a></li>
  <li><a href="#pthreadattrsetschedpolity">2.9.3 pthread_attr_setschedpolicy</a></li>
  <li><a href="#pthreadattrgetschedpolicy">2.9.4 pthread_attr_getschedpolicy</a></li>
  <li><a href="#pthreadattrsetschedparam">2.9.5 pthread_attr_setschedparam</a></li>
  <li><a href="#pthreadattrgetschedparam">2.9.6 pthread_attr_getschedparam</a></li>
  <li><a href="#pthreadattrsetinheritsched">2.9.7 pthread_attr_setinheritsched</a></li>
  <li><a href="#pthreadattrgetinheritsched">2.9.8 pthread_attr_getinheritsched</a></li>
  <li><a href="#pthreadattrsetstacksize">2.9.9 pthread_attr_setstacksize</a></li>
  <li><a href="#pthreadattrgetstacksize">2.9.10 pthread_attr_getstacksize</a></li>
  <li><a href="#pthreadcreate">2.9.11 pthread_create</a></li>
  <li><a href="#pthreaddetach">2.9.12 pthread_detach</a></li>
  <li><a href="#pthreadexit">2.9.13 pthread_exit</a></li>
  <li><a href="#pthreadcancel">2.9.14 pthread_cancel</a></li>
  <li><a href="#pthreadsetcancelstate">2.9.15 pthread_setcancelstate</a></li>
  <li><a href="#pthreadtestcancelstate">2.9.16 pthread_testcancelstate</a></li>
  <li><a href="#pthreadjoin">2.9.17 pthread_join</a></li>
  <li><a href="#pthreadyield">2.9.18 pthread_yield</a></li>
  <li><a href="#pthreadself">2.9.19 pthread_self</a></li>
  <li><a href="#pthreadgetschedparam">2.9.20 pthread_getschedparam</a></li>
  <li><a href="#pthreadsetschedparam">2.9.21 pthread_setschedparam</a></li>
  <li><a href="#pthreadkeycreate">2.9.22 pthread_key_create</a></li>
  <li><a href="#pthreadsetspecific">2.9.23 pthread_setspecific</a></li>
  <li><a href="#pthreadgetspecific">2.9.24 pthread_getspecific</a></li>
  <li><a href="#pthreadkeydelete">2.9.25 pthread_key_delete</a></li>
  <li><a href="#pthreadmutexattrinit">2.9.26 pthread_mutexattr_init</a></li>
  <li><a href="#pthreadmutexattrdestroy">2.9.27 pthread_mutexattr_destroy</a></li>
  <li><a href="#pthreadmutexattrgetpshared">2.9.28 pthread_mutexattr_getpshared</a></li>
  <li><a href="#pthreadmutexattrsetpshared">2.9.29 pthread_mutexattr_setpshared</a></li>
  <li><a href="#pthreadmutexinit">2.9.30 pthread_mutex_init</a></li>
  <li><a href="#pthreadmutexdestrory">2.9.31 pthread_mutex_destroy</a></li>
  <li><a href="#pthreadmutexlock">2.9.32 pthread_mutex_lock</a></li>
  <li><a href="#pthreadmutextrylock">2.9.33 pthread_mutex_trylock</a></li>
  <li><a href="#pthreadmutexunlock">2.9.34 pthread_mutex_unlock</a></li>
  <li><a href="#pthreadconaddrinit">2.9.35 pthread_condattr_init</a></li>
  <li><a href="#pthreadocndattrdestroy">2.9.36 pthread_condattr_destroy</a></li>
  <li><a href="#pthreadcondinit">2.9.37 pthread_cond_init</a></li>
  <li><a href="#pthreadconddestroy">2.9.38 pthread_cond_destroy</a></li>
  <li><a href="#pthreadcondbroadcast">2.9.39 pthread_cond_broadcast</a></li>
  <li><a href="#pthreadcondsignal">2.9.40 pthread_cond_signal</a></li>
  <li><a href="#pthreadcondwait">2.9.41 pthread_cond_wait</a></li>
  <li><a href="#pthreadcondtimedwait">2.9.42 pthread_cond_timedwait</a></li>
  <li><a href="#pthreadbarrierattrinit">2.9.43 pthread_barrierattr_init</a></li>
  <li><a href="#pthreadbarrierattrdestroy">2.9.44 pthread_barrierattr_destroy</a></li>
  <li><a href="#pthreadbarrierattrsetpshared">2.9.45 pthread_barrierattr_setpshared</a></li>
  <li><a href="#pthreadbarrierattrgetpshared">2.9.46 pthread_barrierattr_getpshared</a></li>
  <li><a href="#pthreadbarrierinit">2.9.47 pthread_barrier_init</a></li>
  <li><a href="#pthreadbarrierdestroy">2.9.48 pthread_barrier_destroy</a></li>
  <li><a href="#pthreadbarrierwait">2.9.49 pthread_barrier_wait</a></li>
  <li><a href="#pthreadonce">2.9.50 pthread_once</a></li>
  <li><a href="#pthreadkill">2.9.51 pthread_kill</a></li>
  <li><a href="#pthreadsigmask">2.9.52 pthread_sigmask</a></li>
</ul>
<p>
  No support for the ollowing pthread interfaces is provided by NuttX:
</p>
<ul>
  <li><code>pthread_atfork</code>. register fork handlers.</li>
  <li><code>pthread_attr_getdetachstate</code>. get and set the detachstate attribute.</li>
  <li><code>pthread_attr_getguardsize</code>. get and set the thread guardsize attribute.</li>
  <li><code>pthread_attr_getinheritsched</code>. get and set the inheritsched attribute.</li>
  <li><code>pthread_attr_getscope</code>. get and set the contentionscope attribute.</li>
  <li><code>pthread_attr_getstack</code>. get and set stack attributes.</li>
  <li><code>pthread_attr_getstackaddr</code>. get and set the stackaddr attribute.</li>
  <li><code>pthread_attr_setdetachstate</code>. get and set the detachstate attribute.</li>
  <li><code>pthread_attr_setguardsize</code>. get and set the thread guardsize attribute.</li>
  <li><code>pthread_attr_setscope</code>. get and set the contentionscope attribute.</li>
  <li><code>pthread_attr_setstack</code>. get and set stack attributes.</li>
  <li><code>pthread_attr_setstackaddr</code>. get and set the stackaddr attribute.</li>
  <li><code>pthread_barrier_destroy</code>. destroy and initialize a barrier object.</li>
  <li><code>pthread_barrier_init</code>. destroy and initialize a barrier object.</li>
  <li><code>pthread_barrier_wait</code>. synchronize at a barrier.</li>
  <li><code>pthread_cleanup_pop</code>. establish cancellation handlers.</li>
  <li><code>pthread_cleanup_push</code>. establish cancellation handlers.</li>
  <li><code>pthread_condattr_getclock</code>. get and set the clock selection condition variable attribute.</li>
  <li><code>pthread_condattr_getpshared</code>. get and set the process-shared condition variable attributes.</li>
  <li><code>pthread_condattr_setclock</code>. get and set the clock selection condition variable attribute.</li>
  <li><code>pthread_condattr_setpshared</code>. get and set the process-shared condition variable attributes.</li>
  <li><code>pthread_getconcurrency</code>. get and set the level of concurrency.</li>
  <li><code>pthread_getcpuclockid</code>. access a thread CPU-time clock.</li>
  <li><code>pthread_mutex_getprioceiling</code>. get and set the priority ceiling of a mutex.</li>
  <li><code>pthread_mutex_setprioceiling</code>. get and set the priority ceiling of a mutex.</li>
  <li><code>pthread_mutex_timedlock</code>. lock a mutex.</li>
  <li><code>pthread_mutexattr_getprioceiling</code>. get and set the prioceiling attribute of the mutex attributes object.</li>
  <li><code>pthread_mutexattr_getprotocol</code>. get and set the protocol attribute of the mutex attributes object.</li>
  <li><code>pthread_mutexattr_gettype</code>. get and set the mutex type attribute.</li>
  <li><code>pthread_mutexattr_setprioceiling</code>. get and set the prioceiling attribute of the mutex attributes object.</li>
  <li><code>pthread_mutexattr_setprotocol</code>. get and set the protocol attribute of the mutex attributes object.</li>
  <li><code>pthread_mutexattr_settype</code>. get and set the mutex type attribute.</li>
  <li><code>pthread_rwlock_destroy</code>. destroy and initialize a read-write lock object.</li>
  <li><code>pthread_rwlock_init</code>. destroy and initialize a read-write lock object.</li>
  <li><code>pthread_rwlock_rdlock</code>. lock a read-write lock object for reading.</li>
  <li><code>pthread_rwlock_timedrdlock</code>. lock a read-write lock for reading.</li>
  <li><code>pthread_rwlock_timedwrlock</code>. lock a read-write lock for writing.</li>
  <li><code>pthread_rwlock_tryrdlock</code>. lock a read-write lock object for reading.</li>
  <li><code>pthread_rwlock_trywrlock</code>. lock a read-write lock object for writing.</li>
  <li><code>pthread_rwlock_unlock</code>. unlock a read-write lock object.</li>
  <li><code>pthread_rwlock_wrlock</code>. lock a read-write lock object for writing.</li>
  <li><code>pthread_rwlockattr_destroy</code>. destroy and initialize the read-write lock attributes object.</li>
  <li><code>pthread_rwlockattr_getpshared</code>. get and set the process-shared attribute of the read-write lock attributes object.</li>
  <li><code>pthread_rwlockattr_init</code>. destroy and initialize the read-write lock attributes object.</li>
  <li><code>pthread_rwlockattr_setpshared</code>. get and set the process-shared attribute of the read-write lock attributes object.</li>
  <li><code>pthread_setcanceltype</code>. set cancelability state.</li>
  <li><code>pthread_setconcurrency</code>. get and set the level of concurrency.</li>
  <li><code>pthread_spin_destroy</code>. destroy or initialize a spin lock object.</li>
  <li><code>pthread_spin_init</code>. destroy or initialize a spin lock object.</li>
  <li><code>pthread_spin_lock</code>. lock a spin lock object.</li>
  <li><code>pthread_spin_trylock</code>. lock a spin lock object.</li>
  <li><code>pthread_spin_unlock</code>. unlock a spin lock object.</li>
  <li><code>pthread_testcancel</code>. set cancelability state.</li>
</ul>

<H3><a name="pthreadattrinit">2.9.1 pthread_attr_init</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
    #include &lt;pthread.h&gt;
    int pthread_attr_init(pthread_attr_t *attr);
</PRE>
<P>
<B>Description:</B>
Initializes a thread attributes object (attr) with default values
for all of the individual attributes used by the implementation.
<P>
<B>Input Parameters:</B>
<P>
<UL>
  <li><code>param<code>.</li>
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>pthread_attr_init()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
  <li><code>Exxx</code>. </li>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.
<P>
<H3><a name="pthreadattrdestroy">2.9.2 pthread_attr_destroy</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
    #include &lt;pthread.h&gt;
    int pthread_attr_destroy(pthread_attr_t *attr);
</PRE>
<P>
<B>Description:</B>
An attributes object can be deleted when it is no longer needed.
<P>
<B>Input Parameters:</B>
<P>
<UL>
  <li><code>param<code>.</li>
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>pthread_attr_destroy()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
  <li><code>Exxx</code>. </li>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.
<P>
<H3><a name="pthreadattrsetschedpolity">2.9.3 pthread_attr_setschedpolicy</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
    #include &lt;pthread.h&gt;
    int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
  <li><code>param<code>.</li>
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>pthread_attr_setschedpolicy()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
  <li><code>Exxx</code>. </li>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadattrgetschedpolicy">2.9.4 pthread_attr_getschedpolicy</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
    #include &lt;pthread.h&gt;
    int pthread_attr_getschedpolicy(pthread_attr_t *attr, int *policy);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
  <li><code>param<code>.</li>
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>pthread_attr_getschedpolicy()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
  <li><code>Exxx</code>. </li>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadattrsetschedparam">2.9.5 pthread_attr_getschedpolicy</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
   #include &lt;pthread.h&gt;
    int pthread_attr_setschedparam(pthread_attr_t *attr,
				      const struct sched_param *param);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
  <li><code>param<code>.</li>
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>pthread_attr_getschedpolicy()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
  <li><code>Exxx</code>. </li>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadattrgetschedparam">2.9.6 pthread_attr_getschedparam</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
   #include &lt;pthread.h&gt;
     int pthread_attr_getschedparam(pthread_attr_t *attr,
				      struct sched_param *param);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
  <li><code>param<code>.</li>
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>pthread_attr_getschedparam()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
  <li><code>Exxx</code>. </li>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadattrsetinheritsched">2.9.7 pthread_attr_setinheritsched</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
   #include &lt;pthread.h&gt;
    int pthread_attr_setinheritsched(pthread_attr_t *attr,
					int inheritsched);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
  <li><code>param<code>.</li>
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>pthread_attr_setinheritsched()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
  <li><code>Exxx</code>. </li>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.
<P>
<H3><a name="pthreadattrgetinheritsched">2.9.8 pthread_attr_getinheritsched</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
   #include &lt;pthread.h&gt;
     int pthread_attr_getinheritsched(const pthread_attr_t *attr,
					int *inheritsched);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
  <li><code>param<code>.</li>
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>pthread_attr_getinheritsched()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
  <li><code>Exxx</code>. </li>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadattrsetstacksize">2.9.9 pthread_attr_setstacksize</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
   #include &lt;pthread.h&gt;
    int pthread_attr_setstacksize(pthread_attr_t *attr, long stacksize);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
  <li><code>param<code>.</li>
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>pthread_attr_setstacksize()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
  <li><code>Exxx</code>. </li>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadattrgetstacksize">2.9.10 pthread_attr_getstacksize</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
    #include &lt;pthread.h&gt;
   int pthread_attr_getstacksize(pthread_attr_t *attr, long *stackaddr);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
  <li><code>param<code>.</li>
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>pthread_attr_getstacksize()</I> function will return
zero (<I>OK</I>).  Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
  <li><code>Exxx</code>. </li>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="pthreadcreate">2.9.11 pthread_create</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
    #include &lt;pthread.h&gt;
    int pthread_create(pthread_t *thread, pthread_attr_t *attr,
			  pthread_startroutine_t startRoutine,
			  pthread_addr_t arg);
</PRE>
<P>
<B>Description:</B>
To create a thread object and runnable thread, a routine
must be specified as the new thread's start routine.  An
argument may be passed to this routine, as an untyped
address; an untyped address may also be returned as the
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>param<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>Exxx</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>param<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>Exxx</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>param<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>Exxx</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>param<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>Exxx</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>param<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>Exxx</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>param<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>Exxx</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>param<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>Exxx</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>.