Re: Potentially misleading documentation of SECONDS variable

[alex xmb sw ratchev]

i think this includes
if u start a bash
set clock 1h to future
and query after 1s , it may show not 0 or 1 second

On Tue, Aug 6, 2024, 18:26 Koichi Murase <myoga.murase@gmail.com> wrote:

> 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
>
>