From owner-freebsd-i386@FreeBSD.ORG Sun Jul 13 11:30:22 2003 Return-Path: Delivered-To: freebsd-i386@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id CCE6B37B401 for ; Sun, 13 Jul 2003 11:30:22 -0700 (PDT) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id B8F8343F93 for ; Sun, 13 Jul 2003 11:30:21 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.12.9/8.12.9) with ESMTP id h6DIULUp097527 for ; Sun, 13 Jul 2003 11:30:21 -0700 (PDT) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.9/8.12.9/Submit) id h6DIULWR097526; Sun, 13 Jul 2003 11:30:21 -0700 (PDT) Resent-Date: Sun, 13 Jul 2003 11:30:21 -0700 (PDT) Resent-Message-Id: <200307131830.h6DIULWR097526@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-i386@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Andreas Fuchs Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 8896237B401 for ; Sun, 13 Jul 2003 11:22:35 -0700 (PDT) Received: from eris.void.at (212-88-187-152.ADSL.ycn.com [212.88.187.152]) by mx1.FreeBSD.org (Postfix) with ESMTP id A2BC243F75 for ; Sun, 13 Jul 2003 11:22:33 -0700 (PDT) (envelope-from asf@eris.void.at) Received: from eris.void.at (localhost [127.0.0.1]) by eris.void.at (8.12.9/8.12.9) with ESMTP id h6DITw1P029459 for ; Sun, 13 Jul 2003 20:29:58 +0200 (CEST) (envelope-from asf@eris.void.at) Received: (from asf@localhost) by eris.void.at (8.12.9/8.12.9/Submit) id h6DITwLF029458; Sun, 13 Jul 2003 20:29:58 +0200 (CEST) Message-Id: <200307131829.h6DITwLF029458@eris.void.at> Date: Sun, 13 Jul 2003 20:29:58 +0200 (CEST) From: Andreas Fuchs To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Subject: i386/54451: [patch] i386_{get|set}_ldt manual page is confusing X-BeenThere: freebsd-i386@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list Reply-To: Andreas Fuchs List-Id: I386-specific issues for FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 13 Jul 2003 18:30:23 -0000 >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: