Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Subject: Removal of the ioctl_list(2) manual page (was: Re: ioctl_list.2:
 complete overhaul needed)
To:     Heinrich Schuchardt <xypron.glpk@gmx.de>,
        Eugene Syromyatnikov <evgsyr@gmail.com>
Cc:     mtk.manpages@gmail.com, linux-man <linux-man@vger.kernel.org>,
        Mike Christie <mchristi@redhat.com>,
        lkml <linux-kernel@vger.kernel.org>,
        Linux API <linux-api@vger.kernel.org>
References: <545F8D2E.5030308@gmx.de>
 <CAKgNAkh-HBjh5AqNpTTfQjgeJVYx9LGpGDzO87zMWEmgMOd0bA@mail.gmail.com>
 <CACGkJdv5Be4KqmsP2AK99FmkZ5hB9jJk9YzsrS8Qzph8ceBvvQ@mail.gmail.com>
 <5e9b4408-410f-6fb4-9c8b-0bd68e64577d@gmx.de>
Message-ID: <ebd773bc-1277-c346-3edc-370c843cc968@gmail.com>
Date:   Thu, 16 Apr 2020 09:10:43 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.6.0
MIME-Version: 1.0
In-Reply-To: <5e9b4408-410f-6fb4-9c8b-0bd68e64577d@gmx.de>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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