From marcov@stack.nl  Wed Jul 10 09:26:34 2002
Return-Path: <marcov@stack.nl>
Received: from mx1.FreeBSD.org (mx1.FreeBSD.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id CA52637B400
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 10 Jul 2002 09:26:34 -0700 (PDT)
Received: from skynet.stack.nl (insgate.stack.nl [131.155.140.2])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 4355B43E42
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 10 Jul 2002 09:26:34 -0700 (PDT)
	(envelope-from marcov@stack.nl)
Received: from toad.stack.nl (toad.stack.nl [2001:610:1108:5010:202:b3ff:fe17:9e1a])
	by skynet.stack.nl (Postfix) with ESMTP id 484923FF3
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 10 Jul 2002 18:26:33 +0200 (CEST)
Received: by toad.stack.nl (Postfix, from userid 816)
	id 1F9B998D1; Wed, 10 Jul 2002 18:26:33 +0200 (CEST)
Message-Id: <20020710162633.1F9B998D1@toad.stack.nl>
Date: Wed, 10 Jul 2002 18:26:33 +0200 (CEST)
From: Marco van de Voort <marcov@stack.nl>
Reply-To: Marco van de Voort <marcov@stack.nl>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Keyboard(4)'s definition of parameters to GETFKEY/SETFKEY off by one.
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         40423
>Category:       docs
>Synopsis:       Keyboard(4)'s definition of parameters to GETFKEY/SETFKEY off by one.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jul 10 09:30:02 PDT 2002
>Closed-Date:    
>Last-Modified:  Thu Jul 11 13:10:01 PDT 2002
>Originator:     Marco van de Voort
>Release:        FreeBSD 4.6-STABLE i386
>Organization:
MCGV Stack
>Environment:
System: FreeBSD toad.stack.nl 4.6-STABLE FreeBSD 4.6-STABLE #0: Sun Jun 23 17:18:50 CEST 2002 marcolz@toad.stack.nl:/toad.mnt/sources/4.x/sys/compile/toad_vwww i386
 (Man page, system unimportant)
>Description:
The C IOCTL (SET/GETFKEY) interface to set "function keys" requires
parameters in the range 0..63 (actually 0..95)

Kbdcontrol -f remaps them to 1..64 (1..96)

Keyboard(4) which describes (amongst others) the SET/GETFKEY functions
specifies the range as 1..64, while not mentioning that kbdcontrol
add/subtracts 1 internally when necessary

>How-To-Repeat:
 man 4 keyboard
>Fix:
Mention that there is a difference between the C level interface and the
kbdcontrol parameter with respect to the range of the function keys.


>Release-Note:
>Audit-Trail:

From: Giorgos Keramidas <keramida@freebsd.org>
To: Marco van de Voort <marcov@stack.nl>
Cc: bug-followup@freebsd.org
Subject: Re: docs/40423: Keyboard(4)'s definition of parameters to GETFKEY/SETFKEY off by one.
Date: Thu, 11 Jul 2002 21:27:47 +0300

 On 2002-07-10 18:26 +0000, Marco van de Voort wrote:
 > The C IOCTL (SET/GETFKEY) interface to set "function keys" requires
 > parameters in the range 0..63 (actually 0..95)
 >
 > Kbdcontrol -f remaps them to 1..64 (1..96)
 >
 > Keyboard(4) which describes (amongst others) the SET/GETFKEY
 > functions specifies the range as 1..64, while not mentioning that
 > kbdcontrol add/subtracts 1 internally when necessary
 
 I think the intent was to make it easier for users of kbdcontrol(1)
 who will have to use the manpage to find out the proper number to pass
 to the -f option of kbdcontrol.  The kbdcontrol(1) manpage refers to
 atkbd(4) which also uses the 1..64 numbering.  Someone who uses a
 programmatic interface should always use the F(x) interface of
 <sys/kbio.h> and will never get to see the actual raw number of a
 function key listed in the source of a program.
 
 - Giorgos
 

From: marcov@stack.nl (Marco van de Voort)
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: Marco van de Voort <marcov@stack.nl>, bug-followup@freebsd.org
Subject: Re: docs/40423: Keyboard(4)'s definition of parameters to GETFKEY/SETFKEY
 off by one.
Date: Thu, 11 Jul 2002 22:02:26 +0200 (CEST)

 > On 2002-07-10 18:26 +0000, Marco van de Voort wrote:
 > > The C IOCTL (SET/GETFKEY) interface to set "function keys" requires
 > > parameters in the range 0..63 (actually 0..95)
 > >
 > > Kbdcontrol -f remaps them to 1..64 (1..96)
 > >
 > > Keyboard(4) which describes (amongst others) the SET/GETFKEY
 > > functions specifies the range as 1..64, while not mentioning that
 > > kbdcontrol add/subtracts 1 internally when necessary
 > 
 > I think the intent was to make it easier for users of kbdcontrol(1)
 > who will have to use the manpage to find out the proper number to pass
 > to the -f option of kbdcontrol. 
 
 Hmm, the page mentions both the GETFKEY IOCTL-function, and the structure
 that is used to set the function keys is also mentioned.
 
 I'd say it is for both the programmatic as the kbdcontrol struct. Since the
 kbdcontrol struct has its own manpage, at least a small note is in order
 IMHO.
 
 > The kbdcontrol(1) manpage refers to atkbd(4) which also uses the 1..64
 > numbering. 
 
 Then that is also incorrect ;-) I think it is wise to make cler.
 
 > Someone who uses a programmatic interface should always use
 > the F(x) interface of <sys/kbio.h> and will never get to see the actual
 > raw number of a function key listed in the source of a program.
 
 I don't know what you mean by the F(x) interface.
 
 I've translated kbio.h for fixing up the console experience of some project,
 and was quite confused by this for a while.
 
>Unformatted:
