SEM_WAIT(3C) Standard C Library Functions SEM_WAIT(3C)
NAME
sem_wait, sem_trywait - acquire or wait for a semaphore
SYNOPSIS
#include <semaphore.h>
int sem_wait(
sem_t *sem);
int sem_trywait(
sem_t *sem);
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(3C) function is executed and returns
successfully.
The
sem_wait() function is interruptible by the delivery of a signal.
RETURN VALUES
The
sem_wait() and
sem_trywait() functions return
0 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
-1 and sets
errno to
indicate the error.
ERRORS
The
sem_wait() and
sem_trywait() functions will fail if:
EINVAL The
sem function does not refer to a valid semaphore.
ENOSYS The
sem_wait() and
sem_trywait() functions are not supported
by the system.
The
sem_trywait() function will fail if:
EAGAIN The semaphore was already locked, so it cannot be immediately
locked by the
sem_trywait() operation.
The
sem_wait() and
sem_trywait() functions may fail if:
EDEADLK A deadlock condition was detected; that is, two separate
processes are waiting for an available resource to be
released via a semaphore "held" by the other process.
EINTR A signal interrupted this function.
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.
EXAMPLES
Example 1: The customer waiting-line in a bank may be analogous to the
synchronization scheme of a semaphore utilizing
sem_wait() and
sem_trywait():
#include <errno.h>
#define TELLERS 10
sem_t bank_line; /* semaphore */
int banking_hours(), deposit_withdrawal;
void *customer(), do_business(), skip_banking_today();
thread_t tid;
...
sem_init(&bank_line,TRUE,TELLERS); /* 10 tellers
available */
while(banking_hours())
thr_create(NULL, NULL, customer,
(void *)deposit_withdrawal, THREAD_NEW_LWP, &tid);
...
void *
customer(deposit_withdrawal)
void *deposit_withdrawal;
{
int this_customer, in_a_hurry = 50;
this_customer = rand() % 100;
if (this_customer == in_a_hurry) {
if (sem_trywait(&bank_line) != 0)
if (errno == EAGAIN) { /* no teller available */
skip_banking_today(this_customer);
return;
} /*else go immediately to available teller
& decrement bank_line*/
}
else
sem_wait(&bank_line); /* wait for next teller,
then proceed, and decrement bank_line */
do_business((int *)deposit_withdrawal);
sem_getvalue(&bank_line,&num_tellers);
sem_post(&bank_line); /* increment bank_line;
this_customer's teller is now available */
}
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-------------------+
|Interface Stability | Committed |
+--------------------+-------------------+
|MT-Level | MT-Safe |
+--------------------+-------------------+
|Standard | See
standards(7). |
+--------------------+-------------------+
SEE ALSO
sem_post(3C),
attributes(7),
standards(7) February 5, 2008
SEM_WAIT(3C)