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

Hell Éric

On 4/2/20 10:49 PM, Eric Rannaud wrote:

On Thu, Apr 2, 2020 at 1:19 PM Michael Kerrisk (man-pages)
[off-list ref] wrote:

quoted

quoted

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 think you are looking at an older version of POSIX (when what you 
say was true). In the POSIX.1-2008/SUSv4 specification of <errno.h>, 
we have:
[[
[ENOTSUP] Not supported (may be the same value as [EOPNOTSUPP]).
EOPNOTSUPP] Operation not supported on socket (may be the same value as
[ENOTSUP]).
]]

suppose for man2 it makes sense to pick one, whereas man3p has to make
the distinction.

It's a mess of course. It looks like the usual reason: BSD vs
other historical implementations. BSD invented EOPNOTSUPP for
the sockets API (and you see this reflected in POSIX.1). Other
implementations (presumably System V) had ENOTSUP (which
is what appears in POSIX.1 for timer_create() and
clock_nanosleep()).

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.

Actually, there are 0 mentions of ENOTSUP in the kernel
(other than in tools and samples). The constant that appears
in the kernel is one called ENOTSUPP (2 P's) defined as 524 
in include/linux/errno.h !! Yikes! What a mess!

And then EOPNOTSUPP defined with value 95 in the kernel file
include/uapi/asm-generic/errno.h (and with some architecture
variations as you note).

And then in glibc sysdeps/unix/sysv/linux/bits/errno.h:

[[
/* Older Linux headers do not define these constants.  */
# ifndef ENOTSUP
#  define ENOTSUP               EOPNOTSUPP
# endif
]]

And in glibc EOPNOTSUPP is 95

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.

I'm not sure we do need to pick one here. See POSIX, which uses
both. 

And see the definition of EOPNOTSUPP in POSIX. Arguably,
it is only for sockets, and everything else should be ENOTSUP.
(And for the most part, that's how things are done in the 
POSIX specifications of the APIs.)

In summary, I'm going to do nothing :-}. I checked
* the time/clock man pages; they use ENOTSUP (consistent with 
  POSIX)
* the pthreads man pages; they use ENOTSUP (consistent with POSIX)
* the sockets APIs man pages; they use EOPNOTSUPP (consistent 
  with POSIX)

The rest of the pages are a mixed bag (mostly not specified in
POSIX), and I don;t think there's any really clear fix.

quoted

quoted

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

quoted

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

Its okay -- don't feel any obligation here. You already contributed!

Cheers,

Michael

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