windows: fix conversions related to Filetime

Filetime.Nanoseconds() has a major drawback: the returned int64 is too
small to represent Filetime's zero value (January 1, 1601) in terms of
nanoseconds since Epoch (00:00:00 UTC, January 1, 1970); MinInt64 only
dates back to year 1677.

This has real-life implications, e.g., some Windows sub systems
(Perflib, to name one) create registry keys with the last write time
property set to zero. In this case, using Nanoseconds() reports an
underflow-affected value of 2185-07-22T00:34:33.709551+01:00.

This commit clearly marks the well-defined boundaries of Nanoseconds().
It introduces the new Unix() that returns a well-known pair of seconds
and nanoseconds (see other mentions in syscall.go) thus is capable to
cover the full range of Filetime values. Additionally, other conversions
related to Filetime are refactored to use full-range values where
possible, and to reflect boundaries in the docstring where not.

See also golang/go#74335

Author: gremat

windows/example_test.go

@@ -0,0 +1,51 @@
+// Copyright 2025 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package windows_test
+
+import (
+	"fmt"
+	"math"
+	"time"
+
+	"golang.org/x/sys/windows"
+)
+
+func ExampleFiletime_Unix() {
+	ftZero := windows.Filetime{
+		HighDateTime: 0x0,
+		LowDateTime:  0x0,
+	}
+	secs, nsecs := ftZero.Unix()
+	fmt.Println(secs, nsecs)
+
+	zeroTime := time.Unix(ftZero.Unix())
+	match := zeroTime.Equal(time.Date(1601, time.January, 1, 0, 0, 0, 0, time.UTC))
+	fmt.Printf("Matches January 1, 1601: %v\n", match)
+
+	// Output:
+	// -11644473600 0
+	// Matches January 1, 1601: true
+}
+
+func ExampleNsecToFiletime() {
+	ftMin := windows.NsecToFiletime(math.MinInt64)
+	fmt.Println("Minimal Filetime with nanoseconds only:")
+	fmt.Printf("hi: %#x lo: %#x\n", ftMin.HighDateTime, ftMin.LowDateTime)
+	fmt.Printf("= %v\n", time.Unix(0, math.MinInt64).UTC())
+
+	ftMax := windows.NsecToFiletime(math.MaxInt64)
+	fmt.Println("\nMaximum Filetime with nanoseconds only:")
+	fmt.Printf("hi: %#x lo: %#x\n", ftMax.HighDateTime, ftMax.LowDateTime)
+	fmt.Printf("= %v\n", time.Unix(0, math.MaxInt64).UTC())
+
+	// Output:
+	// Minimal Filetime with nanoseconds only:
+	// hi: 0x5603ca lo: 0x5a5d3852
+	// = 1677-09-21 00:12:43.145224192 +0000 UTC
+	//
+	// Maximum Filetime with nanoseconds only:
+	// hi: 0x2e55ff3 lo: 0x501fc7ae
+	// = 2262-04-11 23:47:16.854775807 +0000 UTC
+}

windows/syscall_windows.go

@@ -740,7 +740,7 @@ func Ftruncate(fd Handle, length int64) (err error) {
 func Gettimeofday(tv *Timeval) (err error) {
 	var ft Filetime
 	GetSystemTimeAsFileTime(&ft)
-	*tv = NsecToTimeval(ft.Nanoseconds())
+	*tv = ft.ToTimeval()
 	return nil
 }
 
@@ -773,8 +773,8 @@ func Utimes(path string, tv []Timeval) (err error) {
 		return e
 	}
 	defer CloseHandle(h)
-	a := NsecToFiletime(tv[0].Nanoseconds())
-	w := NsecToFiletime(tv[1].Nanoseconds())
+	a := tv[0].ToFiletime()
+	w := tv[1].ToFiletime()
 	return SetFileTime(h, nil, &a, &w)
 }
 

windows/types_windows.go

@@ -779,10 +779,34 @@ func (tv *Timeval) Nanoseconds() int64 {
 	return (int64(tv.Sec)*1e6 + int64(tv.Usec)) * 1e3
 }
 
+func (tv *Timeval) ToFiletime() Filetime {
+	// Convert to 100-nanosecond intervals
+	hsec := uint64(tv.Sec)*1e7 + uint64(tv.Usec)/100
+	// Change starting time to January 1, 1601
+	// Note: No overflow here (11644473600*1e7 < math.MaxUint64/1e2)
+	hsec += 116444736000000000
+	// Split into high / low.
+	return Filetime{
+		LowDateTime:  uint32(hsec & 0xffffffff),
+		HighDateTime: uint32(hsec >> 32 & 0xffffffff),
+	}
+}
+
+// NsecToTimeval converts a nanosecond value nsec to a Timeval tv. The
+// result is undefined if the nanosecond value cannot be represented by
+// a Timeval (values equivalent to dates before the year 1901 or after
+// the year 2038).
 func NsecToTimeval(nsec int64) (tv Timeval) {
-	tv.Sec = int32(nsec / 1e9)
-	tv.Usec = int32(nsec % 1e9 / 1e3)
-	return
+	// Ignore overflow (math.MaxInt64/1e9 > math.MaxInt32)
+	sec := int32(nsec / 1e9)
+	usec := int32(nsec % 1e9 / 1e3)
+	if usec < 0 {
+		usec += 1e6
+		sec--
+	}
+	tv.Sec = sec
+	tv.Usec = usec
+	return tv
 }
 
 type Overlapped struct {
@@ -805,22 +829,53 @@ type Filetime struct {
 	HighDateTime uint32
 }
 
+// Unix returns Filetime ft in seconds and nanoseconds
+// since Epoch (00:00:00 UTC, January 1, 1970).
+func (ft *Filetime) Unix() (sec int64, nsec int64) {
+	// 100-nanosecond intervals since January 1, 1601
+	hsec := uint64(ft.HighDateTime)<<32 + uint64(ft.LowDateTime)
+	// Convert _before_ gauging; the nanosecond difference between Epoch
+	// (00:00:00 UTC, January 1, 1970) and Filetime's zero offset (January
+	// 1, 1601) is out of bounds for int64:
+	// -11644473600*1e7*1e2 < math.MinInt64
+	sec = int64(hsec/1e7) - 11644473600
+	nsec = int64(hsec%1e7) * 100
+	return sec, nsec
+}
+
 // Nanoseconds returns Filetime ft in nanoseconds
 // since Epoch (00:00:00 UTC, January 1, 1970).
+// The result is undefined if the Filetime cannot be represented by an
+// int64 (values equivalent to dates before the year 1677 or after the
+// year 2262, see also example of NsecToFiletime). Note that this
+// explicitly excludes the zero value of Filetime, which is equivalent
+// to January 1, 1601.
+//
+// Deprecated: use Unix instead, which returns both seconds and
+// nanoseconds thus covers the full available range of Filetime.
 func (ft *Filetime) Nanoseconds() int64 {
-	// 100-nanosecond intervals since January 1, 1601
-	nsec := int64(ft.HighDateTime)<<32 + int64(ft.LowDateTime)
-	// change starting time to the Epoch (00:00:00 UTC, January 1, 1970)
-	nsec -= 116444736000000000
-	// convert into nanoseconds
-	nsec *= 100
-	return nsec
+	sec, nsec := ft.Unix()
+	return (sec*1e9 + nsec)
+}
+
+// ToTimeval converts a Filetime ft to a Timeval tv. The result is
+// undefined if the Filetime cannot be represented by a Timeval (values
+// equivalent to dates before the year 1901 or after the year 2038).
+func (ft *Filetime) ToTimeval() Timeval {
+	sec, nsec := ft.Unix()
+	// Ignore overflow (math.MaxUint64*1e2/1e9 > math.MaxInt32)
+	return Timeval{
+		Sec:  int32(sec),
+		Usec: int32(nsec / 1e3),
+	}
 }
 
+// TODO: Drop NsecTo... altogether (at least in windows)
 func NsecToFiletime(nsec int64) (ft Filetime) {
 	// convert into 100-nanosecond
 	nsec /= 100
 	// change starting time to January 1, 1601
+	// note: no overflow here (11644473600*1e7 < math.MaxInt64/1e1)
 	nsec += 116444736000000000
 	// split into high / low
 	ft.LowDateTime = uint32(nsec & 0xffffffff)