| 1 |
.\" Copyright 1995, Michael Chastain <[email protected]> |
| 2 |
.\" Copyright 2015, Andrew Lutomirski <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: GPL-2.0-or-later |
| 6 |
.\" |
| 7 |
.TH modify_ldt 2 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
modify_ldt \- get or set a per-process LDT entry |
| 10 |
.SH LIBRARY |
| 11 |
Standard C library |
| 12 |
.RI ( libc ,\~ \-lc ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.BR "#include <asm/ldt.h>" " /* Definition of " "struct user_desc" " */" |
| 16 |
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" |
| 17 |
.B #include <unistd.h> |
| 18 |
.P |
| 19 |
.BR "int syscall(" "unsigned long bytecount;" |
| 20 |
.BI " SYS_modify_ldt, int " func ", void " ptr [ bytecount ], |
| 21 |
.BI " unsigned long " bytecount ); |
| 22 |
.fi |
| 23 |
.P |
| 24 |
.IR Note : |
| 25 |
glibc provides no wrapper for |
| 26 |
.BR modify_ldt (), |
| 27 |
necessitating the use of |
| 28 |
.BR syscall (2). |
| 29 |
.SH DESCRIPTION |
| 30 |
.BR modify_ldt () |
| 31 |
reads or writes the local descriptor table (LDT) for a process. |
| 32 |
The LDT |
| 33 |
is an array of segment descriptors that can be referenced by user code. |
| 34 |
Linux allows processes to configure a per-process (actually per-mm) LDT. |
| 35 |
For more information about the LDT, see the Intel Software Developer's |
| 36 |
Manual or the AMD Architecture Programming Manual. |
| 37 |
.P |
| 38 |
When |
| 39 |
.I func |
| 40 |
is 0, |
| 41 |
.BR modify_ldt () |
| 42 |
reads the LDT into the memory pointed to by |
| 43 |
.IR ptr . |
| 44 |
The number of bytes read is the smaller of |
| 45 |
.I bytecount |
| 46 |
and the actual size of the LDT, although the kernel may act as though |
| 47 |
the LDT is padded with additional trailing zero bytes. |
| 48 |
On success, |
| 49 |
.BR modify_ldt () |
| 50 |
will return the number of bytes read. |
| 51 |
.P |
| 52 |
When |
| 53 |
.I func |
| 54 |
is 1 or 0x11, |
| 55 |
.BR modify_ldt () |
| 56 |
modifies the LDT entry indicated by |
| 57 |
.IR ptr\->entry_number . |
| 58 |
.I ptr |
| 59 |
points to a |
| 60 |
.I user_desc |
| 61 |
structure |
| 62 |
and |
| 63 |
.I bytecount |
| 64 |
must equal the size of this structure. |
| 65 |
.P |
| 66 |
The |
| 67 |
.I user_desc |
| 68 |
structure is defined in |
| 69 |
.I <asm/ldt.h> |
| 70 |
as: |
| 71 |
.P |
| 72 |
.in +4n |
| 73 |
.EX |
| 74 |
struct user_desc { |
| 75 |
unsigned int entry_number; |
| 76 |
unsigned int base_addr; |
| 77 |
unsigned int limit; |
| 78 |
unsigned int seg_32bit:1; |
| 79 |
unsigned int contents:2; |
| 80 |
unsigned int read_exec_only:1; |
| 81 |
unsigned int limit_in_pages:1; |
| 82 |
unsigned int seg_not_present:1; |
| 83 |
unsigned int useable:1; |
| 84 |
}; |
| 85 |
.EE |
| 86 |
.in |
| 87 |
.P |
| 88 |
In Linux 2.4 and earlier, this structure was named |
| 89 |
.IR modify_ldt_ldt_s . |
| 90 |
.P |
| 91 |
The |
| 92 |
.I contents |
| 93 |
field is the segment type (data, expand-down data, non-conforming code, or |
| 94 |
conforming code). |
| 95 |
The other fields match their descriptions in the CPU manual, although |
| 96 |
.BR modify_ldt () |
| 97 |
cannot set the hardware-defined "accessed" bit described in the CPU manual. |
| 98 |
.P |
| 99 |
A |
| 100 |
.I user_desc |
| 101 |
is considered "empty" if |
| 102 |
.I read_exec_only |
| 103 |
and |
| 104 |
.I seg_not_present |
| 105 |
are set to 1 and all of the other fields are 0. |
| 106 |
An LDT entry can be cleared by setting it to an "empty" |
| 107 |
.I user_desc |
| 108 |
or, if |
| 109 |
.I func |
| 110 |
is 1, by setting both |
| 111 |
.I base |
| 112 |
and |
| 113 |
.I limit |
| 114 |
to 0. |
| 115 |
.P |
| 116 |
A conforming code segment (i.e., one with |
| 117 |
.IR contents==3 ) |
| 118 |
will be rejected if |
| 119 |
.I |
| 120 |
func |
| 121 |
is 1 or if |
| 122 |
.I seg_not_present |
| 123 |
is 0. |
| 124 |
.P |
| 125 |
When |
| 126 |
.I func |
| 127 |
is 2, |
| 128 |
.BR modify_ldt () |
| 129 |
will read zeros. |
| 130 |
This appears to be a leftover from Linux 2.4. |
| 131 |
.SH RETURN VALUE |
| 132 |
On success, |
| 133 |
.BR modify_ldt () |
| 134 |
returns either the actual number of bytes read (for reading) |
| 135 |
or 0 (for writing). |
| 136 |
On failure, |
| 137 |
.BR modify_ldt () |
| 138 |
returns \-1 and sets |
| 139 |
.I errno |
| 140 |
to indicate the error. |
| 141 |
.SH ERRORS |
| 142 |
.TP |
| 143 |
.B EFAULT |
| 144 |
.I ptr |
| 145 |
points outside the address space. |
| 146 |
.TP |
| 147 |
.B EINVAL |
| 148 |
.I ptr |
| 149 |
is 0, |
| 150 |
or |
| 151 |
.I func |
| 152 |
is 1 and |
| 153 |
.I bytecount |
| 154 |
is not equal to the size of the structure |
| 155 |
.IR user_desc , |
| 156 |
or |
| 157 |
.I func |
| 158 |
is 1 or 0x11 and the new LDT entry has invalid values. |
| 159 |
.TP |
| 160 |
.B ENOSYS |
| 161 |
.I func |
| 162 |
is neither 0, 1, 2, nor 0x11. |
| 163 |
.SH STANDARDS |
| 164 |
Linux. |
| 165 |
.SH NOTES |
| 166 |
.BR modify_ldt () |
| 167 |
should not be used for thread-local storage, as it slows down context |
| 168 |
switches and only supports a limited number of threads. |
| 169 |
Threading libraries should use |
| 170 |
.BR set_thread_area (2) |
| 171 |
or |
| 172 |
.BR arch_prctl (2) |
| 173 |
instead, except on extremely old kernels that do not support those system |
| 174 |
calls. |
| 175 |
.P |
| 176 |
The normal use for |
| 177 |
.BR modify_ldt () |
| 178 |
is to run legacy 16-bit or segmented 32-bit code. |
| 179 |
Not all kernels allow 16-bit segments to be installed, however. |
| 180 |
.P |
| 181 |
Even on 64-bit kernels, |
| 182 |
.BR modify_ldt () |
| 183 |
cannot be used to create a long mode (i.e., 64-bit) code segment. |
| 184 |
The undocumented field "lm" in |
| 185 |
.I user_desc |
| 186 |
is not useful, and, despite its name, |
| 187 |
does not result in a long mode segment. |
| 188 |
.SH BUGS |
| 189 |
On 64-bit kernels before Linux 3.19, |
| 190 |
.\" commit e30ab185c490e9a9381385529e0fd32f0a399495 |
| 191 |
setting the "lm" bit in |
| 192 |
.I user_desc |
| 193 |
prevents the descriptor from being considered empty. |
| 194 |
Keep in mind that the |
| 195 |
"lm" bit does not exist in the 32-bit headers, but these buggy kernels |
| 196 |
will still notice the bit even when set in a 32-bit process. |
| 197 |
.SH SEE ALSO |
| 198 |
.BR arch_prctl (2), |
| 199 |
.BR set_thread_area (2), |
| 200 |
.BR vm86 (2) |