kern/37726: request documentation of 2147 second limit on adjtime(2)

[nbsd1%y2008.pianocast.net@localhost]

>Number:         37726
>Category:       kern
>Synopsis:       request documentation of 2147 second limit on adjtime(2)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    kern-bug-people
>State:          open
>Class:          change-request
>Submitter-Id:   net
>Arrival-Date:   Wed Jan 09 13:00:00 +0000 2008
>Originator:     Dave B
>Release:        NetBSD 3.1_STABLE / i386
>Organization:
>Environment:
Many versions / platforms are probably affected.  A quick Google
search suggested the problem existed in, e.g., FreeBSD in 1999, as
well.
>Description:
If I pass a value of 2147 (long) in tv_sec, adjtime()
works fine--and the clock gradually advances; however, if
I pass a value of 2148 or greater, it returns success, yet
the clock starts to slow down--and a subsequent call
adjtime() returns erroneous, negative values in
olddelta.tv_sec and olddelta.tv_usec.

>How-To-Repeat:
/* A code snippet which may help. ** adjtime.c ** */

#include <stdio.h>
#include <stdlib.h>
#include <sys/time.h>

int
adjtime( const struct timeval *delta, struct timeval *olddelta );

main( int argc, char *argv[] )
{
  int stat ;
  long l_sec, l_usec ;
  struct timeval delta, olddelta ;

  if ( argc != 2 ) {
    fprintf( stderr, "Usage: %s <(long) seconds to step>\n\n",
      argv[0] );
    exit(1);
  }

  l_sec = atol( argv[1] );

  delta.tv_sec = l_sec ;
  delta.tv_usec = 0L ;

  stat = adjtime( &delta, &olddelta );
  if (stat != 0) {
    perror( "main()/adjtime()" );
  }

  printf( "Old: %ld.%ldsec\n", olddelta.tv_sec, olddelta.tv_usec );
}
>Fix:
Add user-friendly explanation (by someone with the needed language
skills...) of the limitation described above to the adjtime(2) man
page (and maybe to rdate(8)? Although rdate(8) does refer to adjtime(2)
already; so, less necessary).