Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## pthread_attr_setstackaddr_np

> Changes the stack address and size of the specified thread attributes object.

### Syntax

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

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

C Binding #include <pthread.h>

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

### Arguments

> #### attr

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

> #### stackaddr

> New value for 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 uses the values specified in the stackaddr and size arguments to set the base stack address and size 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 default value for the stack address attribute of an initialized thread attributes object is NULL.

> Unlike `pthread_attr_setstackaddr()` , this routine is a much more reliable portable interface. With the POSIX standard `pthread_attr_setstackaddr()` , 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_setstackaddr_np()` . Instead of specifying a stack address, you specify 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_getstackaddr_np()`

## pthread_attr_setstacksize

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

### Syntax

> pthread_attr_setstacksize(
> attr ,
> stacksize );

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

C Binding #include <pthread.h>

int
pthread_attr_setstacksize (
pthread_attr_t *attr,
size_t stacksize);

### Arguments

> #### attr

> Threads attributes object to be modified.

> #### stacksize

> New value for the stacksize attribute of the thread attributes object specified by the attr argument. The stacksize argument must be greater than or equal to `PTHREAD_STACK_MIN` . `PTHREAD_STACK_MIN` specifies the minimum size (in bytes) of the stack needed for a thread.

### Description

> This routine sets the stacksize attribute in the thread attributes object specified by the attr argument. Use this routine to adjust the size of the writable area of the stack for a new thread.

> The size of a thread's stack is fixed at the time of thread creation. On OpenVMS systems, only the initial thread can dynamically extend its stack. On Tru64 UNIX systems, very large stacks can be created, but only a few pages are committed.

> Many compilers do not check for stack overflow. Ensure that the new thread's stack is sufficient for the resources required by routines that are called from the 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 value specified by stacksize either is less than `PTHREAD_STACK_MIN` or exceeds a Threads Library-imposed limit.

#### Associated Routines

> `pthread_attr_init()`
> `pthread_attr_getstacksize()`
> `pthread_create()`

## pthread_cancel

> Allows a thread to request a thread to terminate execution.

### Syntax

> pthread_cancel(
> thread );

> Argument | Data Type | Access
> --- | --- | ---
> thread | opaque pthread_t | read

C Binding #include <pthread.h>

int
pthread_cancel (
pthread_t thread);

### Arguments

> #### thread

> Thread that will receive a cancelation request.

### Description

> This routine sends a cancelation request to the specified target thread. A cancelation request is a mechanism by which a calling thread requests the target thread to terminate as quickly as possible. Issuing a cancelation request does not guarantee that the target thread will receive or handle the request.

> When the cancelation request is acted on, all active cleanup handler routines for the target thread are called. When the last cleanup handler returns, the thread-specific data destructor routines are called for each thread-specific data key with a destructor and for which the target thread has a non-NULL value. Finally, the target thread is terminated.

> Note that cancelation of the target thread runs asynchronously with respect to the calling thread's returning from `pthread_cancel()` . The target thread's cancelability state and type determine when or if the cancelation takes place, as follows:

> 1. The target thread can delay cancelation during critical operations by setting its cancelability state to `PTHREAD_CANCEL_DISABLE` .
> 2. Because of communication delays, the calling thread can only rely on the fact that a cancelation request will eventually become pending in the target thread (provided that the target thread does not terminate beforehand).
> 3. The calling thread has no guarantee that a pending cancelation request will be delivered because delivery is controlled by the target thread.

> When a cancelation request is delivered to a thread, termination processing is similar to that for `pthread_exit()` . For more information about thread termination, see the Thread Termination section of `pthread_create()` .

> This routine is preferred in implementing an Ada `abort` statement and any other language- or software-defined construct for requesting thread cancelation.

> The results of this routine are unpredictable if the value specified in thread refers to a thread that does not currently exist.

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 thread is invalid.
[ESRCH] | The thread argument does not specify an existing thread.

#### Associated Routines

> `pthread_cleanup_pop()`
> `pthread_cleanup_push()`
> `pthread_create()`
> `pthread_exit()`
> `pthread_join()`
> `pthread_setcancelstate()`
> `pthread_setcanceltype()`
> `pthread_testcancel()`

## pthread_cleanup_pop

> (Macro) Removes the cleanup handler routine from the calling thread's cleanup handler stack and optionally executes it.

### Syntax

> pthread_cleanup_pop(
> execute );

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

C Binding #include <pthread.h>

void
pthread_cleanup_pop(
int execute);

### Arguments

> #### execute

> Integer that specifies whether the cleanup handler routine specified in the matching call to `pthread_cleanup_push()` is executed. A nonzero value causes the cleanup handler routine to be executed.

### Description

> This routine removes the cleanup handler routine established by the matching call to `pthread_cleanup_push()` from the calling thread's cleanup handler stack, then executes it if the value specified in this routine's execute argument is nonzero.

> A cleanup handler routine can be used to clean up from a block of code whether exited by normal completion, cancelation, or the raising (or reraising) of an exception. The routine is popped from the calling thread's cleanup handler stack and is called with the arg argument (see the description for `pthread_cleanup_push()` ) when any of the following actions occur:

> - The thread calls `pthread_cleanup_pop()` and specifies a nonzero value for the execute argument.
> - The thread calls `pthread_exit()` .
> - The thread is canceled.
> - An exception is raised and is caught when the Threads Library unwinds the calling thread's stack to the lexical scope of the `pthread_cleanup_push()` and `pthread_cleanup_pop()` pair.

> This routine and `pthread_cleanup_push()` are implemented as macros and must appear as statements and in pairs within the same lexical scope. You can think of the `pthread_cleanup_push()` macro as expanding to a string whose first character is a left brace ({) and `pthread_cleanup_pop()` as expanding to a string containing the corresponding right brace (}). This routine and `pthread_cleanup_push()` are implemented as exceptions, and may not work in a C++ environment. (See Chapter 5 for more information.)

Return Values None

#### Associated Routines

> `pthread_cancel()`
> `pthread_cleanup_push()`
> `pthread_create()`
> `pthread_exit()`

## pthread_cleanup_push

> (Macro) Establishes a cleanup handler routine to be executed when the thread exits or is canceled.

### Syntax

> pthread_cleanup_push(
> routine,
> arg );

> Argument | Data Type | Access
> --- | --- | ---
> routine | procedure | read
> arg | user_arg | read

C Binding #include <phtread.h>

void
pthread_cleanup_push(
void (*routine)(void *),
void *arg);

### Arguments

> #### routine

> Routine executed as the cleanup handler.

> #### arg

> Argument passed to the cleanup handler routine.

### Description

> This routine pushes the specified routine onto the calling thread's cleanup handler stack. The cleanup handler routine is popped from the stack and called with the arg argument when any of the following actions occur:
> - The thread calls `pthread_cleanup_pop()` and specifies a nonzero value for the execute argument.
> - The thread calls `pthread_exit()` .
> - The thread is canceled.
> - An exception is raised and is caught when the Threads Library unwinds the calling thread's stack to the lexical scope of the `pthread_cleanup_push()` and `pthread_cleanup_pop()` pair.

> This routine and `pthread_cleanup_pop()` are implemented as macros and must appear as statements and in pairs within the same lexical scope. You can think of the `pthread_cleanup_push()` macro as expanding to a string whose first character is a left brace ({) and `pthread_cleanup_pop()` as expanding to a string containing the corresponding right brace (}). This routine and `pthread_cleanup_pop()` are implemented as exceptions, and may not work in a C++ environment. (See Chapter 5 for more information.)

Return Values None

#### Associated Routines

> `pthread_cancel()`
> `pthread_cleanup_pop()`
> `pthread_create()`
> `pthread_exit()`
> `pthread_testcancel()`

## pthread_condattr_destroy

> Destroys a condition variable attributes object.

### Syntax

> pthread_condattr_destroy(
> attr );

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

C Binding #include <pthread.h>

int
pthread_condattr_destroy (
pthread_condattr_t *attr);

### Arguments

> #### attr

> Condition variable attributes object to be destroyed.

### Description

> This routine destroys the specified condition variable attributes object. Call this routine when a condition variable attributes object will no longer be referenced.

> Condition variables that were created using this attributes object are not affected by the destruction of the condition variable attributes object.

> The results of calling this routine are unpredictable if the value specified by the attr argument refers to a condition variable attributes object that does not exist.

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 attributes object specified by attr is invalid.

#### Associated Routines

> `pthread_condattr_init()`

## pthread_condattr_getpshared

> Obtains the process-shared attribute of the specified condition variable attributes object.

> This routine is for Tru64 UNIX systems only.

### Syntax

> pthread_condattr_getpshared(
> attr ,
> pshared );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_condattr_t | read
> pshared | int | write

C Binding #include <pthread.h>

int
pthread_condattr_getpshared (
const pthread_condattr_t *attr,
int *pshared);

### Arguments

> #### attr

> Address of the condition variable attributes object whose process-shared attribute is obtained.

> #### pshared

> Receives the value of the process-shared attribute of the condition variable attributes object specified by attr.

### Description

> This routine obtains the value of the process-shared attribute of the condition variable attributes object specified by the attr argument and stores it in the location specified by the pshared argument. The specified attributes object must already be initialized at the time this routine is called.

> Creating a condition variable whose process-shared attribute is set to `PTHREAD_PROCESS_PRIVATE` permits it to be operated upon by threads created within the same process as the thread that initialized that condition variable. If threads in other processes attempt to operate on such a condition variable, the behavior is undefined.

> The default value of the process-shared attribute of an initialized condition variable attributes object is `PTHREAD_PROCESS_PRIVATE` .

> Creating a condition variable whose process-shared attribute is set to `PTHREAD_PROCESS_SHARED` permits it to be operated upon by any thread that has access to the memory where that condition variable is allocated, even if it is allocated in memory that is shared by multiple processes.

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

#### Associated Routines

> `pthread_condattr_destroy()`
> `pthread_condattr_init()`
> `pthread_condattr_setpshared()`
> `pthread_cond_init()`

## pthread_condattr_init

> Initializes a condition variable attributes object.

### Syntax

> pthread_condattr_init(
> attr );

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

C Binding #include <pthread.h>

int
pthread_condattr_init (
pthread_condattr_t *attr);

### Arguments

> #### attr

> Address of the condition variable attributes object to be initialized.

### Description

> This routine initializes the condition variable attributes object specified by the attr argument with a set of default attribute values.

> When an attributes object is used to create a condition variable, the values of the individual attributes determine the characteristics of the new condition variable. Attributes objects act as additional arguments to condition variable creation. Changing individual attributes in an attributes object does not affect any condition variables that were previously created using that attributes object.

> You can use the same condition variable attributes object in successive calls to `pthread_condattr_init()` , from any thread. If multiple threads can change attributes in a shared attributes object, your program must use a mutex to protect the integrity of that attributes object.

> Results are undefined if this routine is called and the attr argument specifies a condition variable attributes object that is already initialized.

> Currently, on OpenVMS systems, no attributes affecting condition variables are defined; you cannot change any attributes in the condition variable attributes object. On Tru64 UNIX systems, the `PSHARED` attribute is defined.

> The `pthread_condattr_init()` and `pthread_condattr_destroy()` routines are provided for future expandability of the pthread interface and to conform with the POSIX.1 standard. These routines serve no useful function, because there are no `pthread_condattr_set*()` type routines available at this time.

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 condition variable attributes object.
[ENOMEM] | Insufficient memory exists to initialize the condition variable attributes object.

#### Associated Routines

> `pthread_condattr_destroy()`
> `pthread_cond_init()`

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_016.HTML