Sets the thread-specific data value associated with the specified key for the calling thread.

Syntax

pthread_setspecific(
key ,
value );

Argument	Data Type	Access
key	opaque pthread_key_t	read
value	void *	read

int
pthread_setspecific (
pthread_key_t key,
const void *value);

Arguments

key

Thread-specific key that identifies the thread-specific data to receive value. This key value must be obtained from pthread_key_create().

value

New thread-specific data value to associate with the specified key for the calling thread.

Description

This routine sets the thread-specific data value associated with the specified key for the current thread. If a value is defined for the key in this thread (the current value is not NULL), the new value is substituted for it. The key is obtained by a previous call to pthread_key_create().

Different threads can bind different values to the same key. These values are typically pointers to blocks of dynamically allocated memory that are reserved for use by the calling thread.

Do not call this routine from a thread-specific data destructor function.

Note that although the type for value (void *) implies that it represents an address, the type is being used as a "universal scalar type." DECthreads simply stores value for later retrieval.

Associated Routines

• pthread_getspecific()
• pthread_key_create()
• pthread_key_delete()

Examine or change the calling thread's signal mask.

This routine is for Tru64 UNIX systems only.

Syntax

pthread_sigmask(
how ,
set ,
oset );

Argument	Data Type	Access
how	integer	read
set	sigset_t	read
oset	sigset_t	write

int
pthread_sigmask (
int how,
const sigset_t *set,
sigset_t *oset);

Arguments

how

Indicates the manner in which the set of masked signals is changed. The optional values are as follows:

	SIG_BLOCK	The resulting set is the union of the current set and the signal set pointed to by the set argument.
	SIG_UNBLOCK	The resulting set is the intersection of the current set and the complement of the signal set pointed to by the set argument.
	SIG_SETMASK	The resulting set is the signal set pointed to by the set argument.

set

Specifies the signal set by pointing to a set of signals used to change the blocked set. If this set value is NULL, the how argument is ignored and the process signal mask is unchanged.

oset

Receives the value of the current signal mask (unless this value is NULL).

Description

This routine examines or changes the calling thread's signal mask. Typically, you use the SIG_BLOCK option for the how value to block signals during a critical section of code, and then use this routine's SIG_SETMASK option to restore the mask to the previous value returned by the previous call to the pthread_sigmask() routine.

If there are any unblocked signals pending after a call to this routine, at least one of those signals will be delivered before this routine returns.

This routine does not allow the SIGKILL or SIGSTOP signals to be blocked. If a program attempts to block one of these signals, pthread_sigmask() gives no indication of the error.

Requests delivery of a pending cancelation request to the calling thread.

Syntax

pthread_testcancel( );

void
pthread_testcancel (void);

Arguments

None

Description

This routine requests delivery of a pending cancelation request to the calling thread. Thus, calling this routine creates a cancelation point within the calling thread.

The cancelation request is delivered only if a request is pending for the calling thread and the calling thread's cancelability state is enabled. (A thread disables delivery of cancelation requests to itself by calling pthread_setcancelstate().)

When called within very long loops, this routine ensures that a pending cancelation request is noticed by the calling thread within a reasonable amount of time.

Associated Routines

• pthread_setcancelstate()

Unlocks the DECthreads global mutex.

Syntax

pthread_unlock_global_np( );

int
pthread_unlock_global_np (void);

Arguments

None

Description

This routine unlocks the DECthreads global mutex. Because the global mutex is recursive, the unlock occurs when each call to pthread_lock_global_np() has been matched by a call to this routine. For example, if you called pthread_lock_global_np() three times, pthread_unlock_global_np() unlocks the global mutex when you call it the third time.

If no threads are waiting for the DECthreads global mutex, it becomes unlocked with no current owner. If one or more threads are waiting to lock the global mutex, this routine causes one thread to unblock and try to acquire the global mutex. The scheduling policy is used to determine which thread is awakened. For the policies SCHED_FIFO and SCHED_RR, a blocked thread is chosen in priority order, using first-in/first-out (FIFO) within priorities.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return	Description
0	Successful completion.
[EPERM]	The mutex is unlocked or owned by another thread.

Associated Routines

• pthread_lock_global_np()

Notifies the scheduler that the current thread is willing to release its processor to other threads of the same or higher priority.

Syntax

pthread_yield_np( );

Arguments

None

Description

This routine notifies the thread scheduler that the current thread is willing to release its processor to other threads of equivalent or greater scheduling precedence. (A thread generally will release its processor to a thread of a greater scheduling precedence without calling this routine.) If no other threads of equivalent or greater scheduling precedence are ready to execute, the thread continues.

This routine can allow knowledge of the details of an application to be used to improve its performance. If a thread does not call pthread_yield_np(), other threads may be given the opportunity to run at arbitrary points (possibly even when the interrupted thread holds a required resource). By making strategic calls to pthread_yield_np(), other threads can be given the opportunity to run when the resources are free. This improves performance by reducing contention for the resource.

As a general guideline, consider calling this routine after a thread has released a resource (such as a mutex) which is heavily contended for by other threads. This can be especially important if the program is running on a uniprocessor machine, or if the thread acquires and releases the resource inside a tight loop.

Use this routine carefully and sparingly, because misuse can cause unnecessary context switching which will increase overhead and actually degrade performance. For example, it is counter-productive for a thread to yield while it holds a resource which the threads to which it is yielding will need. Likewise, it is pointless to yield unless there is likely to be another thread which is ready to run.

Note pthread_yield_np() is equivalent to sched_yield(). It is recommended to use sched_yield() since it is part of the standard portable POSIX threads library.

Associated Routines

• pthread_attr_setschedparam()
• pthread_getschedparam()
• pthread_setschedparam()

Returns the maximum priority for the specified scheduling policy.

Syntax

sched_get_priority_max(
policy );

Argument	Data Type	Access
policy	integer	read

int
sched_get_priority_max (
int policy);

Arguments

policy

One of the scheduling policies, as defined in sched.h.

Description

This routine returns the maximum priority for the scheduling policy specified in the policy argument. The argument value must be one of the scheduling policies (SCHED_FIFO, SCHED_RR, or SCHED_OTHER), as defined in the sched.h header file.

No special privileges are required to use this routine.

Returns the minimum priority for the specified scheduling policy.

Syntax

sched_get_priority_min(
policy );

Argument	Data Type	Access
policy	integer	read

int
sched_get_priority_min (
int policy);

Arguments

policy

One of the scheduling policies, as defined in sched.h.

Description

This routine returns the minimum priority for the scheduling policy specified in the policy argument. The argument value must be one of the scheduling policies (SCHED_FIFO, SCHED_RR, or SCHED_OTHER), as defined in the sched.h header file.

No special privileges are required to use this routine.

Yields execution to another thread.

Syntax

sched_yield( );

int
sched_yield (void);

Arguments

None

Description

In conformance with the IEEE POSIX.1b-1995 standard, the sched_yield() function causes the calling thread to yield execution to another thread. It is useful when a thread running under the SCHED_FIFO scheduling policy must allow another thread at the same priority to run. The thread that is interrupted by sched_yield() goes to the end of the queue for its priority.

If no other thread is runnable at the priority of the calling thread, the calling thread continues to run.

Threads with higher priority are allowed to preempt the calling thread, so the sched_yield() function has no effect on the scheduling of higher- or lower-priority threads.

The sched_yield() routine takes no arguments. No special privileges are needed to use the sched_yield() function.

Associated Routines

• pthread_attr_setschedparam()
• pthread_getschedparam()
• pthread_setschedparam()

Suspends a calling thread until a signal arrives.

This routine is for Tru64 UNIX systems only.

Syntax

sigwait(
set ,
signal );

Argument	Data Type	Access
set	sigset_t	read
signal	integer	write

int
sigwait (
sigset_t *set,
int *signal);

Arguments

set

Set of signals to wait for.

signal

Signal number obtained for the selected signal.

Description

This routine blocks the calling thread until at least one of the signals in the set argument is in the caller's set of pending signals. When this happens, one of those signals is automatically selected and removed from the set of pending signals. The signal number identifying that signal is then returned.

This routine stores the signal number obtained in the address specified in the signal argument.

The effect of calling this routine is unspecified if any signals in the set argument are not blocked at the time of the call.

The set signal set object is created using the set manipulation routines sigemptyset(), sigfillset(), sigaddset(), and sigdelset().

If, while this routine is waiting, a signal occurs that is eligible for delivery (that is, not blocked by the signal mask), that signal is handled asynchronously and the wait is interrupted.