Adding some more precision to the documentation, and tweaking the unit test.
2020-05-31 Bruno Haible <br...@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; }