Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## pthread_attr_setinheritsched

> Changes the inherit scheduling attribute of the specified thread attributes object.

### Syntax

> pthread_attr_setinheritsched(
> attr ,
> inheritsched );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_attr_t | write
> inheritsched | integer | read

C Binding #include <pthread.h>

int
pthread_attr_setinheritsched (
pthread_attr_t *attr,
int inheritsched);

### Arguments

> #### attr

> Thread attributes object whose inherit scheduling attribute is to be modified.

> #### inheritsched

> New value for the inherit scheduling attribute. Valid values are as follows:

> | `PTHREAD_INHERIT_SCHED` | The created thread inherits the scheduling policy and associated scheduling attributes of the thread calling `pthread_create()` . Any scheduling attributes in the attributes object specified by the `pthread_create()` attr argument are ignored during thread creation. This is the default value.
> | `PTHREAD_EXPLICIT_SCHED` | The scheduling policy and associated scheduling attributes of the created thread are set to the corresponding values from the attribute object specified by the `pthread_create()` attr argument.

### Description

> This routine changes the inherit scheduling attribute of the thread attributes object specified by the attr argument. The inherit scheduling attribute specifies whether a thread created using the specified attributes object inherits the scheduling attributes of the creating thread, or uses the scheduling attributes stored in the attributes object specified by the `pthread_create()` attr argument.

> The first thread in an application has a scheduling policy of `SCHED_OTHER` . See the `pthread_attr_setschedparam()` and `pthread_attr_setschedpolicy()` routines for more information on valid priority values and valid scheduling policy values.

> Inheriting scheduling attributes (instead of using the scheduling attributes stored in the attributes object) is useful when a thread is creating several helper threads---that is, threads that are intended to work closely with the creating thread to cooperatively solve the same problem. For example, inherited scheduling attributes ensure that helper threads created in a sort routine execute with the same priority as the calling 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 value specified by the attr argument is not a valid thread attributes object, or the inheritsched argument contains an invalid value.
[ENOTSUP] | An attempt was made to set the attribute to an unsupported value.

#### Associated Routines

> `pthread_attr_init()`
> `pthread_attr_getinheritsched()`
> `pthread_attr_setschedpolicy()`
> `pthread_attr_setschedparam()`
> `pthread_attr_setscope()`
> `pthread_create()`

## pthread_attr_setname_np

> Changes the object name attribute in a thread attributes object.

### Syntax

> pthread_attr_setname_np(
> attr ,
> name ,
> mbz );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_attr_t | write
> name | char | read
> mbz | void | read

C Binding #include <pthread.h>

int
pthread_attr_setname_np (
pthread_attr_t *attr,
const char *name,
void *mbz);

### Arguments

> #### attr

> Address of the thread attributes object whose object name attribute is to be changed.

> #### name

> Object name value to copy into the thread attributes object's object name attribute.

> #### mbz

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

### Description

> This routine changes the object name attribute in the thread attributes object specified by the attr argument to the value specified by the name argument. A new thread created using the thread attributes object is initialized with the object name that was set in that attributes object.

> 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_setname_np()` , which changes the object name in the thread object for an existing 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 value specified by attr is not a valid thread attributes object, or the length in characters of name exceeds 31.
[ENOMEM] | Insufficient memory exists to create a copy of the object name string.

#### Associated Routines

> `pthread_attr_getname_np()`
> `pthread_getname_np()`
> `pthread_setname_np()`

## pthread_attr_setschedparam

> Changes the values of the parameters associated with a scheduling policy of the specified thread attributes object.

### Syntax

> pthread_attr_setschedparam(
> attr ,
> param );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_attr_t | write
> param | struct sched_param | read

C Binding #include <pthread.h>

int
pthread_attr_setschedparam (
pthread_attr_t *attr,
const struct sched_param *param);

### Arguments

> #### attr

> Thread attributes object for the scheduling policy attribute whose parameters are to be set.

> #### param

> A structure containing new values for scheduling parameters associated with the scheduling policy attribute of the specified thread attributes object.

> Note The Threads Library provides only the `sched_priority` scheduling parameter. See below for information about this scheduling parameter.

### Description

> This routine sets the scheduling parameters associated with the scheduling policy attribute of the thread attributes object specified by the attr argument.

> Scheduling Priority

> Use the `sched_priority` field of a `sched_param` structure to set a thread's execution priority. The effect of the scheduling priority you assign depends on the scheduling policy specified for the attributes object specified by the attr argument.

> By default, a created thread inherits the priority of the thread calling `pthread_create()` . To specify a priority using this routine, scheduling inheritance must be disabled at the time the thread is created. Before calling `pthread_create()` , call `pthread_attr_setinheritsched()` and specify the value `PTHREAD_EXPLICIT_SCHED` for the inherit argument.

> An application specifies priority only to express the urgency of executing the thread relative to other threads. Do not use priority to control mutual exclusion when you are accessing shared data. With a sufficient number of processors present, all ready threads, regardless of priority, execute simultaneously. Even on a uniprocessor, a lower priority thread could either execute before or be interleaved with a higher priority thread, for example due to page fault behavior. See Chapter 1 and Chapter 2 for more information.

> Valid values of the `sched_priority` scheduling parameter 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 Library provides nonportable priority range constants, as follows:

> Policy | Low | High
> --- | --- | ---
> `SCHED_FIFO` | `PRI_FIFO_MIN` | `PRI_FIFO_MAX`
> `SCHED_RR` | `PRI_RR_MIN` | `PRI_RR_MAX`
> `SCHED_OTHER` | `PRI_OTHER_MIN` | `PRI_OTHER_MAX`
> `SCHED_FG_NP` | `PRI_FG_MIN_NP` | `PRI_FG_MAX_NP`
> `SCHED_BG_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.)

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 by attr is not a valid thread attributes object, or the value specified by param is invalid.
[ENOTSUP] | An attempt was made to set the attribute to an unsupported value.

#### Associated Routines

> `pthread_attr_init()`
> `pthread_attr_getschedparam()`
> `pthread_attr_setinheritsched()`
> `pthread_attr_setschedpolicy()`
> `pthread_create()`
> `sched_yield()`

## pthread_attr_setschedpolicy

> Changes the scheduling policy attribute of the specified thread attributes object.

### Syntax

> pthread_attr_setschedpolicy(
> attr ,
> policy );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_attr_t | write
> policy | integer | read

C Binding #include <pthread.h>

int
pthread_attr_setschedpolicy (
pthread_attr_t *attr,
int policy);

### Arguments

> #### attr

> Thread attributes object to be modified.

> #### policy

> New value for the scheduling policy attribute. Valid values are as follows:

> > `SCHED_BG_NP`
> > `SCHED_FG_NP` (also known as `SCHED_OTHER` )
> > `SCHED_FIFO`
> > `SCHED_RR`

> `SCHED_OTHER` is the default value. See Section 2.3.2.2 for a description of the scheduling policies.

### Description

> This routine sets the scheduling policy of a thread that is created using the attributes object specified by the attr argument. The default value of the scheduling attribute is `SCHED_OTHER` .

> By default, a created thread inherits the policy of the thread calling `pthread_create()` . To specify a policy using this routine, scheduling inheritance must be disabled at the time the thread is created. Before calling `pthread_create()` , call `pthread_attr_setinheritsched()` and specify the value `PTHREAD_EXPLICIT_SCHED` for the inherit argument.

> Preemption is caused by both scheduling and policy. Never attempt to use scheduling as a mechanism for synchronization. (Refer to Chapter 1 and Chapter 2.)

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 by attr is not a valid thread attributes object, or the value specified by policy is invalid.

#### Associated Routines

> `pthread_attr_init()`
> `pthread_attr_getschedpolicy()`
> `pthread_attr_setinheritsched()`
> `pthread_attr_setschedparam()`
> `pthread_create()`

## pthread_attr_setscope

> Sets the contention scope attribute of the specified thread attributes object.

### Syntax

> pthread_attr_setscope(
> attr ,
> scope );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_attr_t | write
> scope | int | read

C Binding #include <pthread.h>

int
pthread_attr_setscope (
pthread_attr_t *attr,
int scope);

### Arguments

> #### attr

> Address of the thread attributes object whose contention scope attribute is to be modified.

> #### scope

> New value for the contention scope attribute of the thread attributes object specified by attr.

### Description

> This routine uses the value specified in the scope argument to set the contention scope attribute of the thread attributes object specified in the attr argument.

> When creating a thread, use a thread attributes object to specify nondefault values for thread attributes. The contention scope attribute specifies the set of threads with which a thread must compete for processing resources. The contention scope attribute specifies whether the new thread competes for processing resources only with other threads in its own process, called process contention scope, or with all threads on the system, called system contention scope.

> Note On Tru64 UNIX, the Threads Library supports both process contention scope and system contention scope threads. On OpenVMS, the Threads Library supports only process contention scope threads.

> The Threads Library selects at most one thread to execute on each processor at any point in time. The Threads Library resolves the contention based on each thread's scheduling attributes (for example, priority) and scheduling policy (for example, round-robin).

> A thread created using a thread attributes object whose contention scope attribute is set to `PTHREAD_SCOPE_PROCESS` contends for processing resources with other threads within its own process that also were created with `PTHREAD_SCOPE_PROCESS` . It is unspecified how such threads are scheduled relative to either threads in other processes or threads in the same process that were created with `PTHREAD_SCOPE_SYSTEM` contention scope.

> A thread created using a thread attributes object whose contention scope attribute is set to `PTHREAD_SCOPE_SYSTEM` contends for processing resources with other threads in any process that also were created with `PTHREAD_SCOPE_SYSTEM` .

> Note that the value of the contention scope attribute of a particular thread attributes object does not necessarily correspond to the actual scheduling contention scope of any existing thread in your multithreaded program.

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 by attr is not a valid thread attributes value, or the value specified by scope is not valid.
[ENOTSUP] | An attempt was made to set the attribute to an unsupported value.

#### Associated Routines

> `pthread_attr_destroy()`
> `pthread_attr_init()`
> `pthread_attr_getscope()`
> `pthread_attr_setinheritsched()`
> `pthread_create()`

## pthread_attr_setstackaddr

> Changes the stack address attribute of the specified thread attributes object.

### Syntax

> pthread_attr_setstackaddr(
> attr ,
> stackaddr );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_attr_t | write
> stackaddr | void | read

C Binding #include <pthread.h>

int
pthread_attr_setstackaddr (
pthread_attr_t *attr,
void *stackaddr);

### Arguments

> #### attr

> Address of the thread attributes object whose stack address attribute is to be modified.

> #### stackaddr

> New value for the stack address attribute of the thread attributes object specified by attr.

### Description

> This routine uses the value specified in the stackaddr argument to set the stack address attribute of the thread attributes object specified in the attr argument.

> When creating a thread, use a thread attributes object to specify nondefault values for thread attributes. The stack address attribute of a thread attributes object points to the origin of the stack for a new thread.

> The default value for the stack address attribute of an initialized thread attributes object is NULL.

> Note Correct use of this routine depends upon details of the target platform's stack architecture. Thus, this routine cannot be used in a portable manner. The size of the stack must be at least `PTHREAD_STACK_MIN` bytes (see the `pthread.h` header file). However, because the Threads Library must use a portion of this stack memory to begin thread execution and to maintain thread state, your program's "user thread code" cannot rely on using all of the stack memory allocated.

> For your program to calculate a value for the stackaddr attribute, note that:

> - Your program must allocate the memory that will be used for the new thread's stack.
> - On Tru64 UNIX, to create a new thread using a thread attributes object, the stackaddr attribute must be an address that points to the high-memory end of the memory region allocated for the stack. This address must point to the highest even-boundary quadword in the allocated memory region.

> Also note that:

> - If you use the `pthread_attr_setstackaddr()` routine to set a thread attributes object's stack address attribute and use that attributes object to create a new thread, the Threads Library ignores the attributes object's guardsize attribute and provides no thread stack guard area or overflow warning area for the new thread.
> - If you use the same thread attributes object to create more than one thread and each created thread uses a nondefault stack address, you must use the `pthread_attr_setstackaddr()` routine to set a unique stack address attribute value for each new thread created using that attributes object.

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 by attr is not a valid thread attributes object.

#### Associated Routines

> `pthread_attr_getguardsize()`
> `pthread_attr_getstackaddr()`
> `pthread_attr_getstacksize()`
> `pthread_attr_init()`
> `pthread_attr_setguardsize()`
> `pthread_attr_setstacksize()`
> `pthread_create()`

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_015.HTML