Merging upstream version 6.8.

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

1 files changed, 97 insertions, 0 deletions

diff --git a/man/man2/set_tid_address.2 b/man/man2/set_tid_address.2
new file mode 100644
index 0000000..dd9d9bc
--- /dev/null
+++ b/man/man2/set_tid_address.2
@@ -0,0 +1,97 @@
+.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH set_tid_address 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+set_tid_address \- set pointer to thread ID
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "pid_t syscall(SYS_set_tid_address, int *" tidptr );
+.fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR set_tid_address (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+For each thread, the kernel maintains two attributes (addresses) called
+.I set_child_tid
+and
+.IR clear_child_tid .
+These two attributes contain the value NULL by default.
+.TP
+.I set_child_tid
+If a thread is started using
+.BR clone (2)
+with the
+.B CLONE_CHILD_SETTID
+flag,
+.I set_child_tid
+is set to the value passed in the
+.I ctid
+argument of that system call.
+.IP
+When
+.I set_child_tid
+is set, the very first thing the new thread does
+is to write its thread ID at this address.
+.TP
+.I clear_child_tid
+If a thread is started using
+.BR clone (2)
+with the
+.B CLONE_CHILD_CLEARTID
+flag,
+.I clear_child_tid
+is set to the value passed in the
+.I ctid
+argument of that system call.
+.P
+The system call
+.BR set_tid_address ()
+sets the
+.I clear_child_tid
+value for the calling thread to
+.IR tidptr .
+.P
+When a thread whose
+.I clear_child_tid
+is not NULL terminates, then,
+if the thread is sharing memory with other threads,
+then 0 is written at the address specified in
+.I clear_child_tid
+and the kernel performs the following operation:
+.P
+.in +4n
+.EX
+futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);
+.EE
+.in
+.P
+The effect of this operation is to wake a single thread that
+is performing a futex wait on the memory location.
+Errors from the futex wake operation are ignored.
+.SH RETURN VALUE
+.BR set_tid_address ()
+always returns the caller's thread ID.
+.SH ERRORS
+.BR set_tid_address ()
+always succeeds.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.5.48.
+.P
+Details as given here are valid since Linux 2.5.49.
+.SH SEE ALSO
+.BR clone (2),
+.BR futex (2),
+.BR gettid (2)