Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 139 insertions, 0 deletions

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 <mtk.manpages@gmail.com>
+.\"
+.\" 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)