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