Re: [PATCH v2 2/2] landlock.7: Document Landlock ABI v3 (file truncation; kernel 6.2)

["Günther Noack" <gnoack3000@gmail.com>]

Hello Alex!

On Wed, Mar 01, 2023 at 10:21:13PM +0100, Alejandro Colomar wrote:
> In the subject it's not so important, but for consistency with the
> language used within the pages, I'd ask you to rewrite it as Linux 6.2
> (and similarly for patch 1/2).

Done, sure thing.


> On 2/28/23 21:52, Günther Noack wrote:
> > diff --git a/man7/landlock.7 b/man7/landlock.7
> > index f70a01484..9ddb17ae8 100644
> > --- a/man7/landlock.7
> > +++ b/man7/landlock.7
> > +Note that you might additionally need the
> 
> "Note that" is usually redundant.
> See:
> <https://lore.kernel.org/linux-man/20210729223535.qvyomfqvvahzmu5w@localhost.localdomain/>
> <https://lore.kernel.org/linux-man/20230105225235.6cjtz6orjzxzvo6v@illithid/>

Thank you, that is a good observation, the "Kemper notectomy".
This is very helpful, exactly the kind of review I was hoping for. :)

How about this rewording:

  LANDLOCK_ACCESS_FS_WRITE

    Open a file with write access.

    When opening files for writing, you will often additionally need
    the LANDLOCK_ACCESS_FS_TRUNCATE right.  In many cases, these
    system calls truncate existing files when overwriting them (e.g.
    creat(2)).

This paragraph started with "note that" because it talks about an
unintuitive side-aspect of the LANDLOCK_ACCESS_FS_WRITE_FILE right.

I reworded it to make it more clear why that should be relevant to the
reader (because creat(2) and its open(2) equivalent are used very
commonly).

Does that sound better?

The man page also explains it in more detail in the "Truncating files"
section further below.


> > +system call, this can also be done through
> > +.BR open (2)
> > +with the flags
> > +.BR "O_RDONLY | O_TRUNC" .
> 
> Expressions should go in italics.  See man-pages(7):
> 
>        Expressions, if not written on a separate indented line, should
>        be  specified in italics.  Again, the use of nonbreaking spaces
>        may be appropriate if the expression  is  inlined  with  normal
>        text.

Done.

Thank you for the review!
–Günther