NAME

       get_thread_area, set_thread_area - manipulate thread-local storage information

SYNOPSIS

       #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

       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

       On x86, these system calls return 0 on success, and -1 on failure, with errno set appropriately.

       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

       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

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

CONFORMING TO

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

NOTES

       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

       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

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

COLOPHON

       This  page  is  part  of  release  5.05  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/.