]>
Commit | Line | Data |
---|---|---|
2c731798 | 1 | '\" t |
c11b1abf | 2 | .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
2c731798 | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
2c731798 MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
2c731798 MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
10d76543 MK |
17 | .\" the use of the information contained herein. The author(s) may not |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
2c731798 MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
2c731798 | 25 | .\" |
460495ca | 26 | .TH SEM_OVERVIEW 7 2015-08-08 "Linux" "Linux Programmer's Manual" |
2c731798 | 27 | .SH NAME |
f68512e9 | 28 | sem_overview \- overview of POSIX semaphores |
2c731798 | 29 | .SH DESCRIPTION |
d9bfdb9c | 30 | POSIX semaphores allow processes and threads to synchronize their actions. |
2c731798 MK |
31 | |
32 | A semaphore is an integer whose value is never allowed to fall below zero. | |
c13182ef MK |
33 | Two operations can be performed on semaphores: |
34 | increment the semaphore value by one | |
2c731798 MK |
35 | .RB ( sem_post (3)); |
36 | and decrement the semaphore value by one | |
37 | .RB ( sem_wait (3)). | |
c13182ef | 38 | If the value of a semaphore is currently zero, then a |
2c731798 MK |
39 | .BR sem_wait (3) |
40 | operation will block until the value becomes greater than zero. | |
41 | ||
c13182ef | 42 | POSIX semaphores come in two forms: named semaphores and |
2c731798 | 43 | unnamed semaphores. |
9bfe1b39 MK |
44 | .TP |
45 | .B Named semaphores | |
c13182ef | 46 | A named semaphore is identified by a name of the form |
e2cbd475 MK |
47 | .IR /somename ; |
48 | that is, a null-terminated string of up to | |
13e0f2a9 MK |
49 | .BI NAME_MAX \-4 |
50 | (i.e., 251) characters consisting of an initial slash, | |
e2cbd475 MK |
51 | .\" glibc allows the initial slash to be omitted, and makes |
52 | .\" multiple initial slashes equivalent to a single slash. | |
53 | .\" This differs from the implementation of POSIX message queues. | |
54 | followed by one or more characters, none of which are slashes. | |
55 | .\" glibc allows subdirectory components in the name, in which | |
56 | .\" case the subdirectory tree must exist under /dev/shm, and | |
57 | .\" the fist subdirectory component must exist as the name | |
58 | .\" sem.name, and all of the subdirectory components must allow the | |
59 | .\" required permissions if a user wants to create a semaphore | |
60 | .\" object in a subdirectory. | |
c13182ef | 61 | Two processes can operate on the same named semaphore by passing |
2c731798 MK |
62 | the same name to |
63 | .BR sem_open (3). | |
64 | ||
c13182ef | 65 | The |
2c731798 | 66 | .BR sem_open (3) |
c13182ef | 67 | function creates a new named semaphore or opens an existing |
2c731798 MK |
68 | named semaphore. |
69 | After the semaphore has been opened, it can be operated on using | |
70 | .BR sem_post (3) | |
71 | and | |
72 | .BR sem_wait (3). | |
73 | When a process has finished using the semaphore, it can use | |
74 | .BR sem_close (3) | |
75 | to close the semaphore. | |
c13182ef | 76 | When all processes have finished using the semaphore, |
2c731798 MK |
77 | it can be removed from the system using |
78 | .BR sem_unlink (3). | |
9bfe1b39 MK |
79 | .TP |
80 | .B Unnamed semaphores (memory-based semaphores) | |
2c731798 MK |
81 | An unnamed semaphore does not have a name. |
82 | Instead the semaphore is placed in a region of memory that | |
c13182ef | 83 | is shared between multiple threads (a |
2c731798 | 84 | .IR "thread-shared semaphore" ) |
c13182ef | 85 | or processes (a |
2c731798 | 86 | .IR "process-shared semaphore" ). |
c13182ef | 87 | A thread-shared semaphore is placed in an area of memory shared |
37cdfc43 | 88 | between the threads of a process, for example, a global variable. |
c13182ef MK |
89 | A process-shared semaphore must be placed in a shared memory region |
90 | (e.g., a System V shared memory segment created using | |
179343f9 | 91 | .BR shmget (2), |
2c731798 MK |
92 | or a POSIX shared memory object built created using |
93 | .BR shm_open (3)). | |
94 | ||
d9bfdb9c | 95 | Before being used, an unnamed semaphore must be initialized using |
2c731798 MK |
96 | .BR sem_init (3). |
97 | It can then be operated on using | |
98 | .BR sem_post (3) | |
99 | and | |
100 | .BR sem_wait (3). | |
101 | When the semaphore is no longer required, | |
102 | and before the memory in which it is located is deallocated, | |
103 | the semaphore should be destroyed using | |
104 | .BR sem_destroy (3). | |
9bfe1b39 MK |
105 | .PP |
106 | The remainder of this section describes some specific details | |
107 | of the Linux implementation of POSIX semaphores. | |
2c731798 | 108 | .SS Versions |
33a0ccb2 | 109 | Prior to kernel 2.6, Linux supported only unnamed, |
2c731798 | 110 | thread-shared semaphores. |
c13182ef | 111 | On a system with Linux 2.6 and a glibc that provides the NPTL |
2c731798 MK |
112 | threading implementation, |
113 | a complete implementation of POSIX semaphores is provided. | |
114 | .SS Persistence | |
115 | POSIX named semaphores have kernel persistence: | |
116 | if not removed by | |
63f6a20a | 117 | .BR sem_unlink (3), |
2c731798 MK |
118 | a semaphore will exist until the system is shut down. |
119 | .SS Linking | |
120 | Programs using the POSIX semaphores API must be compiled with | |
2c5f8c8c | 121 | .I cc \-pthread |
2c731798 MK |
122 | to link against the real-time library, |
123 | .IR librt . | |
9ee4a2b6 MK |
124 | .SS Accessing named semaphores via the filesystem |
125 | On Linux, named semaphores are created in a virtual filesystem, | |
2c731798 MK |
126 | normally mounted under |
127 | .IR /dev/shm , | |
c13182ef | 128 | with names of the form |
e2cbd475 | 129 | .IR \fBsem.\fPsomename . |
13e0f2a9 MK |
130 | (This is the reason that semaphore names are limited to |
131 | .BI NAME_MAX \-4 | |
132 | rather than | |
133 | .B NAME_MAX | |
134 | characters.) | |
30586560 MK |
135 | |
136 | Since Linux 2.6.19, ACLs can be placed on files under this directory, | |
137 | to control object permissions on a per-user and per-group basis. | |
2c731798 MK |
138 | .SH NOTES |
139 | System V semaphores | |
140 | .RB ( semget (2), | |
141 | .BR semop (2), | |
142 | etc.) are an older semaphore API. | |
143 | POSIX semaphores provide a simpler, and better designed interface than | |
c13182ef MK |
144 | System V semaphores; |
145 | on the other hand POSIX semaphores are less widely available | |
2c731798 MK |
146 | (especially on older systems) than System V semaphores. |
147 | .SH EXAMPLE | |
148 | An example of the use of various POSIX semaphore functions is shown in | |
149 | .BR sem_wait (3). | |
47297adb | 150 | .SH SEE ALSO |
2c731798 MK |
151 | .BR sem_close (3), |
152 | .BR sem_destroy (3), | |
2c731798 | 153 | .BR sem_getvalue (3), |
f0c34053 | 154 | .BR sem_init (3), |
2c731798 MK |
155 | .BR sem_open (3), |
156 | .BR sem_post (3), | |
157 | .BR sem_unlink (3), | |
f58c4bd8 MK |
158 | .BR sem_wait (3), |
159 | .BR pthreads (7) |