guarantee `current-seconds', etc. from 1/1/1970 UTC

For all currently supported platforms, the result was already
portable, despite the documentation's hedging.

Also fixed up the documentation in other ways, such as the fact
that `seconds->date' returns a `date*'.

collects/scribblings/reference/filesystem.scrbl

@@ -281,12 +281,13 @@ existing @racket[new].}
                                            [fail-thunk (-> any) (lambda () (raise (make-exn:fail:filesystem ....)))])
          any]{
 
-Returns the file or directory's last modification date as
+Returns the file or directory's last modification date in seconds
-platform-specific seconds (see also @secref["time"]) when
+since midnight UTC, January 1, 1970 (see also @secref["time"]) when
-@racket[secs-n] is not provided or is @racket[#f]. (For FAT
+@racket[secs-n] is not provided or is @racket[#f].
-filesystems on Windows, directories do not have modification
+
+For FAT filesystems on Windows, directories do not have modification
 dates. Therefore, the creation date is returned for a directory, but
-the modification date is returned for a file.)
+the modification date is returned for a file.
 
 If @racket[secs-n] is provided and not @racket[#f], the access and
 modification times of @racket[path] are set to the given time.

collects/scribblings/reference/time.scrbl

@@ -5,33 +5,38 @@
 
 @defproc[(current-seconds) exact-integer?]{
 
-Returns the current time in seconds. This time is always an exact
+Returns the current time in seconds since midnight UTC, January 1,
-integer based on a platform-specific starting date (with a
+1970.}
-platform-specific minimum and maximum value).
+
+
+@defproc[(current-inexact-milliseconds) real?]{
+
+Returns the current time in milliseconds since midnight UTC, January
+1, 1970. The result may contain fractions of a millisecond.
+
+@examples[(eval:alts
+(current-inexact-milliseconds)
+1289513737015.418
+)]
+
+In this example, @racket[1289513737015] is in milliseconds and @racket[418]
+is in microseconds.}
 
-The value of @racket[(current-seconds)] increases as time passes
-(increasing by 1 for each second that passes). The current time in
-seconds can be compared with a time returned by
-@racket[file-or-directory-modify-seconds].}
 
 @defproc[(seconds->date [secs-n real?]
                         [local-time? any/c #t])
-         date?]{
+         date*?]{
 
 Takes @racket[secs-n], a platform-specific time in seconds returned by
-@racket[current-seconds], @racket[current-inexact-milliseconds], 
+@racket[current-seconds], @racket[file-or-directory-modify-seconds],
-or @racket[file-or-directory-modify-seconds],
+or 1/1000th of @racket[current-inexact-milliseconds], and returns an
-and returns an instance of the @racket[date*] structure type.  If
+instance of the @racket[date*] structure type. Note that
-@racket[secs-n] is too small or large, the @exnraise[exn:fail].
+@racket[secs-n] can include fractions of a second. If @racket[secs-n]
+is too small or large, the @exnraise[exn:fail].
 
-The resulting @racket[date] reflects the time according to the local
+The resulting @racket[date*] reflects the time according to the local
 time zone if @racket[local-time?] is @racket[#t], otherwise it
-reflects a date in UTC.
+reflects a date in UTC.}
-
-The value returned by @racket[current-seconds] or
-@racket[file-or-directory-modify-seconds] is not portable among
-platforms. Convert a time in seconds using @racket[seconds->date] when
-portability is needed.}
 
 @defstruct[date ([second (integer-in 0 61)]
                  [minute (integer-in 0 59)]
@@ -74,8 +79,8 @@ See also the @racketmodname[racket/date] library.}
 @defstruct[(date* date) ([nanosecond (integer-in 0 999999999)]
                          [time-zone-name (and/c string? immutable?)])]{
 
-Extends @racket[date] with a time zone name, such as @racket["MDT"],
+Extends @racket[date] with nanoseconds and a time zone name, such as
-@racket["Mountain Daylight Time"], or @racket["UTC"].
+@racket["MDT"], @racket["Mountain Daylight Time"], or @racket["UTC"].
 
 When a @racket[date*] record is generated by @racket[seconds->date]
 with @racket[#f] as the second argument, then the
@@ -87,25 +92,10 @@ The @racket[date*] constructor accepts a mutable string for
 
 @defproc[(current-milliseconds) exact-integer?]{
 
-Returns the current ``time'' in @tech{fixnum} milliseconds (possibly
+Like @racket[current-inexact-milliseconds], but coerced to a
-negative). This time is based on a platform-specific starting date or
+@tech{fixnum} (possibly negative). Since the result is a
-on the machine's start-up time. Since the result is a @tech{fixnum},
+@tech{fixnum}, the value increases only over a limited (though
-the value increases only over a limited (though reasonably long)
+reasonably long) time on a 32-bit platform.}
-time.}
-
-
-@defproc[(current-inexact-milliseconds) real?]{
-
-Returns the current time in milliseconds since midnight UTC, January
-1, 1970. The result may contain fractions of a millisecond.
-
-@examples[(eval:alts
-(current-inexact-milliseconds)
-1289513737015.418
-)]
-
-In this example @racket[1289513737015] is in milliseconds and @racket[418]
-is in microseconds.}
 
 
 @defproc[(current-process-milliseconds [thread (or/c thread? #f)]) 
@@ -119,7 +109,7 @@ is for all Racket threads, otherwise the result is specific to the
 time while @racket[thread] ran.
 The precision of the result is platform-specific, and
 since the result is a @tech{fixnum}, the value increases only over a
-limited (though reasonably long) time.}
+limited (though reasonably long) time on a 32-bit platform.}
 
 
 @defproc[(current-gc-milliseconds) exact-integer?]{

doc/release-notes/racket/HISTORY.txt

@@ -5,6 +5,8 @@ racket/control: added call/prompt, call/comp, abort/cc and
 racket/future: handling of internal stack overflow without
  necessarily blocking on process 0; added 'overflow and
  'start-overflow-work log events
+racket/base: guarantee portable results for current-seconds
+ and file-or-directory-modify-seconds
 
 Version 5.3.0.10
 racket/base: add progress-evt?, thread-cell-values?, prefab-key?,

src/racket/src/fun.c

@@ -8542,6 +8542,7 @@ intptr_t scheme_get_thread_milliseconds(Scheme_Object *thrd)
 intptr_t scheme_get_seconds(void)
 {
 #ifdef USE_MACTIME
+  /* This is wrong, since it's not since January 1, 1970 */
   unsigned long secs;
   GetDateTime(&secs);
   return secs;