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

NAME

6       semaphore,  sema_init, sema_destroy, sema_wait, sema_trywait, sema_post
7       - semaphores
8

SYNOPSIS

10       cc [ flag... ] file... -lthread  -lc [ library... ]
11       #include <synch.h>
12
13       int sema_init(sema_t *sp, unsigned int count, int type,
14            void * arg);
15
16
17       int sema_destroy(sema_t *sp);
18
19
20       int sema_wait(sema_t *sp);
21
22
23       int sema_trywait(sema_t *sp);
24
25
26       int sema_post(sema_t *sp);
27
28

DESCRIPTION

30       A semaphore is a non-negative integer count and is  generally  used  to
31       coordinate  access  to resources. The initial semaphore count is set to
32       the number of free resources, then threads slowly increment and  decre‐
33       ment  the  count  as resources  are added and removed. If the semaphore
34       count drops to 0, which means no available resources,  threads attempt‐
35       ing  to  decrement  the semaphore will block until the count is greater
36       than 0.
37
38
39       Semaphores can synchronize threads in this process and other  processes
40       if  they are allocated in writable memory  and shared among the cooper‐
41       ating processes (see mmap(2)), and have been initialized for this  pur‐
42       pose.
43
44
45       Semaphores  must be initialized before use; semaphores pointed to by sp
46       to count are initialized by sema_init(). The type argument  can  assign
47       several  different  types  of  behavior to a semaphore. No current type
48       uses arg, although it may be used in the future.
49
50
51       The type argument may be one of the following:
52
53       USYNC_PROCESS     The semaphore can synchronize threads in this process
54                         and   other  processes.  Initializing  the  semaphore
55                         should be done by only one process. A semaphore  ini‐
56                         tialized  with  this type must be allocated in memory
57                         shared between processes, either in Sys V shared mem‐
58                         ory  (see  shmop(2)),  or  in memory mapped to a file
59                         (see mmap(2)). It is illegal to initialize the object
60                         this  way  and not allocate it in such shared memory.
61                         arg is ignored.
62
63
64       USYNC_THREAD      The semaphore can synchronize  threads only  in  this
65                         process.  The  arg  argument is ignored. USYNC_THREAD
66                         does not support multiple mappings to the same  logi‐
67                         cal  synch  object.  If  you  need  to mmap() a synch
68                         object to different locations within the same address
69                         space, then the synch object should be initialized as
70                         a shared object USYNC_PROCESS for Solaris threads and
71                         PTHREAD_PROCESS_PRIVATE for POSIX threads.
72
73
74
75       A semaphore must not be simultaneously initialized by multiple threads,
76       nor re-initialized while in use by other threads.
77
78
79       Default semaphore initialization (intra-process):
80
81         sema_t sp;
82         int count  =  1;
83         sema_init(&sp, count, NULL, NULL);
84
85
86
87       or
88
89         sema_init(&sp, count, USYNC_THREAD, NULL);
90
91
92
93       Customized semaphore initialization (inter-process):
94
95         sema_t sp;
96         int count  =  1;
97         sema_init(&sp, count, USYNC_PROCESS, NULL);
98
99
100
101       The sema_destroy() function destroys any state related to the semaphore
102       pointed to by sp. The semaphore storage space is not released.
103
104
105       The  sema_wait() function blocks the calling thread until the semaphore
106       count pointed to by sp is greater than 0, and then it atomically decre‐
107       ments the count.
108
109
110       The  sema_trywait()  function atomically decrements the semaphore count
111       pointed to by sp, if the count is greater than 0; otherwise, it returns
112       an error.
113
114
115       The  sema_post()  function  atomically  increments  the semaphore count
116       pointed to by sp. If there are any threads blocked  on  the  semaphore,
117       one will be unblocked.
118
119
120       The  semaphore  functionality  described  on  this  man page is for the
121       Solaris threads implementation.   For  the  POSIX-conforming  semaphore
122       interface  documentation,  see sem_close(3C), sem_destroy(3C), sem_get‐
123       value(3C), sem_init(3C),  sem_open(3C),  sem_post(3C),  sem_unlink(3C),
124       and sem_wait(3C).
125

RETURN VALUES

127       Upon successful completion,  0 is returned; otherwise, a non-zero value
128       indicates an error.
129

ERRORS

131       These functions will fail if:
132
133       EINVAL     The sp argument does not refer to a valid semaphore.
134
135
136       EFAULT     Either the sp or arg argument points to an illegal address.
137
138
139
140       The sema_wait() function will fail if:
141
142       EINTR     The wait was interrupted by a signal or fork().
143
144
145
146       The sema_trywait() function will fail if:
147
148       EBUSY     The semaphore pointed to by sp has a 0 count.
149
150
151
152       The sema_post() function will fail if:
153
154       EOVERFLOW     The  semaphore   value   pointed   to   by   sp   exceeds
155                     SEM_VALUE_MAX.
156
157

EXAMPLES

159       Example 1 The customer waiting-line in a bank is analogous to the  syn‐
160       chronization scheme of a  semaphore  using  sema_wait()  and  sema_try‐
161       wait():
162
163         /* cc [ flag ... ] file ... -lthread [ library ... ] */
164         #include <errno.h>
165         #define TELLERS 10
166         sema_t     tellers;     /* semaphore */
167         int banking_hours(), deposit_withdrawal;
168         void*customer(), do_business(), skip_banking_today();
169         ...
170
171         sema_init(&tellers, TELLERS, USYNC_THREAD, NULL);
172             /* 10 tellers available */
173         while(banking_hours())
174             pthread_create(NULL, NULL, customer, deposit_withdrawal);
175         ...
176
177         void *
178         customer(int deposit_withdrawal)
179         {
180              int this_customer, in_a_hurry = 50;
181              this_customer = rand() % 100;
182
183              if (this_customer == in_a_hurry)  {
184                  if (sema_trywait(&tellers) != 0)
185                      if (errno == EBUSY){ /* no teller available */
186                           skip_banking_today(this_customer);
187                           return;
188                  } /* else go immediately to available teller and
189                                         decrement tellers */
190               }
191               else
192                  sema_wait(&tellers); /* wait for next teller, then
193                                         proceed, and decrement tellers */
194
195               do_business(deposit_withdrawal);
196               sema_post(&tellers); /* increment tellers; this_customer's
197                                       teller is now available */
198         }
199
200

ATTRIBUTES

202       See attributes(5) for descriptions of the following attributes:
203
204
205
206
207       ┌─────────────────────────────┬─────────────────────────────┐
208       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
209       ├─────────────────────────────┼─────────────────────────────┤
210       │MT-Level                     │Async-Signal-Safe            │
211       └─────────────────────────────┴─────────────────────────────┘
212

SEE ALSO

214       mmap(2),  shmop(2),  sem_close(3C),  sem_destroy(3C), sem_getvalue(3C),
215       sem_init(3C), sem_open(3C), sem_post(3C), sem_unlink(3C), sem_wait(3C),
216       attributes(5), standards(5)
217

NOTES

219       These functions are also available by way of:
220
221         #include <thread.h>
222
223
224
225       By  default,  there  is  no  defined  order  of unblocking for multiple
226       threads waiting for a semaphore.
227
228
229
230SunOS 5.11                        5 Feb 2008                     semaphore(3C)
Impressum