From fb180daafff75fd3bec7307a9fec2354db72208f Mon Sep 17 00:00:00 2001 From: Omar Sandoval Date: Tue, 18 Aug 2026 11:45:35 -0700 Subject: [PATCH 1/3] 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/3] 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/3] 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;