https://github.com/python/cpython/commit/13ab4c2861442f3c558abdb5971716261bf15964 commit: 13ab4c2861442f3c558abdb5971716261bf15964 branch: main author: Omar Sandoval <[email protected]> committer: StanFromIreland <[email protected]> date: 2026-08-25T18:47:38+01:00 summary:
Fix various issues in the 'Timer File Descriptors' documentation (#156027) Co-authored-by: Stan Ulbrych <[email protected]> files: M Doc/library/os.rst M Modules/clinic/posixmodule.c.h M Modules/posixmodule.c diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 0f033efefd209cd..596597b1ab223ee 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4577,16 +4577,17 @@ Naturally, they are all only available on Linux. - :const:`time.CLOCK_BOOTTIME` (Since Linux 3.15 for timerfd_create) If *clockid* is :const:`time.CLOCK_REALTIME`, a settable system-wide - real-time clock is used. If system clock is changed, timer setting need - to be updated. To cancel timer when system clock is changed, see + real-time clock is used. If the system clock is changed, the timer setting + needs to be updated. To cancel the timer when the system clock is changed, see :const:`TFD_TIMER_CANCEL_ON_SET`. If *clockid* is :const:`time.CLOCK_MONOTONIC`, a non-settable monotonically increasing clock is used. Even if the system clock is changed, the timer setting will not be affected. - If *clockid* is :const:`time.CLOCK_BOOTTIME`, same as :const:`time.CLOCK_MONOTONIC` - except it includes any time that the system is suspended. + If *clockid* is :const:`time.CLOCK_BOOTTIME`, it is the same as + :const:`time.CLOCK_MONOTONIC` except it includes any time that the system + is suspended. The file descriptor's behaviour can be modified by specifying a *flags* value. Any of the following variables may be used, combined using bitwise OR @@ -4597,8 +4598,8 @@ Naturally, they are all only available on Linux. If :const:`TFD_NONBLOCK` is not set as a flag, :func:`read` blocks until the timer expires. If it is set as a flag, :func:`read` doesn't block, but - If there hasn't been an expiration since the last call to read, - :func:`read` raises :class:`OSError` with ``errno`` is set to + if there hasn't been an expiration since the last call to read, + :func:`read` raises :class:`OSError` with ``errno`` set to :const:`errno.EAGAIN`. :const:`TFD_CLOEXEC` is always set by Python automatically. @@ -4613,7 +4614,7 @@ Naturally, they are all only available on Linux. .. versionadded:: 3.13 -.. function:: timerfd_settime(fd, /, *, flags=flags, initial=0.0, interval=0.0) +.. function:: timerfd_settime(fd, /, *, flags=0, initial=0.0, interval=0.0) Alter a timer file descriptor's internal timer. This function operates the same interval timer as :func:`timerfd_settime_ns`. @@ -4628,12 +4629,11 @@ Naturally, they are all only available on Linux. - :const:`TFD_TIMER_CANCEL_ON_SET` The timer is disabled by setting *initial* to zero (``0``). - If *initial* is equal to or greater than zero, the timer is enabled. + If *initial* is greater than zero, the timer is enabled. If *initial* is less than zero, it raises an :class:`OSError` exception - with ``errno`` set to :const:`errno.EINVAL` + with ``errno`` set to :const:`errno.EINVAL`. By default the timer will fire when *initial* seconds have elapsed. - (If *initial* is zero, timer will fire immediately.) However, if the :const:`TFD_TIMER_ABSTIME` flag is set, the timer will fire when the timer's clock @@ -4644,13 +4644,13 @@ Naturally, they are all only available on Linux. If *interval* is greater than zero, the timer fires every time *interval* seconds have elapsed since the previous expiration. If *interval* is less than zero, it raises :class:`OSError` with ``errno`` - set to :const:`errno.EINVAL` + set to :const:`errno.EINVAL`. If the :const:`TFD_TIMER_CANCEL_ON_SET` flag is set along with :const:`TFD_TIMER_ABSTIME` and the clock for this timer is :const:`time.CLOCK_REALTIME`, the timer is marked as cancelable if the real-time clock is changed discontinuously. Reading the descriptor is - aborted with the error ECANCELED. + aborted with the error :const:`errno.ECANCELED`. Linux manages system clock as UTC. A daylight-savings time transition is done by changing time offset only and doesn't cause discontinuous system diff --git a/Modules/clinic/posixmodule.c.h b/Modules/clinic/posixmodule.c.h index 6278eb81481402d..7c8171c04c0727b 100644 --- a/Modules/clinic/posixmodule.c.h +++ b/Modules/clinic/posixmodule.c.h @@ -7077,9 +7077,9 @@ PyDoc_STRVAR(os_timerfd_settime_ns__doc__, " flags\n" " 0 or a bit mask of TFD_TIMER_ABSTIME or TFD_TIMER_CANCEL_ON_SET.\n" " initial\n" -" initial expiration timing in seconds.\n" +" initial expiration timing in nanoseconds.\n" " interval\n" -" interval for the timer in seconds."); +" interval for the timer in nanoseconds."); #define OS_TIMERFD_SETTIME_NS_METHODDEF \ {"timerfd_settime_ns", _PyCFunction_CAST(os_timerfd_settime_ns), METH_FASTCALL|METH_KEYWORDS, os_timerfd_settime_ns__doc__}, @@ -7175,7 +7175,7 @@ PyDoc_STRVAR(os_timerfd_gettime__doc__, "timerfd_gettime($module, fd, /)\n" "--\n" "\n" -"Return a tuple of a timer file descriptor\'s (interval, next expiration) in float seconds.\n" +"Return a tuple of a timer file descriptor\'s (next expiration, interval) in float seconds.\n" "\n" " fd\n" " A timer file descriptor."); @@ -7210,7 +7210,7 @@ PyDoc_STRVAR(os_timerfd_gettime_ns__doc__, "timerfd_gettime_ns($module, fd, /)\n" "--\n" "\n" -"Return a tuple of a timer file descriptor\'s (interval, next expiration) in nanoseconds.\n" +"Return a tuple of a timer file descriptor\'s (next expiration, interval) in nanoseconds.\n" "\n" " fd\n" " A timer file descriptor."); @@ -13747,4 +13747,4 @@ os__emscripten_log(PyObject *module, PyObject *const *args, Py_ssize_t nargs, Py #ifndef OS__EMSCRIPTEN_LOG_METHODDEF #define OS__EMSCRIPTEN_LOG_METHODDEF #endif /* !defined(OS__EMSCRIPTEN_LOG_METHODDEF) */ -/*[clinic end generated code: output=a5bea01c02d27152 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=d4e858cbdf280235 input=a9049054013a1b77]*/ diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index a9375e48a11d899..a114a617918f7ce 100644 --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -11484,9 +11484,9 @@ os.timerfd_settime_ns flags: int = 0 0 or a bit mask of TFD_TIMER_ABSTIME or TFD_TIMER_CANCEL_ON_SET. initial: long_long = 0 - initial expiration timing in seconds. + initial expiration timing in nanoseconds. interval: long_long = 0 - interval for the timer in seconds. + interval for the timer in nanoseconds. Alter a timer file descriptor's internal timer in nanoseconds. [clinic start generated code]*/ @@ -11494,7 +11494,7 @@ Alter a timer file descriptor's internal timer in nanoseconds. static PyObject * os_timerfd_settime_ns_impl(PyObject *module, int fd, int flags, long long initial, long long interval) -/*[clinic end generated code: output=6273ec7d7b4cc0b3 input=261e105d6e42f5bc]*/ +/*[clinic end generated code: output=6273ec7d7b4cc0b3 input=94bdcea7292157eb]*/ { struct itimerspec new_value; struct itimerspec old_value; @@ -11524,12 +11524,12 @@ os.timerfd_gettime A timer file descriptor. / -Return a tuple of a timer file descriptor's (interval, next expiration) in float seconds. +Return a tuple of a timer file descriptor's (next expiration, interval) in float seconds. [clinic start generated code]*/ static PyObject * os_timerfd_gettime_impl(PyObject *module, int fd) -/*[clinic end generated code: output=ec5a94a66cfe6ab4 input=05f7d568a4820dc6]*/ +/*[clinic end generated code: output=ec5a94a66cfe6ab4 input=7b0a7cc61ea9e31a]*/ { struct itimerspec curr_value; int result; @@ -11551,12 +11551,12 @@ os.timerfd_gettime_ns A timer file descriptor. / -Return a tuple of a timer file descriptor's (interval, next expiration) in nanoseconds. +Return a tuple of a timer file descriptor's (next expiration, interval) in nanoseconds. [clinic start generated code]*/ static PyObject * os_timerfd_gettime_ns_impl(PyObject *module, int fd) -/*[clinic end generated code: output=580633a4465f39fe input=d0de95b9782179c5]*/ +/*[clinic end generated code: output=580633a4465f39fe input=89702268455fa93b]*/ { struct itimerspec curr_value; int result; _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
