Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## pthread_delay_np

> Delays a thread's execution.

### Syntax

> pthread_delay_np(
> interval );

> Argument | Data Type | Access
> --- | --- | ---
> interval | struct timespec | read

C Binding #include <pthread.h>

int
pthread_delay_np (
const struct timespec *interval);

### Arguments

> #### interval

> Number of seconds and nanoseconds to delay execution. The value specified for each must be greater than or equal to zero.

### Description

> This routine causes a thread to delay execution for a specific interval of time. This interval ends at the current time plus the specified interval. The routine will not return before the end of the interval is reached, but may return an arbitrary amount of time after the end of the interval is reached. This can be due to system load, thread priorities, and system timer granularity.

> Specifying an interval of zero (0) seconds and zero (0) nanoseconds is allowed and can be used to force the thread either to give up the processor or to deliver a pending cancelation request.

> The `timespec` structure contains the following two fields:

> - `tv_sec` is an integral number of seconds.
> - `tv_nsec` is an integral number of nanoseconds.

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 interval is invalid.

## pthread_detach

> Marks a thread object for deletion.

### Syntax

> pthread_detach(
> thread );

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

C Binding #include <pthread.h>

int
pthread_detach (
pthread_t thread);

### Arguments

> #### thread

> Thread object being marked for deletion.

### Description

> This routine marks the specified thread object to indicate that storage for the corresponding thread can be reclaimed when the thread terminates. This includes storage for the thread argument's return value, as well as the thread object. If thread has not terminated when this routine is called, this routine does not cause it to terminate.

> When a thread object is no longer referenced, call this routine.

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

> You can create a thread already detached by setting its thread object's detachstate attribute.

> The `pthread_join()` routine also detaches the target thread after `pthread_join()` returns successfully.

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 value specified by thread does not refer to a joinable thread.
[ESRCH] | The value specified by thread cannot be found.

#### Associated Routines

> `pthread_cancel()`
> `pthread_create()`
> `pthread_exit()`
> `pthread_join()`

## pthread_equal

> Compares one thread identifier to another thread identifier.

### Syntax

> pthread_equal(
> t1 ,
> t2 );

> Argument | Data Type | Access
> --- | --- | ---
> t1 | opaque pthread_t | read
> t2 | opaque pthread_t | read

C Binding #include <pthread.h>

int
pthread_equal (
pthread_t t1,
pthread_t t2);

### Arguments

> #### t1

> The first thread identifier to be compared.

> #### t2

> The second thread identifier to be compared.

### Description

> This routine compares one thread identifier to another thread identifier.

> If either t1 or t2 are not valid thread identifiers, this routine's behavior is undefined.

Return Values Possible return values are as follows:

Return | Description
--- | ---
0 | Values of t1 and t2 do not designate the same object.
Non-zero | Values of t1 and t2 designate the same object.

## pthread_exc_get_status_np

> (Macro) Obtains a system-defined error status from a status exception object.

### Syntax

> pthread_exc_get_status_np(
> exception ,
> code );

> Argument | Data Type | Access
> --- | --- | ---
> exception | EXCEPTION | read
> code | unsigned long | write

C Binding #include <pthread_exception.h>

int
pthread_exc_get_status_np (
EXCEPTION *exception,
unsigned long *code);

### Arguments

> #### exception

> Threads Library status exception object whose status code is obtained.

> #### code

> Receives the system-specific status code associated with the specified status exception object.

### Description

> This routine obtains and returns the system-specific status value from the status exception object specified in the exception argument. This value must have already been associated with the exception object using the `pthread_exc_set_status_np()` routine.

> In a program that uses Threads Library status exceptions, use this routine within a `CATCH` or `CATCH_ALL` code block to obtain the status code value associated with a caught exception. Note that any exception objects set to the same status value are considered equivalent by the Threads Library.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. If the routine's exception object argument is a status exception, it sets the code argument and returns zero (0). Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion.
[EINVAL] | The exception argument is not a valid status exception object.

#### Associated Routines

> `pthread_exc_set_status_np()`

## pthread_exc_matches_np

> (Macro) Determines whether two Threads Library exception objects are identical.

### Syntax

> pthread_exc_matches_np(
> exception1 ,
> exception2 );

> Argument | Data Type | Access
> --- | --- | ---
> exception1 | EXCEPTION | read
> exception2 | EXCEPTION | read

C Binding #include <pthread_exception.h>

int
pthread_exc_matches_np (
EXCEPTION *exception1,
EXCEPTION *exception2);

### Arguments

> #### exception1

> Threads Library exception object.

> #### exception2

> Threads Library exception object.

### Description

> This routine compares two exception objects, taking into consideration whether each is an address exception or status exception.

> This routine returns either the C language value `TRUE` or the C language value `FALSE` , indicating whether the two exception objects specified in the arguments exception1 and exception2 are identical.

Return Values The C language value `TRUE` if the exception objects are identical, or the C language value `FALSE` if not.

#### Associated Routines

> `pthread_exc_get_status_np()`
> `pthread_exc_report_np()`
> `pthread_exc_set_status_np()`

## pthread_exc_report_np

> Produces a message that reports what a specified Threads Library status exception object represents.

### Syntax

> pthread_exc_report_np(
> exception );

> Argument | Data Type | Access
> --- | --- | ---
> exception | EXCEPTION | read

C Binding #include <pthread_exception.h>

void
pthread_exc_report_np (
EXCEPTION *exception);

### Arguments

> #### exception

> Threads Library exception object that has been set with a status value.

### Description

> This routine produces a text message on the `stderr` device (Tru64 UNIX systems) or SYS$ERROR device (OpenVMS systems) that describes the exception whose exception object is specified in the exception argument.

> In a program that uses status exceptions, use this routine within a `CATCH` or `CATCH_ALL` code block to produce the message associated with a caught exception. Note that any exception objects set to the same status value are considered equivalent by the Threads Library.

Return Values None

#### Associated Routines

> `pthread_exc_get_status_np()`
> `pthread_exc_set_status_np()`

## pthread_exc_set_status_np

> (Macro) Imports a system-defined error status into a Threads Library address exception object.

### Syntax

> pthread_exc_set_status_np(
> exception ,
> code );

> Argument | Data Type | Access
> --- | --- | ---
> exception | EXCEPTION | write
> code | unsigned long | read

C Binding #include <pthread_exception.h>

void
pthread_exc_set_status_np (
EXCEPTION *exception,
unsigned long code);

### Arguments

> #### exception

> Threads Library address exception object into which the specified status code is imported.

> #### code

> System-specific status code to be imported.

### Description

> This routine associates a system-specific status value with the specified address exception object. This transforms the address exception object into a status exception object.

> The exception argument must already have been initialized with the exception package's `EXCEPTION_INIT` macro.

> Use this routine to associate any system-specific status value with the specified address exception object. Note that any exception objects set to the same status value are considered equivalent by the Threads Library.

Return Values None

#### Associated Routines

> `pthread_exc_get_status_np()`

## pthread_exit

> Terminates the calling thread.

### Syntax

> pthread_exit(
> value _ptr );

> Argument | Data Type | Access
> --- | --- | ---
> value_ptr | void * | read

C Binding #include <pthread.h>

void
pthread_exit (
void *value_ptr);

### Arguments

> #### value_ptr

> Value copied and returned to the caller of `pthread_join()` . Note that `void *` is used as a universal datatype, not as a pointer. The Threads Library treats the value_ptr as a value and stores it to be returned by `pthread_join()` .

### Description

> This routine terminates the calling thread and makes a status value (value_ptr) available to any thread that calls `pthread_join()` and specifies the terminating thread.

> Any cleanup handlers that have been pushed and not yet popped from the stack are popped in the reverse order that they were pushed and then executed. After all cleanup handlers have been executed, appropriate destructor functions are called in an unspecified order if the thread has any thread-specific data. Thread termination does not release any application-visible process resources, including, but not limited to mutexes and file descriptors, nor does it perform any process-level cleanup actions, including, but not limited to calling any `atexit()` routine that may exist.

> The Threads Library issues an implicit call to `pthread_exit()` when a thread returns from the start routine that was used to create it. The Threads Library writes the function's return value as the return value in the thread's thread object. The process exits when the last running thread calls `pthread_exit()` .

> After a thread has terminated, the result of access to local (that is, explicitly or implicitly declared `auto` ) variables of the thread is undefined. So, do not use references to local variables of the existing thread for the value_ptr argument of the `pthread_exit()` routine.

Return Values None

#### Associated Routines

> `pthread_cancel()`
> `pthread_create()`
> `pthread_detach()`
> `pthread_join()`

## pthread_getconcurrency

> Obtains the value of the concurrency level global variable for this process.

### Syntax

> pthread_getconcurrency(
> );

C Binding #include <pthread.h>

int
pthread_getconcurrency (
void);

### Description

> This routine obtains and returns the value of the "concurrency level" global setting for the calling thread's process. Because the Threads Library automatically manages the concurrency of all threads in a multithreaded process, it ignores this concurrency level value.

> The concurrency level value has no effect on the behavior of a multithreaded program that uses the Threads Library. This routine is provided for Single UNIX Specification, Version 2, source code compatibility and has no other effect when called.

> The initial concurrency level is zero (0), indicating that the Threads Library controls the concurrency level.

> The concurrency level can be set using the `pthread_setconcurrency()` routine.

Return Values This routine always returns the value of this process' concurrency level global variable. If this process has never called the `pthread_setconcurrency()` routine, this routine returns zero (0).

#### Associated Routines

> `pthread_setconcurrency()`

## pthread_getname_np

> Obtains the object name from the thread object for an existing thread.

### Syntax

> pthread_getname_np(
> thread ,
> name ,
> len );

> Argument | Data Type | Access
> --- | --- | ---
> thread | opaque pthread_thread_t | read
> name | char | write
> len | opaque size_t | read

C Binding #include <pthread.h>

int
pthread_getname_np (
pthread_thread_t thread,
char *name,
size_t len);

### Arguments

> #### thread

> Thread object whose object name is to be obtained.

> #### name

> Location to store the obtained object name.

> #### len

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

### Description

> This routine copies the object name from the thread object specified by the thread 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.

> 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 object has not been previously set with an object name, this routine copies a C language null string into the buffer at location name.

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.
[ESRCH] | The thread specified by thread does not exist.

#### Associated Routines

> `pthread_setname_np()`

## pthread_getschedparam

> Obtains the current scheduling policy and scheduling parameters of a thread.

### Syntax

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

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

C Binding #include <pthread.h>

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

### Arguments

> #### thread

> Thread whose scheduling policy and parameters are obtained.

> #### policy

> Receives the value of the scheduling policy for the thread specified in thread. Refer to the description of the `pthread_setschedparam()` routine for valid policies and their meanings.

> #### param

> Receives the value of the scheduling parameters for the thread specified in thread. Refer to the description of the `pthread_setschedparam()` routine for valid values.

### Description

> This routine obtains both the current scheduling policy and associated scheduling parameters of the thread specified by the thread argument.

> The priority value returned in the param structure is the value specified either in the attr argument passed to `pthread_create()` or by the most recent call to `pthread_setschedparam()` that affects the target thread.

> This routine differs from `pthread_attr_getschedpolicy()` and
> `pthread_attr_getschedparam()` , in that those routines get the scheduling policy and parameter attributes that are used to establish the priority and scheduling policy of a new thread when it is created. This routine, however, obtains the scheduling policy and parameters of 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.
[ESRCH] | The value specified by thread does not refer to an existing thread.

#### Associated Routines

> `pthread_attr_getschedparam()`
> `pthread_attr_getschedpolicy()`
> `pthread_create()`
> `pthread_self()`
> `pthread_setschedparam()`

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_019.HTML