Upstream maintainer here.
On 12/20/19 9:32 PM, Marc Lehmann wrote:
> Package: manpages-dev
> Version: 5.04-1
> Severity: wishlist
>
> Dear Maintainer,
>
> the timerfd_create/settime/... manpage documents that reads from a timerfd
> configured with TFD_TIMER_CANCEL_ON_SET fail with ECANCELED, however, I
> found that timerfd_settime (and probably timerfd_gettime and others) have
> the same behaviour, and of course youc an poll for this event as well, and
> all this is not documented.
Thanks for the bug report.
Using a small test program, I can confirm that this behavior occurs
for timerfd_settime(). (It looks like it doesn't occur for
timerfd_gettime() though.)
> Background: I was implementing time jump detection in libev using the
> relatively new TFD_TIMER_CANCEL_ON_SET feature. For this, I arm the timer
> with some future value and only use it for the side effect of getting
> canceled (although it might occasionally expire).
>
> The timerfd_create/settime calls look like this (future it_value.tv_sec
> value, zero interval):
>
> timerfd_create(CLOCK_REALTIME, TFD_CLOEXEC|TFD_NONBLOCK) = 5
> timerfd_settime(5, TFD_TIMER_ABSTIME|TFD_TIMER_CANCEL_ON_SET,
> {it_interval={tv_sec=0, tv_nsec=0}, it_value={tv_sec=1579464284, tv_nsec=0}},
> NULL) = 0
>
> all normal so far: On every time jump, I rearm the timer with
> timerfd_settime, without having any other interaction with the timerfd
> (other than polling it for read events). The following is the effect of
> "date -s somevalue" three times:
>
> timerfd_settime(5, TFD_TIMER_ABSTIME|TFD_TIMER_CANCEL_ON_SET,
> {it_interval={tv_sec=0, tv_nsec=0}, it_value={tv_sec=949273200, tv_nsec=0}},
> NULL) = -1 ECANCELED (Operation canceled)
> timerfd_settime(5, TFD_TIMER_ABSTIME|TFD_TIMER_CANCEL_ON_SET,
> {it_interval={tv_sec=0, tv_nsec=0}, it_value={tv_sec=949273200, tv_nsec=0}},
> NULL) = -1 ECANCELED (Operation canceled)
> timerfd_settime(5, TFD_TIMER_ABSTIME|TFD_TIMER_CANCEL_ON_SET,
> {it_interval={tv_sec=0, tv_nsec=0}, it_value={tv_sec=949273200, tv_nsec=0}},
> NULL) = -1 ECANCELED (Operation canceled)
>
>>From this, I learn that timerfd_settime fails the same way as a read would
> do (probably some error slippage happening) and despite timerfd_settime
> failing with ECANCELED, it actually succeeds in rearming the timer.
Likewise, I confirm that the call does seem to change the timer value,
even though an error is returned.
> Don't know if this is a kernel bug, but I assume this works more or less
> as designed, but has escaped the documentation as TFD_TIMER_CANCEL_ON_SET
> is a relatively new feature.
Actually, it smells of a kernel bug to me. Either an ECANCELED error should
not be returned, or the timer should not get modified. But not both.
I will attempt to follow this up on LKML.
> As a minor nitpick, the "Operating on a timer file descriptor" is a tiny
> bit misleading, as it doesn't mention timerfd_gettime etc. as supported
> "operations on a timerfd fd". And while it probably isn't a major thing in
> the context, I do expect the utmost exactness from manpages-dev because
> that is my past experiencw with it, so I suggest adding "additional" here:
>
> The file descriptor returned by timerfd_create() supports the
> following additional operations:
Yes, that makes sense. Done. (But not yet pushed to Git.)
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
