From fb180daafff75fd3bec7307a9fec2354db72208f Mon Sep 17 00:00:00 2001 From: Omar Sandoval Date: Tue, 18 Aug 2026 11:45:35 -0700 Subject: [PATCH 1/5] Fix os.timerfd_settime() flags default argument doc typo Document the correct default of 0 (based on the clinic input and os.timerfd_settime_ns()). --- Doc/library/os.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 525ec3a0c858ff1..fd180ec48ee88f2 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4608,7 +4608,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`. From 02659dd67c67b144cfde0d9e88201a99d3c28279 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 19 Aug 2026 11:05:48 +0100 Subject: [PATCH 2/5] Fix various additional issues --- Doc/library/os.rst | 13 ++++++------- Modules/clinic/posixmodule.c.h | 6 +++--- Modules/posixmodule.c | 6 +++--- 3 files changed, 12 insertions(+), 13 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index fd180ec48ee88f2..33e91eca767826d 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4572,7 +4572,7 @@ 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 + real-time clock is used. If system clock is changed, timer setting needs to be updated. To cancel timer when system clock is changed, see :const:`TFD_TIMER_CANCEL_ON_SET`. @@ -4592,8 +4592,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. @@ -4623,12 +4623,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 @@ -4639,7 +4638,7 @@ 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 diff --git a/Modules/clinic/posixmodule.c.h b/Modules/clinic/posixmodule.c.h index c9307a1c44d315c..1c8c09b41739053 100644 --- a/Modules/clinic/posixmodule.c.h +++ b/Modules/clinic/posixmodule.c.h @@ -7076,9 +7076,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__}, @@ -13746,4 +13746,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=f77ed566165d51da input=a9049054013a1b77]*/ +/*[clinic end generated code: output=b72b502cc7d06dde input=a9049054013a1b77]*/ diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index d94291e2ae524bc..323a19a3463c672 100644 --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -11518,9 +11518,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]*/ @@ -11528,7 +11528,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; From 5edac05f7730818eca7b589938ce6e7f1cfa44a6 Mon Sep 17 00:00:00 2001 From: Omar Sandoval Date: Wed, 19 Aug 2026 09:56:19 -0700 Subject: [PATCH 3/5] Fix return tuple order in os.timerfd_gettime*() docstring The reST docs have it right, but it's backwards in the docstring. --- Modules/clinic/posixmodule.c.h | 6 +++--- Modules/posixmodule.c | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Modules/clinic/posixmodule.c.h b/Modules/clinic/posixmodule.c.h index 1c8c09b41739053..051b6417579fd96 100644 --- a/Modules/clinic/posixmodule.c.h +++ b/Modules/clinic/posixmodule.c.h @@ -7174,7 +7174,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."); @@ -7209,7 +7209,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."); @@ -13746,4 +13746,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=b72b502cc7d06dde input=a9049054013a1b77]*/ +/*[clinic end generated code: output=d04c7c420e12abbc input=a9049054013a1b77]*/ diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index 323a19a3463c672..8a0792d0ebfcd0a 100644 --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -11558,12 +11558,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; @@ -11585,12 +11585,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; From 2cf5d93b145f48053254140f4c1f9738e3d37b9b Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 25 Aug 2026 13:49:06 +0100 Subject: [PATCH 4/5] Fix three additional issues --- Doc/library/os.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 33e91eca767826d..4a1ea66040e4d10 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4572,16 +4572,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 needs - 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 @@ -4644,7 +4645,7 @@ Naturally, they are all only available on Linux. :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 From 2f0a97e120e1aded66c07fba3c3675671937078d Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 25 Aug 2026 13:52:00 +0100 Subject: [PATCH 5/5] Regenerate clinic --- Modules/clinic/posixmodule.c.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) 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]*/