sem_wait(3c)

1sem_wait(3C)             Standard C Library Functions             sem_wait(3C)
2
3
4

NAME

6       sem_wait, sem_trywait - acquire or wait for a semaphore
7

SYNOPSIS

9       #include <semaphore.h>
10
11       int sem_wait(sem_t *sem);
12
13
14       int sem_trywait(sem_t *sem);
15
16

DESCRIPTION

18       The  sem_wait()  function locks the semaphore referenced by sem by per‐
19       forming a semaphore lock operation on that semaphore. If the  semaphore
20       value  is currently zero, then the calling thread  will not return from
21       the call to sem_wait() until it either locks the semaphore or the  call
22       is  interrupted by a signal. The sem_trywait() function locks the sema‐
23       phore referenced by sem only if the semaphore is currently not  locked;
24       that  is,  if  the semaphore value is currently positive. Otherwise, it
25       does not lock the semaphore.
26
27
28       Upon successful return, the  state  of  the  semaphore  is  locked  and
29       remains  locked until the sem_post(3C) function is executed and returns
30       successfully.
31
32
33       The sem_wait() function is interruptible by the delivery of a signal.
34

RETURN VALUES

36       The sem_wait() and sem_trywait() functions return   0  if  the  calling
37       process successfully performed the semaphore lock operation on the sem‐
38       aphore designated by sem. If the call was unsuccessful,  the  state  of
39       the  semaphore is unchanged, and the function returns −1 and sets errno
40       to indicate the error.
41

ERRORS

43       The  sem_wait() and sem_trywait() functions will fail if:
44
45       EINVAL     The sem function does not refer to a valid semaphore.
46
47
48       ENOSYS     The sem_wait() and sem_trywait() functions are not supported
49                  by the system.
50
51
52
53       The  sem_trywait() function will fail if:
54
55       EAGAIN     The  semaphore  was  already locked, so it cannot be immedi‐
56                  ately locked by the sem_trywait() operation.
57
58
59
60       The  sem_wait() and sem_trywait() functions may fail if:
61
62       EDEADLK     A deadlock condition was detected; that  is,  two  separate
63                   processes  are  waiting  for  an  available  resource to be
64                   released via a semaphore "held" by the other process.
65
66
67       EINTR       A signal interrupted this function.
68
69

USAGE

71       Realtime applications may encounter priority inversion when using sema‐
72       phores.  The  problem  occurs when a high priority thread "locks" (that
73       is, waits on) a semaphore that is about  to  be  "unlocked"  (that  is,
74       posted)  by  a low priority thread, but the low priority thread is pre‐
75       empted by a medium priority thread. This  scenario  leads  to  priority
76       inversion;  a high priority thread is blocked by lower priority threads
77       for an unlimited period of time. During system  design,  realtime  pro‐
78       grammers  must take into account the possibility of this kind of prior‐
79       ity inversion. They can deal with it in a number of ways,  such  as  by
80       having  critical  sections  that are guarded by semaphores execute at a
81       high priority, so that a thread cannot be preempted while executing  in
82       its critical section.
83

EXAMPLES

85       Example  1  The customer waiting-line in a bank may be analogous to the
86       synchronization scheme of a semaphore utilizing sem_wait() and sem_try‐
87       wait():
88
89         #include <errno.h>
90         #define TELLERS 10
91         sem_t  bank_line;      /* semaphore */
92         int banking_hours(), deposit_withdrawal;
93         void *customer(), do_business(), skip_banking_today();
94         thread_t tid;
95         ...
96
97         sem_init(&bank_line,TRUE,TELLERS);  /* 10 tellers
98                                                available */
99         while(banking_hours())
100                 thr_create(NULL, NULL, customer,
101                     (void *)deposit_withdrawal, THREAD_NEW_LWP, &tid);
102         ...
103
104         void *
105         customer(deposit_withdrawal)
106         void *deposit_withdrawal;
107         {
108             int this_customer, in_a_hurry = 50;
109             this_customer = rand() % 100;
110             if (this_customer == in_a_hurry)  {
111                 if (sem_trywait(&bank_line) != 0)
112                 if (errno == EAGAIN) {    /* no teller available */
113                     skip_banking_today(this_customer);
114                     return;
115                 }     /*else go immediately to available teller
116                        & decrement bank_line*/
117             }
118             else
119                 sem_wait(&bank_line); /* wait for next teller,
120                      then proceed, and decrement bank_line */
121             do_business((int *)deposit_withdrawal);
122             sem_getvalue(&bank_line,&num_tellers);
123             sem_post(&bank_line); /* increment bank_line;
124                 this_customer's teller is now available */
125         }
126
127

ATTRIBUTES

129       See attributes(5) for descriptions of the following attributes:
130
131
132
133
134       ┌─────────────────────────────┬─────────────────────────────┐
135       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
136       ├─────────────────────────────┼─────────────────────────────┤
137       │Interface Stability          │Committed                    │
138       ├─────────────────────────────┼─────────────────────────────┤
139       │MT-Level                     │MT-Safe                      │
140       ├─────────────────────────────┼─────────────────────────────┤
141       │Standard                     │See standards(5).            │
142       └─────────────────────────────┴─────────────────────────────┘
143