Date: Sun, 13 Jul 2003 20:29:58 +0200 (CEST)
From: Andreas Fuchs <asf@void.at>
To: FreeBSD-gnats-submit@FreeBSD.org
Subject: i386/54451: [patch] i386_{get|set}_ldt manual page is confusing
Message-ID: <200307131829.h6DITwLF029458@eris.void.at>
Resent-Message-ID: <200307131830.h6DIULWR097526@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 54451
>Category: i386
>Synopsis: [patch] i386_{get|set}_ldt manual page is confusing
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-i386
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Sun Jul 13 11:30:16 PDT 2003
>Closed-Date:
>Last-Modified:
>Originator: Andreas Fuchs
>Release: FreeBSD 5.1-CURRENT i386
>Organization:
>Environment:
System: FreeBSD boinkine.defun.at 5.1-CURRENT FreeBSD 5.1-CURRENT #1: Sun Jun 22 15:11:58 CEST 2003 root@boinkine.defun.at:/usr/obj/usr/src/sys/BOINKINE i386
>Description:
The i386_get_ldt (which serves for _set_, too) man page is written
in a confusing and long-winded style, especially regarding the
meaning of the start_ldt parameter.
>How-To-Repeat:
man 2 i386_get_ldt
>Fix:
I've rewritten the portions which were confusing to me and added
an example section.
I'm not so sure about what to do with the goofy WARNING, as many
other syscalls can also really hose one's processes but don't state
it explicitly. I've left it in in the patch, but my gut feeling
says that is should go (-:
The attached patch is against
$FreeBSD: src/lib/libc/i386/sys/i386_get_ldt.2,v 1.17 2003/06/09 11:46:22 jhb Exp $
--- /usr/src/lib/libc/i386/sys/i386_get_ldt.2 Sun Jun 22 14:18:31 2003
+++ i386_get_ldt.2 Sun Jul 13 18:20:17 2003
@@ -52,46 +52,60 @@
The
.Fn i386_get_ldt
system call
-will return the list of i386 descriptors that the process has in its
-LDT.
+will copy the list of i386 descriptors that the process has in its
+LDT. It does so starting from the LDT entry index
+.Fa start_sel
+into an arrary pointed to by
+.Fa descs ,
+which must be
+.Fa num_sel
+elements wide.
+.Pp
The
.Fn i386_set_ldt
system call
will set a list of i386 descriptors for the current process in its
-LDT.
-Both routines accept a starting selector number
-.Fa start_sel ,
-an array of memory that
-will contain the descriptors to be set or returned
-.Fa descs ,
-and the number of entries to set or return
-.Fa num_sels .
+LDT, starting from the LDT entry index
+.Fa start_sel .
+It copies
+.Fa num_descs
+descriptors in the array pointed to by
+.Fa descs
+into the LDT.
.Pp
The argument
.Fa descs
can be either segment_descriptor or gate_descriptor and are defined in
.Aq Pa i386/segments.h .
These structures are defined by the architecture
-as disjoint bit-fields, so care must be taken in constructing them.
+as disjoint bit-fields, so you must take care in constructing them.
.Sh RETURN VALUES
-Upon successful completion,
+If successful,
.Fn i386_get_ldt
returns the number of descriptors currently in the LDT.
-The
.Fn i386_set_ldt
-system call
-returns the first selector set.
-Otherwise, a value of -1 is returned and the global
+returns the index first selector that it set on success. If an error
+occurred, the procedures return a value of -1 and set the global
variable
.Va errno
-is set to indicate the error.
+to indicate the error.
+.Sh EXAMPLES
+To set the
+.Va "my_ldt_index"
+th slot of the process's LDT to the value of
+.Va my_ldt_entry ,
+use something like this:
+.Bd -literal -offset indent
+if (i386_set_ldt(my_ldt_index, &my_ldt_entry, 1) < 0) {
+ perror("i386_set_ldt");
+}
.Sh ERRORS
The
.Fn i386_get_ldt
and
.Fn i386_set_ldt
system calls
-will fail if:
+will fail with:
.Bl -tag -width Er
.It Bq Er EINVAL
An inappropriate value was used for
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200307131829.h6DITwLF029458>