Re: [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors - Michael Kerrisk (man-pages)

From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: Eric Rannaud <eric.rannaud@gmail.com>
Cc: Eric Rannaud <e@nanocritical.com>,
	linux-man <linux-man@vger.kernel.org>,
	Linux API <linux-api@vger.kernel.org>
Subject: Re: [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors
Date: Thu, 2 Apr 2020 22:19:45 +0200	[thread overview]
Message-ID: <CAKgNAkipcX47quv23SACeorSexO00nUAJR3QSTA3bFNMresE4Q@mail.gmail.com> (raw)
In-Reply-To: <CA+zRj8XYLpa_gep+VxUfQuqeKu+=thMit-jNv1soC8Mh5H43Ug@mail.gmail.com>

Hello Éric,

On Thu, 2 Apr 2020 at 22:07, Eric Rannaud <eric.rannaud@gmail.com> wrote:
>
> Micheal,
>
> I'm conscious that saying "dynamic POSIX clock device" without any
> explanation may be too obscure for a man page.

It's true that more detail would be nice, but...

> There is documentation in:
> - include/linux/posix-clock.h
> - Documentation/driver-api/ptp.rst (explicitly states that EOPNOTSUPP
> should be returned)

(Is this a reference to the tack that I tweaked your patch to change
EOPNOTSUPP to ENOTSUP?)

> - include/uapi/linux/ptp_clock.h

... it's a bit of a stretch to call any of those documentation, since
they don't really describe the concept of a dynamic POSIX clock
device.

>
> (IEEE 1588 PTP is the canonical user of these dynamic clock devices)
>
> Would you want to refer to any of these from the man page?

See above. I would be happy to add a 2 or 3 sentence note to the page
that briefly describes the concept of a POSIX clock. Would you be able
to come up with something?

> Thanks for maintaining this project!

Thanks. Though it has suffered a lot of neglect of late :-(.

Cheers,

Michael