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.
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.
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.
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:
Thanks,
Marc
-- System Information:
Debian Release: 10.2
APT prefers stable
APT policy: (990, 'stable'), (500, 'unstable-debug'), (500, 'testing-debug'),
(500, 'stable-updates'), (500, 'stable-debug'), (500, 'oldstable-updates'),
(500, 'oldstable-debug'), (500, 'unstable'), (500, 'testing'), (500,
'oldstable'), (1, 'experimental-debug'), (1, 'experimental')
Architecture: amd64 (x86_64)
Foreign Architectures: i386, x32
Kernel: Linux 5.2.21-050221-generic (SMP w/8 CPU cores)
Kernel taint flags: TAINT_PROPRIETARY_MODULE, TAINT_OOT_MODULE,
TAINT_UNSIGNED_MODULE
Locale: LANG=en_DK.UTF-8, LC_CTYPE=en_DK.UTF-8 (charmap=UTF-8),
LANGUAGE=en_DK.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
Versions of packages manpages-dev depends on:
ii manpages 4.16-2
manpages-dev recommends no packages.
Versions of packages manpages-dev suggests:
ii konqueror [man-browser] 4:18.12.0-1
ii man-db [man-browser] 2.8.5-2
-- no debconf information
