Linux-man Archive on lore.kernel.org
 help / color / Atom feed
* clock_settime(2) error for non-settable clocks
@ 2020-03-20 18:02 Eric Rannaud
  2020-03-21  3:56 ` Aleksa Sarai
  2020-03-26  8:37 ` Michael Kerrisk (man-pages)
  0 siblings, 2 replies; 15+ messages in thread
From: Eric Rannaud @ 2020-03-20 18:02 UTC (permalink / raw)
  To: linux-api, linux-man

If clock_id is a valid clock on the system (i.e. it can be passed to
clock_gettime(2)), clock_settime(clock_id, &ts) sets errno to, either:

  - EINVAL if CONFIG_POSIX_TIMERS is not enabled (kernel/posix-stubs.c);
  - EINVAL if CONFIG_POSIX_TIMERS is enabled (kernel/posix-timers.c)
and the k_clock has no set function (e.g. CLOCK_BOOTTIME);
  - EACCES for dynamic posix clock devices that lack F_WRITE
(kernel/posix-time.c);
  - EOPNOTSUPP for dynamic posix clock devices that have F_WRITE but
don't have a clock_settime op.
  - EOPNOTSUPP for drivers/ptp/ptp_kvm.c (they provide a clock_settime
op that returns -EOPNOTSUPP directly, rather than opt to leave
clock_settime NULL which would do the same thing, see previous point).

The manpage for clock_settime(2) is not very clear:

       EINVAL The clk_id specified is not supported on this system.

       EPERM  clock_settime() does not have permission to set the clock  indi‐
              cated.

To me, the manpage reads like EPERM should be expected when trying to
set a clock that is not settable.

Should we update the manpage to more fully explain the range of
possible errors or instead try to have more consistent errors? For
syscalls, what's the backward-compatibility contract for errno values?

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: clock_settime(2) error for non-settable clocks
  2020-03-20 18:02 clock_settime(2) error for non-settable clocks Eric Rannaud
@ 2020-03-21  3:56 ` Aleksa Sarai
  2020-03-26  8:37 ` Michael Kerrisk (man-pages)
  1 sibling, 0 replies; 15+ messages in thread
From: Aleksa Sarai @ 2020-03-21  3:56 UTC (permalink / raw)
  To: Eric Rannaud; +Cc: linux-api, linux-man


[-- Attachment #1: Type: text/plain, Size: 715 bytes --]

On 2020-03-20, Eric Rannaud <eric.rannaud@gmail.com> wrote:
> Should we update the manpage to more fully explain the range of
> possible errors or instead try to have more consistent errors? For
> syscalls, what's the backward-compatibility contract for errno values?

It's the same as everything else -- "if it breaks an existing
application, it's a regression". There was an infamous case of this
exact scenario happening (changing the errno returned from an ioctl
broke pulseaudio) in 2012[1].

[1]: https://lore.kernel.org/lkml/CA+55aFzX56kPPwSO97X=UyPaMzV5QRNG9ScN=nxnHFjmz=_8yA@mail.gmail.com/

-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
<https://www.cyphar.com/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: clock_settime(2) error for non-settable clocks
  2020-03-20 18:02 clock_settime(2) error for non-settable clocks Eric Rannaud
  2020-03-21  3:56 ` Aleksa Sarai
@ 2020-03-26  8:37 ` Michael Kerrisk (man-pages)
  2020-03-29 20:49   ` Michael Kerrisk (man-pages)
  1 sibling, 1 reply; 15+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-03-26  8:37 UTC (permalink / raw)
  To: Eric Rannaud, linux-api, linux-man; +Cc: mtk.manpages, Aleksa Sarai

Eric,

On 3/20/20 7:02 PM, Eric Rannaud wrote:
> If clock_id is a valid clock on the system (i.e. it can be passed to
> clock_gettime(2)), clock_settime(clock_id, &ts) sets errno to, either:
> 
>   - EINVAL if CONFIG_POSIX_TIMERS is not enabled (kernel/posix-stubs.c);
>   - EINVAL if CONFIG_POSIX_TIMERS is enabled (kernel/posix-timers.c)
> and the k_clock has no set function (e.g. CLOCK_BOOTTIME);
>   - EACCES for dynamic posix clock devices that lack F_WRITE
> (kernel/posix-time.c);
>   - EOPNOTSUPP for dynamic posix clock devices that have F_WRITE but
> don't have a clock_settime op.
>   - EOPNOTSUPP for drivers/ptp/ptp_kvm.c (they provide a clock_settime
> op that returns -EOPNOTSUPP directly, rather than opt to leave
> clock_settime NULL which would do the same thing, see previous point).
> 
> The manpage for clock_settime(2) is not very clear:
> 
>        EINVAL The clk_id specified is not supported on this system.
> 
>        EPERM  clock_settime() does not have permission to set the clock  indi‐
>               cated.
> 
> To me, the manpage reads like EPERM should be expected when trying to
> set a clock that is not settable.
> 
> Should we update the manpage to more fully explain the range of
> possible errors or instead try to have more consistent errors? For
> syscalls, what's the backward-compatibility contract for errno values?

A man-pages patch would be most appropriate. Would you be able to put
something together?

Thanks,

Michael



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

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: clock_settime(2) error for non-settable clocks
  2020-03-26  8:37 ` Michael Kerrisk (man-pages)
@ 2020-03-29 20:49   ` Michael Kerrisk (man-pages)
  2020-04-02 11:48     ` Michael Kerrisk (man-pages)
  0 siblings, 1 reply; 15+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-03-29 20:49 UTC (permalink / raw)
  To: Eric Rannaud, Linux API, linux-man; +Cc: Aleksa Sarai

On Thu, 26 Mar 2020 at 09:37, Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
>
> Eric,
>
> On 3/20/20 7:02 PM, Eric Rannaud wrote:
> > If clock_id is a valid clock on the system (i.e. it can be passed to
> > clock_gettime(2)), clock_settime(clock_id, &ts) sets errno to, either:
> >
> >   - EINVAL if CONFIG_POSIX_TIMERS is not enabled (kernel/posix-stubs.c);
> >   - EINVAL if CONFIG_POSIX_TIMERS is enabled (kernel/posix-timers.c)
> > and the k_clock has no set function (e.g. CLOCK_BOOTTIME);
> >   - EACCES for dynamic posix clock devices that lack F_WRITE
> > (kernel/posix-time.c);
> >   - EOPNOTSUPP for dynamic posix clock devices that have F_WRITE but
> > don't have a clock_settime op.
> >   - EOPNOTSUPP for drivers/ptp/ptp_kvm.c (they provide a clock_settime
> > op that returns -EOPNOTSUPP directly, rather than opt to leave
> > clock_settime NULL which would do the same thing, see previous point).
> >
> > The manpage for clock_settime(2) is not very clear:
> >
> >        EINVAL The clk_id specified is not supported on this system.
> >
> >        EPERM  clock_settime() does not have permission to set the clock  indi‐
> >               cated.
> >
> > To me, the manpage reads like EPERM should be expected when trying to
> > set a clock that is not settable.
> >
> > Should we update the manpage to more fully explain the range of
> > possible errors or instead try to have more consistent errors? For
> > syscalls, what's the backward-compatibility contract for errno values?
>
> A man-pages patch would be most appropriate. Would you be able to put
> something together?

I have in the meantime added this patch:

commit 238442a2de3821921e9b78117bf89519f8093c42 (HEAD -> master)
Author: Michael Kerrisk <mtk.manpages@gmail.com>
Date:   Sun Mar 29 22:36:19 2020 +0200

    clock_getres.2: ERRORS: add EINVAL for attempt to set a nonsettable clock

    Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
index ed9310208..66ed84c5c 100644
--- a/man2/clock_getres.2
+++ b/man2/clock_getres.2
@@ -237,6 +237,13 @@ is negative or
 .I tp.tv_nsec
 is outside the range [0..999,999,999].
 .TP
+.B EINVAL
+The
+.I clk_id
+specified in a call to
+.BR clock_settime ()
+is not a settable clock.
+.TP
 .BR EINVAL " (since Linux 4.3)"
 .\" commit e1d7ba8735551ed79c7a0463a042353574b96da3
 A call to

Thanks,

Michael

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

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: clock_settime(2) error for non-settable clocks
  2020-03-29 20:49   ` Michael Kerrisk (man-pages)
@ 2020-04-02 11:48     ` Michael Kerrisk (man-pages)
  2020-04-02 14:23       ` [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors Eric Rannaud
  2020-04-02 14:29       ` clock_settime(2) error for non-settable clocks Eric Rannaud
  0 siblings, 2 replies; 15+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-04-02 11:48 UTC (permalink / raw)
  To: Eric Rannaud, Linux API, linux-man; +Cc: Aleksa Sarai

Eric,

See also my changes in
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=96d951a401c65525bec0f973946b8dfb24afd670

A textual table in that commit captures most of what I know. Still,
some pieces that you mentioned are not covered. (patches welcome)

Thanks,

Michael

^ permalink raw reply	[flat|nested] 15+ messages in thread

* [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors
  2020-04-02 11:48     ` Michael Kerrisk (man-pages)
@ 2020-04-02 14:23       ` Eric Rannaud
  2020-04-02 19:55         ` Michael Kerrisk (man-pages)
  2020-04-02 20:06         ` Eric Rannaud
  2020-04-02 14:29       ` clock_settime(2) error for non-settable clocks Eric Rannaud
  1 sibling, 2 replies; 15+ messages in thread
From: Eric Rannaud @ 2020-04-02 14:23 UTC (permalink / raw)
  To: linux-man
  Cc: Michael Kerrisk (man-pages), Linux API, Eric Rannaud, Eric Rannaud

See Linux source as of v5.4:
  kernel/time/posix-clock.c

Signed-off-by: Eric Rannaud <e@nanocritical.com>
---
 man2/clock_getres.2 | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
index 0154f9d32473..71f7f8dfa662 100644
--- a/man2/clock_getres.2
+++ b/man2/clock_getres.2
@@ -260,6 +260,10 @@ specified in a call to
 .BR clock_settime ()
 is not a settable clock.
 .TP
+.B EOPNOTSUPP
+The operation is not supported by the dynamic POSIX clock device
+specified.
+.TP
 .BR EINVAL " (since Linux 4.3)"
 .\" commit e1d7ba8735551ed79c7a0463a042353574b96da3
 A call to
@@ -276,6 +280,11 @@ clock.
 .B EPERM
 .BR clock_settime ()
 does not have permission to set the clock indicated.
+.TP
+.B EACCES
+.BR clock_settime ()
+does not have write permission for the dynamic POSIX
+clock device indicated.
 .SH VERSIONS
 These system calls first appeared in Linux 2.6.
 .SH ATTRIBUTES
-- 
2.26.0


^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: clock_settime(2) error for non-settable clocks
  2020-04-02 11:48     ` Michael Kerrisk (man-pages)
  2020-04-02 14:23       ` [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors Eric Rannaud
@ 2020-04-02 14:29       ` Eric Rannaud
  1 sibling, 0 replies; 15+ messages in thread
From: Eric Rannaud @ 2020-04-02 14:29 UTC (permalink / raw)
  To: mtk.manpages; +Cc: Linux API, linux-man, Aleksa Sarai

Hi Michael,

I just sent a patch to the mailing list [1] capturing additional error
codes returned for dynamic POSIX clock devices.

Thanks,
Eric

1. https://marc.info/?l=linux-man&m=158583744306140&w=2

On Thu, Apr 2, 2020 at 4:48 AM Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
>
> Eric,
>
> See also my changes in
> https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=96d951a401c65525bec0f973946b8dfb24afd670
>
> A textual table in that commit captures most of what I know. Still,
> some pieces that you mentioned are not covered. (patches welcome)
>
> Thanks,
>
> Michael

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors
  2020-04-02 14:23       ` [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors Eric Rannaud
@ 2020-04-02 19:55         ` Michael Kerrisk (man-pages)
  2020-04-02 20:06         ` Eric Rannaud
  1 sibling, 0 replies; 15+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-04-02 19:55 UTC (permalink / raw)
  To: Eric Rannaud, linux-man; +Cc: mtk.manpages, Linux API, Eric Rannaud

Hello Eric,

On 4/2/20 4:23 PM, Eric Rannaud wrote:
> See Linux source as of v5.4:
>   kernel/time/posix-clock.c
> 
> Signed-off-by: Eric Rannaud <e@nanocritical.com>

Thanks! Patch applied.

Cheers,

Michael

> ---
>  man2/clock_getres.2 | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
> index 0154f9d32473..71f7f8dfa662 100644
> --- a/man2/clock_getres.2
> +++ b/man2/clock_getres.2
> @@ -260,6 +260,10 @@ specified in a call to
>  .BR clock_settime ()
>  is not a settable clock.
>  .TP
> +.B EOPNOTSUPP
> +The operation is not supported by the dynamic POSIX clock device
> +specified.
> +.TP
>  .BR EINVAL " (since Linux 4.3)"
>  .\" commit e1d7ba8735551ed79c7a0463a042353574b96da3
>  A call to
> @@ -276,6 +280,11 @@ clock.
>  .B EPERM
>  .BR clock_settime ()
>  does not have permission to set the clock indicated.
> +.TP
> +.B EACCES
> +.BR clock_settime ()
> +does not have write permission for the dynamic POSIX
> +clock device indicated.
>  .SH VERSIONS
>  These system calls first appeared in Linux 2.6.
>  .SH ATTRIBUTES
> 


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

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors
  2020-04-02 14:23       ` [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors Eric Rannaud
  2020-04-02 19:55         ` Michael Kerrisk (man-pages)
@ 2020-04-02 20:06         ` Eric Rannaud
  2020-04-02 20:19           ` Michael Kerrisk (man-pages)
  1 sibling, 1 reply; 15+ messages in thread
From: Eric Rannaud @ 2020-04-02 20:06 UTC (permalink / raw)
  To: Eric Rannaud; +Cc: linux-man, Michael Kerrisk (man-pages), Linux API

Micheal,

I'm conscious that saying "dynamic POSIX clock device" without any
explanation may be too obscure for a man page.

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

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

Thanks for maintaining this project!
Eric

On Thu, Apr 2, 2020 at 7:24 AM Eric Rannaud <e@nanocritical.com> wrote:
>
> See Linux source as of v5.4:
>   kernel/time/posix-clock.c
>
> Signed-off-by: Eric Rannaud <e@nanocritical.com>
> ---
>  man2/clock_getres.2 | 9 +++++++++
>  1 file changed, 9 insertions(+)
>
> diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
> index 0154f9d32473..71f7f8dfa662 100644
> --- a/man2/clock_getres.2
> +++ b/man2/clock_getres.2
> @@ -260,6 +260,10 @@ specified in a call to
>  .BR clock_settime ()
>  is not a settable clock.
>  .TP
> +.B EOPNOTSUPP
> +The operation is not supported by the dynamic POSIX clock device
> +specified.
> +.TP
>  .BR EINVAL " (since Linux 4.3)"
>  .\" commit e1d7ba8735551ed79c7a0463a042353574b96da3
>  A call to
> @@ -276,6 +280,11 @@ clock.
>  .B EPERM
>  .BR clock_settime ()
>  does not have permission to set the clock indicated.
> +.TP
> +.B EACCES
> +.BR clock_settime ()
> +does not have write permission for the dynamic POSIX
> +clock device indicated.
>  .SH VERSIONS
>  These system calls first appeared in Linux 2.6.
>  .SH ATTRIBUTES
> --
> 2.26.0
>

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors
  2020-04-02 20:06         ` Eric Rannaud
@ 2020-04-02 20:19           ` Michael Kerrisk (man-pages)
  2020-04-02 20:49             ` Eric Rannaud
  0 siblings, 1 reply; 15+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-04-02 20:19 UTC (permalink / raw)
  To: Eric Rannaud; +Cc: Eric Rannaud, linux-man, Linux API

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

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors
  2020-04-02 20:19           ` Michael Kerrisk (man-pages)
@ 2020-04-02 20:49             ` Eric Rannaud
  2020-04-02 20:50               ` Eric Rannaud
                                 ` (2 more replies)
  0 siblings, 3 replies; 15+ messages in thread
From: Eric Rannaud @ 2020-04-02 20:49 UTC (permalink / raw)
  To: mtk.manpages; +Cc: Eric Rannaud, linux-man, Linux API

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

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors
  2020-04-02 20:49             ` Eric Rannaud
@ 2020-04-02 20:50               ` Eric Rannaud
  2020-04-03  7:02               ` Michael Kerrisk (man-pages)
  2020-04-20 11:13               ` Michael Kerrisk (man-pages)
  2 siblings, 0 replies; 15+ messages in thread
From: Eric Rannaud @ 2020-04-02 20:50 UTC (permalink / raw)
  To: mtk.manpages; +Cc: Eric Rannaud, linux-man, Linux API

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

Err.. please ignore the values in this paragraph, they belong to the
next paragraph referring to kernel code.

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors
  2020-04-02 20:49             ` Eric Rannaud
  2020-04-02 20:50               ` Eric Rannaud
@ 2020-04-03  7:02               ` Michael Kerrisk (man-pages)
  2020-04-03 16:42                 ` Eric Rannaud
  2020-04-20 11:13               ` Michael Kerrisk (man-pages)
  2 siblings, 1 reply; 15+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-04-03  7:02 UTC (permalink / raw)
  To: Eric Rannaud; +Cc: mtk.manpages, Eric Rannaud, linux-man, Linux API

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

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

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/

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors
  2020-04-03  7:02               ` Michael Kerrisk (man-pages)
@ 2020-04-03 16:42                 ` Eric Rannaud
  0 siblings, 0 replies; 15+ messages in thread
From: Eric Rannaud @ 2020-04-03 16:42 UTC (permalink / raw)
  To: Michael Kerrisk (man-pages); +Cc: Eric Rannaud, linux-man, Linux API

On Fri, Apr 3, 2020 at 12:02 AM Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
> 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!

> ...

Fair enough! I didn't even see the extra P in ENOTSUPP when I was
looking at the kernel code. Thanks for the detailed analysis.

Eric

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors
  2020-04-02 20:49             ` Eric Rannaud
  2020-04-02 20:50               ` Eric Rannaud
  2020-04-03  7:02               ` Michael Kerrisk (man-pages)
@ 2020-04-20 11:13               ` Michael Kerrisk (man-pages)
  2 siblings, 0 replies; 15+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-04-20 11:13 UTC (permalink / raw)
  To: Eric Rannaud; +Cc: Eric Rannaud, linux-man, Linux API

Hello Eric,

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

Cough! I found an old patch in my inbox...

https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=f377393edddb6321a53c3e5ba516977e04d10445
(plus some edits in some subsequent commits)

Thanks,

Michael

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

^ permalink raw reply	[flat|nested] 15+ messages in thread

end of thread, back to index

Thread overview: 15+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-03-20 18:02 clock_settime(2) error for non-settable clocks Eric Rannaud
2020-03-21  3:56 ` Aleksa Sarai
2020-03-26  8:37 ` Michael Kerrisk (man-pages)
2020-03-29 20:49   ` Michael Kerrisk (man-pages)
2020-04-02 11:48     ` Michael Kerrisk (man-pages)
2020-04-02 14:23       ` [PATCH 1/1] clock_getres.2: dynamic POSIX clock devices can return other errors Eric Rannaud
2020-04-02 19:55         ` Michael Kerrisk (man-pages)
2020-04-02 20:06         ` Eric Rannaud
2020-04-02 20:19           ` Michael Kerrisk (man-pages)
2020-04-02 20:49             ` Eric Rannaud
2020-04-02 20:50               ` Eric Rannaud
2020-04-03  7:02               ` Michael Kerrisk (man-pages)
2020-04-03 16:42                 ` Eric Rannaud
2020-04-20 11:13               ` Michael Kerrisk (man-pages)
2020-04-02 14:29       ` clock_settime(2) error for non-settable clocks Eric Rannaud

Linux-man Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-man/0 linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ https://lore.kernel.org/linux-man \
		linux-man@vger.kernel.org
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-man


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git