set_thread_area(2)

✨ set_thread_area(2) ✨

okay bestie, we're in the System Calls Manual section today 💅 and this one is called set_thread_area(2) — well, technically it's a two-for-one deal, so buckle up 🎀

---

💖 NAME 💖

get_thread_area, set_thread_area — manipulate thread-local storage information

🌸 LIBRARY 🌸

Standard C library (libc, -lc)

🦋 SYNOPSIS 🦋

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

#if defined __i386__ || defined __x86_64__
# include <asm/ldt.h>        /* Definition of struct user_desc */

int syscall(SYS_get_thread_area, struct user_desc *u_info);
int syscall(SYS_set_thread_area, struct user_desc *u_info);

#elif defined __m68k__

int syscall(SYS_get_thread_area);
int syscall(SYS_set_thread_area, unsigned long tp);

#elif defined __mips__ || defined __csky__

int syscall(SYS_set_thread_area, unsigned long addr);

#endif

Note: glibc provides no wrappers for these system calls, necessitating the use of syscall(2).

not a single lil wrapper in sight 😭 — literally nothing, so you have to go through syscall(2). no shortcuts, no cute little libc hug. periodt.

👑 DESCRIPTION 👑

So these calls are the architecture-specific backbone of a thread-local storage implementation — the girlies doing the real work behind the scenes, no cap. Right now set_thread_area() is available on m68k, MIPS, C-SKY, and x86 (both the 32-bit and 64-bit variants, she's flexible 💅), and get_thread_area() is available on m68k and x86.

On m68k, MIPS and C-SKY, set_thread_area() lets you stash an arbitrary pointer in the kernel data structure that belongs to the calling thread — that pointer comes in via the tp argument on m68k, and via the addr argument on MIPS and C-SKY ✨. Later you can get that pointer back with get_thread_area() (and if you're on MIPS, peep NOTES for how to fetch the thread pointer, iykyk).

On x86, Linux dedicates three global descriptor table (GDT) entries for thread-local storage 🎀. Want the lore on the GDT? Go read the Intel Software Developer's Manual or the AMD Architecture Programming Manual. main character reading material fr.

Both of these system calls take an argument that's a pointer to a structure of exactly this shape:

struct user_desc {
    unsigned int  entry_number;
    unsigned int  base_addr;
    unsigned int  limit;
    unsigned int  seg_32bit:1;
    unsigned int  contents:2;
    unsigned int  read_exec_only:1;
    unsigned int  limit_in_pages:1;
    unsigned int  seg_not_present:1;
    unsigned int  useable:1;
#ifdef __x86_64__
    unsigned int  lm:1;
#endif
};

• get_thread_area() reads the GDT entry indicated by u_info->entry_number and fills in the rest of the fields in u_info. she reads, she reports back, obsessed 📖
• set_thread_area() sets a TLS entry in the GDT.

The TLS array entry that set_thread_area() sets corresponds to the value of u_info->entry_number that you passed in. If that value is in bounds, set_thread_area() writes the TLS descriptor pointed to by u_info into the thread's TLS array. in bounds = we're on, out of bounds = we are NOT on 💀

When set_thread_area() gets an entry_number of -1, it goes searching for a free TLS entry 🔍. If it finds one, the value of u_info->entry_number is set upon return so you know which entry got changed. mystery solved bestie ✨

A user_desc is considered "empty" if read_exec_only and seg_not_present are set to 1 and all of the other fields are 0. If you pass an "empty" descriptor to set_thread_area(), the corresponding TLS entry gets cleared 🧼. See BUGS for the extra details, because of course there are extra details.

Since Linux 3.19, set_thread_area() cannot be used to write non-present segments, 16-bit segments, or code segments — although clearing a segment is still totally acceptable ✅.

💜 RETURN VALUE 💜

On x86, these system calls return 0 on success, and -1 on failure, with errno set to indicate the error.

On C-SKY, MIPS and m68k, set_thread_area() always returns 0. On m68k, get_thread_area() returns the thread area pointer value (the one you previously set via set_thread_area()), giving back what you gave her, iconic behavior 🫶

🍓 ERRORS 🍓

• EFAULT — u_info is an invalid pointer. 💀
• EINVAL — u_info->entry_number is out of bounds.
• ENOSYS — get_thread_area() or set_thread_area() was invoked as a 64-bit system call. not the 64-bit call, bestie, read the SYNOPSIS again 😭
• ESRCH — (set_thread_area()) A free TLS entry could not be located.

🌈 STANDARDS 🌈

Linux.

🧚 HISTORY 🧚

• set_thread_area() — Linux 2.5.29.
• get_thread_area() — Linux 2.5.32.

⭐ NOTES ⭐

These system calls are generally intended for use only by threading libraries — they're not like, casual hangout calls, they have a job 💅

arch_prctl(2) can interfere with set_thread_area() on x86 👀. See arch_prctl(2) for more details. This is not normally a problem, as arch_prctl(2) is normally used only by 64-bit programs. so like, usually fine, don't spiral

On MIPS, the current value of the thread area pointer can be obtained using the instruction:

rdhwr dest, $29

This instruction traps and is handled by kernel. sneaky lil trap, she's got secrets 🎀

🙈 BUGS 🙈

On 64-bit kernels before Linux 3.19, one of the padding bits in user_desc, if set, would prevent the descriptor from being considered empty (see modify_ldt(2)). As a result, the only reliable way to clear a TLS entry is to use memset(3) to zero the entire user_desc structure, including padding bits, and then to set the read_exec_only and seg_not_present bits. On Linux 3.19, a user_desc consisting entirely of zeros except for entry_number will also be interpreted as a request to clear a TLS entry, but this behaved differently on older kernels. older kernels said "we're not doing it that way" 🫠

Prior to Linux 3.19, the DS and ES segment registers must not reference TLS entries. do NOT do it. this is not a drill.

💜 SEE ALSO 💜

arch_prctl(2), modify_ldt(2), ptrace(2) (PTRACE_GET_THREAD_AREA and PTRACE_SET_THREAD_AREA)

---

and that's the whole thing bestie, you ate that 🍽️✨ this page was brought to you by Linux man-pages 6.20, dated 2026-02-08, from your fave set_thread_area(2) — go forth and be thread-local 💅🦋