Tribblix: manual page: sem

SEM_TIMEDWAIT(3C) Standard C Library Functions SEM_TIMEDWAIT(3C)

NAME

sem_clockwait, sem_timedwait, sem_relclockwait_np, sem_reltimedwait_np
- lock a semaphore with timeout

SYNOPSIS

#include <sempahore.h>
#include <time.h>

int
sem_clockwait(sem_t *restrict sem, clockid_t clock,
const struct timespec *abstime);

int
sem_timedwait(sem_t *restrict sem, const struct timespec *abstime);

int
sem_relclockwait_np(sem_t *restrict sem, clockid_t clock,
const struct timespec *reltime);

int
sem_reltimedwait_np(sem_t *restrict sem,
const struct timespec *reltime);

DESCRIPTION

The sem_clockwait(), sem_timedwait(), sem_relclockwait_np(), and
sem_reltimewait_np() functions lock the sempahore referenced by sem as
in the sem_wait(3C) function. If the semaphore is locked, the calling
thread will block until it becomes available by another process or
thread unlocking the semaphore by calling sem_post(3C). However, if
the semaphore does not become available within a specified timeout,
then the function call will terminate without acquiring the semaphore
and return the ETIMEDOUT error. These functions all differ in terms of
how the timeout is specified and the clock that is used to determine
when the timeout has elapsed.

In general, the system provides the ability to program timeouts against
either the realtime clock, CLOCK_REALTIME, which measures the wall
clock and is subject to changes due to time synchronization daemons
such as NTP and PTP, or the high-resolution clock, CLOCK_HIGHRES, which
is a non-adjustable high-resolution clock that is provided by system
hardware. The specified timeout may either be specified as an absolute
time in the future or as a relative amount of time that should elapse.
Each clock has its own resolution, which can be determined by
clock_getres(3C). Timeouts may be rounded up to a given clock's
resolution. Due to scheduling effects, it is possible that more time
may elapse than was specified in the timeout when the caller does not
successfully acquire the lock.

The sem_clockwait() and sem_relclocklock_np() functions allow the clock
source to be used to be specified by the clock argument. While there
are additional clocks in the system, only CLOCK_REALTIME or
CLOCK_HIGHRES may be specified. The thread and process-specific CPU
time clocks cannot be used. Conversely, the sem_timedwait() and
sem_reltimedwait_np() functions will always utilize the realtime clock,
CLOCK_REALTIME.

The sem_clockwait() and sem_timedwait() functions treat the timeout
value, abstime, as the absolute time in the future when the timeout
should expire. Conversely, the and sem_reltimedwait_np() functions
operate in terms of a relative time. The timer will expire when a
specified amount of time passes on the clock specified as indicated by
reltime.

If the semaphore, sem, can be immediately locked, then the timeout
value is ignored entirely, even if the timeout had already expired or
represented a value that didn't make sense. Both are only checked if
the thread would block on the semaphore itself.

RETURN VALUES

Upon successful completion, the sem_clockwait(), sem_timedwait(),
sem_relclockwait_np(), and sem_reltimewait_np() functions return 0 and
the thread will have successfully locked the semaphore. Otherwise -1
is returned and errno is set to indicate the error.

ERRORS

The sem_clockwait(), sem_timedwait(), sem_relclockwait_np(), and
sem_reltimewait_np() functions will fail if:

EINVAL The sem argument does not refer to a valid semaphore
or the process or thread would have blocked, and the
timeout parameter specified a nanoseconds field
value less than zero or greater than or equal to
1,000 million.

For sem_clockwait() or sem_relclockwait_np() the
value of clock is either unsupported for locking or
unknown to the system.

EDEADLK A deadlock condition was detected.

EINTR A signal interrupted this function.

ETIMEDOUT The semaphore could not be locked before the
specified timeout expired.

INTERFACE STABILITY