Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## Part 2
POSIX.1 (pthread) Routines Reference

Part 2 provides detailed descriptions of routines that constitute the pthread interface. These routines (with the prefix `pthread_` ) implement the IEEE POSIX 1003.1-1996 (or POSIX.1) standard, subject to the capabilities of the host operating system.

Note The pthread routines described here are based on the final POSIX.1 standard approved by the IEEE. Threads Library users should be aware that applications that use the obsolete d4 interfaces will require significant modifications to upgrade to the pthread interface. (The obsolete d4 interface corresponds to the IEEE POSIX 1003.4a/Draft 4 document.)

The global errno variable is not used by the pthread interface routines. To indicate errors, the pthread routines return integer values to indicate the error condition.

Routine names with the `_np` suffix denote that the routine is not portable, with respect to the POSIX.1 standard. That is, the routine might not be available in implementations of the POSIX.1 standard other than the Threads Library.

The Threads Library adds the extensions specified by The Open Group's (formerly X/Open) Single UNIX Specification, Version 2---also known as UNIX98. Some of the pthread interface routines that UNIX98 specifies are not present in the IEEE POSIX 1003.1-1996 standard; these routines include `pthread_attr_getguardsize()` , `pthread_attr_setguardsize()` , `pthread_mutexattr_gettype()` , and `pthread_mutexattr_settype()` . The Threads Library does not designate these routines as nonportable---that is, their names do not use the `_np` suffix naming convention. While portable to other implementations of the Single UNIX Specification, Version 2, these routines are not portable to other implementations of the POSIX.1 standard.

## pthread_atfork

> Declares fork handler routines to be called when the calling thread's process forks a child process.

> This routine is for Tru64 UNIX systems only.

### Syntax

> pthread_atfork(
> prepare ,
> parent ,
> child );

> Argument | Data Type | Access
> --- | --- | ---
> prepare | Handler | read
> parent | Handler | read
> child | Handler | read

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

int
pthread_atfork (
void (*prepare)(void),
void (*parent)(void),
void (*child)(void) );

### Arguments

> #### prepare

> Address of a routine that performs the fork preparation handling. This routine is called by the parent process before creating the child process.

> #### parent

> Address of a routine that performs the fork parent handling. This routine is called by the parent process after creating the child process and before returning to the caller of `fork(2)` .

> #### child

> Address of a routine that performs the fork child handling. This routine is called by the child process before returning to the caller of `fork(2)` .

### Description

> This routine allows a main program or library to control resources during a Tru64 UNIX `fork(2)` operation by declaring fork handler routines, as follows:
> - The fork handler routine specified in the prepare argument is called before `fork(2)` executes.
> - The fork handler routine specified in the parent argument is called after `fork(2)` executes within the parent process.
> - The fork handler routine specified in the child argument is called in the new child process after `fork(2)` executes.

> Your program (or library) can use fork handlers to ensure that program context in the child process is consistent and meaningful. After `fork(2)` executes, only the calling thread exists in the child process, and the state of all memory in the parent process is replicated in the child process, including the states of any mutexes, condition variables, and so on.

> For example, the new child process might have locked mutexes that are copies of mutexes that were locked in the parent process by threads that are not in the child process. Therefore, any associated program state might be inconsistent in the child process.

> The program can avoid this problem by calling `pthread_atfork()` to provide routines that acquire and release resources that are critical to the child process. For example, the prepare handler should lock all mutexes that you want to be usable in the child process. The parent handler just unlocks those mutexes. The child handler will also unlock them all---and might also create threads or reset any program state for the child process.

> To illustrate, if your library uses the mutex my_mutex, you might provide `pthread_atfork()` handler routines coded as follows:

>      void  my_prepare(void)
>            {
>            pthread_mutex_lock(&my_mutex);
>            }

>      void  my_parent(void)
>            {
>            pthread_mutex_unlock(&my_mutex);
>            }

>      void  my_child(void)
>            {
>            pthread_mutex_unlock(&my_mutex);
>            /* Reinitialize state that does not apply...like heap owned */
>            /* by other threads         */
>            }

>         {
>            .
>            .
>            .

>          pthread_atfork(my_prepare, my_parent, my_child);
>            .
>            .
>          fork();
>         }

> If you do not want to use fork handlers, you can set any of this routine's arguments to NULL.

> Note It is illegal to call `pthread_atfork()` from within a fork handler routine. Doing so could cause a deadlock.

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

Return | Description
--- | ---
0 | Successful completion.
[ENOMEM] | Insufficient table space to record the fork handler routines' addresses.

#### Associated Routines

> `pthread_create()`

## pthread_attr_destroy

> Destroys a thread attributes object.

### Syntax

> pthread_attr_destroy(
> attr );

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

C Binding #include <pthread.h>

int
pthread_attr_destroy (
pthread_attr_t *attr);

### Arguments

> #### attr

> Thread attributes object to be destroyed.

### Description

> This routine destroys a thread attributes object. Call this routine when a thread attributes object will no longer be referenced.

> Threads that were created using this thread attributes object are not affected by the destruction of the thread attributes object.

> The results of calling this routine are unpredictable if the value specified by the attr argument refers to a thread 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 value specified by attr is not a valid thread attributes object.

#### Associated Routines

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

## pthread_attr_getdetachstate

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

### Syntax

> pthread_attr_getdetachstate(
> attr ,
> detachstate );

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

C Binding #include <pthread.h>

int
pthread_attr_getdetachstate (
const pthread_attr_t *attr,
int *detachstate);

### Arguments

> #### attr

> Thread attributes object whose detachstate attribute is obtained.

> #### detachstate

> Receives the value of the detachstate attribute.

### Description

> This routine obtains the detachstate attribute of a thread attributes object. This attribute specifies whether threads created using the specified thread attributes object are created in a detached state.

> On successful completion, this routine returns a zero and the detachstate attribute is set in detachstate. A value of `PTHREAD_CREATE_JOINABLE` indicates the thread is not detached, and a value of `PTHREAD_CREATE_DETACHED` indicates the thread is detached.

> See the `pthread_attr_setdetachstate()` description for information about the detachstate attribute.

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 does not refer to an existing thread attributes object.

#### Associated Routines

> `pthread_attr_init()`
> `pthread_attr_setdetachstate()`

## pthread_attr_getguardsize

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

### Syntax

> pthread_attr_getguardsize(
> attr ,
> guardsize );

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

C Binding #include <pthread.h>

int
pthread_attr_getguardsize (
const pthread_attr_t *attr,
size_t *guardsize);

### Arguments

> #### attr

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

> #### guardsize

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

### Description

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

> 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 can help a multithreaded program detect the 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. When any thread attempts to access a memory location within this region, a memory addressing violation occurs.

> Note that the value of the guardsize attribute of a particular thread attributes object does not necessarily correspond to the actual size of the guard area 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 does not refer to an existing thread attributes object.

#### Associated Routines

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

## pthread_attr_getinheritsched

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

### Syntax

> pthread_attr_getinheritsched(
> attr ,
> inheritsched );

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

C Binding #include <pthread.h>

int
pthread_attr_getinheritsched (
const pthread_attr_t *attr,
int *inheritsched);

### Arguments

> #### attr

> Thread attributes object whose inherit scheduling attribute is obtained.

> #### inheritsched

> Receives the value of the inherit scheduling attribute. Refer to the description of the `pthread_attr_setinheritsched()` function for valid values.

### Description

> This routine obtains the value of the inherit scheduling attribute from the specified thread attributes object. The inherit scheduling attribute specifies whether threads created using the attributes object inherit the scheduling attributes of the creating thread, or use the scheduling attributes stored in the attributes object that is passed to `pthread_create()` .

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_setinheritsched()`
> `pthread_create()`

## pthread_attr_getname_np

> Obtains the object name attribute from a thread attributes object.

### Syntax

> pthread_attr_getname_np(
> attr ,
> name ,
> len ,
> mbz );

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

C Binding #include <pthread.h>

int
pthread_attr_getname_np (
const pthread_attr_t *attr,
char *name,
size_t len,
void **mbz);

### Arguments

> #### attr

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

> #### name

> Location to store the obtained object name.

> #### len

> Length in bytes of buffer at the location specified by name.

> #### mbz

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

### Description

> This routine copies the object name attribute from the thread attributes object specified by the attr argument to the buffer at the location specified by the name argument. Before calling this routine, your program must allocate the buffer indicated by name. 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.

> If the specified thread attributes object has not been previously set with an object name, this routine copies a C language null string into the buffer at location name.

> This routine contrasts with `pthread_getname_np()` , which obtains the object name from 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.

#### Associated Routines

> `pthread_getname_np()`
> `pthread_attr_setname_np()`
> `pthread_setname_np()`

## pthread_attr_getschedparam

> Obtains the scheduling parameters for an attribute of the specified thread attributes object.

### Syntax

> pthread_attr_getschedparam(
> attr ,
> param );

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

C Binding #include <pthread.h>

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

### Arguments

> #### attr

> Thread attributes object of the scheduling policy attribute whose parameters are obtained.

> #### param

> Receives the values of scheduling parameters for the scheduling policy attribute of the attributes object specified by the attr argument. Refer to the description of the `pthread_attr_setschedparam()` routine for valid parameters and their values.

### Description

> This routine obtains the scheduling parameters associated with the scheduling policy attribute of the specified thread 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_setschedparam()`
> `pthread_create()`

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_013.HTML