Re: [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors

[Eric Rannaud <eric.rannaud@gmail.com>]

On Thu, Apr 2, 2020 at 1:19 PM Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
> > 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?)

Oh not at all, I hadn't noticed your patch. I just wrote that sentence
to point to ptp.rst as a spec of sorts for that particular behavior
addressed by this patch.

I never know which one to use of EOPNOTSUPP or ENOTSUP since they have
the same value (in userspace) but POSIX.1 says they shouldn't. I
suppose for man2 it makes sense to pick one, whereas man3p has to make
the distinction.

For what it's worth, man2/ has 29 mentions of EOPNOTSUPP (value of 95
on x86) and 8 mentions of ENOTSUP (with a value 524).

In the kernel sources, it's 6324 vs 1512. But note that in kernel
code, EOPNOTSUPP has a value of 95 (on x86 anyway, it is arch
dependent), whereas ENOTSUP is 524. Glibc is the one that defines
ENOTSUP to EOPNOTSUPP.

So if we had to pick one for man2/ (and man7), I'd argue for
EOPNOTSUPP, for consistency with kernel code, now that I look at it in
more details.


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

I'll try, but I've never used them, so I'm not convinced I can capture
the concept clearly.

Thanks,
Eric