source: rtems/doc/posix_users/semaphores.t @ 3d7e9240

4.104.114.84.95
Last change on this file since 3d7e9240 was 3d7e9240, checked in by Joel Sherrill <joel.sherrill@…>, on 10/11/99 at 19:51:56

Now build.

  • Property mode set to 100644
File size: 14.1 KB
Line 
1@c
2@c  COPYRIGHT(c) 1988-1998.
3@c  On-Line Applications Research Corporation(OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Semaphore Manager
10
11@section Introduction
12
13The semaphore manager provides functions to allocate, delete, and control
14semaphores. This manager is based on the POSIX 1003.1 standard.
15
16The directives provided by the semaphore manager are:
17
18@itemize @bullet
19@item @code{sem_init} - Initialize an unnamed semaphore
20@item @code{sem_destroy} - Destroy an unnamed semaphore
21@item @code{sem_open} - Open a named semaphore
22@item @code{sem_close} - Close a named semaphore
23@item @code{sem_unlink} - Remove a named semaphore
24@item @code{sem_wait} - Lock a semaphore
25@item @code{sem_trywait} - Lock a semaphore
26@item @code{sem_post} - Unlock a semaphore
27@item @code{sem_getvalue} - Get the value of a semeaphore
28@end itemize
29
30@section Background
31
32@subsection Theory
33Semaphores are used for synchronization and mutual exclusion by indicating the
34availability and number of resources. The task (the task which is returning
35resources) notifying other tasks of an event increases the number of resources
36held by the semaphore by one. The task (the task which will obtain resources)
37waiting for the event decreases the number of resources held by the semaphore
38by one. If the number of resources held by a semaphore is insufficient (namely
390), the task requiring resources will wait until the next time resources are
40returned to the semaphore. If there is more than one task waiting for a
41semaphore, the tasks will be placed in the queue.
42
43@subsection "sem_t" Structure
44The "sem_t" structure is used to represent semaphores. It is passed as an
45argument to the semaphore directives and is defined as follows:
46
47@example
48  /*
49   * sem_t structure
50   */
51
52  typedef int sem_t
53@end example
54 
55@subsection Building a Semaphore Attribute Set
56
57@section Operations
58
59@subsection Using as a Binary Semaphore
60Although POSIX supports mutexes, they are only visible between threads. To work
61between processes, a binary semaphore must be used.
62 
63Creating a semaphore with a limit on the count of 1 effectively restricts the
64semaphore to being a binary semaphore. When the binary semaphore is available,
65the count is 1. When the binary semaphore is unavailable, the count is 0.
66
67Since this does not result in a true binary semaphore, advanced binary features like the Priority Inheritance and Priority Ceiling Protocols are not available.
68
69There is currently no text in this section.
70
71@section Directives
72
73This section details the semaphore manager's directives.
74A subsection is dedicated to each of this manager's directives
75and describes the calling sequence, related constants, usage,
76and status codes.
77
78@page
79@subsection sem_init - Initialize an unnamed semaphore
80
81@subheading CALLING SEQUENCE:
82
83@ifset is-C
84@example
85int sem_init(
86  sem_t *sem,
87  int pshared,
88  unsigned int value
89);
90@end example
91@end ifset
92
93@ifset is-Ada
94@end ifset
95
96@subheading STATUS CODES:
97
98@table @b
99@item EINVAL
100The value argument exceeds SEM_VALUE_MAX
101
102@item ENOSPC
103A resource required to initialize the semaphore has been exhausted
104The limit on semaphores (SEM_VALUE_MAX) has been reached
105
106@item ENOSYS
107The function sem_init is not supported by this implementation
108
109@item EPERM
110The process lacks appropriate privileges to initialize the semaphore
111
112@end table
113
114@subheading DESCRIPTION:
115The sem_init function is used to initialize the unnamed semaphore referred to
116by "sem". The value of the initialized semaphore is the parameter "value". The
117semaphore remains valid until it is destroyed.
118
119ADD MORE HERE XXX
120
121@subheading NOTES:
122If the functions completes successfully, it shall return a value of zero.
123Otherwise, it shall return a value of -1 and set "errno" to specify the error
124that occurred.
125
126Multiprocessing is currently not supported in this implementation.
127
128@page
129@subsection sem_destroy - Destroy an unnamed semaphore
130
131@subheading CALLING SEQUENCE:
132
133@ifset is-C
134@example
135int sem_destroy(
136  sem_t *sem
137);
138@end example
139@end ifset
140
141@ifset is-Ada
142@end ifset
143
144@subheading STATUS CODES:
145
146@table @b
147@item EINVAL
148The value argument exceeds SEM_VALUE_MAX
149
150@item ENOSYS
151The function sem_init is not supported by this implementation
152
153@item EBUSY
154There are currently processes blocked on the semaphore
155
156@end table
157
158@subheading DESCRIPTION:
159The sem_destroy function is used to destroy an unnamed semaphore refered to by
160"sem". sem_destroy can only be used on a semaphore that was created using
161sem_init.
162
163@subheading NOTES:
164If the functions completes successfully, it shall return a value of zero.
165Otherwise, it shall return a value of -1 and set "errno" to specify the error
166that occurred.
167
168Multiprocessing is currently not supported in this implementation.
169
170
171@page
172@subsection sem_open - Open a named semaphore
173
174@subheading CALLING SEQUENCE:
175
176@ifset is-C
177@example
178int sem_open)
179  const char *name,
180  int oflag
181);
182@end example
183@end ifset
184
185@ifset is-Ada
186@end ifset
187
188@subheading ARGUMENTS:
189
190The following flag bit may be set in oflag:
191
192@code{O_CREAT} - Creates the semaphore if it does not already exist.  If O_CREAT
193is set and the semaphore already exists then O_CREAT has no effect.  Otherwise,
194sem_open() creates a semaphore.  The O_CREAT flag requires the third and fourth
195argument:  mode and value of type mode_t and unsigned int, respectively.
196
197@code{O_EXCL} - If O_EXCL and O_CREAT are set, all call to sem_open() shall fail
198if the semaphore name exists
199
200@subheading STATUS CODES:
201
202@table @b
203@item EACCES
204Valid name specified but oflag permissions are denied,  or the semaphore name
205specified does not exist and permission to create the named semaphore is denied.
206
207@item EEXIST
208O_CREAT and O_EXCL are set and the named semaphore already exists.
209
210@item EINTR
211The sem_open() operation was interrupted  by a signal.
212
213@item EINVAL
214The sem_open() operation is not supported for the given name.
215
216@item EMFILE
217Too many semaphore descriptors or file descriptors in use by this process.
218
219@item ENAMETOOLONG
220The length of the name exceed PATH_MAX or  name component is longer than NAME_MAX
221while POSIX_NO_TRUNC  is in effect.
222
223@item ENOENT
224O_CREAT is not set and the named semaphore does not exist.
225
226@item ENOSPC
227There is insufficient space for the creation of a new named semaphore.
228
229@item ENOSYS
230The function sem_open() is not supported by this implementation.
231
232@end table
233
234@subheading DESCRIPTION:
235The sem_open() function establishes a connection between a specified semaphore and
236a process.  After a call to sem_open with a specified semaphore name, a process
237can reference to semaphore by the associated name using the address returned by
238the call.  The oflag arguments listed above control the state of the semaphore by
239determining if the semaphore is created or accessed by a call to sem_open().
240
241@subheading NOTES:
242
243
244@page
245@subsection sem_close - Close a named semaphore
246
247@subheading CALLING SEQUENCE:
248
249@ifset is-C
250@example
251int sem_close(
252  sem_t *sem_close
253);
254@end example
255@end ifset
256
257@ifset is-Ada
258@end ifset
259
260@subheading STATUS CODES:
261
262@table @b
263@item EACCES
264The semaphore argument is  not a valid semaphore descriptor.
265
266@item ENOSYS
267The function sem_close is not supported by this implementation.
268
269@end table
270
271@subheading DESCRIPTION:
272The sem_close() function is used to indicate that the calling process is finished
273using the named semaphore indicated by sem.  The function sem_close deallocates
274any system resources that were previously allocated by a sem_open system call.  If
275sem_close() completes successfully it returns a 1, otherwise a value of -1 is
276return and errno is set.
277
278@subheading NOTES:
279
280@page
281@subsection sem_unlink - Unlink a semaphore
282
283@subheading CALLING SEQUENCE:
284
285@ifset is-C
286@example
287int sem_unlink(
288  const char *name
289);
290@end example
291@end ifset
292
293@ifset is-Ada
294@end ifset
295
296@subheading STATUS CODES:
297
298@table @b
299@item EACCESS
300Permission is denied to unlink a semaphore.
301
302@item ENAMETOOLONG
303The length of the strong  name exceed NAME_MAX while POSIX_NO_TRUNC is in effect.
304
305@item ENOENT
306The name of the semaphore does not exist.
307
308@item ENOSPC
309There is insufficient space for the creation of a new named semaphore.
310
311@item ENOSYS
312The function sem_unlink is not supported by this implementation.
313
314@end table
315
316@subheading DESCRIPTION:
317The sem_unlink() function shall remove the semaphore name by the string name. If
318a process is currently  accessing the name semaphore, the sem_unlink command has
319no effect. If one or more processes have the semaphore open when the sem_unlink
320function is called, the destruction of semaphores shall be postponed until all
321reference to semaphore are destroyed by calls to sem_close, _exit(), or exec. 
322After all references have been destroyed, it returns immediately. 
323
324If the termination is successful, the function shall return 0.  Otherwise, a -1
325is returned and the errno is set.
326
327@subheading NOTES:
328
329@page
330@subsection sem_wait - Wait on a Semaphore
331
332@subheading CALLING SEQUENCE:
333
334@ifset is-C
335@example
336int sem_wait(
337  sem_t *sem
338);
339@end example
340@end ifset
341
342@ifset is-Ada
343@end ifset
344
345@subheading STATUS CODES:
346
347@table @b
348@item EINVAL
349The "sem" argument does not refer to a valid semaphore
350
351@end table
352
353@subheading DESCRIPTION:
354This function attempts to lock a semaphore specified by @code{sem}.  If the
355semaphore is available, then the semaphore is locked (i.e., the semaphore
356value is decremented).  If the semaphore is unavailable (i.e., the semaphore
357value is zero), then the function will block until the semaphore becomes
358available.  It will then successfully lock the semaphore.  The semaphore
359remains locked until released by a @code{sem_post()} call.
360
361If the call is unsuccessful, then the function returns -1 and sets errno to the
362appropriate error code.
363
364@subheading NOTES:
365Multiprocessing is not supported in this implementation.
366
367@page
368@subsection sem_trywait - Non-blocking Wait on a Semaphore
369
370@subheading CALLING SEQUENCE:
371
372@ifset is-C
373@example
374int sem_trywait(
375  sem_t *sem
376);
377@end example
378@end ifset
379
380@ifset is-Ada
381@end ifset
382
383@subheading STATUS CODES:
384
385@table @b
386@item EAGAIN
387The semaphore is not available (i.e., the semaphore value is zero), so the
388semaphore could not be locked.
389
390@item EINVAL
391The @code{sem} argument does not refewr to a valid semaphore
392
393@end table
394
395@subheading DESCRIPTION:
396This function attempts to lock a semaphore specified by @code{sem}.  If the
397semaphore is available, then the semaphore is locked (i.e., the semaphore
398value is decremented) and the function returns a value of 0.  The semaphore
399remains locked until released by a @code{sem_post()} call.  If the semaphore
400is unavailable (i.e., the semaphore value is zero), then the function will
401return a value of -1 immediately and set @code{errno} to EAGAIN.
402
403If the call is unsuccessful, then the function returns -1 and sets
404@code{errno} to the appropriate error code.
405
406@subheading NOTES:
407Multiprocessing is not supported in this implementation.
408
409@page
410@subsection sem_timedwait - Wait on a Semaphore for a Specified Time
411
412@subheading CALLING SEQUENCE:
413
414@ifset is-C
415@example
416int sem_timedwait(
417  sem_t *sem,
418  const struct timespec *timeout
419);
420@end example
421@end ifset
422
423@ifset is-Ada
424@end ifset
425
426@subheading STATUS CODES:
427
428@table @b
429@item EAGAIN
430The semaphore is not available (i.e., the semaphore value is zero), so the
431semaphore could not be locked.
432
433@item EINVAL
434The @code{sem} argument does not refewr to a valid semaphore
435
436@end table
437
438@subheading DESCRIPTION:
439This function attemtps to lock a semaphore specified by @code{sem}, and will
440wait for the semaphore for an interval specified by @code{timeout}.  If the
441semaphore is available, then the semaphore is locked (i.e., the semaphore
442value is decremented) and the function returns a value of 0.  The semaphore
443remains locked until released by a @code{sem_post()} call.  If the semaphore
444is unavailable, then the function will wait for the semaphore to become
445available for the amount of time specified by @code{timeout}.
446
447If the semaphore does not become available within the interval specified by
448@code{timeout}, then the function returns -1 and sets @code{errno} to EAGAIN.
449If any other error occurs, the function returns -1 and sets @code{errno} to
450the appropriate error code.
451
452@subheading NOTES:
453Multiprocessing is not supported in this implementation.
454
455@page
456@subsection sem_post - Unlock a Semaphore
457
458@subheading CALLING SEQUENCE:
459
460@ifset is-C
461@example
462int sem_post(
463  sem_t *sem
464);
465@end example
466@end ifset
467
468@ifset is-Ada
469@end ifset
470
471@subheading STATUS CODES:
472
473@table @b
474@item EINVAL
475The @code{sem} argument does not refer to a valid semaphore
476
477@end table
478
479@subheading DESCRIPTION:
480This function attempts to release the semaphore specified by @code{sem}.  If
481other tasks are waiting on the semaphore, then one of those tasks (which one
482depends on the scheduler being used) is allowed to lock the semaphore and
483return from its @code{sem_wait()}, @code{sem_trywait()}, or
484@code{sem_timedwait()} call.  If there are no other tasks waiting on the
485semaphore, then the semaphore value is simply incremented.  @code{sem_post()}
486returns 0 upon successful completion.
487
488If an error occurs, the function returns -1 and sets @code{errno} to the
489appropriate error code.
490
491@subheading NOTES:
492Multiprocessing is not supported in this implementation.
493
494@page
495@subsection sem_getvalue - Get the value of a semaphore
496
497@subheading CALLING SEQUENCE:
498
499@ifset is-C
500@example
501int sem_getvalue(
502  sem_t *sem,
503  int *sval
504);
505@end example
506@end ifset
507
508@ifset is-Ada
509@end ifset
510
511@subheading STATUS CODES:
512
513@table @b
514@item EINVAL
515The "sem" argument does not refer to a valid semaphore
516
517@item ENOSYS
518The function sem_getvalue is not supported by this implementation
519
520@end table
521
522@subheading DESCRIPTION:
523The sem_getvalue functions sets the location referenced by the "sval" argument
524to the value of the semaphore without affecting the state of the semaphore. The
525updated value represents a semaphore value that occurred at some point during
526the call, but is not necessarily the actual value of the semaphore when it
527returns to the calling process.
528 
529If "sem" is locked, the value returned by sem_getvalue will be zero or a
530negative number whose absolute value is the number of processes waiting for the
531semaphore at some point during the call.
532
533@subheading NOTES:
534If the functions completes successfully, it shall return a value of zero.
535Otherwise, it shall return a value of -1 and set "errno" to specify the error
536that occurred.
Note: See TracBrowser for help on using the repository browser.