set_tid_address(2)

1set_tid_address(2)            System Calls Manual           set_tid_address(2)
2
3
4

NAME

6       set_tid_address - set pointer to thread ID
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

53       set_tid_address() always returns the caller's thread ID.
54

ERRORS

56       set_tid_address() always succeeds.
57

STANDARDS

59       Linux.
60

HISTORY

62       Linux 2.5.48.
63
64       Details as given here are valid since Linux 2.5.49.
65