2021-12-28 Paul Eggert <eggert@cs.ucla.edu>
+ clock_getres: document portability issues better
+ * doc/posix-functions/clock_getres.texi:
+ * doc/posix-functions/timespec_getres.texi:
+ Document problems with timestamp resolution.
+
timespec_getres: new module
* lib/time.in.h (timespec_getres): New decl.
* lib/timespec_getres.c, m4/timespec_getres.m4:
@item
This function is missing on some platforms:
Mac OS X 10.11, Minix 3.1.8, mingw, MSVC 14.
+
+@item
+On many platforms, this function returns a value other than the clock
+resolution of @code{clock_gettime}, i.e., the minimum distance between
+differing timestamps. For example, on AIX 7.2 it returns 10
+milliseconds even though the clock resolution is 1 microsecond.
+Conversely, on GNU/Linux it typically returns 1 nanosecond even
+though the clock resolution may be greater.
@end itemize
The Gnulib module @code{gettime-res} is a partial substitute; it implements
-the @code{CLOCK_REALTIME} functionality of @code{clock_getres}.
+the @code{CLOCK_REALTIME} functionality of @code{clock_getres},
+and fixes the too-high resolution bug of platforms like AIX 7.2.
Portability problems not fixed by Gnulib:
@itemize
+@item
+On some platforms, this function returns a value other than the clock
+resolution of @code{timespec_get}, i.e., the minimum distance between
+differing timestamps. For example, on GNU/Linux it typically returns
+1 nanosecond regardless of the actual clock resolution.
@end itemize
+
+The Gnulib module @code{gettime-res} is a partial substitute; it implements
+the @code{TIME_UTC} functionality of @code{timespec_getres}.