ioctl_list.2: complete overhaul needed
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.
I further suggest to remove all documentation of structure details.
The following command can be used to create the raw data for a new list
grep -GHrn -B3 -A3 --regexp="\s_IO[R|W|RW]\?[_BAD]\?\s*(" \include/uapi | \
sed ':a;N;$!ba;s/\\\s*\n[^-]*-[^-]*-/ /g' | \
sort | \
grep --regexp="\s_IO[R|W|RW]\?[BAD]\?\s*(" | grep -n ''
Best regards
Heinrich Schuchardt
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Hello Heinrich,
Quoted 8 lines · Heinrich Schuchardt
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.
Yep. There's no doubt that the man page is in a sorry state. (But, I think a few of those other ioctls are documented in some section 4 and section 7 pages.)
Quoted 13 lines
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
Quoted 8 lines
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_IDHence hex values should be removed.
It sounds like you are right that the hex values should be removed. But, how did you determine those different hex values above? Grepping the sources, it's not obvious that amd64 and mips should be different.
Quoted 1 line
I further suggest to remove all documentation of structure details.
Could you elaborate this point a little. Some examples, and why you think they should be removed. I'm not disagreeing, just looking to clarify what you mean.
Quoted 7 lines
The following command can be used to create the raw data for a new list
grep -GHrn -B3 -A3 --regexp="\s_IO[R|W|RW]\?[_BAD]\?\s*(" \
include/uapi| \
sed ':a;N;$!ba;s/\\\s*\n[^-]*-[^-]*-/ /g' | \
sort | \
grep --regexp="\s_IO[R|W|RW]\?[BAD]\?\s*(" | grep -n ''
Thanks -- that's very helpful!
Cheers,
Michael
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 21 lines · Michael Kerrisk (man-pages)
Quoted 20 lines · Heinrich Schuchardt
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_IDOn 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
Quoted 6 lines
Quoted 1 line
Hence hex values should be removed.
It sounds like you are right that the hex values should be removed. But, how did you determine those different hex values above? Grepping the sources, it's not obvious that amd64 and mips should be different.
ioctl's can integrate the type size right ? so wouldn't be surprised if it changed across arches.
fwiw, strace carries a script to try and do all this magic automatically:
http://sourceforge.net/p/strace/code/ci/master/tree/linux/ioctlent.sh
of course it misses out on ioctls that aren't exported in headers and are internal to specific drivers. i.e. it's not perfect at all, but that's because ioctls are a goddamn mess :).
i agree though that the man page should drop hex values as they aren't useful. if you're using a "standard" ioctl, you should get it from the relevant header file. if you're using a "non-standard" ioctl, then you get the pieces.
Quoted 5 lines
Quoted 1 line
I further suggest to remove all documentation of structure details.
Could you elaborate this point a little. Some examples, and why you think they should be removed. I'm not disagreeing, just looking to clarify what you mean.
i think for the common/standard ioctls, it's useful to have manpages that delve down into the details. but for the fringe ones, it's a waste of time for the vast majority of people.
maybe one way to determine whether it's worth documenting, see if strace has a decoder for it :).
-mike
Hi Mike,
Quoted 24 lines · Mike Frysinger
Quoted 23 lines · Michael Kerrisk (man-pages)
Quoted 21 lines · Heinrich Schuchardt
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_IDOn 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_IDHence hex values should be removed.
Quoted 7 lines
Quoted 4 lines
It sounds like you are right that the hex values should be removed. But, how did you determine those different hex values above? Grepping the sources, it's not obvious that amd64 and mips should be different.
ioctl's can integrate the type size right ? so wouldn't be surprised if it changed across arches.
Yes. I'd actually noticed that detail,and should have said so. I suppose what I really meant was: is that the only source of the difference in the constants?
Quoted 5 lines
fwiw, strace carries a script to try and do all this magic automatically:
http://sourceforge.net/p/strace/code/ci/master/tree/linux/ioctlent.sh
of course it misses out on ioctls that aren't exported in headers and are internal to specific drivers. i.e. it's not perfect at all, but that's because ioctls are a goddamn mess :).
Thanks for that pointer.
Quoted 3 lines
i agree though that the man page should drop hex values as they aren't useful. if you're using a "standard" ioctl, you should get it from the relevant header file. if you're using a "non-standard" ioctl, then you get the pieces.
Agreed.
Quoted 6 lines
Quoted 5 lines
Quoted 1 line
I further suggest to remove all documentation of structure details.
Could you elaborate this point a little. Some examples, and why you think they should be removed. I'm not disagreeing, just looking to clarify what you mean.
Quoted 6 lines
i think for the common/standard ioctls, it's useful to have manpages that delve down into the details. but for the fringe ones, it's a waste of time for the vast majority of people.
maybe one way to determine whether it's worth documenting, see if strace has a decoder for it :).
Sounds like a reasonable idea to me.
Cheers,
Michael
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Hello Heinrich,
Quoted 23 lines · Heinrich Schuchardt
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
Quoted 8 lines
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_IDHence hex values should be removed.
As you suggest, I've removed the hex values from the lists.
Thanks,
Michael
Quoted 13 lines
I further suggest to remove all documentation of structure details.
The following command can be used to create the raw data for a new list
grep -GHrn -B3 -A3 --regexp="\s_IO[R|W|RW]\?[_BAD]\?\s*(" \
include/uapi| \
sed ':a;N;$!ba;s/\\\s*\n[^-]*-[^-]*-/ /g' | \
sort | \
grep --regexp="\s_IO[R|W|RW]\?[BAD]\?\s*(" | grep -n ''Best regards
Heinrich Schuchardt
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Quoted 34 lines · Michael Kerrisk (man-pages)
Hello Heinrich,
Quoted 30 lines · Heinrich Schuchardt
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_IDOn 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
Quoted 4 lines
Quoted 1 line
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).
Quoted 25 lines
Thanks,
Michael
Quoted 10 lines
I further suggest to remove all documentation of structure details.
The following command can be used to create the raw data for a new list
grep -GHrn -B3 -A3 --regexp="\s_IO[R|W|RW]\?[_BAD]\?\s*(" \
include/uapi| \
sed ':a;N;$!ba;s/\\\s*\n[^-]*-[^-]*-/ /g' | \
sort | \
grep --regexp="\s_IO[R|W|RW]\?[BAD]\?\s*(" | grep -n ''Quoted 3 lines
Best regards
Heinrich Schuchardt
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Signature · 3 lines
Eugene Syromyatnikov mailto:[email protected] xmpp:esyr@jabber.{ru|org}
Quoted 41 lines · Eugene Syromyatnikov
Quoted 34 lines · Michael Kerrisk (man-pages)
Hello Heinrich,
Quoted 30 lines · Heinrich Schuchardt
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_IDOn 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_IDQuoted 4 lines
Quoted 1 line
Hence hex values should be removed.
As you suggest, I've removed the hex values from the lists.
Quoted 7 lines
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*.handlinux/*/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?
Best regards
Heinrich
Quoted 29 lines
Quoted 26 lines
Thanks,
Michael
Quoted 10 lines
I further suggest to remove all documentation of structure details.
The following command can be used to create the raw data for a new list
grep -GHrn -B3 -A3 --regexp="\s_IO[R|W|RW]\?[_BAD]\?\s*(" \
include/uapi| \
sed ':a;N;$!ba;s/\\\s*\n[^-]*-[^-]*-/ /g' | \
sort | \
grep --regexp="\s_IO[R|W|RW]\?[BAD]\?\s*(" | grep -n ''Quoted 3 lines
Best regards
Heinrich Schuchardt
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Hello Heinrich,
Quoted 50 lines · Heinrich Schuchardt
Quoted 41 lines · Eugene Syromyatnikov
Quoted 34 lines · Michael Kerrisk (man-pages)
Hello Heinrich,
Quoted 30 lines · Heinrich Schuchardt
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_IDOn 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_IDQuoted 4 lines
Quoted 1 line
Hence hex values should be removed.
As you suggest, I've removed the hex values from the lists.
Quoted 7 lines
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*.handlinux/*/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).
Quoted 2 lines
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.
Quoted 2 lines
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.)
Quoted 1 line
shouldn't it be dropped?
I'm inclined to do so. Let's see if anyone else comments.
Cheers,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Removal of the ioctl_list(2) manual page (was: Re: ioctl_list.2: complete overhaul needed)
In reply to Heinrich Schuchardt[CC widened]
Hello Heinrich, Eugene,
Quoted 7 lines · Heinrich Schuchardt
Quoted 6 lines · Eugene Syromyatnikov
Quoted 4 lines · Michael Kerrisk (man-pages)
Hello Heinrich,
On Sun, 9 Nov 2014 at 16:52, Heinrich Schuchardt <[email protected]> wrote:
[...]
Quoted 10 lines
Quoted 9 lines
Quoted 1 line
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*.handlinux/*/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).
Quoted 5 lines
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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/