source: rtems/doc/posix_users/semaphores.t @ 9b4f75e

Last change on this file since 9b4f75e was 9b4f75e, checked in by Joel Sherrill <joel.sherrill@…>, on Jul 24, 2008 at 8:44:47 PM

2008-07-24 Joel Sherrill <joel.sherrill@…>

PR 1291/cpukit

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