linux-kernel - Removal of the ioctl_list(2) manual page (was: Re: ioctl

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Message-ID: <ebd773bc-1277-c346-3edc-370c843cc968@gmail.com>
Date:   Thu, 16 Apr 2020 09:10:43 +0200
From:   "Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
To:     Heinrich Schuchardt <xypron.glpk@....de>,
        Eugene Syromyatnikov <evgsyr@...il.com>
Cc:     mtk.manpages@...il.com, linux-man <linux-man@...r.kernel.org>,
        Mike Christie <mchristi@...hat.com>,
        lkml <linux-kernel@...r.kernel.org>,
        Linux API <linux-api@...r.kernel.org>
Subject: Removal of the ioctl_list(2) manual page (was: Re: ioctl_list.2:
 complete overhaul needed)

[CC widened]

Hello Heinrich, Eugene,

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@...il.com> wrote:
>>>
>>> Hello Heinrich,
>>>
>>> On Sun, 9 Nov 2014 at 16:52, Heinrich Schuchardt <xypron.glpk@....de> wrote:

[...]

>>> 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.
> 
> If ioctl_list.2 has not been reasonably maintained since Linux 1.3.27
> and hence is not a reliable source of information, shouldn't it be dropped?

As already noted, I'm inclined to agree that yes, this page probably
should be removed. What really is needed is pages such as ioctl_fat(2),
ioctl_userfaultfd(2), and ioctl_ns(2) that give useful details
to user-space programmers.

Just FYI, I've queued a change that removes the ioctl_list(2) page
in a private branch. By the time of the next release, I'll merge
that branch, unless someone has (good) objections.

There is one piece of ioctl_list(2) that is perhaps worth preserving:
the "ioctl structure" subsection. As part of these changes, I've
migrated that text to ioctl(2).

Cheers,

Michael

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