man2/set_tid_address.2

   1 .\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .TH SET_TID_ADDRESS 2 2012-07-19 "Linux" "Linux Programmer's Manual"
  24 .SH NAME
  25 set_tid_address \- set pointer to thread ID
  26 .SH SYNOPSIS
  27 .nf
  28 .B #include <linux/unistd.h>
  29 .sp
  30 .BI "long set_tid_address(int *" tidptr );
  31 .fi
  32 .SH DESCRIPTION
  33 For each process, the kernel maintains two attributes (addresses) called
  34 .I set_child_tid
  35 and
  36 .IR clear_child_tid .
  37 These two attributes contain the value NULL by default.
  38 .TP
  39 .I set_child_tid
  40 If a process is started using
  41 .BR clone (2)
  42 with the
  43 .B CLONE_CHILD_SETTID
  44 flag,
  45 .I set_child_tid
  46 is set to the value passed in the
  47 .I ctid
  48 argument of that system call.
  49 .IP
  50 When
  51 .I set_child_tid
  52 is set, the very first thing the new process does
  53 is writing its PID at this address.
  54 .TP
  55 .I clear_child_tid
  56 If a process is started using
  57 .BR clone (2)
  58 with the
  59 .B CLONE_CHILD_CLEARTID
  60 flag,
  61 .I clear_child_tid
  62 is set to the value passed in the
  63 .I ctid
  64 argument of that system call.
  65 .LP
  66 The system call
  67 .BR set_tid_address ()
  68 sets the
  69 .I clear_child_tid
  70 value for the calling process to
  71 .IR tidptr .
  72 .LP
  73 When a process whose
  74 .I clear_child_tid
  75 is not NULL terminates, then,
  76 if the process is sharing memory with other processes or threads,
  77 then 0 is written at the address specified in
  78 .I clear_child_tid
  79 and the kernel performs the following operation:
  80
  81     futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);
  82
  83 The effect of this operation is to wake a single process that
  84 is performing a futex wait on the memory location.
  85 Errors from the futex wake operation are ignored.
  86 .SH RETURN VALUE
  87 .BR set_tid_address ()
  88 always returns the PID of the calling process.
  89 .SH ERRORS
  90 .BR set_tid_address ()
  91 always succeeds.
  92 .SH VERSIONS
  93 This call is present since Linux 2.5.48.
  94 Details as given here are valid since Linux 2.5.49.
  95 .SH CONFORMING TO
  96 This system call is Linux-specific.
  97 .SH SEE ALSO
  98 .BR clone (2),
  99 .BR futex (2)