From 3d08cd331c1adcf0d917392f7e527b3f00511748 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:22 +0200 Subject: Merging upstream version 6.8. Signed-off-by: Daniel Baumann --- man/man7/sem_overview.7 | 139 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 man/man7/sem_overview.7 (limited to 'man/man7/sem_overview.7') diff --git a/man/man7/sem_overview.7 b/man/man7/sem_overview.7 new file mode 100644 index 0000000..01d918c --- /dev/null +++ b/man/man7/sem_overview.7 @@ -0,0 +1,139 @@ +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_overview 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_overview \- overview of POSIX semaphores +.SH DESCRIPTION +POSIX semaphores allow processes and threads to synchronize their actions. +.P +A semaphore is an integer whose value is never allowed to fall below zero. +Two operations can be performed on semaphores: +increment the semaphore value by one +.RB ( sem_post (3)); +and decrement the semaphore value by one +.RB ( sem_wait (3)). +If the value of a semaphore is currently zero, then a +.BR sem_wait (3) +operation will block until the value becomes greater than zero. +.P +POSIX semaphores come in two forms: named semaphores and +unnamed semaphores. +.TP +.B Named semaphores +A named semaphore is identified by a name of the form +.IR /somename ; +that is, a null-terminated string of up to +.BI NAME_MAX \-4 +(i.e., 251) characters consisting of an initial slash, +.\" glibc allows the initial slash to be omitted, and makes +.\" multiple initial slashes equivalent to a single slash. +.\" This differs from the implementation of POSIX message queues. +followed by one or more characters, none of which are slashes. +.\" glibc allows subdirectory components in the name, in which +.\" case the subdirectory tree must exist under /dev/shm, and +.\" the fist subdirectory component must exist as the name +.\" sem.name, and all of the subdirectory components must allow the +.\" required permissions if a user wants to create a semaphore +.\" object in a subdirectory. +Two processes can operate on the same named semaphore by passing +the same name to +.BR sem_open (3). +.IP +The +.BR sem_open (3) +function creates a new named semaphore or opens an existing +named semaphore. +After the semaphore has been opened, it can be operated on using +.BR sem_post (3) +and +.BR sem_wait (3). +When a process has finished using the semaphore, it can use +.BR sem_close (3) +to close the semaphore. +When all processes have finished using the semaphore, +it can be removed from the system using +.BR sem_unlink (3). +.TP +.B Unnamed semaphores (memory-based semaphores) +An unnamed semaphore does not have a name. +Instead the semaphore is placed in a region of memory that +is shared between multiple threads (a +.IR "thread-shared semaphore" ) +or processes (a +.IR "process-shared semaphore" ). +A thread-shared semaphore is placed in an area of memory shared +between the threads of a process, for example, a global variable. +A process-shared semaphore must be placed in a shared memory region +(e.g., a System V shared memory segment created using +.BR shmget (2), +or a POSIX shared memory object built created using +.BR shm_open (3)). +.IP +Before being used, an unnamed semaphore must be initialized using +.BR sem_init (3). +It can then be operated on using +.BR sem_post (3) +and +.BR sem_wait (3). +When the semaphore is no longer required, +and before the memory in which it is located is deallocated, +the semaphore should be destroyed using +.BR sem_destroy (3). +.P +The remainder of this section describes some specific details +of the Linux implementation of POSIX semaphores. +.SS Versions +Before Linux 2.6, Linux supported only unnamed, +thread-shared semaphores. +On a system with Linux 2.6 and a glibc that provides the NPTL +threading implementation, +a complete implementation of POSIX semaphores is provided. +.SS Persistence +POSIX named semaphores have kernel persistence: +if not removed by +.BR sem_unlink (3), +a semaphore will exist until the system is shut down. +.SS Linking +Programs using the POSIX semaphores API must be compiled with +.I cc \-pthread +to link against the real-time library, +.IR librt . +.SS Accessing named semaphores via the filesystem +On Linux, named semaphores are created in a virtual filesystem, +normally mounted under +.IR /dev/shm , +with names of the form +.IR \fBsem.\fPsomename . +(This is the reason that semaphore names are limited to +.BI NAME_MAX \-4 +rather than +.B NAME_MAX +characters.) +.P +Since Linux 2.6.19, ACLs can be placed on files under this directory, +to control object permissions on a per-user and per-group basis. +.SH NOTES +System V semaphores +.RB ( semget (2), +.BR semop (2), +etc.) are an older semaphore API. +POSIX semaphores provide a simpler, and better designed interface than +System V semaphores; +on the other hand POSIX semaphores are less widely available +(especially on older systems) than System V semaphores. +.SH EXAMPLES +An example of the use of various POSIX semaphore functions is shown in +.BR sem_wait (3). +.SH SEE ALSO +.BR sem_close (3), +.BR sem_destroy (3), +.BR sem_getvalue (3), +.BR sem_init (3), +.BR sem_open (3), +.BR sem_post (3), +.BR sem_unlink (3), +.BR sem_wait (3), +.BR pthreads (7), +.BR shm_overview (7) -- cgit v1.2.3