Re: Revised add_key(2) man page for review

From: Michael Kerrisk (man-pages)
Date: Tue Dec 13 2016 - 06:23:33 EST


Hello David

Thanks for the review!

On 12/13/2016 11:58 AM, David Howells wrote:
> Michael Kerrisk (man-pages) <mtk.manpages@xxxxxxxxx> wrote:
>
>> The destination keyring serial number may be that of a valid
>> keyring for which the caller has write permission, or it may be
>> one of the following special keyring IDs:
>
> No comma before "or".

Actually, I think its okay with the comma. But I decided anyway to
reword this into two sentences.

>> "user" This is a general purpose key type whose payload may be
>> ...
>> "keyring"
>
> It probably makes sense to put keyring either first or last.

Done.

>
>> "keyring"
>> Keyrings are special key types that may contain links to
>> sequences of other keys of any type. If this interface
>> is used to create a keyring, then a NULL payload should
>> be specified, and plen should be zero.
>
> I think "then payload should be NULL and plen should be zero." sounds better.

Agreed. Fixed.

>> "logon" (since Linux 3.3)
>> This key type is essentially the same as "user", but it
>> does not provide reading.
>
> "permit the key to be read" rather than "provide reading", I think.

Fixed.

>> "big_key" (since Linux 3.13)
>> This key type is similar to "user", but may hold a payâ
>> load of up to 1 MiB. If the key payload is large, then
>> it may be stored in swap space rather than kernel memâ
>> ory.
>
> "stored encrypted in swap space".

Fixed.

>> printf("Key ID is %lx\n", (long) key);
>
> key_serial_t is an int. It doesn't really need casting to long.

Well, this is a common way of dealing with opaque integer system data
types, so that one does not encode a representational dependency into
printf(). (Relies on the assumption that the underlying type is no
bigger than long. The alternative these days is a cast to (intmax_t)
plus %jd.) [So, for the moment, I'll leave the text as is.]

Cheers,

Micael

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/