_lwp_cond_timedwait(2)
_lwp_cond_timedwait --
wait on a condition variable for a limited time
Synopsis
#include <synch.h>
#include <sys/time.h>
int _lwp_cond_timedwait(lwp_cond_t *cond, lwp_mutex_t *mutex,
timestruc_t *abstime);
Parameters
cond-
pointer to the condition variable to wait for
mutex-
pointer to a locked mutex
abstime-
absolute time at which to time out
Description
_lwp_cond_timedwait,
similar to _lwp_cond_wait,
waits for the occurrence of a condition associated with the given
object cond.
However, if the absolute time specified by abstime has passed,
and the indicated condition is not signaled,
the operation returns ETIME to the caller.
The calling lightweight process (LWP) must lock
the mutual exclusion lock (mutex) pointed to by mutex
before calling cond_timedwait,
otherwise the behavior is unpredictable.
_lwp_timedwait automatically releases the mutex before blocking on
the condition variable.
When the condition is signalled, the time expires or the wait is interrupted,
_lwp_cond_timedwait
reacquires the mutex and returns to the caller.
If the wait is interrupted,
The mutex is reacquired before a signal handler or any other user code
can be executed.
A wait on _lwp_cond_timedwait is interruptible.
If _lwp_cond_timedwait is interrupted the function always fails.
The calling LWP is allowed to resume execution when
the condition is signaled or broadcast, timeout occurs, or when interrupted.
User-visible timers are not affected by a call to _lwp_cond_timedwait.
cond parameter
The condition variable denoted by cond
must previously have been statically initialized (zero-filled).
mutex parameter
mutex is a mutual exclusion variable
protecting a shared resource associated with the condition
represented by the condition variable, cond.
The calling LWP must lock mutex
before calling _lwp_cond_timedwait,
otherwise the behavior is unpredictable.
abstime parameter
abstime represents the time at which _lwp_cond_timedwait
should time out.
The time is expressed in elapsed seconds and nanoseconds since
Universal Coordinated Time, January 1, 1970.
gettimeofday(2)
returns the current time,
but in seconds and microseconds.
To construct abstime,
convert the current time to a timestruc_t,
and add to that the waiting time.
Return values
_lwp_cond_timedwait returns zero on success or an error number on
failure, as described below.
Errors
If any of the following conditions is detected,
_lwp_cond_timedwait fails and returns the corresponding value:
EINVAL-
The condition variable pointed to by cond
or the mutex pointed to by mutex is invalid.
EINVAL-
abstime is NULL.
EFAULT-
Either cond, mutex, or abstime
points to an illegal address.
(This error may not be detected; a SIGSEGV signal may be posted to the
faulting LWP if an illegal address is used.)
If any of the following conditions occurs,
_lwp_cond_timedwait fails and returns the corresponding value:
ETIME-
Time specified by abstime has passed.
EINTR-
The operation was interrupted by a signal or a fork operation.
Usage
See the description of how to use condition variables
under USAGE on
cond_init(3synch).
Because the condition can change between the time the
condition is signaled and the mutex is re-locked,
the calling LWP must always re-check the condition upon return
from _lwp_cond_timedwait.
References
_lwp_cond_broadcast(2),
_lwp_cond_signal(2),
_lwp_cond_wait(2),
cond_broadcast(3synch),
cond_destroy(3synch),
cond_init(3synch),
cond_signal(3synch),
cond_timedwait(3synch),
cond_wait(3synch)
Notices
Lightweight processes (LWPs) are internal interfaces and are subject
to change. Their use should be avoided.
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004