set_tid_address(2)

💖 set_tid_address(2) — the syscall manual page, bestie edition 💖

okay so this is a page from the System Calls Manual, and we're talking about set_tid_address. it's giving "tiny syscall, big responsibilities", and honestly? iconic. let's get into it 🫶

---

✨ NAME ✨

set_tid_address — set pointer to thread ID

📚 LIBRARY 📚

Standard C library (libc, -lc)

🌸 SYNOPSIS 🌸

#include <sys/syscall.h>      /* Definition of SYS_* constants */
#include <unistd.h>

pid_t syscall(SYS_set_tid_address, int *tidptr);

🚨 bestie, important heads up: glibc provides no wrapper for set_tid_address(), so you literally have to go through syscall(2). no shortcut, no cute little libc function, you're doing it raw. periodt.

💅 DESCRIPTION 💅

so for every single thread, the kernel keeps two attributes (they're addresses, js) called set_child_tid and clear_child_tid. and out of the box, both of these are NULL. like, default state: nothing, nobody, empty. 🌫️

🧸 set_child_tid

if a thread gets started with clone(2) and the CLONE_CHILD_SETTID flag, then set_child_tid gets set to the value that was passed in the ctid argument of that syscall.

and when set_child_tid is set? the very first thing the new thread does — like, before anything else, main character behavior — is write its thread ID at this address. no cap. 💫

🧹 clear_child_tid

if a thread gets started with clone(2) and the CLONE_CHILD_CLEARTID flag, then clear_child_tid gets set to the value passed in the ctid argument of that syscall.

and the syscall set_tid_address() — that's our girl — sets the clear_child_tid value for the calling thread to tidptr.

now here's the juicy part 🍓: when a thread whose clear_child_tid is not NULL terminates, and if that thread is sharing memory with other threads, then 0 gets written at the address specified in clear_child_tid, and the kernel runs this:

futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);

what does that do? it wakes up a single thread that's doing a futex wait on that memory location. one thread. one. and any errors from the futex wake operation? ignored. not our problem, not our vibe. 🙈

🎀 RETURN VALUE 🎀

set_tid_address() always returns the caller's thread ID. every time. no plot twists.

💀 ERRORS 💀

set_tid_address() always succeeds. literally cannot fail. the reliability is unmatched, fr fr. 👑

🌈 STANDARDS 🌈

Linux.

🦋 HISTORY 🦋

Linux 2.5.48.

and the details as given here? those have been valid since Linux 2.5.49.

👀 SEE ALSO 👀

• clone(2)
• futex(2)
• gettid(2)

---

and that's the whole page, bestie!! you ate that. go forth and set your tid pointers responsibly 💜

sign-off time: this lovely little manual page comes to you from Linux man-pages 6.20, dated 2026-02-08. mwah 💋 ✨💖🎀