Re: ioctl_list.2: complete overhaul needed

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hello Heinrich,

On 4/14/20 6:21 PM, Heinrich Schuchardt wrote:
> On 2020-04-14 17:37, Eugene Syromyatnikov wrote:
>> On Tue, Apr 14, 2020 at 5:18 PM Michael Kerrisk (man-pages)
>> <mtk.manpages@gmail.com> wrote:
>>>
>>> Hello Heinrich,
>>>
>>> On Sun, 9 Nov 2014 at 16:52, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>>>>
>>>>
>>>> Hello Michael,
>>>>
>>>> the current ioctl_list.2 man-page descripton starts
>>>> "This  is  Ioctl List 1.3.27, a list of ioctl calls in Linux/i386 kernel
>>>> 1.3.27."
>>>> So the man-page represents the state of Sep 14th, 1995.
>>>> It enumerates only 421 out of over 1200 calls.
>>>>
>>>> The list contains hex values of different constants. I just wonder for
>>>> which architecture (alpha, i386, mips, or sparc at that time). No
>>>> information is supplied.
>>>>
>>>> Current values depend on the architecture, e.g.
>>>>
>>>> On amd64
>>>> 0x82307201      VFAT_IOCTL_READDIR_BOTH
>>>> 0x82307202      VFAT_IOCTL_READDIR_SHORT
>>>> 0x80047210      FAT_IOCTL_GET_ATTRIBUTES
>>>> 0x40047211      FAT_IOCTL_SET_ATTRIBUTES
>>>> 0x80047213      FAT_IOCTL_GET_VOLUME_ID
>>>>
>>>> On mips
>>>> 0x42187201      VFAT_IOCTL_READDIR_BOTH
>>>> 0x42187202      VFAT_IOCTL_READDIR_SHORT
>>>> 0x40047210      FAT_IOCTL_GET_ATTRIBUTES
>>>> 0x80047211      FAT_IOCTL_SET_ATTRIBUTES
>>>> 0x40047213      FAT_IOCTL_GET_VOLUME_ID
>>>>
>>>> Hence hex values should be removed.
>>>
>>>
>>> As you suggest, I've removed the hex values from the lists.
>>
>> Those can be replaced with the _IO* macro definitions. Meanwhile,  the
>> list is somewhat far from complete; strace has some approximation that
>> can be uses a basis of a more complete and reliable list
>> (linux/{32,64}/ioctls_inc*.h and linux/*/ioctls_arch*.h), but I'm not
>> sure if it is worth adding to the man page (moreover, entries are
>> constantly being added and changed there; yes, breaking the kernel ABI
>> in the process sometimes).
> 
> Man-pages like netdevices.7 or ioctl_fat.2 are what is needed to help a
> user who does not want to read through the kernel code.

Yes, I agree.

> If ioctl_list.2 has not been reasonably maintained since Linux 1.3.27
> and hence is not a reliable source of information,

I must confess I've never loved that page. and in the 24+ years since 
it was released, it's seen very little useful change to the content.
(You of course are well qualified to know that, since the biggest 
changes have come from you, and as we know they've not been anything
big.)

> shouldn't it be dropped?

I'm inclined to do so. Let's see if anyone else comments.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/