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

4.104.114.84.95
Last change on this file since e73014b was e73014b, checked in by Joel Sherrill <joel.sherrill@…>, on 11/23/99 at 19:39:19

Added sem_timedwait to bullet list at front of chapter.

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