Bug 40423

Summary: Keyboard(4)'s definition of parameters to GETFKEY/SETFKEY off by one.
Product: Documentation Reporter: marcov <marcov>
Component: Manual PagesAssignee: freebsd-bugs (Nobody) <bugs>
Status: Open ---    
Severity: Affects Only Me CC: doc, gonzo
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   
Attachments:
Description Flags
ithread.9 rewrite by trhodes@ none

Description marcov 2002-07-10 17:30:02 UTC
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

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.
How-To-Repeat:  man 4 keyboard
Comment 1 Giorgos Keramidas freebsd_committer 2002-07-11 19:27:47 UTC
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
Comment 2 marcov 2002-07-11 21:02:26 UTC
> 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.
Comment 3 Eitan Adler freebsd_committer freebsd_triage 2017-12-31 07:59:50 UTC
For bugs matching the following criteria:

Status: In Progress Changed: (is less than) 2014-06-01

Reset to default assignee and clear in-progress tags.

Mail being skipped
Comment 4 Oleksandr Tymoshenko freebsd_committer freebsd_triage 2018-04-13 01:55:52 UTC
Created attachment 192474 [details]
ithread.9 rewrite by trhodes@

This is cleaned-up patch by trhodes@ plus renaming manpages hardlinks and removal of old ones
Comment 5 Oleksandr Tymoshenko freebsd_committer freebsd_triage 2018-04-13 01:57:12 UTC
The content of attachment 192474 [details] has been deleted for the following reason:

Attached to wrong bug