Re: Potentially misleading documentation of SECONDS variable

[Koichi Murase]

2024年8月7日(水) 0:24 Bash-help via Bug reports for the GNU Bourne Again
SHell <bug-bash@gnu.org>:
> Reading the manual at
> <https://www.gnu.org/software/bash/manual/bash.html#Bash-Variables>
> regarding the SECONDS variable, it states that
> " [..] Assignment to this variable resets the count to the value assigned,
> and the expanded value becomes the value assigned plus the number
> of seconds since the assignment. [..]"
>
> [...]
>
> As we sleep less than a full second the expanded value of SECONDS should 
> never be greater than 0 but it sometimes is. I guess this is because the 
> assignment might occur, say X.7 seconds and the expanded value will then read 
> (X+1).2 which would be rounded down to (X+1).

I think the next sentence in the manual

https://www.gnu.org/software/bash/manual/bash.html#Bash-Variables
> [...] The number of seconds at shell
> invocation and the current time are always determined by querying the
> system clock. [...]

is supposed to imply that technically. It says "The number of seconds
at shell invocation", so the starting time point is considered to have
only the "second" resolution and doesn't have the subsecond
resolution. Then, when a value is assigned, the starting time point
would be updated to the number of "seconds" at the assignment.

For example, when the assignment occurs at time X.7, the recorded time
becomes just X (with the fraction part being truncated). Then, the
value obtained from SECONDS is incremented when the clock becomes
(X+1).0. This is consistent with the observed behavior.

However, I agree that this is implicit and ambiguous. A minimal
modification is probably something like

diff --git a/doc/bash.1 b/doc/bash.1
index 1f0a23d3..3ace21e9 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -2091,7 +2091,7 @@ the value returned upon subsequent
 references is
 the number of seconds since the assignment plus the value assigned.
 The number of seconds at shell invocation and the current time are always
-determined by querying the system clock.
+determined by querying the system clock at the resolution of a second.
 If
 .SM
 .B SECONDS
diff --git a/doc/bashref.texi b/doc/bashref.texi
index 510b43f6..6ee0083b 100644
--- a/doc/bashref.texi
+++ b/doc/bashref.texi
@@ -7038,7 +7038,7 @@ Assignment to this variable resets the count to
the value assigned, and the
 expanded value becomes the value assigned plus the number of seconds
 since the assignment.
 The number of seconds at shell invocation and the current time are always
-determined by querying the system clock.
+determined by querying the system clock at the resolution of a second.
 If @env{SECONDS}
 is unset, it loses its special properties,
 even if it is subsequently reset.

--
Koichi