Re: [PATCH manpages 0/2] Improve modify_ldt, [gs]et_thread_area docs

Re: [PATCH manpages 0/2] Improve modify_ldt, [gs]et_thread_area docs

[Michael Kerrisk (man-pages)]

On 01/29/2015 10:47 PM, Andy Lutomirski wrote:
> The docs for set_thread_area, get_thread_area, and modify_ldt are pretty
> bad, and there have been a number of kernel changes lately.  Improve
> and update the docs.

Thanks very much for this, Andy! Those pages were indeed in a sorry 
state.

Cheers,

Michael

> Andy Lutomirski (2):
>   modify_ldt.2: Overhaul the documentation
>   arch_prctl.2, set_thread_area.2, get_thread_area.2: Improve TLS
>     documentation
> 
>  man2/arch_prctl.2      |  22 +++++++----
>  man2/get_thread_area.2 |  58 +---------------------------
>  man2/modify_ldt.2      | 101 ++++++++++++++++++++++++++++++++++++++-----------
>  man2/set_thread_area.2 |  93 ++++++++++++++++++++++++++++++++++++++++++---
>  4 files changed, 180 insertions(+), 94 deletions(-)
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH manpages 2/2] arch_prctl.2, set_thread_area.2, get_thread_area.2: Improve TLS documentation

[Michael Kerrisk (man-pages)]

Hi Andy,

Thanks for this!

I've merged this into a branch and done some light editing. 
A few questions below.

On 01/29/2015 10:47 PM, Andy Lutomirski wrote:
> The documentation for set_thread_area was very vague.  This improves
> it, accounts for recent kernel changes, and merges it with
> get_thread_area.2.

(Yep, merging seems a good idea.)
> 
> While I'm at it, clarify the related arch_prctl.2 man page.
> 
> Signed-off-by: Andy Lutomirski <luto-kltTT9wpgjJwATOyAt5JVQ@public.gmane.org>
> ---
>  man2/arch_prctl.2      | 22 +++++++-----
>  man2/get_thread_area.2 | 58 +------------------------------
>  man2/set_thread_area.2 | 93 ++++++++++++++++++++++++++++++++++++++++++++++----
>  3 files changed, 102 insertions(+), 71 deletions(-)
> 
> diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
> index a3ab2b566915..c89fa3c7b744 100644
> --- a/man2/arch_prctl.2
> +++ b/man2/arch_prctl.2
> @@ -114,27 +114,33 @@ The 64-bit base changes when a new 32-bit segment selector is loaded.
>  is disabled in some kernels.
>  
>  Context switches for 64-bit segment bases are rather expensive.
> -It may be a faster alternative to set a 32-bit base using a
> -segment selector by setting up an LDT with
> -.BR modify_ldt (2)
> -or using the
> +As an optimization, if a 32-bit TLS base address is used,
> +.BR arch_prctl (2)
> +may use a real TLS entry as if
>  .BR set_thread_area (2)
> -system call in kernel 2.5 or later.
> -.BR arch_prctl ()
> -is needed only when you want to set bases that are larger than 4GB.
> +had been called instead of manipulating the segment base register directly.
>  Memory in the first 2GB of address space can be allocated by using
>  .BR mmap (2)
>  with the
>  .B MAP_32BIT
>  flag.
>  
> +As a result, using

Something doesn't quite flow here. "As a result" *of what*? Should this rather 
be something like:

    Because of the aforementioned optimization, using

> +.BR arch_prctl (2)
> +and
> +.BR set_thread_area (2)
> +in the same thread is dangerous, as they may overwrite each other's
> +TLS entries.
> +
>  As of version 2.7, glibc provides no prototype for
>  .BR arch_prctl ().
>  You have to declare it yourself for now.
>  This may be fixed in future glibc versions.
>  
>  .I FS
> -may be already used by the threading library.
> +may be already used by the threading library.  Glibc programs that use

What is a "Glibc program"?

> +.I ARCH_SET_FS
> +directly are very likely to crash.
>  .SH SEE ALSO
>  .BR mmap (2),
>  .BR modify_ldt (2),
> diff --git a/man2/get_thread_area.2 b/man2/get_thread_area.2
> index 08589e413cc4..a03fe54fb08e 100644
> --- a/man2/get_thread_area.2
> +++ b/man2/get_thread_area.2
> @@ -1,57 +1 @@
> -.\" Copyright (C) 2003 Free Software Foundation, Inc.
> -.\" Written by Kent Yoder.
> -.\"
> -.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
> -.\" This file is distributed according to the GNU General Public License.
> -.\" %%%LICENSE_END
> -.\"
> -.TH GET_THREAD_AREA 2 2012-07-13 "Linux" "Linux Programmer's Manual"
> -.SH NAME
> -get_thread_area \- get a thread-local storage (TLS) area
> -.SH SYNOPSIS
> -.B #include <linux/unistd.h>
> -.br
> -.B #include <asm/ldt.h>
> -.sp
> -.BI "int get_thread_area(struct user_desc *" u_info );
> -
> -.IR Note :
> -There is no glibc wrapper for this system call; see NOTES.
> -.SH DESCRIPTION
> -.BR get_thread_area ()
> -returns an entry in the current thread's thread-local storage (TLS) array.
> -The index of the entry corresponds to the value
> -of \fIu_info\->entry_number\fP, passed in by the user.
> -If the value is in bounds,
> -.BR get_thread_area ()
> -copies the corresponding
> -TLS entry into the area pointed to by \fIu_info\fP.
> -.SH RETURN VALUE
> -.BR get_thread_area ()
> -returns 0 on success.
> -Otherwise, it returns \-1 and sets
> -.I errno
> -appropriately.
> -.SH ERRORS
> -.TP
> -.B EFAULT
> -\fIu_info\fP is an invalid pointer.
> -.TP
> -.B EINVAL
> -\fIu_info\->entry_number\fP is out of bounds.
> -.SH VERSIONS
> -A version of
> -.BR get_thread_area ()
> -first appeared in Linux 2.5.32.
> -.SH CONFORMING TO
> -.BR get_thread_area ()
> -is Linux-specific and should not be used in programs
> -that are intended to be portable.
> -.SH NOTES
> -Glibc does not provide a wrapper for this system call,
> -since it is generally intended for use only by threading libraries.
> -In the unlikely event that you want to call it directly, use
> -.BR syscall (2).
> -.SH SEE ALSO
> -.BR modify_ldt (2),
> -.BR set_thread_area (2)
> +.so man2/set_thread_area.2
> diff --git a/man2/set_thread_area.2 b/man2/set_thread_area.2
> index 321beb396312..6acc5f79d1ad 100644
> --- a/man2/set_thread_area.2
> +++ b/man2/set_thread_area.2
> @@ -1,25 +1,54 @@
>  .\" Copyright (C) 2003 Free Software Foundation, Inc.
> +.\" Copyright (C) 2015 Andrew Lutomirski
>  .\" Author: Kent Yoder
>  .\"
>  .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
>  .\" This file is distributed according to the GNU General Public License.
>  .\" %%%LICENSE_END
>  .\"
> -.TH SET_THREAD_AREA 2 2012-07-13 "Linux" "Linux Programmer's Manual"
> +.TH SET_THREAD_AREA 2 2015-01-29 "Linux" "Linux Programmer's Manual"
>  .SH NAME
> -set_thread_area \- set a thread local storage (TLS) area
> +set_thread_area \- set a GDT entry for thread-local storage
>  .SH SYNOPSIS
>  .B #include <linux/unistd.h>
>  .br
>  .B #include <asm/ldt.h>
>  .sp
> +.BI "int get_thread_area(struct user_desc *" u_info );
>  .BI "int set_thread_area(struct user_desc *" u_info );
> +.in +4n
> +.nf
> +
> +struct user_desc {
> +    unsigned int  entry_number;
> +    unsigned long 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;
> +};
> +.fi
> +.in
>  
>  .IR Note :
>  There is no glibc wrapper for this system call; see NOTES.
>  .SH DESCRIPTION
> +Linux dedicates three global descriptor table (GDT) entries for
> +thread-local storage.  For more information about the LDT, see the

s/LDT/GDT? in the previous line, right?

> +Intel Software Developer's Manual or the AMD Architecture Programming Manual.
> +
> +.BR get_thread_area ()
> +reads the GDT entry indicated by
> +.I u_info\->entry_number
> +and fills in the rest of the fields in
> +.I u_info.
> +
>  .BR set_thread_area ()
> -sets an entry in the current thread's thread-local storage (TLS) array.
> +sets a TLS entry in the GDT.
> +.PP
>  The TLS array entry set by
>  .BR set_thread_area ()
>  corresponds to the value of
> @@ -27,7 +56,7 @@ corresponds to the value of
>  passed in by the user.
>  If this value is in bounds,
>  .BR set_thread_area ()
> -copies the TLS descriptor pointed to by
> +writes the TLS descriptor pointed to by
>  .I u_info
>  into the thread's TLS array.
>  .PP
> @@ -35,12 +64,29 @@ When
>  .BR set_thread_area ()
>  is passed an
>  .I entry_number
> -of \-1, it uses a free TLS entry.
> +of \-1, it finds a free TLS entry.

s/finds/searched for/ ?

>  If
>  .BR set_thread_area ()
>  finds a free TLS entry, the value of
>  .I u_info\->entry_number
>  is set upon return to show which entry was changed.
> +.PP
> +A
> +.I user_desc
> +is considered "empty" if
> +.I read_exec_only
> +and
> +.I seg_not_present
> +are set to 1 and all of the other fields are 0.  If an "empty" descriptor
> +is passed to
> +.BR set_thread_area,
> +the corresponding TLS entry will be cleared.  See BUGS for additional
> +details.
> +.PP
> +On Linux 3.19 and newer,
> +.BR set_thread_area ()
> +cannot be used to write non-present segments, 16-bit segments, or code
> +segments, although clearing a segment is still acceptable.
>  .SH RETURN VALUE
>  .BR set_thread_area ()
>  returns 0 on success, and \-1 on failure, with
> @@ -56,6 +102,11 @@ set appropriately.
>  .TP
>  .B ESRCH
>  A free TLS entry could not be located.
> +.B ENOSYS
> +.BR get_thread_area (2)
> +or
> +.BR set_thread_area (2)
> +was invoked as a 64-bit syscall.
>  .SH VERSIONS
>  A version of
>  .BR set_thread_area ()
> @@ -64,10 +115,40 @@ first appeared in Linux 2.5.29.
>  .BR set_thread_area ()
>  is Linux-specific and should not be used in programs that are intended
>  to be portable.
> +.SH BUGS
> +On 64-bit kernels before Linux 3.19, one of the padding bits in

Was that commit e30ab185c490e9a9381385529e0fd32f0a399495 ?

> +.I user_desc,
> +if set, would prevent the descriptor from being considered empty.
> +As a result, the only reliable way to clear a TLS entry is to use
> +memset to zero the entire
> +.I user_desc
> +structure, including padding bits, and then to set the
> +.I read_exec_only
> +and
> +.I seg_not_present
> +bits.  On Linux 3.19, a
> +.I user_desc
> +consisting entirely of zeros except for
> +.I entry_number
> +will also be interpreted as a request to clear a TLS entry, but this
> +behaved differently on older kernels.
> +.PP
> +Prior to Linux 3.19, the DS and ES segment registers must not reference
> +TLS entries.
>  .SH NOTES
>  Glibc does not provide a wrapper for this system call,
>  since it is generally intended only for use by threading libraries.
>  In the unlikely event that you want to call it directly, use
>  .BR syscall (2).
> +.PP
> +.BR arch_prctl (2)
> +can interfere with
> +.BR set_thread_area (2).
> +See
> +.BR arch_prctl (2)
> +for more details.  This is not normally a problem, as
> +.BR arch_prctl (2)
> +is normally only used by 64-bit programs.
>  .SH SEE ALSO
> -.BR get_thread_area (2)
> +.BR arch_prctl (2),
> +.BR modify_ldt (2)

Thanks,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH manpages 2/2] arch_prctl.2, set_thread_area.2, get_thread_area.2: Improve TLS documentation

[Andy Lutomirski]

On Jan 30, 2015 8:59 AM, "Michael Kerrisk (man-pages)"
<mtk.manpages@gmail.com> wrote:
>
> Hi Andy,
>
> Thanks for this!
>
> I've merged this into a branch and done some light editing.
> A few questions below.
>
> On 01/29/2015 10:47 PM, Andy Lutomirski wrote:
> > The documentation for set_thread_area was very vague.  This improves
> > it, accounts for recent kernel changes, and merges it with
> > get_thread_area.2.
>
> (Yep, merging seems a good idea.)
> >
> > While I'm at it, clarify the related arch_prctl.2 man page.
> >
> > Signed-off-by: Andy Lutomirski <luto@amacapital.net>
> > ---
> >  man2/arch_prctl.2      | 22 +++++++-----
> >  man2/get_thread_area.2 | 58 +------------------------------
> >  man2/set_thread_area.2 | 93 ++++++++++++++++++++++++++++++++++++++++++++++----
> >  3 files changed, 102 insertions(+), 71 deletions(-)
> >
> > diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
> > index a3ab2b566915..c89fa3c7b744 100644
> > --- a/man2/arch_prctl.2
> > +++ b/man2/arch_prctl.2
> > @@ -114,27 +114,33 @@ The 64-bit base changes when a new 32-bit segment selector is loaded.
> >  is disabled in some kernels.
> >
> >  Context switches for 64-bit segment bases are rather expensive.
> > -It may be a faster alternative to set a 32-bit base using a
> > -segment selector by setting up an LDT with
> > -.BR modify_ldt (2)
> > -or using the
> > +As an optimization, if a 32-bit TLS base address is used,
> > +.BR arch_prctl (2)
> > +may use a real TLS entry as if
> >  .BR set_thread_area (2)
> > -system call in kernel 2.5 or later.
> > -.BR arch_prctl ()
> > -is needed only when you want to set bases that are larger than 4GB.
> > +had been called instead of manipulating the segment base register directly.
> >  Memory in the first 2GB of address space can be allocated by using
> >  .BR mmap (2)
> >  with the
> >  .B MAP_32BIT
> >  flag.
> >
> > +As a result, using
>
> Something doesn't quite flow here. "As a result" *of what*? Should this rather
> be something like:
>
>     Because of the aforementioned optimization, using

Sure.

>
> > +.BR arch_prctl (2)
> > +and
> > +.BR set_thread_area (2)
> > +in the same thread is dangerous, as they may overwrite each other's
> > +TLS entries.
> > +
> >  As of version 2.7, glibc provides no prototype for
> >  .BR arch_prctl ().
> >  You have to declare it yourself for now.
> >  This may be fixed in future glibc versions.
> >
> >  .I FS
> > -may be already used by the threading library.
> > +may be already used by the threading library.  Glibc programs that use
>
> What is a "Glibc program"?

A program that links against glibc.  Maybe that should just say "Programs".

The idea I'm trying to get across is that using ARCH_SET_FS for
private purposes is a bad idea, since your threading library
(glibc/libpthread) is very likely to use ARCH_SET_FS for its own
purposes.  ARCH_SET_GS, on the other hand, is more likely to be
available for private use.

This is most relevant for programs written for the purpose of testing
arch_prctl -- using ARCH_SET_FS following by calling any glibc
function is very likely to segfault.

>
> > +.I ARCH_SET_FS
> > +directly are very likely to crash.
> >  .SH SEE ALSO
> >  .BR mmap (2),
> >  .BR modify_ldt (2),
> > diff --git a/man2/get_thread_area.2 b/man2/get_thread_area.2
> > index 08589e413cc4..a03fe54fb08e 100644
> > --- a/man2/get_thread_area.2
> > +++ b/man2/get_thread_area.2
> > @@ -1,57 +1 @@
> > -.\" Copyright (C) 2003 Free Software Foundation, Inc.
> > -.\" Written by Kent Yoder.
> > -.\"
> > -.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
> > -.\" This file is distributed according to the GNU General Public License.
> > -.\" %%%LICENSE_END
> > -.\"
> > -.TH GET_THREAD_AREA 2 2012-07-13 "Linux" "Linux Programmer's Manual"
> > -.SH NAME
> > -get_thread_area \- get a thread-local storage (TLS) area
> > -.SH SYNOPSIS
> > -.B #include <linux/unistd.h>
> > -.br
> > -.B #include <asm/ldt.h>
> > -.sp
> > -.BI "int get_thread_area(struct user_desc *" u_info );
> > -
> > -.IR Note :
> > -There is no glibc wrapper for this system call; see NOTES.
> > -.SH DESCRIPTION
> > -.BR get_thread_area ()
> > -returns an entry in the current thread's thread-local storage (TLS) array.
> > -The index of the entry corresponds to the value
> > -of \fIu_info\->entry_number\fP, passed in by the user.
> > -If the value is in bounds,
> > -.BR get_thread_area ()
> > -copies the corresponding
> > -TLS entry into the area pointed to by \fIu_info\fP.
> > -.SH RETURN VALUE
> > -.BR get_thread_area ()
> > -returns 0 on success.
> > -Otherwise, it returns \-1 and sets
> > -.I errno
> > -appropriately.
> > -.SH ERRORS
> > -.TP
> > -.B EFAULT
> > -\fIu_info\fP is an invalid pointer.
> > -.TP
> > -.B EINVAL
> > -\fIu_info\->entry_number\fP is out of bounds.
> > -.SH VERSIONS
> > -A version of
> > -.BR get_thread_area ()
> > -first appeared in Linux 2.5.32.
> > -.SH CONFORMING TO
> > -.BR get_thread_area ()
> > -is Linux-specific and should not be used in programs
> > -that are intended to be portable.
> > -.SH NOTES
> > -Glibc does not provide a wrapper for this system call,
> > -since it is generally intended for use only by threading libraries.
> > -In the unlikely event that you want to call it directly, use
> > -.BR syscall (2).
> > -.SH SEE ALSO
> > -.BR modify_ldt (2),
> > -.BR set_thread_area (2)
> > +.so man2/set_thread_area.2
> > diff --git a/man2/set_thread_area.2 b/man2/set_thread_area.2
> > index 321beb396312..6acc5f79d1ad 100644
> > --- a/man2/set_thread_area.2
> > +++ b/man2/set_thread_area.2
> > @@ -1,25 +1,54 @@
> >  .\" Copyright (C) 2003 Free Software Foundation, Inc.
> > +.\" Copyright (C) 2015 Andrew Lutomirski
> >  .\" Author: Kent Yoder
> >  .\"
> >  .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
> >  .\" This file is distributed according to the GNU General Public License.
> >  .\" %%%LICENSE_END
> >  .\"
> > -.TH SET_THREAD_AREA 2 2012-07-13 "Linux" "Linux Programmer's Manual"
> > +.TH SET_THREAD_AREA 2 2015-01-29 "Linux" "Linux Programmer's Manual"
> >  .SH NAME
> > -set_thread_area \- set a thread local storage (TLS) area
> > +set_thread_area \- set a GDT entry for thread-local storage
> >  .SH SYNOPSIS
> >  .B #include <linux/unistd.h>
> >  .br
> >  .B #include <asm/ldt.h>
> >  .sp
> > +.BI "int get_thread_area(struct user_desc *" u_info );
> >  .BI "int set_thread_area(struct user_desc *" u_info );
> > +.in +4n
> > +.nf
> > +
> > +struct user_desc {
> > +    unsigned int  entry_number;
> > +    unsigned long 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;
> > +};
> > +.fi
> > +.in
> >
> >  .IR Note :
> >  There is no glibc wrapper for this system call; see NOTES.
> >  .SH DESCRIPTION
> > +Linux dedicates three global descriptor table (GDT) entries for
> > +thread-local storage.  For more information about the LDT, see the
>
> s/LDT/GDT? in the previous line, right?

Yes.

--Andy

>
> > +Intel Software Developer's Manual or the AMD Architecture Programming Manual.
> > +
> > +.BR get_thread_area ()
> > +reads the GDT entry indicated by
> > +.I u_info\->entry_number
> > +and fills in the rest of the fields in
> > +.I u_info.
> > +
> >  .BR set_thread_area ()
> > -sets an entry in the current thread's thread-local storage (TLS) array.
> > +sets a TLS entry in the GDT.
> > +.PP
> >  The TLS array entry set by
> >  .BR set_thread_area ()
> >  corresponds to the value of
> > @@ -27,7 +56,7 @@ corresponds to the value of
> >  passed in by the user.
> >  If this value is in bounds,
> >  .BR set_thread_area ()
> > -copies the TLS descriptor pointed to by
> > +writes the TLS descriptor pointed to by
> >  .I u_info
> >  into the thread's TLS array.
> >  .PP
> > @@ -35,12 +64,29 @@ When
> >  .BR set_thread_area ()
> >  is passed an
> >  .I entry_number
> > -of \-1, it uses a free TLS entry.
> > +of \-1, it finds a free TLS entry.
>
> s/finds/searched for/ ?

How about "searches for"?

>
> >  If
> >  .BR set_thread_area ()
> >  finds a free TLS entry, the value of
> >  .I u_info\->entry_number
> >  is set upon return to show which entry was changed.
> > +.PP
> > +A
> > +.I user_desc
> > +is considered "empty" if
> > +.I read_exec_only
> > +and
> > +.I seg_not_present
> > +are set to 1 and all of the other fields are 0.  If an "empty" descriptor
> > +is passed to
> > +.BR set_thread_area,
> > +the corresponding TLS entry will be cleared.  See BUGS for additional
> > +details.
> > +.PP
> > +On Linux 3.19 and newer,
> > +.BR set_thread_area ()
> > +cannot be used to write non-present segments, 16-bit segments, or code
> > +segments, although clearing a segment is still acceptable.
> >  .SH RETURN VALUE
> >  .BR set_thread_area ()
> >  returns 0 on success, and \-1 on failure, with
> > @@ -56,6 +102,11 @@ set appropriately.
> >  .TP
> >  .B ESRCH
> >  A free TLS entry could not be located.
> > +.B ENOSYS
> > +.BR get_thread_area (2)
> > +or
> > +.BR set_thread_area (2)
> > +was invoked as a 64-bit syscall.
> >  .SH VERSIONS
> >  A version of
> >  .BR set_thread_area ()
> > @@ -64,10 +115,40 @@ first appeared in Linux 2.5.29.
> >  .BR set_thread_area ()
> >  is Linux-specific and should not be used in programs that are intended
> >  to be portable.
> > +.SH BUGS
> > +On 64-bit kernels before Linux 3.19, one of the padding bits in
>
> Was that commit e30ab185c490e9a9381385529e0fd32f0a399495 ?

Yes.

>
> > +.I user_desc,
> > +if set, would prevent the descriptor from being considered empty.
> > +As a result, the only reliable way to clear a TLS entry is to use
> > +memset to zero the entire
> > +.I user_desc
> > +structure, including padding bits, and then to set the
> > +.I read_exec_only
> > +and
> > +.I seg_not_present
> > +bits.  On Linux 3.19, a
> > +.I user_desc
> > +consisting entirely of zeros except for
> > +.I entry_number
> > +will also be interpreted as a request to clear a TLS entry, but this
> > +behaved differently on older kernels.
> > +.PP
> > +Prior to Linux 3.19, the DS and ES segment registers must not reference
> > +TLS entries.
> >  .SH NOTES
> >  Glibc does not provide a wrapper for this system call,
> >  since it is generally intended only for use by threading libraries.
> >  In the unlikely event that you want to call it directly, use
> >  .BR syscall (2).
> > +.PP
> > +.BR arch_prctl (2)
> > +can interfere with
> > +.BR set_thread_area (2).
> > +See
> > +.BR arch_prctl (2)
> > +for more details.  This is not normally a problem, as
> > +.BR arch_prctl (2)
> > +is normally only used by 64-bit programs.
> >  .SH SEE ALSO
> > -.BR get_thread_area (2)
> > +.BR arch_prctl (2),
> > +.BR modify_ldt (2)
>
> Thanks,
>
> Michael
>
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH manpages 2/2] arch_prctl.2, set_thread_area.2, get_thread_area.2: Improve TLS documentation

[Michael Kerrisk (man-pages)]

On 01/30/2015 03:45 PM, Andy Lutomirski wrote:
> On Jan 30, 2015 8:59 AM, "Michael Kerrisk (man-pages)"
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>
>> Hi Andy,
>>
>> Thanks for this!
>>
>> I've merged this into a branch and done some light editing.
>> A few questions below.
>>
>> On 01/29/2015 10:47 PM, Andy Lutomirski wrote:
>>> The documentation for set_thread_area was very vague.  This improves
>>> it, accounts for recent kernel changes, and merges it with
>>> get_thread_area.2.
>>
>> (Yep, merging seems a good idea.)
>>>
>>> While I'm at it, clarify the related arch_prctl.2 man page.
>>>
>>> Signed-off-by: Andy Lutomirski <luto-kltTT9wpgjJwATOyAt5JVQ@public.gmane.org>
>>> ---
>>>  man2/arch_prctl.2      | 22 +++++++-----
>>>  man2/get_thread_area.2 | 58 +------------------------------
>>>  man2/set_thread_area.2 | 93 ++++++++++++++++++++++++++++++++++++++++++++++----
>>>  3 files changed, 102 insertions(+), 71 deletions(-)
>>>
>>> diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
>>> index a3ab2b566915..c89fa3c7b744 100644
>>> --- a/man2/arch_prctl.2
>>> +++ b/man2/arch_prctl.2
>>> @@ -114,27 +114,33 @@ The 64-bit base changes when a new 32-bit segment selector is loaded.
>>>  is disabled in some kernels.
>>>
>>>  Context switches for 64-bit segment bases are rather expensive.
>>> -It may be a faster alternative to set a 32-bit base using a
>>> -segment selector by setting up an LDT with
>>> -.BR modify_ldt (2)
>>> -or using the
>>> +As an optimization, if a 32-bit TLS base address is used,
>>> +.BR arch_prctl (2)
>>> +may use a real TLS entry as if
>>>  .BR set_thread_area (2)
>>> -system call in kernel 2.5 or later.
>>> -.BR arch_prctl ()
>>> -is needed only when you want to set bases that are larger than 4GB.
>>> +had been called instead of manipulating the segment base register directly.
>>>  Memory in the first 2GB of address space can be allocated by using
>>>  .BR mmap (2)
>>>  with the
>>>  .B MAP_32BIT
>>>  flag.
>>>
>>> +As a result, using
>>
>> Something doesn't quite flow here. "As a result" *of what*? Should this rather
>> be something like:
>>
>>     Because of the aforementioned optimization, using
> 
> Sure.

Changed.

>>> +.BR arch_prctl (2)
>>> +and
>>> +.BR set_thread_area (2)
>>> +in the same thread is dangerous, as they may overwrite each other's
>>> +TLS entries.
>>> +
>>>  As of version 2.7, glibc provides no prototype for
>>>  .BR arch_prctl ().
>>>  You have to declare it yourself for now.
>>>  This may be fixed in future glibc versions.
>>>
>>>  .I FS
>>> -may be already used by the threading library.
>>> +may be already used by the threading library.  Glibc programs that use
>>
>> What is a "Glibc program"?
> 
> A program that links against glibc.  Maybe that should just say "Programs".


Okay /S/Glibc programs/Programs/

> The idea I'm trying to get across is that using ARCH_SET_FS for
> private purposes is a bad idea, since your threading library
> (glibc/libpthread) is very likely to use ARCH_SET_FS for its own
> purposes.  ARCH_SET_GS, on the other hand, is more likely to be
> available for private use.
> 
> This is most relevant for programs written for the purpose of testing
> arch_prctl -- using ARCH_SET_FS following by calling any glibc
> function is very likely to segfault.

(Okay.)

[...]

>>> diff --git a/man2/get_thread_area.2 b/man2/get_thread_area.2
>>> index 08589e413cc4..a03fe54fb08e 100644
>>> --- a/man2/set_thread_area.2
>>> +++ b/man2/set_thread_area.2
>>>  .IR Note :
>>>  There is no glibc wrapper for this system call; see NOTES.
>>>  .SH DESCRIPTION
>>> +Linux dedicates three global descriptor table (GDT) entries for
>>> +thread-local storage.  For more information about the LDT, see the
>>
>> s/LDT/GDT? in the previous line, right?
> 
> Yes.

Fixed.

>>> +Intel Software Developer's Manual or the AMD Architecture Programming Manual.
>>> +
>>> +.BR get_thread_area ()
>>> +reads the GDT entry indicated by
>>> +.I u_info\->entry_number
>>> +and fills in the rest of the fields in
>>> +.I u_info.
>>> +
>>>  .BR set_thread_area ()
>>> -sets an entry in the current thread's thread-local storage (TLS) array.
>>> +sets a TLS entry in the GDT.
>>> +.PP
>>>  The TLS array entry set by
>>>  .BR set_thread_area ()
>>>  corresponds to the value of
>>> @@ -27,7 +56,7 @@ corresponds to the value of
>>>  passed in by the user.
>>>  If this value is in bounds,
>>>  .BR set_thread_area ()
>>> -copies the TLS descriptor pointed to by
>>> +writes the TLS descriptor pointed to by
>>>  .I u_info
>>>  into the thread's TLS array.
>>>  .PP
>>> @@ -35,12 +64,29 @@ When
>>>  .BR set_thread_area ()
>>>  is passed an
>>>  .I entry_number
>>> -of \-1, it uses a free TLS entry.
>>> +of \-1, it finds a free TLS entry.
>>
>> s/finds/searched for/ ?
> 
> How about "searches for"?

D'oh! That's what I meant. Changed.

[...]

>>> +.SH BUGS
>>> +On 64-bit kernels before Linux 3.19, one of the padding bits in
>>
>> Was that commit e30ab185c490e9a9381385529e0fd32f0a399495 ?
> 
> Yes.

Okay.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html