man2/modify_ldt.2

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