set_thread_area(2) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | BUGS | SEE ALSO | COLOPHON

SET_THREAD_AREA(2)      Linux Programmer's Manual     SET_THREAD_AREA(2)

NAME         top

       get_thread_area, set_thread_area - manipulate thread-local
       storage information

SYNOPSIS         top

       #include <linux/unistd.h>

       #if defined __i386__ || defined __x86_64__
       # include <asm/ldt.h>

       int get_thread_area(struct user_desc *u_info);
       int set_thread_area(struct user_desc *u_info);

       #elif defined __m68k__

       int get_thread_area(void);
       int set_thread_area(unsigned long tp);

       #elif defined __mips__

       int set_thread_area(unsigned long addr);

       #endif

       Note: There are no glibc wrappers for these system calls; see
       NOTES.

DESCRIPTION         top

       These calls provide architecture-specific support for a thread-
       local storage implementation.  At the moment, set_thread_area()
       is available on m68k, MIPS, and x86 (both 32-bit and 64-bit
       variants); get_thread_area() is available on m68k and x86.

       On m68k and MIPS, set_thread_area() allows storing an arbitrary
       pointer (provided in the tp argument on m68k and in the addr
       argument on MIPS) in the kernel data structure associated with
       the calling thread; this pointer can later be retrieved using
       get_thread_area() (see also NOTES for information regarding
       obtaining the thread pointer on MIPS).

       On x86, Linux dedicates three global descriptor table (GDT)
       entries for thread-local storage.  For more information about the
       GDT, see the Intel Software Developer's Manual or the AMD
       Architecture Programming Manual.

       Both of these system calls take an argument that is a pointer to
       a structure of the following type:

           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.

       set_thread_area() sets a TLS entry in the GDT.

       The TLS array entry set by set_thread_area() corresponds to the
       value of u_info->entry_number passed in by the user.  If this
       value is in bounds, set_thread_area() writes the TLS descriptor
       pointed to by u_info into the thread's TLS array.

       When set_thread_area() is passed an entry_number of -1, it
       searches for a free TLS entry.  If set_thread_area() finds a free
       TLS entry, the value of u_info->entry_number is set upon return
       to show which entry was changed.

       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 an "empty" descriptor is passed to set_thread_area(), the
       corresponding TLS entry will be cleared.  See BUGS for additional
       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 acceptable.

RETURN VALUE         top

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

       On MIPS and m68k, set_thread_area() always returns 0.  On m68k,
       get_thread_area() returns the thread area pointer value
       (previously set via set_thread_area()).

ERRORS         top

       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.

       ESRCH  (set_thread_area()) A free TLS entry could not be located.

VERSIONS         top

       set_thread_area() first appeared in Linux 2.5.29.
       get_thread_area() first appeared in Linux 2.5.32.

CONFORMING TO         top

       set_thread_area() and get_thread_area() are Linux-specific and
       should not be used in programs that are intended to be portable.

NOTES         top

       Glibc does not provide wrappers for these system calls, since
       they are generally intended for use only by threading libraries.
       In the unlikely event that you want to call them directly, use
       syscall(2).

       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.

       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.

BUGS         top

       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.

       Prior to Linux 3.19, the DS and ES segment registers must not
       reference TLS entries.

SEE ALSO         top

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

COLOPHON         top

       This page is part of release 5.11 of the Linux man-pages project.
       A description of the project, information about reporting bugs,
       and the latest version of this page, can be found at
       https://www.kernel.org/doc/man-pages/.

Linux                          2021-03-22             SET_THREAD_AREA(2)

Pages that refer to this page: strace(1)arch_prctl(2)clone(2)modify_ldt(2)ptrace(2)syscalls(2)