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

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

#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);

The (), (), (), and () 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 () and () 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 () and () functions treat the timeout value, abstime, as the absolute time in the future when the timeout should expire. Conversely, the and () 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.

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

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

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.

A deadlock condition was detected.
A signal interrupted this function.
The semaphore could not be locked before the specified timeout expired.

semctl(2), semget(2), semop(2), time(2), clock_getres(3C), sem_post(3C), sem_trywait(3C), sem_wait(3C), attributes(7), standards(7)

June 23, 2024 OmniOS