getrandom: doc and test tweaks

[Bruno Haible]

Adding some more precision to the documentation, and tweaking the unit test.


2020-05-31  Bruno Haible  <bruno@clisp.org>

        getrandom: Doc and test tweaks.
        * lib/getrandom.c (getrandom): Mention that it never returns 0, and that
        it sets errno when failing.
        * tests/test-getrandom.c (main): Disable the high-quality check on those
        platforms on which it fails.
        * doc/glibc-functions/getrandom.texi: Add Minix, AIX, HP-UX, IRIX,
        Cygwin to the list of platforms that don't have the function. Add a note
        about the quality of the result.
        * doc/glibc-headers/sys_random.texi: Don't mention the 'getrandom'
        declaration; this is fixed by module 'getrandom'.

diff --git a/doc/glibc-functions/getrandom.texi 
b/doc/glibc-functions/getrandom.texi
index 99712c7..3baf390 100644
--- a/doc/glibc-functions/getrandom.texi
+++ b/doc/glibc-functions/getrandom.texi
@@ -21,8 +21,7 @@ Portability problems fixed by Gnulib:
 @itemize
 @item
 This function is missing on some platforms:
-glibc 2.24, Mac OS X 10.5, FreeBSD 11.0, NetBSD 5.0, OpenBSD 3.8,
-Solaris 11.0, mingw, MSVC 14, Android 9.0.
+glibc 2.24, Mac OS X 10.5, FreeBSD 11.0, NetBSD 5.0, OpenBSD 3.8, Minix 3.1.8, 
AIX 7.1, HP-UX 11.31, IRIX 6.5, Solaris 11.0, Cygwin, mingw, MSVC 14, Android 
9.0.
 @item
 This function has a different return type on some platforms:
 Solaris 11.4.
@@ -30,7 +29,6 @@ Solaris 11.4.
 
 Portability problems not fixed by Gnulib:
 @itemize
-@item
-This function is missing on some platforms:
-Minix 3.1.8, IRIX 6.5.
+This function cannot produce truly random numbers on some platforms:
+GNU/Hurd, Mac OS X, GNU/kFreeBSD, FreeBSD 12.0, OpenBSD 6.5, Minix 3.3, AIX 
7.1, Haiku, mingw, MSVC 14.
 @end itemize
diff --git a/doc/glibc-headers/sys_random.texi 
b/doc/glibc-headers/sys_random.texi
index 3f33962..8f5951d 100644
--- a/doc/glibc-headers/sys_random.texi
+++ b/doc/glibc-headers/sys_random.texi
@@ -26,9 +26,6 @@ glibc 2.24, NetBSD 5.0, OpenBSD 3.8, Minix 3.1.8, AIX 7.1, 
HP-UX 11.11, IRIX 6.5
 @item
 This header file is not self-contained on some platforms:
 Mac OS X 10.13.
-@item
-This header file does not declare the @code{getrandom} function on some 
platforms:
-Mac OS X 10.5, FreeBSD 11.0, HP-UX 11.31, Solaris 11.0.
 @end itemize
 
 Portability problems not fixed by Gnulib:
diff --git a/lib/getrandom.c b/lib/getrandom.c
index ad49cae..f0b3f53 100644
--- a/lib/getrandom.c
+++ b/lib/getrandom.c
@@ -98,7 +98,8 @@ initialize (void)
 #endif
 
 /* Set BUFFER (of size LENGTH) to random bytes under the control of FLAGS.
-   Return the number of bytes written, or -1 on error.  */
+   Return the number of bytes written (> 0).
+   Upon error, return -1 and set errno.  */
 ssize_t
 getrandom (void *buffer, size_t length, unsigned int flags)
 #undef getrandom
diff --git a/tests/test-getrandom.c b/tests/test-getrandom.c
index 8b25958..f4a31c6 100644
--- a/tests/test-getrandom.c
+++ b/tests/test-getrandom.c
@@ -73,12 +73,37 @@ main (void)
 
   /* Check that GRND_NONBLOCK works.  */
   ret = getrandom (large_buf, sizeof (large_buf), GRND_RANDOM | GRND_NONBLOCK);
+  ASSERT (ret <= (ssize_t) sizeof (large_buf));
   /* It is very unlikely that so many truly random bytes were ready.  */
   if (ret < 0)
     ASSERT (errno == ENOSYS || errno == EAGAIN
             || errno == EINVAL /* Solaris */);
   else
-    ASSERT (ret > 0 && ret < sizeof (large_buf));
+    {
+      ASSERT (ret > 0);
+      /* This assertion fails on
+           - GNU/Hurd,
+           - Mac OS X,
+           - GNU/kFreeBSD, FreeBSD 12.0,
+           - OpenBSD 6.5,
+           - Minix 3.3,
+           - AIX 7.1,
+           - Haiku,
+           - native Windows.
+         This indicates that the function, when called with GRND_RANDOM flag,
+         probably does not return truly random numbers, but instead uses a
+         pseudo-random number generator.  */
+#if !(defined __GNU__ || (defined __APPLE__ && defined __MACH__) || defined 
__FreeBSD_kernel__ || defined __FreeBSD__ || defined __OpenBSD__ || defined 
__minix || defined _AIX || defined __HAIKU__ || (defined _WIN32 && ! defined 
__CYGWIN__))
+      ASSERT (ret < (ssize_t) sizeof (large_buf));
+#endif
+    }
+
+  if (getrandom (buf1, 1, 0) < 1)
+    if (getrandom (buf1, 1, GRND_RANDOM) < 1)
+      {
+        fputs ("Skipping test: getrandom is ineffective\n", stderr);
+        return 77;
+      }
 
   return 0;
 }