Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## sched_get_priority_min

> Returns the minimum priority for the specified scheduling policy.

### Syntax

> sched_get_priority_min(
> policy );

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

C Binding #include <sched.h>

int
sched_get_priority_min (
int policy);

### Arguments

> #### policy

> One of the scheduling policies, as defined in `sched.h` .

### Description

> This routine returns the minimum priority for the scheduling policy specified in the policy argument. The argument value must be one of the scheduling policies ( `SCHED_FIFO` , `SCHED_RR` , or `SCHED_OTHER` ), as defined in the `sched.h` header file.

> No special privileges are required to use this routine.

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 of the policy argument does not represent a defined scheduling policy.

## sched_yield

> Yields execution to another thread.

### Syntax

> sched_yield( );

C Binding #include <sched.h>
#include <unistd.h>

int
sched_yield (void);

### Arguments

> ####

> None

### Description

> In conformance with the IEEE POSIX.1-1996 standard, the `sched_yield()` function causes the calling thread to yield execution to another thread. It is useful when a thread running under the `SCHED_FIFO` scheduling policy must allow another thread at the same priority to run. The thread that is interrupted by `sched_yield()` goes to the end of the queue for its priority.

> If no other thread is runnable at the priority of the calling thread, the calling thread continues to run.

> Threads with higher priority are allowed to preempt the calling thread, so the `sched_yield()` function has no effect on the scheduling of higher- or lower-priority threads.

> The `sched_yield()` routine takes no arguments. No special privileges are needed to use the `sched_yield()` function.

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.
[ENOSYS] | The routine `sched_yield()` is not supported by this implementation.

#### Associated Routines

> `pthread_attr_setschedparam()`
> `pthread_getschedparam()`
> `pthread_setschedparam()`

## sigwait

> Suspends a calling thread until a signal arrives.

> This routine is for Tru64 UNIX systems only.

### Syntax

> sigwait(
> set ,
> signal );

> Argument | Data Type | Access
> --- | --- | ---
> set | sigset_t | read
> signal | integer | write

C Binding #include <signal.h>

int
sigwait (
sigset_t *set,
int *signal);

### Arguments

> #### set

> Set of signals to wait for.

> #### signal

> Signal number obtained for the selected signal.

### Description

> This routine blocks the calling thread until at least one of the signals in the set argument is in the caller's set of pending signals. When this happens, one of those signals is automatically selected and removed from the set of pending signals. The signal number identifying that signal is then returned.

> This routine stores the signal number obtained in the address specified in the signal argument.

> The effect of calling this routine is unspecified if any signals in the set argument are not blocked at the time of the call.

> The set signal set object is created using the set manipulation routines `sigemptyset()` , `sigfillset()` , `sigaddset()` , and `sigdelset()` .

> If, while this routine is waiting, a signal occurs that is eligible for delivery (that is, not blocked by the signal mask), that signal is handled asynchronously and the wait is interrupted.

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 of the set argument contains an invalid or unsupported signal number.
[EINTR] | The wait was interrupted by an unblocked, caught signal.

## Part 3
Compaq Proprietary Interfaces: tis Routines Reference

Part 3 provides detailed descriptions of the Compaq proprietary thread-independent services (or tis) interface routines.

These routines are designed to provide efficient tools for thread safety in libraries whose routines do not themselves use threads. The tis interface provides functions similar to the pthread functions for synchronization. In a program that creates or uses threads, the tis functions provide full thread synchronization and coherence of memory access. But, in a program that does not use threads, the same tis calls provide low-overhead "stub" implementations of pthread features.

The objects created using tis interface routines are the same as pthread interface objects.

The variable errno is not used by the tis routines. Like the pthread routines, the tis routines return integer values indicating the type of error.

Note Never use `tis_cond_wait()` in a nonthreaded environment. It cannot wait, as there would be no thread able to awaken the waiter. The tis "stub" will abort your program.

When threads are present, the guidelines for using pthread routines apply to using the corresponding tis routines.

## tis_cond_broadcast

> Wakes all threads that are waiting on a condition variable.

### Syntax

> tis_cond_broadcast(
> cond );

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

C Binding #include <tis.h>

int
tis_cond_broadcast (
pthread_cond_t *cond);

### Arguments

> #### cond

> Address of the condition variable (passed by reference) on which to broadcast.

### Description

> When threads are not present, this routine has no effect.

> When threads are present, this routine unblocks all threads waiting on the specified condition variable cond.

> For further information about actions when threads are present, refer to the `pthread_cond_broadcast()` description.

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

> `tis_cond_destroy()`
> `tis_cond_init()`
> `tis_cond_signal()`
> `tis_cond_wait()`

## tis_cond_destroy

> Destroys the specified condition variable.

### Syntax

> tis_cond_destroy(
> cond );

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

C Binding #include <tis.h>

int
tis_cond_destroy (
pthread_cond_t *cond);

### Arguments

> #### cond

> Address of the condition variable (passed by reference) to be destroyed.

### Description

> This routine destroys the condition variable specified by cond. After this routine is called, the Threads Library may reclaim internal storage used by the condition variable object. Call this routine when a condition variable will no longer be referenced.

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

> For more information about actions when threads are present, refer to the `pthread_cond_destroy()` description.

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.
[EBUSY] | The object being referenced by cond is being referenced by another thread that is currently executing a `tis_cond_wait()` on the condition variable specified in cond. (This error can only occur when threads are present.)
[EINVAL] | The value specified by cond is not a valid condition variable.

#### Associated Routines

> `tis_cond_broadcast()`
> `tis_cond_init()`
> `tis_cond_signal()`
> `tis_cond_wait()`

## tis_cond_init

> Initializes a condition variable.

### Syntax

> tis_cond_init(
> cond );

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

C Binding #include <tis.h>

int
tis_cond_init (
pthread_cond_t *cond);

### Arguments

> #### cond

> Address of the condition variable (passed by reference) to be initialized.

### Description

> This routine initializes a condition variable (cond) with the Threads Library default condition variable attributes.

> A condition variable is a synchronization object used with a mutex. A mutex controls access to shared data. When threads are present, a condition variable allows threads to wait for data to enter a defined state.

> For more information about actions taken when threads are present, refer to the `pthread_cond_init()` description.

> Your program can use the macro `PTHREAD_COND_INITIALIZER` to initialize statically allocated condition variables to the default condition variable attributes. Static initialization can be used only for a condition variable with storage class "extern" or "static" --- "automatic" (stack local) objects must be initialized by calling `tis_cond_init()` . Use this macro as follows:
> `pthread_cond_t` condition = `PTHREAD_COND_INITIALIZER` ;

> When statically initialized, a condition variable should not also be initialized using `tis_cond_init()` .

Return Values If there is an error condition, the following occurs:

- The routine returns an integer value indicating the type of error.
- The condition variable is not initialized.
- The contents of condition variable cond are undefined.

The 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 cond is not a valid condition variable.
[ENOMEM] | Insufficient memory to initialize the condition variable.

#### Associated Routines

> `tis_cond_broadcast()`
> `tis_cond_destroy()`
> `tis_cond_signal()`
> `tis_cond_wait()`

## tis_cond_signal

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

### Syntax

> tis_cond_signal(
> cond );

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

C Binding #include <tis.h>

int
tis_cond_signal (
pthread_cond_t *cond);

### Arguments

> #### cond

> Address of the condition variable (passed by reference) on which to signal.

### Description

> When threads are present, this routine unblocks at least one thread that is waiting on the specified condition variable cond. When threads are not present, this routine has no effect.

> For more information about actions taken when threads are present, refer to the `pthread_cond_signal()` description.

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

> `tis_cond_broadcast()`
> `tis_cond_destroy()`
> `tis_cond_init()`
> `tis_cond_wait()`

## tis_cond_timedwait

> Causes a thread to wait for the specified condition variable to be signaled or broadcast, such that it will awake after a specified period of time.

### Syntax

> tis_cond_timedwait(
> cond ,
> mutex ,
> abstime );

> Argument | Data Type | Access
> --- | --- | ---
> cond | opaque pthread_cond_t | modify
> mutex | opaque pthread_mutex_t | modify
> abstime | structure timespec | read

C Binding #include <tis.h>

int
tis_cond_timedwait (
pthread_cond_t *cond,
pthread_mutex_t *mutex,
const struct timespec *abstime);

### Arguments

> #### cond

> Condition variable that the calling thread waits on.

> #### mutex

> Mutex associated with the condition variable specified in cond.

> #### abstime

> Absolute time at which the wait expires, if the condition has not been signaled or broadcast. See the `tis_get_expiration()` routine, which is used to obtain a value for this argument.

> The abstime argument is specified in Universal Coordinated Time (UTC). In the UTC-based model, time is represented as seconds since the Epoch. The Epoch is defined as the time 0 hours, 0 minutes, 0 seconds, January 1st, 1970 UTC.

### Description

> If threads are not present, this function is equivalent to `sleep()` .

> This routine causes a thread to wait until one of the following occurs:

> - The specified condition variable is signaled or broadcast.
> - The current system clock time is greater than or equal to the time specified by the abstime argument.

> This routine is identical to `tis_cond_wait()` , except that this routine can return before a condition variable is signaled or broadcast, specifically, when the specified time expires. For more information, see the `tis_cond_wait()` description.

> This routine atomically releases the mutex and causes the calling thread to wait on the condition. When the thread regains control after calling `tis_cond_timedwait()` , the mutex is locked and the thread is the owner. This is true regardless of why the wait ended. If general cancelability is enabled, the thread reacquires the mutex (blocking for it if necessary) before the cleanup handlers are run (or before the exception is raised).

> If the current time equals or exceeds the expiration time, this routine returns immediately, releasing and reacquiring the mutex. It might cause the calling thread to yield (see the `sched_yield()` description). Your code should check the return status whenever this routine returns and take the appropriate action. Otherwise, waiting on the condition variable can become a nonblocking loop.

> Call this routine after you have locked the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex. The only routines that are supported for use with asynchronous cancelability enabled are those that disable asynchronous cancelability.

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 cond, mutex, or abstime is invalid, or Different mutexes are supplied for concurrent `tis_cond_timedwait()` operations or `tis_cond_wait()` operations on the same condition variable, or The mutex was not owned by the calling thread at the time of the call.
[ETIMEDOUT] | The time specified by abstime expired.
[ENOMEM] | The Threads Library cannot acquire memory needed to block using a statically initialized condition variable.

#### Associated Routines

> `tis_cond_broadcast()`
> `tis_cond_destroy()`
> `tis_cond_init()`
> `tis_cond_signal()`
> `tis_cond_wait()`
> `tis_get_expiration()`

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_026.HTML