Debian Codegraph @

upstream/debian-unstable/man2/modify_ldt.2

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