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?
