Debian Codegraph @

upstream/debian-unstable/man7/sem_overview.7

raw
1 .\" Copyright 2006, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH sem_overview 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 sem_overview \- overview of POSIX semaphores
9 .SH DESCRIPTION
10 POSIX semaphores allow processes and threads to synchronize their actions.
11 .P
12 A semaphore is an integer whose value is never allowed to fall below zero.
13 Two operations can be performed on semaphores:
14 increment the semaphore value by one
15 .RB ( sem_post (3));
16 and decrement the semaphore value by one
17 .RB ( sem_wait (3)).
18 If the value of a semaphore is currently zero, then a
19 .BR sem_wait (3)
20 operation will block until the value becomes greater than zero.
21 .P
22 POSIX semaphores come in two forms: named semaphores and
23 unnamed semaphores.
24 .TP
25 .B Named semaphores
26 A named semaphore is identified by a name of the form
27 .IR /somename ;
28 that is, a null-terminated string of up to
29 .BI NAME_MAX \-4
30 (i.e., 251) characters consisting of an initial slash,
31 .\" glibc allows the initial slash to be omitted, and makes
32 .\" multiple initial slashes equivalent to a single slash.
33 .\" This differs from the implementation of POSIX message queues.
34 followed by one or more characters, none of which are slashes.
35 .\" glibc allows subdirectory components in the name, in which
36 .\" case the subdirectory tree must exist under /dev/shm, and
37 .\" the fist subdirectory component must exist as the name
38 .\" sem.name, and all of the subdirectory components must allow the
39 .\" required permissions if a user wants to create a semaphore
40 .\" object in a subdirectory.
41 Two processes can operate on the same named semaphore by passing
42 the same name to
43 .BR sem_open (3).
44 .IP
45 The
46 .BR sem_open (3)
47 function creates a new named semaphore or opens an existing
48 named semaphore.
49 After the semaphore has been opened, it can be operated on using
50 .BR sem_post (3)
51 and
52 .BR sem_wait (3).
53 When a process has finished using the semaphore, it can use
54 .BR sem_close (3)
55 to close the semaphore.
56 When all processes have finished using the semaphore,
57 it can be removed from the system using
58 .BR sem_unlink (3).
59 .TP
60 .B Unnamed semaphores (memory-based semaphores)
61 An unnamed semaphore does not have a name.
62 Instead the semaphore is placed in a region of memory that
63 is shared between multiple threads (a
64 .IR "thread-shared semaphore" )
65 or processes (a
66 .IR "process-shared semaphore" ).
67 A thread-shared semaphore is placed in an area of memory shared
68 between the threads of a process, for example, a global variable.
69 A process-shared semaphore must be placed in a shared memory region
70 (e.g., a System V shared memory segment created using
71 .BR shmget (2),
72 or a POSIX shared memory object built created using
73 .BR shm_open (3)).
74 .IP
75 Before being used, an unnamed semaphore must be initialized using
76 .BR sem_init (3).
77 It can then be operated on using
78 .BR sem_post (3)
79 and
80 .BR sem_wait (3).
81 When the semaphore is no longer required,
82 and before the memory in which it is located is deallocated,
83 the semaphore should be destroyed using
84 .BR sem_destroy (3).
85 .P
86 The remainder of this section describes some specific details
87 of the Linux implementation of POSIX semaphores.
88 .SS Versions
89 Before Linux 2.6, Linux supported only unnamed,
90 thread-shared semaphores.
91 On a system with Linux 2.6 and a glibc that provides the NPTL
92 threading implementation,
93 a complete implementation of POSIX semaphores is provided.
94 .SS Persistence
95 POSIX named semaphores have kernel persistence:
96 if not removed by
97 .BR sem_unlink (3),
98 a semaphore will exist until the system is shut down.
99 .SS Linking
100 Programs using the POSIX semaphores API must be compiled with
101 .I cc \-pthread
102 to link against the real-time library,
103 .IR librt .
104 .SS Accessing named semaphores via the filesystem
105 On Linux, named semaphores are created in a virtual filesystem,
106 normally mounted under
107 .IR /dev/shm ,
108 with names of the form
109 .IR sem. somename.
110 (This is the reason that semaphore names are limited to
111 .BI NAME_MAX \-4
112 rather than
113 .B NAME_MAX
114 characters.)
115 .P
116 Since Linux 2.6.19, ACLs can be placed on files under this directory,
117 to control object permissions on a per-user and per-group basis.
118 .SH NOTES
119 System V semaphores
120 .RB ( semget (2),
121 .BR semop (2),
122 etc.) are an older semaphore API.
123 POSIX semaphores provide a simpler, and better designed interface than
124 System V semaphores;
125 on the other hand POSIX semaphores are less widely available
126 (especially on older systems) than System V semaphores.
127 .SH EXAMPLES
128 An example of the use of various POSIX semaphore functions is shown in
129 .BR sem_wait (3).
130 .SH SEE ALSO
131 .BR sem_close (3),
132 .BR sem_destroy (3),
133 .BR sem_getvalue (3),
134 .BR sem_init (3),
135 .BR sem_open (3),
136 .BR sem_post (3),
137 .BR sem_unlink (3),
138 .BR sem_wait (3),
139 .BR pthreads (7),
140 .BR shm_overview (7)