[prev in list] [next in list] [prev in thread] [next in thread] 

List:       gnulib-bug
Subject:    [PATCH 5/5] clock_getres: document portability issues better
From:       Paul Eggert <eggert () cs ! ucla ! edu>
Date:       2021-12-28 20:05:14
Message-ID: 20211228200514.375290-5-eggert () cs ! ucla ! edu
[Download RAW message or body]

* doc/posix-functions/clock_getres.texi:
* doc/posix-functions/timespec_getres.texi:
Document problems with timestamp resolution.
---
 ChangeLog                                |  5 +++++
 doc/posix-functions/clock_getres.texi    | 11 ++++++++++-
 doc/posix-functions/timespec_getres.texi |  8 ++++++++
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/ChangeLog b/ChangeLog
index 79739541e..ac8d1baea 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 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:
diff --git a/doc/posix-functions/clock_getres.texi b/doc/posix-functions/clock_getres.texi
index 1381c4649..e93e8b30f 100644
--- a/doc/posix-functions/clock_getres.texi
+++ b/doc/posix-functions/clock_getres.texi
@@ -15,7 +15,16 @@ Portability problems not fixed by Gnulib:
 @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.
diff --git a/doc/posix-functions/timespec_getres.texi b/doc/posix-functions/timespec_getres.texi
index 89d3e6f16..c18a3635f 100644
--- a/doc/posix-functions/timespec_getres.texi
+++ b/doc/posix-functions/timespec_getres.texi
@@ -15,4 +15,12 @@ glibc 2.33, macOS 12, FreeBSD 13.0, NetBSD 9.2, OpenBSD 7.0, Minix 3.3.0, AIX 7.
 
 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}.
-- 
2.33.1


[prev in list] [next in list] [prev in thread] [next in thread]