Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## pthread_setname_np

> Changes the object name in the thread object for an existing thread.

### Syntax

> pthread_setname_np(
> thread ,
> name ,
> mbz );

> Argument | Data Type | Access
> --- | --- | ---
> thread | opaque pthread_thread_t | write
> name | char | read
> mbz | void | read

C Binding #include <pthread.h>

int
pthread_setname_np (
pthread_thread_t thread,
const char *name,
void *mbz);

### Arguments

> #### thread

> Thread object whose object name is to be changed.

> #### name

> Object name value to copy into the thread object.

> #### mbz

> Reserved for future use. The value must be zero (0).

### Description

> This routine changes the object name in the thread object for the thread specified by the thread argument to the value specified by the name argument. To set an existing thread's object name, call this routine after creating the thread. However, with this approach your program must account for the possibility that the target thread either has already exited or has been canceled before this routine is called.

> The object name is a C language string and provides an identifier that is meaningful to a person debugging a multithreaded application. The maximum number of characters in the object name is 31.

> This routine contrasts with `pthread_attr_setname_np()` , which changes the object name attribute in a thread attributes object that is used to create a new thread.

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.
[EINVAL] | The length in characters of name exceeds 31.
[ENOMEM] | Insufficient memory to create a copy of the object name string.
[ESRCH] | The thread specified by thread does not exist.

#### Associated Routines

> `pthread_attr_getname_np()`
> `pthread_attr_setname_np()`
> `pthread_getname_np()`

## pthread_setschedparam

> Changes a thread's scheduling policy and scheduling parameters.

### Syntax

> pthread_setschedparam(
> thread ,
> policy ,
> param );

> Argument | Data Type | Access
> --- | --- | ---
> thread | opaque pthread_t | read
> policy | integer | read
> param | struct sched_param | read

C Binding #include <pthread.h>

int
pthread_setschedparam (
pthread_t thread,
int policy,
const struct sched_param *param);

### Arguments

> #### thread

> Thread whose scheduling policy and parameters are to be changed.

> #### policy

> New scheduling policy value for the thread specified in thread. The following are valid values:

> > `SCHED_BG_NP`
> > `SCHED_FG_NP`
> > `SCHED_FIFO`
> > `SCHED_OTHER`
> > `SCHED_RR`

> See Section 2.3.2.2 for a description of thread scheduling policies.

> #### param

> New values of the scheduling parameters associated with the scheduling policy for the thread specified in thread. Valid values for the `sched_priority` field of a `sched_param` structure depend on the chosen scheduling policy. Use the POSIX routines `sched_get_priority_min()` or `sched_get_priority_max()` to determine the low and high limits of each policy.

> Additionally, the Threads Librray provides nonportable priority range constants, as follows:

> Low | High
> --- | ---
> `PRI_FIFO_MIN` | `PRI_FIFO_MAX`
> `PRI_RR_MIN` | `PRI_RR_MAX`
> `PRI_OTHER_MIN` | `PRI_OTHER_MAX`
> `PRI_FG_MIN_NP` | `PRI_FG_MAX_NP`
> `PRI_BG_MIN_NP` | `PRI_BG_MAX_NP`

> The default priority varies by platform. On Tru64 UNIX, the default is 19 (that is, the POSIX priority of a normal timeshare process). On other platforms the default priority is the midpoint between `PRI_FG_MIN_NP` and `PRI_FG_MAX_NP` . ( Section 2.3.6 describes how to specify priorities between the minimum and maximum values.)

### Description

> This routine changes both the current scheduling policy and associated scheduling parameters of the thread specified by thread to the policy and associated parameters provided in policy and param, respectively.

> All currently implemented scheduling policies have one scheduling parameter called `sched_priority` . For the policy you choose, you must specify an appropriate value in the `sched_priority` field of the `sched_param` structure.

> Changing the scheduling policy or priority, or both, of a thread can cause it either to start executing or to be preempted by another thread. A thread changes its own scheduling policy and priority by using the handle returned by the `pthread_self()` routine.

> This routine differs from `pthread_attr_setschedpolicy()` and
> `pthread_attr_setschedparam()` , in that those routines set the scheduling policy and parameter attributes that are used to establish the scheduling priority and scheduling policy of a new thread when it is created. However, this routine changes the scheduling policy and parameters of an existing thread.

Return Values If an error condition occurs, no scheduling policy or parameters are changed for the target thread, and this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion.
[EINVAL] | The value specified by policy or param is invalid.
[ENOTSUP] | An attempt was made to set the scheduling policy or a parameter to an unsupported value.
[EPERM] | The caller does not have the appropriate privileges to set the scheduling policy or parameters of the specified thread.
[ESRCH] | The value specified by thread does not refer to an existing thread.

#### Associated Routines

> `pthread_attr_setschedparam()`
> `pthread_attr_setschedpolicy()`
> `pthread_create()`
> `pthread_self()`
> `sched_yield()`

## pthread_setspecific

> 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

C Binding #include <pthread.h>

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." The Threads Library simply stores value for later retrieval.

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

Return | Description
--- | ---
0 | Successful completion.
[EINVAL] | The specified key is invalid.
[ENOMEM] | Insufficient memory to associate the value with the key.

#### Associated Routines

> `pthread_getspecific()`
> `pthread_key_create()`
> `pthread_key_delete()`

## pthread_sigmask

> 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

C Binding #include <pthread.h>
include <signal.h>

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.

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.
[EINVAL] | The value specified for how is invalid.

## pthread_testcancel

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

### Syntax

> pthread_testcancel( );

C Binding #include <pthread.h>

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.

Return Values None

#### Associated Routines

> `pthread_setcancelstate()`

## pthread_unlock_global_np

> Unlocks the Threads Library global mutex.

### Syntax

> pthread_unlock_global_np( );

C Binding #include <pthread.h>

int
pthread_unlock_global_np (void);

### Arguments

> ####

> None

### Description

> This routine unlocks the Threads Library 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 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 to try to acquire the global mutex. The scheduling policy is used by this routine 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()`

## pthread_yield_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( );

C Binding int
pthread_yield_np (void);

### 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 either 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 that the threads to which it is yielding will need. Likewise, it is pointless to yield unless there is likely to be another thread that is ready to run.

> Note `pthread_yield_np()` is equivalent to `sched_yield()` . Use `sched_yield()` since it is part of the standard portable POSIX Threads Library.

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.
[ENOSYS] | The routine `pthread_yield_np()` is not supported by this implementation.

#### Associated Routines

> `pthread_attr_setschedparam()`
> `pthread_getschedparam()`
> `pthread_setschedparam()`

## sched_get_priority_max

> Returns the maximum priority for the specified scheduling policy.

### Syntax

> sched_get_priority_max(
> policy );

> Argument | Data Type | Access
> --- | --- | ---
> policy | integer | read

C Binding #include <sched.h>

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.

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.
[EINVAL] | The value of the policy argument does not represent a defined scheduling policy.

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_025.HTML