[PATCH v8 9/9] landlock: Document IOCTL support

[Günther Noack]

On Wed, Dec 13, 2023 at 12:25:15PM +0100, Mickaël Salaün wrote:
> On Fri, Dec 08, 2023 at 04:51:21PM +0100, Günther Noack wrote:
> >  Documentation/userspace-api/landlock.rst | 119 ++++++++++++++++++++---
> >  1 file changed, 104 insertions(+), 15 deletions(-)
> > 
> 
> > +Restricting IOCTL commands
> > +--------------------------
> > +
> > +When the ``LANDLOCK_ACCESS_FS_IOCTL`` access right is handled, Landlock will
> 
> I only use "right" (instead of "access right") when LANDLOCK_ACCESS_*
> precede to avoid repetition.

Done.

> > +restrict the invocation of IOCTL commands.  However, to *permit* these IOCTL
> 
> This patch introduces the "permit*" wording instead of the currently
> used "allowed", which is inconsistent.

Done.


> > ++------------------------+-------------+-------------------+-------------------+
> > +|                        | ``IOCTL``   | ``IOCTL`` handled | ``IOCTL`` handled |
> 
> I was a bit confused at first read, wondering why IOCTL was quoted, then
> I realized that it was in fact LANDLOCK_ACCESS_FS_IOCTL. Maybe using the
> "FS_" prefix would avoid this kind of misreading (same for READ_FILE)?

Done.


> > +|                        | not handled | and permitted     | and not permitted |
> > ++------------------------+-------------+-------------------+-------------------+
> > +| ``READ_FILE`` not      | allow       | allow             | deny              |
> > +| handled                |             |                   |                   |
> > ++------------------------+             +-------------------+-------------------+
> > +| ``READ_FILE`` handled  |             | allow                                 |
> > +| and permitted          |             |                                       |
> > ++------------------------+             +-------------------+-------------------+
> > +| ``READ_FILE`` handled  |             | deny                                  |
> > +| and not permitted      |             |                                       |
> 
> If it makes the raw text easier to read, it should be OK to extend this
> table to 100 columns (I guess checkpatch.pl will not complain).

I got it down to 72 columns and it still reads reasonably well.
(Emacs has support for editing ASCII tables. :))

—Günther