Improve modify_ldt, [gs]et_thread_area docs

PATCH In review Andy Lutomirski 2 participants 10 messages Jan 29, 2015 – Jan 30, 2015 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Andy Lutomirski

author

2015-01-29 21:48 UTC #0 lore raw

cover Improve modify_ldt, [gs]et_thread_area docs

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.

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(-)

Signature · 1 line

2.1.0

Andy Lutomirski

author

2015-01-29 21:48 UTC #1 lore raw

PATCH 1/2 modify_ldt.2: Overhaul the documentation

This clarifies the behavior and documents all four functions.

Signed-off-by Andy Lutomirski <[email protected]>

---
 man2/modify_ldt.2 | 101 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 78 insertions(+), 23 deletions(-)

man2/modify_ldt.2 +78 ~~-23~~

index d128664716c6..f3cc94d397b3 100644
@@ -1,4 +1,5 @@
 .\" Copyright (c) 1995 Michael Chastain ([email protected]), 22 July 1995.
+.\" Copyright (c) 2015 Andrew Lutomirski
 .\"
 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
 .\" This is free documentation; you can redistribute it and/or

@@ -23,37 +24,43 @@
 .\"
 .TH MODIFY_LDT 2 2012-07-13 "Linux" "Linux Programmer's Manual"
 .SH NAME
-modify_ldt \- get or set ldt
+modify_ldt \- get or set a per-process LDT entry
 .SH SYNOPSIS
 .nf
 .B #include <sys/types.h>
 .sp
 .BI "int modify_ldt(int " "func" ", void *" "ptr" ", unsigned long " "bytecount" );
 .fi
-
+.PP
 .IR Note :
 There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
 .BR modify_ldt ()
-reads or writes the local descriptor table (ldt) for a process.
-The ldt is a per-process memory management table used by the i386 processor.
-For more information on this table, see an Intel 386 processor handbook.
+reads or writes the local descriptor table (LDT) for a process.  The LDT
+is an array of segment descriptors that can be referenced by user code.
+Linux allows processes to configure a per-process (actually per-mm) LDT.
+For more information about the LDT, see the Intel Software Developer's
+Manual or the AMD Architecture Programming Manual.
 .PP
 When
 .I func
 is 0,
 .BR modify_ldt ()
-reads the ldt into the memory pointed to by
+reads the LDT into the memory pointed to by
 .IR ptr .
 The number of bytes read is the smaller of
 .I bytecount
-and the actual size of the ldt.
+and the actual size of the LDT, although the kernel may act as though
+the LDT is padded with additional trailing zero bytes.  On success,
+.BR modify_ldt ()
+will return the number of bytes read.
 .PP
 When
 .I func
-is 1,
+is 1 or 0x11,
 .BR modify_ldt ()
-modifies one ldt entry.
+modifies the LDT entry indicated by
+.I ptr\->entry_number.
 .I ptr
 points to a
 .I user_desc

@@ -61,11 +68,6 @@ structure
 and
 .I bytecount
 must equal the size of this structure.
-.\"
-.\" FIXME Should this page say something about func == 2 and func == 0x11?
-.\" In Linux 2.4, func == 2 returned "the default ldt"
-.\" In Linux 2.6, func == 2 is a nop, returning a zeroed out structure.
-.\" Linux 2.4 and 2.6 implement an operation for func == 0x11
 
 The
 .I user_desc

@@ -89,12 +91,44 @@ struct user_desc {
 .PP
 In Linux 2.4 and earlier, this structure was named
 .IR modify_ldt_ldt_s .
-.\" .PP
-.\" The ldt is specific for the calling process. Any attempts to change
-.\" the ldt to include the address space of another process or the kernel
-.\" will result in a segmentation violation when trying to access the memory
-.\" outside of the process address space. The memory protection is enforced
-.\" at the paging layer.
+.PP
+The
+.I contents
+field is the segment type (data, expand-down data, non-conforming code, or
+conforming code).  The other fields match their descriptions in the
+CPU manual, although
+.BR modify_ldt ()
+cannot set the accessed bit.
+.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.
+An LDT entry can be cleared by setting it to an "empty"
+.I user_desc
+or, if
+.I func
+is 1, by setting both
+.I base
+and
+.I limit
+to 0.
+.PP
+A conforming code segment will be rejected if
+.I
+func
+is 1 or if
+.I seg_not_present
+is 0.
+.PP
+When
+.I func
+is 2,
+.BR modify_ldt ()
+will read zeros.  This appears to be a leftover from Linux 2.4.
 .SH RETURN VALUE
 On success,
 .BR modify_ldt ()

@@ -119,19 +153,40 @@ or
 is 1 and
 .I bytecount
 is not equal to the size of the structure
-.IR modify_ldt_ldt_s ,
+.IR user_desc ,
 or
 .I func
-is 1 and the new ldt entry has invalid values.
+is 1 or 0x11 and the new ldt entry has invalid values.
 .TP
 .B ENOSYS
 .I func
-is neither 0 nor 1.
+is neither 0, 1, 2, nor 0x11.
 .SH CONFORMING TO
 This call is Linux-specific and should not be used in programs intended
 to be portable.
+.SH BUGS
+On 64-bit kernels before Linux 3.19, one of the padding bits in
+.I user_desc,
+if set, would prevent the descriptor from being considered empty.
 .SH NOTES
 Glibc does not provide a wrapper for this system call; call it using
 .BR syscall (2).
+.PP
+.BR modify_ldt ()
+should not be used for thread-local storage, as it slows down context
+switches and only supports a limited number of threads.  Threading libraries
+should use
+.BR set_thread_area (2)
+or
+.BR arch_prctl (2)
+instead, except on extremely old kernels that do not support those system
+calls.
+.PP
+The normal use for
+.BR modify_ldt (2)
+is to run legacy 16-bit or segmented 32-bit code.  Not all kernels allow
+16-bit segments to be installed, however.
 .SH SEE ALSO
+.BR set_thread_area (2),
+.BR arch_prctl (2),
 .BR vm86 (2)

Signature · 1 line

2.1.0

Michael Kerrisk (man-pages)

2015-01-30 12:18 UTC #2 lore raw

Re: [PATCH manpages 1/2] modify_ldt.2: Overhaul the documentation

Hi Andy,

Quoted 1 line · Andy Lutomirski

This clarifies the behavior and documents all four functions.

Thanks! I've merged this in a branch, pending one or two questions below.

Quoted 88 lines

Signed-off-by Andy Lutomirski <[email protected]>

---
 man2/modify_ldt.2 | 101 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 78 insertions(+), 23 deletions(-)

man2/modify_ldt.2 +16 ~~-18~~

index d128664716c6..f3cc94d397b3 100644
@@ -1,4 +1,5 @@
 .\" Copyright (c) 1995 Michael Chastain ([email protected]), 22 July 1995.
+.\" Copyright (c) 2015 Andrew Lutomirski
 .\"
 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
 .\" This is free documentation; you can redistribute it and/or

@@ -23,37 +24,43 @@
 .\"
 .TH MODIFY_LDT 2 2012-07-13 "Linux" "Linux Programmer's Manual"
 .SH NAME
-modify_ldt \- get or set ldt
+modify_ldt \- get or set a per-process LDT entry
 .SH SYNOPSIS
 .nf
 .B #include <sys/types.h>
 .sp
 .BI "int modify_ldt(int " "func" ", void *" "ptr" ", unsigned long " "bytecount" );
 .fi
-
+.PP
 .IR Note :
 There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
 .BR modify_ldt ()
-reads or writes the local descriptor table (ldt) for a process.
-The ldt is a per-process memory management table used by the i386 processor.
-For more information on this table, see an Intel 386 processor handbook.
+reads or writes the local descriptor table (LDT) for a process.  The LDT
+is an array of segment descriptors that can be referenced by user code.
+Linux allows processes to configure a per-process (actually per-mm) LDT.
+For more information about the LDT, see the Intel Software Developer's
+Manual or the AMD Architecture Programming Manual.
 .PP
 When
 .I func
 is 0,
 .BR modify_ldt ()
-reads the ldt into the memory pointed to by
+reads the LDT into the memory pointed to by
 .IR ptr .
 The number of bytes read is the smaller of
 .I bytecount
-and the actual size of the ldt.
+and the actual size of the LDT, although the kernel may act as though
+the LDT is padded with additional trailing zero bytes.  On success,
+.BR modify_ldt ()
+will return the number of bytes read.
 .PP
 When
 .I func
-is 1,
+is 1 or 0x11,
 .BR modify_ldt ()
-modifies one ldt entry.
+modifies the LDT entry indicated by
+.I ptr\->entry_number.
 .I ptr
 points to a
 .I user_desc

@@ -61,11 +68,6 @@ structure
 and
 .I bytecount
 must equal the size of this structure.
-.\"
-.\" FIXME Should this page say something about func == 2 and func == 0x11?
-.\" In Linux 2.4, func == 2 returned "the default ldt"
-.\" In Linux 2.6, func == 2 is a nop, returning a zeroed out structure.
-.\" Linux 2.4 and 2.6 implement an operation for func == 0x11
 
 The
 .I user_desc

@@ -89,12 +91,44 @@ struct user_desc {
 .PP
 In Linux 2.4 and earlier, this structure was named
 .IR modify_ldt_ldt_s .
-.\" .PP
-.\" The ldt is specific for the calling process. Any attempts to change
-.\" the ldt to include the address space of another process or the kernel
-.\" will result in a segmentation violation when trying to access the memory

man2/modify_ldt.2 struct user_desc { · line 101

Quoted 10 lines

man2/modify_ldt.2 +8 -2

-.\" outside of the process address space. The memory protection is enforced
-.\" at the paging layer.
+.PP
+The
+.I contents
+field is the segment type (data, expand-down data, non-conforming code, or
+conforming code).  The other fields match their descriptions in the
+CPU manual, although
+.BR modify_ldt ()
+cannot set the accessed bit.

The "accessed bit" is mentioned here for the first time. Is this something described in the CPU Manual? If so, we better say that. As it is, I started hunting the rest of this man page for an explanation of this bit, without success.

Quoted 14 lines

man2/modify_ldt.2 +14 -0

+.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.
+An LDT entry can be cleared by setting it to an "empty"
+.I user_desc
+or, if
+.I func
+is 1, by setting both
+.I base

man2/modify_ldt.2 struct user_desc { · line 125

Quoted 10 lines

man2/modify_ldt.2 +10 -0

+and
+.I limit
+to 0.
+.PP
+A conforming code segment will be rejected if
+.I
+func
+is 1 or if
+.I seg_not_present
+is 0.

It's not clear what a "conforming code segment is". Should some words be added here?

Quoted 19 lines

man2/modify_ldt.2 +8 -2

+.PP
+When
+.I func
+is 2,
+.BR modify_ldt ()
+will read zeros.  This appears to be a leftover from Linux 2.4.
 .SH RETURN VALUE
 On success,
 .BR modify_ldt ()

@@ -119,19 +153,40 @@ or
 is 1 and
 .I bytecount
 is not equal to the size of the structure
-.IR modify_ldt_ldt_s ,
+.IR user_desc ,
 or
 .I func
-is 1 and the new ldt entry has invalid values.
+is 1 or 0x11 and the new ldt entry has invalid values.

man2/modify_ldt.2 or · line 168

Quoted 10 lines

man2/modify_ldt.2 +3 -1

 .TP
 .B ENOSYS
 .I func
-is neither 0 nor 1.
+is neither 0, 1, 2, nor 0x11.
 .SH CONFORMING TO
 This call is Linux-specific and should not be used in programs intended
 to be portable.
+.SH BUGS
+On 64-bit kernels before Linux 3.19, one of the padding bits in

Was that commit e30ab185c490e9a9381385529e0fd32f0a399495 ?

Quoted 14 lines

man2/modify_ldt.2 +11 -0

+.I user_desc,
+if set, would prevent the descriptor from being considered empty.
 .SH NOTES
 Glibc does not provide a wrapper for this system call; call it using
 .BR syscall (2).
+.PP
+.BR modify_ldt ()
+should not be used for thread-local storage, as it slows down context
+switches and only supports a limited number of threads.  Threading libraries
+should use
+.BR set_thread_area (2)
+or
+.BR arch_prctl (2)
+instead, except on extremely old kernels that do not support those system

man2/modify_ldt.2 or · line 192

Quoted 10 lines

man2/modify_ldt.2 +8 -0

+calls.
+.PP
+The normal use for
+.BR modify_ldt (2)
+is to run legacy 16-bit or segmented 32-bit code.  Not all kernels allow
+16-bit segments to be installed, however.
 .SH SEE ALSO
+.BR set_thread_area (2),
+.BR arch_prctl (2),
 .BR vm86 (2)

Thanks,

Michael

Signature · 3 lines

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

Andy Lutomirski

author

2015-01-30 14:43 UTC #3 lore raw

Re: [PATCH manpages 1/2] modify_ldt.2: Overhaul the documentation

Quoted 103 lines · Michael Kerrisk (man-pages)

Hi Andy,

Quoted 1 line · Andy Lutomirski

This clarifies the behavior and documents all four functions.

Thanks! I've merged this in a branch, pending one or two questions below.

Quoted 95 lines

Signed-off-by Andy Lutomirski <[email protected]>

---
 man2/modify_ldt.2 | 101 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 78 insertions(+), 23 deletions(-)

man2/modify_ldt.2 +21 ~~-20~~

index d128664716c6..f3cc94d397b3 100644
@@ -1,4 +1,5 @@
 .\" Copyright (c) 1995 Michael Chastain ([email protected]), 22 July 1995.
+.\" Copyright (c) 2015 Andrew Lutomirski
 .\"
 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
 .\" This is free documentation; you can redistribute it and/or

@@ -23,37 +24,43 @@
 .\"
 .TH MODIFY_LDT 2 2012-07-13 "Linux" "Linux Programmer's Manual"
 .SH NAME
-modify_ldt \- get or set ldt
+modify_ldt \- get or set a per-process LDT entry
 .SH SYNOPSIS
 .nf
 .B #include <sys/types.h>
 .sp
 .BI "int modify_ldt(int " "func" ", void *" "ptr" ", unsigned long " "bytecount" );
 .fi
-
+.PP
 .IR Note :
 There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
 .BR modify_ldt ()
-reads or writes the local descriptor table (ldt) for a process.
-The ldt is a per-process memory management table used by the i386 processor.
-For more information on this table, see an Intel 386 processor handbook.
+reads or writes the local descriptor table (LDT) for a process.  The LDT
+is an array of segment descriptors that can be referenced by user code.
+Linux allows processes to configure a per-process (actually per-mm) LDT.
+For more information about the LDT, see the Intel Software Developer's
+Manual or the AMD Architecture Programming Manual.
 .PP
 When
 .I func
 is 0,
 .BR modify_ldt ()
-reads the ldt into the memory pointed to by
+reads the LDT into the memory pointed to by
 .IR ptr .
 The number of bytes read is the smaller of
 .I bytecount
-and the actual size of the ldt.
+and the actual size of the LDT, although the kernel may act as though
+the LDT is padded with additional trailing zero bytes.  On success,
+.BR modify_ldt ()
+will return the number of bytes read.
 .PP
 When
 .I func
-is 1,
+is 1 or 0x11,
 .BR modify_ldt ()
-modifies one ldt entry.
+modifies the LDT entry indicated by
+.I ptr\->entry_number.
 .I ptr
 points to a
 .I user_desc

@@ -61,11 +68,6 @@ structure
 and
 .I bytecount
 must equal the size of this structure.
-.\"
-.\" FIXME Should this page say something about func == 2 and func == 0x11?
-.\" In Linux 2.4, func == 2 returned "the default ldt"
-.\" In Linux 2.6, func == 2 is a nop, returning a zeroed out structure.
-.\" Linux 2.4 and 2.6 implement an operation for func == 0x11
 
 The
 .I user_desc

@@ -89,12 +91,44 @@ struct user_desc {
 .PP
 In Linux 2.4 and earlier, this structure was named
 .IR modify_ldt_ldt_s .
-.\" .PP
-.\" The ldt is specific for the calling process. Any attempts to change
-.\" the ldt to include the address space of another process or the kernel
-.\" will result in a segmentation violation when trying to access the memory
-.\" outside of the process address space. The memory protection is enforced
-.\" at the paging layer.
+.PP
+The
+.I contents
+field is the segment type (data, expand-down data, non-conforming code, or
+conforming code).  The other fields match their descriptions in the

Quoted 8 lines

man2/modify_ldt.2 struct user_desc { · line 101
Quoted 3 lines
man2/modify_ldt.2 +3 -0
+CPU manual, although
+.BR modify_ldt ()
+cannot set the accessed bit.
The "accessed bit" is mentioned here for the first time. Is this something described in the CPU Manual? If so, we better say that. As it is, I started hunting the rest of this man page for an explanation of this bit, without success.

Yes, it's in the CPU manual. Could we say "cannot set the hardware-defined accessed bit"?

Quoted 20 lines

man2/modify_ldt.2 +19 -0

+.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.
+An LDT entry can be cleared by setting it to an "empty"
+.I user_desc
+or, if
+.I func
+is 1, by setting both
+.I base
+and
+.I limit
+to 0.
+.PP
+A conforming code segment will be rejected if

Quoted 8 lines

man2/modify_ldt.2 struct user_desc { · line 125
Quoted 5 lines
man2/modify_ldt.2 +5 -0
+.I
+func
+is 1 or if
+.I seg_not_present
+is 0.
It's not clear what a "conforming code segment is". Should some words be added here?

How about "conforming code segment (i.e. contents == 3)"?

Quoted 24 lines

man2/modify_ldt.2 +8 -3

+.PP
+When
+.I func
+is 2,
+.BR modify_ldt ()
+will read zeros.  This appears to be a leftover from Linux 2.4.
 .SH RETURN VALUE
 On success,
 .BR modify_ldt ()

@@ -119,19 +153,40 @@ or
 is 1 and
 .I bytecount
 is not equal to the size of the structure
-.IR modify_ldt_ldt_s ,
+.IR user_desc ,
 or
 .I func
-is 1 and the new ldt entry has invalid values.
+is 1 or 0x11 and the new ldt entry has invalid values.
 .TP
 .B ENOSYS
 .I func
-is neither 0 nor 1.

Quoted 8 lines

man2/modify_ldt.2 or · line 168
Quoted 6 lines
man2/modify_ldt.2 +3 -0
+is neither 0, 1, 2, nor 0x11.
 .SH CONFORMING TO
 This call is Linux-specific and should not be used in programs 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.

It could be worth adding a note somewhere that 64-bit kernels define a user_desc bit called "lm", but that its only effect is to interfere with detection of "empty" descriptors on older kernels. It may be further worth noting somewhere that it is not possible to use modify_ldt(2) to install a long mode segment.

--Andy

Quoted 35 lines

Quoted 15 lines

man2/modify_ldt.2 +11 -0

+.I user_desc,
+if set, would prevent the descriptor from being considered empty.
 .SH NOTES
 Glibc does not provide a wrapper for this system call; call it using
 .BR syscall (2).
+.PP
+.BR modify_ldt ()
+should not be used for thread-local storage, as it slows down context
+switches and only supports a limited number of threads.  Threading libraries
+should use
+.BR set_thread_area (2)
+or
+.BR arch_prctl (2)
+instead, except on extremely old kernels that do not support those system

man2/modify_ldt.2 or · line 192

Quoted 10 lines

man2/modify_ldt.2 +8 -0

+calls.
+.PP
+The normal use for
+.BR modify_ldt (2)
+is to run legacy 16-bit or segmented 32-bit code.  Not all kernels allow
+16-bit segments to be installed, however.
 .SH SEE ALSO
+.BR set_thread_area (2),
+.BR arch_prctl (2),
 .BR vm86 (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/

Michael Kerrisk (man-pages)

2015-01-30 15:21 UTC #4 lore raw

Re: [PATCH manpages 1/2] modify_ldt.2: Overhaul the documentation

Hi Andy,

Quoted 19 lines · Andy Lutomirski

Quoted 17 lines · Michael Kerrisk (man-pages)
Hi Andy,
Quoted 1 line · Andy Lutomirski
This clarifies the behavior and documents all four functions.
Thanks! I've merged this in a branch, pending one or two questions below.
Quoted 9 lines
Signed-off-by Andy Lutomirski <[email protected]>
---
 man2/modify_ldt.2 | 101 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 78 insertions(+), 23 deletions(-)
man2/modify_ldt.2 +0 -0
index d128664716c6..f3cc94d397b3 100644

[...]

Quoted 14 lines

Quoted 5 lines
Quoted 5 lines
+.PP
man2/modify_ldt.2 +4 -0
+The
+.I contents
+field is the segment type (data, expand-down data, non-conforming code, or
+conforming code).  The other fields match their descriptions in the
Quoted 8 lines
man2/modify_ldt.2 struct user_desc { · line 101
Quoted 3 lines
man2/modify_ldt.2 +3 -0
+CPU manual, although
+.BR modify_ldt ()
+cannot set the accessed bit.
The "accessed bit" is mentioned here for the first time. Is this something described in the CPU Manual? If so, we better say that. As it is, I started hunting the rest of this man page for an explanation of this bit, without success.

Quoted 2 lines

Yes, it's in the CPU manual. Could we say "cannot set the hardware-defined accessed bit"?

I made it "the hardware-defined "accessed" bit described in the CPU manual".

[...]

Quoted 11 lines

Quoted 10 lines
man2/modify_ldt.2 struct user_desc { · line 125
Quoted 7 lines
+.PP
man2/modify_ldt.2 +6 -0
+A conforming code segment will be rejected if
+.I
+func
+is 1 or if
+.I seg_not_present
+is 0.
It's not clear what a "conforming code segment is". Should some words be added here?

Quoted 1 line

How about "conforming code segment (i.e. contents == 3)"?

Done.

[...]

Quoted 6 lines

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

Thanks. I dropped that into the page source.

Quoted 3 lines

It could be worth adding a note somewhere that 64-bit kernels define a user_desc bit called "lm", but that its only effect is to interfere with detection of "empty" descriptors on older kernels.

So, I changed the text here to:

[[
On 64-bit kernels before Linux 3.19,
.\" commit e30ab185c490e9a9381385529e0fd32f0a399495 setting the "lm" padding bit in
.IR user_desc
prevents the descriptor from being considered empty. ]]

Quoted 3 lines

It may be
further worth noting somewhere that it is not possible to use modify_ldt(2) to install a long mode segment.

Do you want to send a patch? (It would at least need to explain where one finds out about "long mode".)

Your revisions are now sitting in the branch at:
http://git.kernel.org/cgit/docs/man-pages/man-pages.git/log/?h=draft_luto

Thanks,

Michael

Signature · 3 lines

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

Andy Lutomirski

author

2015-01-29 21:48 UTC #5 lore raw

PATCH 2/2 arch_prctl.2, set_thread_area.2, get_thread_area.2: Improve TLS documentation

In reply to Andy Lutomirski

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.

While I'm at it, clarify the related arch_prctl.2 man page.

Signed-off-by Andy Lutomirski <[email protected]>

---
 man2/arch_prctl.2      | 22 +++++++-----
 man2/get_thread_area.2 | 58 +------------------------------
 man2/set_thread_area.2 | 93 ++++++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 102 insertions(+), 71 deletions(-)

man2/arch_prctl.2 +14 -8

index a3ab2b566915..c89fa3c7b744 100644
@@ -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
+.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
+.I ARCH_SET_FS
+directly are very likely to crash.
 .SH SEE ALSO
 .BR mmap (2),
 .BR modify_ldt (2),

man2/get_thread_area.2 +1 ~~-57~~

58 lines not on this page · raw message

man2/set_thread_area.2 +87 -6

147 lines not on this page · raw message

Signature · 1 line

2.1.0

Michael Kerrisk (man-pages)

2015-01-30 12:59 UTC #6 lore raw

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

Hi Andy,

Thanks for this!

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

Quoted 3 lines · Andy Lutomirski

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.)

Quoted 27 lines

While I'm at it, clarify the related arch_prctl.2 man page.

Signed-off-by Andy Lutomirski <[email protected]>

---
 man2/arch_prctl.2      | 22 +++++++-----
 man2/get_thread_area.2 | 58 +------------------------------
 man2/set_thread_area.2 | 93 ++++++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 102 insertions(+), 71 deletions(-)

man2/arch_prctl.2 +3 -5

index a3ab2b566915..c89fa3c7b744 100644
@@ -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.

man2/arch_prctl.2 The 64-bit base changes when a new 32-bit segment selector is loaded. · line 128

Quoted 10 lines

man2/arch_prctl.2 +2 -2

-.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

Quoted 4 lines

man2/arch_prctl.2 +4 -0

+.BR arch_prctl (2)
+and
+.BR set_thread_area (2)
+in the same thread is dangerous, as they may overwrite each other's

man2/arch_prctl.2 The 64-bit base changes when a new 32-bit segment selector is loaded. · line 141

Quoted 10 lines

man2/arch_prctl.2 +3 -1

+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"?

Quoted 105 lines

man2/arch_prctl.2 +2 -0

+.I ARCH_SET_FS
+directly are very likely to crash.
 .SH SEE ALSO
 .BR mmap (2),
 .BR modify_ldt (2),

man2/get_thread_area.2 +1 ~~-57~~

index 08589e413cc4..a03fe54fb08e 100644
@@ -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

man2/set_thread_area.2 +16 -2

index 321beb396312..6acc5f79d1ad 100644
@@ -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;

man2/set_thread_area.2 line 40

Quoted 10 lines

man2/set_thread_area.2 +6 -0

+    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?

Quoted 25 lines

man2/set_thread_area.2 +11 -2

+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

man2/set_thread_area.2 When · line 67

Quoted 5 lines

man2/set_thread_area.2 +1 -1

@@ -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/ ?

Quoted 38 lines

man2/set_thread_area.2 +22 -0

 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 ()

man2/set_thread_area.2 first appeared in Linux 2.5.29. · line 119

Quoted 5 lines

man2/set_thread_area.2 +2 -0

@@ -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 ?

Quoted 26 lines

man2/set_thread_area.2 +21 -0

+.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

man2/set_thread_area.2 first appeared in Linux 2.5.29. · line 154

Quoted 10 lines

man2/set_thread_area.2 +8 -1

+.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

Signature · 7 lines

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 [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Andy Lutomirski

author

2015-01-30 14:45 UTC #7 lore raw

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

Quoted 50 lines · 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.

Quoted 3 lines · Andy Lutomirski

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.)

Quoted 36 lines

While I'm at it, clarify the related arch_prctl.2 man page.

Signed-off-by Andy Lutomirski <[email protected]>

---
 man2/arch_prctl.2      | 22 +++++++-----
 man2/get_thread_area.2 | 58 +------------------------------
 man2/set_thread_area.2 | 93 ++++++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 102 insertions(+), 71 deletions(-)

man2/arch_prctl.2 +4 -7

index a3ab2b566915..c89fa3c7b744 100644
@@ -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.

Quoted 6 lines

man2/arch_prctl.2 The 64-bit base changes when a new 32-bit segment selector is loaded. · line 128
Quoted 1 line
man2/arch_prctl.2 +1 -0
+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.

Quoted 12 lines

man2/arch_prctl.2 +6 -0

+.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.

Quoted 5 lines

man2/arch_prctl.2 The 64-bit base changes when a new 32-bit segment selector is loaded. · line 141
Quoted 3 lines
man2/arch_prctl.2 +1 -1
 .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.

Quoted 111 lines

man2/arch_prctl.2 +2 -0

+.I ARCH_SET_FS
+directly are very likely to crash.
 .SH SEE ALSO
 .BR mmap (2),
 .BR modify_ldt (2),

man2/get_thread_area.2 +1 ~~-57~~

index 08589e413cc4..a03fe54fb08e 100644
@@ -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

man2/set_thread_area.2 +20 -2

index 321beb396312..6acc5f79d1ad 100644
@@ -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

Quoted 7 lines

man2/set_thread_area.2 line 40
Quoted 5 lines
man2/set_thread_area.2 +2 -0
 .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

Quoted 25 lines

man2/set_thread_area.2 +11 -2

+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

Quoted 8 lines

man2/set_thread_area.2 When · line 67
Quoted 6 lines
man2/set_thread_area.2 +1 -1
@@ -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"?

Quoted 38 lines

man2/set_thread_area.2 +22 -0

 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 ()

Quoted 8 lines

man2/set_thread_area.2 first appeared in Linux 2.5.29. · line 119
Quoted 6 lines
man2/set_thread_area.2 +2 -0
@@ -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.

Quoted 48 lines

Quoted 27 lines

man2/set_thread_area.2 +21 -0

+.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

man2/set_thread_area.2 first appeared in Linux 2.5.29. · line 154

Quoted 10 lines

man2/set_thread_area.2 +8 -1

+.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/

Michael Kerrisk (man-pages)

2015-01-30 15:18 UTC #8 lore raw

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

Quoted 52 lines · Andy Lutomirski

Quoted 50 lines · 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.
Quoted 3 lines · Andy Lutomirski
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.)
Quoted 36 lines
While I'm at it, clarify the related arch_prctl.2 man page.
Signed-off-by Andy Lutomirski <[email protected]>
---
 man2/arch_prctl.2      | 22 +++++++-----
 man2/get_thread_area.2 | 58 +------------------------------
 man2/set_thread_area.2 | 93 ++++++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 102 insertions(+), 71 deletions(-)
man2/arch_prctl.2 +4 -7
index a3ab2b566915..c89fa3c7b744 100644
@@ -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.
 

Quoted 8 lines

Quoted 6 lines
man2/arch_prctl.2 The 64-bit base changes when a new 32-bit segment selector is loaded. · line 128
Quoted 1 line
man2/arch_prctl.2 +1 -0
+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.

Quoted 11 lines

man2/arch_prctl.2 +6 -0

+.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.

Quoted 7 lines

Quoted 5 lines
man2/arch_prctl.2 The 64-bit base changes when a new 32-bit segment selector is loaded. · line 141
Quoted 3 lines
man2/arch_prctl.2 +1 -1
 .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/

Quoted 9 lines

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.)

[...]

Quoted 12 lines

Quoted 11 lines
man2/set_thread_area.2 line 40
Quoted 9 lines
man2/set_thread_area.2 +2 -0
index 08589e413cc4..a03fe54fb08e 100644
 .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?

Quoted 1 line

Yes.

Fixed.

Quoted 33 lines

Quoted 24 lines

man2/set_thread_area.2 +11 -2

+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

Quoted 8 lines

man2/set_thread_area.2 When · line 67
Quoted 6 lines
man2/set_thread_area.2 +1 -1
@@ -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/ ?

Quoted 1 line

How about "searches for"?

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

[...]

Quoted 6 lines

Quoted 4 lines
man2/set_thread_area.2 first appeared in Linux 2.5.29. · line 119
Quoted 2 lines
man2/set_thread_area.2 +2 -0
+.SH BUGS
+On 64-bit kernels before Linux 3.19, one of the padding bits in
Was that commit e30ab185c490e9a9381385529e0fd32f0a399495 ?
Yes.

Okay.

Thanks,

Michael

Signature · 7 lines

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 [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

2015-01-30 12:18 UTC #9 lore raw

In reply to Andy Lutomirski

Quoted 3 lines · Andy Lutomirski

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

Quoted 11 lines

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(-)

Signature · 3 lines

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