| 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) |