Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## pthread_attr_getschedpolicy

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

### Syntax

> pthread_attr_getschedpolicy(
> attr ,
> policy );

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

C Binding #include <pthread.h>

int
pthread_attr_getschedpolicy (
const pthread_attr_t *attr,
int *policy);

### Arguments

> #### attr

> Thread attributes object whose scheduling policy attribute is obtained.

> #### policy

> Receives the value of the scheduling policy attribute. Refer to the description of the `pthread_attr_setschedpolicy()` routine for valid values.

### Description

> This routine obtains the value of the scheduling policy attribute of the specified thread attributes object. The scheduling policy attribute defines the scheduling policy for threads created using the 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_init()`
> `pthread_attr_setschedpolicy()`
> `pthread_create()`

## pthread_attr_getscope

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

### Syntax

> pthread_attr_getscope(
> attr ,
> scope );

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

C Binding #include <pthread.h>

int
pthread_attr_getscope (
const pthread_attr_t *attr,
int *scope);

### Arguments

> #### attr

> Address of the thread attributes object whose contention scope attribute is obtained.

> #### scope

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

### Description

> This routine obtains the value of the contention scope attribute of the thread attributes object specified in the attr argument and stores it in the location specified by the scope argument. The specified attributes object must already be initialized at the time this routine is called.

> 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.

> 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 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 object.
[ENOSYS] | This routine is not supported by the implementation.

#### Associated Routines

> `pthread_attr_init()`
> `pthread_attr_setscope()`

## pthread_attr_getstackaddr

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

### Syntax

> pthread_attr_getstackaddr(
> attr ,
> stackaddr );

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

C Binding #include <pthread.h>

int
pthread_attr_getstackaddr (
const pthread_attr_t *attr,
void **stackaddr);

### Arguments

> #### attr

> Address of the thread attributes object whose stack address attribute is obtained.

> #### stackaddr

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

### Description

> This routine obtains the value of the stack address attribute of the thread attributes object specified in the attr argument and stores it in the location specified by the stackaddr argument. The specified attributes object must already be initialized when this routine is called.

> The stack address attribute of a thread attributes object points to the origin of the stack for a new thread.

> Note that the value of the stack address attribute of a particular thread attributes object does not necessarily correspond to the actual stack origin 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 object.

#### Associated Routines

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

## pthread_attr_getstackaddr_np

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

### Syntax

> pthread_attr_getstackaddr_np(
> attr ,
> stackaddr ,
> size );

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

C Binding #include <pthread.h>

int
pthread_attr_getstackaddr (
const pthread_attr_t *attr,
void **stackaddr,
size_t *size);

### Arguments

> #### attr

> Address of the thread attributes object whose stack address attribute is obtained.

> #### stackaddr

> Receives the address of the stack region of the thread attributes object specified by attr.

> #### size

> The size of the stack region in bytes.

### Description

> This routine obtains the value of the stack address attribute of the thread attributes object specified in the attr argument and stores it in the location specified by the stackaddr argument. The specified attributes object must already be initialized when this routine is called.

> The stack address attribute of a thread attributes object points to the origin of the stack for a new thread.

> Unlike `pthread_attr_getstackaddr()` , this routine is a much more reliable portable interface. With the POSIX standard `pthread_attr_getstackaddr()` , a stack is specified using a single, undefined, address. An implementation of the standard can only assume that the specified value represents the value to which the thread's stack pointer should be set when beginning execution. However, this requires the application to know how the machine uses the stack. For example, a stack may "grow" either up (to higher addresses) or down (to lower addresses), and may be decreased (or increased) either before or after storing a new value.

> The Threads Library provides an alternative interface with
> `pthread_attr_getstackaddr_np()` . Instead of returning a stack address, it returns the base (lowest) address and the size.

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_setstackaddr_np()`

## pthread_attr_getstacksize

> Obtains the stacksize attribute of the specified thread attributes object.

### Syntax

> pthread_attr_getstacksize(
> attr ,
> stacksize );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_attr_t | read
> stacksize | size_t | write

C Binding #include <pthread.h>

int
pthread_attr_getstacksize (
const pthread_attr_t *attr,
size_t *stacksize);

### Arguments

> #### attr

> Thread attributes object whose stacksize attribute is obtained.

> #### stacksize

> Receives the value for the stacksize attribute of the thread attributes object specified by the attr argument.

### Description

> This routine obtains the stacksize attribute of the thread attributes object specified in the attr argument.

Return Values On successful completion, this routine returns a zero (0) and the stacksize value in bytes in the location specified in the stacksize argument.

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 stack attributes object.

#### Associated Routines

> `pthread_attr_init()`
> `pthread_attr_setstacksize()`
> `pthread_create()`

## pthread_attr_init

> Initializes a thread attributes object.

### Syntax

> pthread_attr_init(
> attr );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_attr_t | write

C Binding #include <pthread.h>

int
pthread_attr_init (
pthread_attr_t *attr);

### Arguments

> #### attr

> Address of a thread attributes object to be initialized.

### Description

> This routine initializes the thread attributes object specified by the attr argument with a set of default attribute values. A thread attributes object is used to specify the attributes of one or more threads when they are created. The attributes object created by this routine is used only in calls to the `pthread_create()` routine.

> The following routines change individual attributes of an initialized thread attributes object:

> > `pthread_attr_setdetachstate()`
> > `pthread_attr_setguardsize()`
> > `pthread_attr_setinheritsched()`
> > `pthread_attr_setschedparam()`
> > `pthread_attr_setschedpolicy()`
> > `pthread_attr_setscope()`
> > `pthread_attr_setstackaddr()`
> > `pthread_attr_setstacksize()`

> The attributes of the thread attributes object are initialized to default values. The default value of each attribute is discussed in the reference description for each routine previously listed.

> When a thread attributes object is used to create a thread, the object's attribute values determine the characteristics of the new thread. Thus, attributes objects act as additional arguments to thread creation. Changing the attributes of a thread attributes object does not affect any threads that were previously created using that attributes object.

> You can use the same thread attributes object in successive calls to `pthread_create()` , from any thread. (However, you cannot use the same value of the stack address attribute to create multiple threads that might run concurrently; threads cannot share a stack.) If more than one thread might change the attributes in a shared attributes object, your program must use a mutex to protect the integrity of the attributes object's contents.

> When you set the scheduling policy or scheduling parameters, or both, in a thread attributes object, you must disable scheduling inheritance if you want the scheduling attributes you set to be used at thread creation. To disable scheduling inheritance, before creating the new thread use the `pthread_attr_setinheritsched()` routine to specify the value `PTHREAD_EXPLICIT_SCHED` for the inherit argument.

Return Values If an error condition occurs, the thread attributes object cannot be used, 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 attr is not a valid thread attributes object.
[ENOMEM] | Insufficient memory to initialize the thread attributes object.

#### Associated Routines

> `pthread_attr_destroy()`
> `pthread_attr_setdetachstate()`
> `pthread_attr_setguardsize()`
> `pthread_attr_setinheritsched()`
> `pthread_attr_setschedparam()`
> `pthread_attr_setschedpolicy()`
> `pthread_attr_setscope()`
> `pthread_attr_setstackaddr()`
> `pthread_attr_setstacksize()`
> `pthread_create()`

## pthread_attr_setdetachstate

> Changes the detachstate attribute in the specified thread attributes object.

### Syntax

> pthread_attr_setdetachstate(
> attr ,
> detachstate );

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

C Binding #include <pthread.h>

int
pthread_attr_setdetachstate (
pthread_attr_t *attr,
int detachstate);

### Arguments

> #### attr

> Thread attributes object to be modified.

> #### detachstate

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

> `PTHREAD_CREATE_JOINABLE` | This is the default value. Threads are created in "undetached" state.
> `PTHREAD_CREATE_DETACHED` | The created thread is detached immediately, before it begins running.

### Description

> This routine changes the detachstate attribute in the thread attributes object specified by the attr argument. The detachstate attribute specifies whether the thread created using the specified thread attributes object is created in a detached state or not. A value of `PTHREAD_CREATE_JOINABLE` indicates the thread is not detached, and a value of `PTHREAD_CREATE_DETACHED` indicates the thread is detached. `PTHREAD_CREATE_JOINABLE` is the default value.

> Your program cannot use the thread handle (the value of type `pthread_t` returned by the `pthread_create()` routine) of a detached thread because the thread might terminate asynchronously, and a detached thread ID is not valid after termination. In particular, it is an error to attempt to detach or join with a detached thread.

> When a thread that has not been detached completes execution, the Threads Library retains the state of that thread to allow another thread to join with it. If the thread is detached before it completes execution, the Threads Library is free to immediately reclaim the thread's storage and resources. Failing to detach threads that have completed execution can result in wasting resources, so threads should be detached as soon as the program is done with them. If there is no need to use the thread's handle after creation, such as to join with it, create the thread initially detached.

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 threads attribute object or the detachstate argument is invalid.

#### Associated Routines

> `pthread_attr_init()`
> `pthread_attr_getdetachstate()`
> `pthread_create()`
> `pthread_join()`

## pthread_attr_setguardsize

> Changes the guardsize attribute of the specified thread attributes object.

### Syntax

> pthread_attr_setguardsize(
> attr ,
> guardsize );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_attr_t | write
> guardsize | size_t | read

C Binding #include <pthread.h>

int
pthread_attr_setguardsize (
pthread_attr_t *attr,
size_t guardsize);

### Arguments

> #### attr

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

> #### guardsize

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

### Description

> This routine uses the value specified in the guardsize argument to set the guardsize 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 guardsize attribute of a thread attributes object specifies the minimum size (in bytes) of the guard area for the stack of a new thread.

> A guard area, with its associated overflow warning area, can help a multithreaded program detect overflow of a thread's stack. A guard area is a region of no-access memory that the Threads Library allocates at the overflow end of the thread's stack, following the thread's overflow warning area. If the thread attempts to write in the overflow warning area, a stack overflow exception occurs. Your program can catch this exception and continue processing as long as the thread does not attempt to write in the guard area. When any thread attempts to access a memory location within the guard area, a memory addressing violation occurs without the possibility of recovery.

> A new thread can be created with a default guardsize attribute value. This value is platform dependent, but will always be at least one "hardware protection unit" (that is, at least one page). For more information, see this guide's platform-specific appendixes.

> After this routine is called, due to platform-specific factors the Threads Library might reserve a larger guard area for the new thread than was specified in the guardsize argument. See this guide's platform-specific appendixes for more information.

> The Threads Library allows your program to specify the size of a thread stack's guard area for two reasons:

> - When a thread allocates large data structures on its stack, a guard area with a size greater than the default size might be required to detect stack overflow.
> - Overflow protection of a thread's stack can potentially waste system resources, such as for an application that creates a large number of threads that will never overflow their stacks. Your multithreaded program can conserve system resources by "turning off" a thread's stack guard area---that is, by specifying a guardsize attribute of zero.

> If a thread is created using a thread attributes object whose stackaddr attribute is set (using the `pthread_attr_setstackaddr()` routine), this routine ignores the object's guardsize attribute and provides no thread stack overflow warning or guard area for the 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 argument attr is not a valid thread attributes object, or the argument guardsize contains an invalid value.

#### Associated Routines

> `pthread_attr_init()`
> `pthread_attr_getguardsize()`
> `pthread_attr_setstacksize()`
> `pthread_create()`

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_014.HTML