man2/set_tid_address.2

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