Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## pthread_condattr_setpshared

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

> This routine is for Tru64 UNIX systems only.

### Syntax

> pthread_condattr_setpshared(
> attr ,
> pshared );

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

C Binding #include <pthread.h>

int
pthread_condattr_setpshared (
pthread_condattr_t *attr,
int pshared);

### Arguments

> #### attr

> Address of the condition variable attributes object whose process-shared attribute is to be modified.

> #### pshared

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

### Description

> This routine uses the value specified in the pshared argument to set the process-shared attribute of the condition variable attributes object specified in the attr argument.

> 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 of differing 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, or the value specified by pshared is outside the range of legal values for that attribute.

#### Associated Routines

> `pthread_condattr_destroy()`
> `pthread_condattr_init()`
> `pthread_condattr_getpshared()`
> `pthread_cond_init()`

## pthread_cond_broadcast

> Wakes all threads that are waiting on the specified condition variable.

### Syntax

> pthread_cond_broadcast(
> cond );

> Argument | Data Type | Access
> --- | --- | ---
> cond | opaque pthread_cond_t | modify

C Binding #include <pthread.h>

int
pthread_cond_broadcast (
pthread_cond_t *cond);

### Arguments

> #### cond

> Condition variable upon which the threads (to be awakened) are waiting.

### Description

> This routine unblocks all threads waiting on the specified condition variable cond. Calling this routine implies that data guarded by the associated mutex has changed, so that it might be possible for one or more waiting threads to proceed. The threads that are unblocked shall contend for the mutex according to their respective scheduling policies (if applicable).

> If only one of the threads waiting on a condition variable may be able to proceed, but one of those threads can proceed, then use `pthread_cond_signal()` instead.

> Whether the associated mutex is locked or unlocked, you can still call this routine. However, if predictable scheduling behavior is required, that mutex should then be locked by the thread calling the `pthread_cond_broadcast()` routine.

> If no threads are waiting on the specified condition variable, this routine takes no action. The broadcast does not propagate to the next condition variable wait.

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 cond is not a valid condition variable.

#### Associated Routines

> `pthread_cond_destroy()`
> `pthread_cond_init()`
> `pthread_cond_signal()`
> `pthread_cond_timedwait()`
> `pthread_cond_wait()`

## pthread_cond_destroy

> Destroys a condition variable.

### Syntax

> pthread_cond_destroy(
> cond );

> Argument | Data Type | Access
> --- | --- | ---
> cond | opaque pthread_cond_t | write

C Binding #include <pthread.h>

int
pthread_cond_destroy (
pthread_cond_t *cond);

### Arguments

> #### cond

> Condition variable to be destroyed.

### Description

> This routine destroys the condition variable specified by cond. This effectively uninitializes the condition variable. Call this routine when a condition variable will no longer be referenced. Destroying a condition variable allows the Threads Library to reclaim internal memory associated with the condition variable.

> It is safe to destroy an initialized condition variable upon which no threads are currently blocked. Attempting to destroy a condition variable upon which other threads are blocked results in unpredictable behavior.

> The results of this routine are unpredictable if the condition variable specified in cond either does not exist or is not initialized.

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 cond is not a valid condition variable.
[EBUSY] | The object being referenced by cond is being referenced by another thread that is currently executing `pthread_cond_wait()` or `pthread_cond_timedwait()` on the condition variable specified in cond.

#### Associated Routines

> `pthread_cond_broadcast()`
> `pthread_cond_init()`
> `pthread_cond_signal()`
> `pthread_cond_timedwait()`
> `pthread_cond_wait()`

## pthread_cond_getname_np

> Obtains the object name from a condition variable object.

### Syntax

> pthread_cond_getname_np(
> cond ,
> name ,
> len );

> Argument | Data Type | Access
> --- | --- | ---
> cond | opaque pthread_cond_t | read
> name | char | write
> len | opaque size_t | read

C Binding #include <pthread.h>

int
pthread_cond_getname_np (
pthread_cond_t *cond,
char *name,
size_t len);

### Arguments

> #### cond

> Address of the condition variable 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 condition variable object specified by the cond 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 condition variable 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.
[EINVAL] | The value specified by cond is not a valid condition variable.

#### Associated Routines

> `pthread_cond_setname_np()`

## pthread_cond_init

> Initializes a condition variable.

### Syntax

> pthread_cond_init(
> cond ,
> attr );

> Argument | Data Type | Access
> --- | --- | ---
> cond | opaque pthread_cond_t | write
> attr | opaque pthread_condattr_t | read

C Binding #include <pthread.h>

int
pthread_cond_init (
pthread_cond_t *cond,
const pthread_condattr_t *attr);

### Arguments

> #### cond

> Condition variable to be initialized.

> #### attr

> Condition variable attributes object that defines the characteristics of the condition variable to be initialized.

### Description

> This routine initializes the condition variable cond with attributes specified in the attr argument. If attr is NULL, the default condition variable attributes are used.

> A condition variable is a synchronization object used in conjunction with a mutex. A mutex controls access to data that is shared among threads; a condition variable allows threads to wait for that data to enter a defined state.

> Condition variables are not owned by a particular thread. Any associated storage is not automatically deallocated when the creating thread terminates.

> Use the macro `PTHREAD_COND_INITIALIZER` to initialize statically allocated condition variables to the default condition variable attributes. To invoke this macro, enter:
> `pthread_cond_t` condition = `PTHREAD_COND_INITIALIZER`

> When statically initialized, a condition variable should not also be initialized using `pthread_cond_init()` . Also, a statically initialized condition variable need not be destroyed using `pthread_cond_destroy()` .

> Under certain circumstances it might be impossible to wait upon a statically initialized condition variable when the process virtual address space (or some other memory limit) is nearly exhausted. In such a case `pthread_cond_wait()` or `pthread_cond_timedwait()` can return [ENOMEM]. To avoid this possibility, initialize critical condition variables using `pthread_cond_init()` .

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.
[EAGAIN] | The system lacks the necessary resources to initialize another condition variable, or The system-imposed limit on the total number of condition variables under execution by a single user is exceeded.
[EBUSY] | The implementation has detected an attempt to reinitialize the object referenced by cond, a previously initialized, but not yet destroyed condition variable.
[EINVAL] | The value specified by attr is not a valid attributes object.
[ENOMEM] | Insufficient memory exists to initialize the condition variable.

#### Associated Routines

> `pthread_cond_broadcast()`
> `pthread_cond_destroy()`
> `pthread_cond_signal()`
> `pthread_cond_timedwait()`
> `pthread_cond_wait()`

## pthread_cond_setname_np

> Changes the object name for a condition variable object.

### Syntax

> pthread_cond_setname_np(
> cond ,
> name ,
> mbz );

> Argument | Data Type | Access
> --- | --- | ---
> cond | opaque pthread_cond_t | write
> name | char | read
> mbz | void | read

C Binding #include <pthread.h>

int
pthread_cond_setname_np (
pthread_cond_t *cond,
const char *name,
void *mbz);

### Arguments

> #### cond

> Address of the condition variable object whose object name is to be changed.

> #### name

> Object name value to copy into the condition variable object.

> #### mbz

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

### Description

> This routine changes the object name in the condition variable object specified by the cond argument to the value specified by the name argument. To set a new condition variable object's object name, call this routine immediately after initializing the condition variable 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.

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 cond is not a valid condition variable 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_cond_getname_np()`

## pthread_cond_signal

> Wakes at least one thread that is waiting on the specified condition variable.

### Syntax

> pthread_cond_signal(
> cond );

> Argument | Data Type | Access
> --- | --- | ---
> cond | opaque pthread_cond_t | modify

C Binding #include <pthread.h>

int
pthread_cond_signal (
pthread_cond_t *cond);

### Arguments

> #### cond

> Condition variable to be signaled.

### Description

> This routine unblocks at least one thread waiting on the specified condition variable cond. Calling this routine implies that data guarded by the associated mutex has changed, thus it might be possible for one of the waiting threads to proceed. In general, only one thread will be released.

> If no threads are waiting on the specified condition variable, this routine takes no action. The signal does not propagate to the next condition variable wait.

> This routine should be called when any thread waiting on the specified condition variable might find its predicate true, but only one thread should proceed. If more than one thread can proceed, or if any of the threads would not be able to proceed, then you must use `pthread_cond_broadcast()` .

> The scheduling policy determines which thread is awakened. For policies `SCHED_FIFO` and `SCHED_RR` , a blocked thread is chosen in priority order, using first-in/first-out (FIFO) within priorities.

> If the calling thread holds the lock to the target condition variable's associated mutex while setting the variable's wait predicate, that thread can call `pthread_cond_signal()` to signal the variable even after releasing the lock on that mutex. However, for more predictable scheduling behavior, call `pthread_cond_signal()` before releasing the target condition variable's associated mutex.

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 cond is not a valid condition variable.

#### Associated Routines

> `pthread_cond_broadcast()`
> `pthread_cond_destroy()`
> `pthread_cond_init()`
> `pthread_cond_timedwait()`
> `pthread_cond_wait()`

## pthread_cond_signal_int_np

> Wakes one thread that is waiting on the specified condition variable (called from interrupt level only).

### Syntax

> pthread_cond_signal_int_np(
> cond );

> Argument | Data Type | Access
> --- | --- | ---
> cond | opaque pthread_cond_t | modify

C Binding #include <pthread.h>

int
pthread_cond_signal_int_np(
pthread_cond_t *cond);

### Arguments

> #### cond

> Condition variable to be signaled.

### Description

> This routine wakes one thread waiting on the specified condition variable. It can only be called from a software interrupt handler routine (such as from a Tru64 UNIX signal handler or OpenVMS AST). Calling this routine implies that it might be possible for a single waiting thread to proceed.

> The scheduling policies of the waiting threads determine which thread is awakened. For policies `SCHED_FIFO` and `SCHED_RR` , a blocked thread is chosen in priority order, using first-in/first-out (FIFO) within priorities.

> This routine does not cause a thread blocked on a condition variable to resume execution immediately. A thread resumes execution at some time after the interrupt handler routine returns. If no threads are waiting on the condition variable at the time of the call to `pthread_cond_signal_int_np()` , the next future waiting thread will be automatically released (that is, it will not actually wait). This routine establishes a "pending" wake if necessary.

> You can call this routine regardless of whether the associated mutex is either locked or unlocked. (Never lock a mutex from an interrupt handler routine.)

> Note This routine allows you to signal a condition variable from a software interrupt handler. Do not call this routine from noninterrupt code. To signal a condition variable from the normal noninterrupt level, use `pthread_cond_signal()` .

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 cond is not a valid condition variable.

#### Associated Routines

> `pthread_cond_broadcast()`
> `pthread_cond_signal()`
> `pthread_cond_sig_preempt_int_np()`
> `pthread_cond_timedwait()`
> `pthread_cond_wait()`

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_017.HTML