Newer
Older
from si_code in a non-standard way).
<LI>POSIX states that "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." 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>
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
<P>
<B>Function Prototype:</B>
<PRE>
#include <signal.h>
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: "If a subsequent occurrence of a pending signal
is generated, it is implementation defined as to whether the signal
is delivered more than once."
<P>
<B>Input Parameters:</B>
<UL>
<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, "If signo is zero (the null signal), error
checking will be performed but no signal is actually sent."
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>
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
<B>Function Prototype:</B>
<PRE>
#include <sys/types.h>
#include <signal.h>
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: "If a subsequent occurrence of a pending signal
is generated, it is implementation defined as to whether the signal
is delivered more than once."
</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.
</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>
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
<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>
<H3><a name="pthreadattrinit">2.9.1 pthread_attr_init</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
#include <pthread.h>
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><I>parm</I>
</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>
</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 <pthread.h>
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><I>parm</I>
</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>
</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 <pthread.h>
int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I>
</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>
</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 <pthread.h>
int pthread_attr_getschedpolicy(pthread_attr_t *attr, int *policy);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I>
</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>
</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 <pthread.h>
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><I>parm</I>
</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>
</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 <pthread.h>
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><I>parm</I>
</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>
</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 <pthread.h>
int pthread_attr_setinheritsched(pthread_attr_t *attr,
int inheritsched);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I>
</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>
</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 <pthread.h>
int pthread_attr_getinheritsched(const pthread_attr_t *attr,
int *inheritsched);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I>
</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>
</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 <pthread.h>
int pthread_attr_setstacksize(pthread_attr_t *attr, long stacksize);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I>
</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>
</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 <pthread.h>
int pthread_attr_getstacksize(pthread_attr_t *attr, long *stackaddr);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I>
</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>
</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>
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
<P>
<B>Function Prototype:</B>
<P>
<PRE>
#include <pthread.h>
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><I>parm</I>
</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>
</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 <pthread.h>
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><I>parm</I>
</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>
</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 <pthread.h>
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><I>parm</I>
</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>
</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>
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
<P>
<B>Function Prototype:</B>
<P>
<PRE>
#include <pthread.h>
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>
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
<P>
<B>Function Prototype:</B>
<P>
<PRE>
#include <pthread.h>
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 <pthread.h>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I>
</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>
</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 <pthread.h>
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><I>parm</I>
</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>
</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 <pthread.h>
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><I>parm</I>
</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>
</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 <pthread.h>
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><I>parm</I>
</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>
</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 <pthread.h>
int pthread_getschedparam(pthread_t thread, int *policy,
struct sched_param *param);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I>
</UL>
<P>
<B>Returned Values:</B>
<P>
If successful, the <I>pthread_getschedparam()</I> function will return
zero (<I>OK</I>). Otherwise, an error number will be
returned to indicate the error:
<P>
<UL>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.
<H3><a name="pthreadsetschedparam">2.9.21 pthread_setschedparam</A></H3>
<P>
<B>Function Prototype:</B>
<P>
<PRE>
#include <pthread.h>
int pthread_setschedparam(pthread_t thread, int policy,
const struct sched_param *param);
</PRE>
<P>
<B>Description:</B>
<P>
<B>Input Parameters:</B>
<P>
<UL>
<LI><I>parm</I>
</UL>
<P>
<B>Returned Values:</B>
<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>
</UL>
<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.
<H3><a name="pthreadkeycreate">2.9.22 pthread_key_create</A></H3>
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
<P>
<B>Function Prototype:</B>
<P>
<PRE>
#include <pthread.h>
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>
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
<P>
<B>Function Prototype:</B>
<P>
<PRE>
#include <pthread.h>
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 <pthread.h>
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