ioctl() forever? [LWN.net]

ioctl() forever?

Posted Jun 9, 2022 15:43 UTC (Thu) by mathstuf (subscriber, #69389)
In reply to: ioctl() forever? by karim
Parent article: ioctl() forever?

So, uh, what format will this communicate the requirements in? Snippets of C headers? ;)

to post comments

ioctl() forever?

Posted Jun 9, 2022 15:54 UTC (Thu) by karim (subscriber, #114) [Link] (4 responses)

man pages may have good examples. If you do a "man 2 open", for instance, it lists all possible open flags with a description. Maybe something like that?

ioctl() forever?

Posted Jun 9, 2022 16:27 UTC (Thu) by mathstuf (subscriber, #69389) [Link] (3 responses)

From `ioman(1)`, sure. But what will `man_ioctl(2)` use to communicate whatever gets converted into groff format (or is the kernel going to speak groff directly?).

ioctl() forever?

Posted Jun 9, 2022 16:39 UTC (Thu) by karim (subscriber, #114) [Link] (2 responses)

Very good question. I can't say I thought it all the way through. Maybe another inspiration could be online help output from commands that print options when you provide "-h" ... i.e. just some free-form text to be printed on screen when invoked. It's a rough cut of an idea. Definitely requires some more forethought to be useful. But, personally, I'd love to have a way to ask about the ioctl()s available for any /dev/foo and even have a tool to invoke them from the command line if it makes sense.

ioctl() forever?

Posted Jun 9, 2022 17:04 UTC (Thu) by NYKevin (subscriber, #129325) [Link] (1 responses)

You can't force people to write documentation. If you try, you just end up with something like the following:

> int FrobnicateSprocket(Sprocket *s)
> Frobnicates a sprocket.
>
> Arguments:
> s: The sprocket to frobnicate.
>
> Returns:
> Zero if no error, or nonzero and sets errno.
>
> Errno values:
> EPERM - Frobnicating this sprocket is not permitted.

IMHO if you're going to do something like this, it should be a machine-readable enumeration of commands, not a man page.

ioctl() forever?

Posted Jun 11, 2022 12:26 UTC (Sat) by pm215 (subscriber, #98099) [Link]

If you're the kernel maintainers you absolutely can force people to write documentation -- just refuse to merge any patch that adds a new syscall or ioctl and doesn't include documentation as part of the patchset. You can set the quality bar at any level you like. If stuff slips through the code review stage without sufficient documentation, you can revert it.

In other words, allowing or not allowing undocumented new interfaces is a choice, just as allowing or not allowing changes that break userspace is a choice.