Debian Codegraph @

upstream/debian-trixie/man7/sem_overview.7

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