Re: clock_settime(2) error for non-settable clocks

On Thu, 26 Mar 2020 at 09:37, Michael Kerrisk (man-pages)
[off-list ref] wrote:

Eric,

On 3/20/20 7:02 PM, Eric Rannaud wrote:

quoted

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 [off-list ref]
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 [off-list ref]

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/