Fix various issues in the 'Timer File Descriptors' documentation

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.
@@ -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`.
@@ -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

Modules/posixmodule.c

@@ -11518,17 +11518,17 @@ 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]*/
 
 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;
@@ -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;