NAME

SYNOPSIS

DESCRIPTION

The
sem_wait()
function locks the semaphore referenced by
sem
by performing a semaphore lock operation
on that semaphore.
If the semaphore value is currently zero,
then the calling thread
will not return from the call to
sem_wait()
until it either locks the semaphore or the call is interrupted by a signal.
The
sem_trywait()
function locks the semaphore referenced by
sem
only if the semaphore is currently not locked;
that is, if the semaphore value is currently positive.
Otherwise, it does not lock the semaphore.

Upon successful return, the state of the semaphore is
locked and remains locked until the
sem_post()
function is executed and returns successfully.

The
sem_wait()
function is interruptible by the delivery of a signal.

RETURN VALUE

The
sem_wait()
and
sem_trywait()
functions return zero if
the calling process successfully performed the
semaphore lock operation
on the semaphore designated by
sem.
If the call was unsuccessful,
the state of the semaphore is unchanged, and
the function returns a value of -1 and sets
errno
to indicate the error.

ERRORS

The
sem_wait()
and
sem_trywait()
functions will fail if:

[EAGAIN]

The semaphore was already locked,
so it cannot be immediately locked by the
sem_trywait()
operation (
sem_trywait
only).

[EINVAL]

The
sem
argument does not refer to a valid semaphore.

[ENOSYS]

The functions
sem_wait()
and
sem_trywait()
are not supported by this implementation.

The
sem_wait()
and
sem_trywait()
functions may fail if:

[EDEADLK]

A deadlock condition was detected.

[EINTR]

A signal interrupted this function.

EXAMPLES

None.

APPLICATION USAGE

Realtime applications may encounter priority inversion when using
semaphores.
The problem occurs when a high priority thread "locks" (that is,
waits on) a semaphore that is about to be "unlocked" (that is, posted)
by a low priority thread, but the low priority thread is preempted by a medium
priority thread.
This scenario leads to priority inversion; a high priority thread is
blocked by lower priority threads for an unlimited period of time.
During system design, realtime programmers must take into account the
possibility of this kind of priority inversion.
They can deal with it in a number of ways, such as by having critical
sections that are guarded by semaphores execute at a high
priority, so that a thread cannot be preempted while executing in its
critical section.