Merging upstream version 6.8.

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

1 files changed, 121 insertions, 0 deletions

diff --git a/man/man7/futex.7 b/man/man7/futex.7
new file mode 100644
index 0000000..c12268a
--- /dev/null
+++ b/man/man7/futex.7
@@ -0,0 +1,121 @@
+.\" This manpage has been automatically generated by docbook2man
+.\" from a DocBook document.  This tool can be found at:
+.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
+.\" Please send any bug reports, improvements, comments, patches,
+.\" etc. to Steve Cheng <steve@ggi-project.org>.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.TH futex 7 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+futex \- fast user-space locking
+.SH SYNOPSIS
+.nf
+.B #include <linux/futex.h>
+.fi
+.SH DESCRIPTION
+The Linux kernel provides futexes ("Fast user-space mutexes")
+as a building block for fast user-space
+locking and semaphores.
+Futexes are very basic and lend themselves well for building higher-level
+locking abstractions such as
+mutexes, condition variables, read-write locks, barriers, and semaphores.
+.P
+Most programmers will in fact not be using futexes directly but will
+instead rely on system libraries built on them,
+such as the Native POSIX Thread Library (NPTL) (see
+.BR pthreads (7)).
+.P
+A futex is identified by a piece of memory which can be
+shared between processes or threads.
+In these different processes, the futex need not have identical addresses.
+In its bare form, a futex has semaphore semantics;
+it is a counter that can be incremented and decremented atomically;
+processes can wait for the value to become positive.
+.P
+Futex operation occurs entirely in user space for the noncontended case.
+The kernel is involved only to arbitrate the contended case.
+As any sane design will strive for noncontention,
+futexes are also optimized for this situation.
+.P
+In its bare form, a futex is an aligned integer which is
+touched only by atomic assembler instructions.
+This integer is four bytes long on all platforms.
+Processes can share this integer using
+.BR mmap (2),
+via shared memory segments, or because they share memory space,
+in which case the application is commonly called multithreaded.
+.SS Semantics
+Any futex operation starts in user space,
+but it may be necessary to communicate with the kernel using the
+.BR futex (2)
+system call.
+.P
+To "up" a futex, execute the proper assembler instructions that
+will cause the host CPU to atomically increment the integer.
+Afterward, check if it has in fact changed from 0 to 1, in which case
+there were no waiters and the operation is done.
+This is the noncontended case which is fast and should be common.
+.P
+In the contended case, the atomic increment changed the counter
+from \-1  (or some other negative number).
+If this is detected, there are waiters.
+User space should now set the counter to 1 and instruct the
+kernel to wake up any waiters using the
+.B FUTEX_WAKE
+operation.
+.P
+Waiting on a futex, to "down" it, is the reverse operation.
+Atomically decrement the counter and check if it changed to 0,
+in which case the operation is done and the futex was uncontended.
+In all other circumstances, the process should set the counter to \-1
+and request that the kernel wait for another process to up the futex.
+This is done using the
+.B FUTEX_WAIT
+operation.
+.P
+The
+.BR futex (2)
+system call can optionally be passed a timeout specifying how long
+the kernel should
+wait for the futex to be upped.
+In this case, semantics are more complex and the programmer is referred
+to
+.BR futex (2)
+for
+more details.
+The same holds for asynchronous futex waiting.
+.SH VERSIONS
+Initial futex support was merged in Linux 2.5.7
+but with different semantics from those described above.
+Current semantics are available from Linux 2.5.40 onward.
+.SH NOTES
+To reiterate, bare futexes are not intended as an easy-to-use
+abstraction for end users.
+Implementors are expected to be assembly literate and to have read
+the sources of the futex user-space library referenced
+below.
+.P
+This man page illustrates the most common use of the
+.BR futex (2)
+primitives; it is by no means the only one.
+.\" .SH AUTHORS
+.\" .P
+.\" Futexes were designed and worked on by Hubertus Franke
+.\" (IBM Thomas J. Watson Research Center),
+.\" Matthew Kirkwood, Ingo Molnar (Red Hat) and
+.\" Rusty Russell (IBM Linux Technology Center).
+.\" This page written by bert hubert.
+.SH SEE ALSO
+.BR clone (2),
+.BR futex (2),
+.BR get_robust_list (2),
+.BR set_robust_list (2),
+.BR set_tid_address (2),
+.BR pthreads (7)
+.P
+.I Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux
+(proceedings of the Ottawa Linux Symposium 2002),
+futex example library, futex-*.tar.bz2
+.UR https://mirrors.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/
+.UE .