set_tid_address(2)

1SET_TID_ADDRESS(2)         Linux Programmer's Manual        SET_TID_ADDRESS(2)
2
3
4

NAME

6       set_tid_address - set pointer to thread ID
7

SYNOPSIS

9       #include <sys/syscall.h>      /* Definition of SYS_* constants */
10       #include <unistd.h>
11
12       pid_t syscall(SYS_set_tid_address, int *tidptr);
13
14       Note:  glibc  provides  no wrapper for set_tid_address(), necessitating
15       the use of syscall(2).
16

DESCRIPTION

18       For each thread, the kernel maintains two attributes (addresses) called
19       set_child_tid  and  clear_child_tid.   These two attributes contain the
20       value NULL by default.
21
22       set_child_tid
23              If a thread is started using clone(2) with the  CLONE_CHILD_SET‐
24              TID  flag,  set_child_tid is set to the value passed in the ctid
25              argument of that system call.
26
27              When set_child_tid is set, the very first thing the  new  thread
28              does is to write its thread ID at this address.
29
30       clear_child_tid
31              If    a    thread   is   started   using   clone(2)   with   the
32              CLONE_CHILD_CLEARTID flag, clear_child_tid is set to  the  value
33              passed in the ctid argument of that system call.
34
35       The  system  call  set_tid_address() sets the clear_child_tid value for
36       the calling thread to tidptr.
37
38       When a thread whose clear_child_tid is not NULL  terminates,  then,  if
39       the  thread  is sharing memory with other threads, then 0 is written at
40       the address specified in clear_child_tid and the  kernel  performs  the
41       following operation:
42
43           futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);
44
45       The  effect  of  this operation is to wake a single thread that is per‐
46       forming a futex wait on the memory location.   Errors  from  the  futex
47       wake operation are ignored.
48

RETURN VALUE

50       set_tid_address() always returns the caller's thread ID.
51

ERRORS

53       set_tid_address() always succeeds.
54

VERSIONS

56       This  call  is  present  since Linux 2.5.48.  Details as given here are
57       valid since Linux 2.5.49.
58

CONFORMING TO

60       This system call is Linux-specific.
61

COLOPHON

66       This page is part of release 5.13 of the Linux  man-pages  project.   A
67       description  of  the project, information about reporting bugs, and the
68       latest    version    of    this    page,    can     be     found     at
69       https://www.kernel.org/doc/man-pages/.
70
71
72
73Linux                             2021-06-20                SET_TID_ADDRESS(2)