]> git.saurik.com Git - apple/xnu.git/blob - bsd/man/man2/i386_get_ldt.2
xnu-1228.9.59.tar.gz
[apple/xnu.git] / bsd / man / man2 / i386_get_ldt.2
1 .\" Copyright (c) 1980, 1991 Regents of the University of California.
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" from: @(#)fork.2 6.5 (Berkeley) 3/10/91
33 .\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/i386/sys/i386_get_ldt.2,v 1.21 2004/07/02 19:07:30 ru Exp $
34 .\"
35 .Dd September 20, 1993
36 .Dt I386_GET_LDT 2
37 .Os
38 .Sh NAME
39 .Nm i386_get_ldt ,
40 .Nm i386_set_ldt
41 .Nd manage i386 per-process Local Descriptor Table entries
42 .Sh LIBRARY
43 .Lb libc
44 .Sh SYNOPSIS
45 .In architecture/i386/table.h
46 .In i386/user_ldt.h
47 .Ft int
48 .Fn i386_get_ldt "int start_sel" "union ldt_entry *descs" "int num_sels"
49 .Ft int
50 .Fn i386_set_ldt "int start_sel" "union ldt_entry *descs" "int num_sels"
51 .Sh DESCRIPTION
52 The
53 .Fn i386_get_ldt
54 system call
55 will return the list of i386 descriptors that the process has in its
56 LDT.
57 The
58 .Fn i386_set_ldt
59 system call
60 will set a list of i386 descriptors for the current process in its
61 LDT.
62 Both routines accept a starting selector number
63 .Fa start_sel ,
64 an array of memory that
65 will contain the descriptors to be set or returned
66 .Fa descs ,
67 and the number of entries to set or return
68 .Fa num_sels .
69 .Pp
70 The argument
71 .Fa descs
72 can be either code_desc_t, data_desc_t or call_gate_t and are defined in
73 .In architecture/i386/desc.h .
74 These structures are defined by the architecture
75 as disjoint bit-fields, so care must be taken in constructing them.
76 .Pp
77 If
78 .Fa start_sel
79 is
80 .Em LDT_AUTO_ALLOC ,
81 .Fa num_sels
82 is 1 and the descriptor pointed to by
83 .Fa descs
84 is legal, then
85 .Fn i386_set_ldt
86 will allocate a descriptor and return its
87 selector number.
88 .Pp
89 If
90 .Fa num_descs
91 is 1,
92 .Fa start_sels
93 is valid, and
94 .Fa descs
95 is NULL, then
96 .Fn i386_set_ldt
97 will free that descriptor
98 (making it available to be reallocated again later).
99 .Pp
100 If
101 .Fa num_descs
102 is 0,
103 .Fa start_sels
104 is 0 and
105 .Fa descs
106 is NULL then, as a special case,
107 .Fn i386_set_ldt
108 will free all descriptors.
109 .Sh RETURN VALUES
110 Upon successful completion,
111 .Fn i386_get_ldt
112 returns the number of descriptors currently in the LDT.
113 The
114 .Fn i386_set_ldt
115 system call
116 returns the first selector set.
117 In the case when a descriptor is allocated by the kernel, its number will
118 be returned.
119 Otherwise, a value of -1 is returned and the global
120 variable
121 .Va errno
122 is set to indicate the error.
123 .Sh ERRORS
124 The
125 .Fn i386_get_ldt
126 and
127 .Fn i386_set_ldt
128 system calls
129 will fail if:
130 .Bl -tag -width Er
131 .It Bq Er EINVAL
132 An inappropriate value was used for
133 .Fa start_sel
134 or
135 .Fa num_sels .
136 .It Bq Er EACCES
137 The caller attempted to use a descriptor that would
138 circumvent protection or cause a failure.
139 .El
140 .Sh SEE ALSO
141 i386 Microprocessor Programmer's Reference Manual, Intel
142 .Sh WARNING
143 You can really hose your process using this.