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

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 2406 bytes --]

On 3/2/23 14:42, Günther Noack wrote:
> Hello Alex!

Hello Günther!

> 
> 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)).

Sounds good.

> 
> 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

Cheers,

Alex


-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]