source: rtems/doc/posix_users/semaphores.t @ d2bfbaf

4.104.114.84.95
Last change on this file since d2bfbaf was d2bfbaf, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 16, 1999 at 9:56:45 PM

Fixed spacing.

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