Debian Codegraph @

upstream/debian-unstable/man2/set_tid_address.2

raw
1 .\" Copyright 2004, Andries E. Brouwer <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH set_tid_address 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 set_tid_address \- set pointer to thread ID
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
15 .B #include <unistd.h>
16 .P
17 .BI "pid_t syscall(SYS_set_tid_address, int *" tidptr );
18 .fi
19 .P
20 .IR Note :
21 glibc provides no wrapper for
22 .BR set_tid_address (),
23 necessitating the use of
24 .BR syscall (2).
25 .SH DESCRIPTION
26 For each thread, the kernel maintains two attributes (addresses) called
27 .I set_child_tid
28 and
29 .IR clear_child_tid .
30 These two attributes contain the value NULL by default.
31 .TP
32 .I set_child_tid
33 If a thread is started using
34 .BR clone (2)
35 with the
36 .B CLONE_CHILD_SETTID
37 flag,
38 .I set_child_tid
39 is set to the value passed in the
40 .I ctid
41 argument of that system call.
42 .IP
43 When
44 .I set_child_tid
45 is set, the very first thing the new thread does
46 is to write its thread ID at this address.
47 .TP
48 .I clear_child_tid
49 If a thread is started using
50 .BR clone (2)
51 with the
52 .B CLONE_CHILD_CLEARTID
53 flag,
54 .I clear_child_tid
55 is set to the value passed in the
56 .I ctid
57 argument of that system call.
58 .P
59 The system call
60 .BR set_tid_address ()
61 sets the
62 .I clear_child_tid
63 value for the calling thread to
64 .IR tidptr .
65 .P
66 When a thread whose
67 .I clear_child_tid
68 is not NULL terminates, then,
69 if the thread is sharing memory with other threads,
70 then 0 is written at the address specified in
71 .I clear_child_tid
72 and the kernel performs the following operation:
73 .P
74 .in +4n
75 .EX
76 futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);
77 .EE
78 .in
79 .P
80 The effect of this operation is to wake a single thread that
81 is performing a futex wait on the memory location.
82 Errors from the futex wake operation are ignored.
83 .SH RETURN VALUE
84 .BR set_tid_address ()
85 always returns the caller's thread ID.
86 .SH ERRORS
87 .BR set_tid_address ()
88 always succeeds.
89 .SH STANDARDS
90 Linux.
91 .SH HISTORY
92 Linux 2.5.48.
93 .P
94 Details as given here are valid since Linux 2.5.49.
95 .SH SEE ALSO
96 .BR clone (2),
97 .BR futex (2),
98 .BR gettid (2)