.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl)
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH set_tid_address 2 2023-03-30 "Linux man-pages 6.04"
.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>
.PP
.BI "pid_t syscall(SYS_set_tid_address, int *" tidptr );
.fi
.PP
.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.
.PP
The system call
.BR set_tid_address ()
sets the
.I clear_child_tid
value for the calling thread to
.IR tidptr .
.PP
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:
.PP
.in +4n
.EX
futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);
.EE
.in
.PP
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.
.PP
Details as given here are valid since Linux 2.5.49.
.SH SEE ALSO
.BR clone (2),
.BR futex (2),
.BR gettid (2)