[m-rev.] for review: document and announce the system RNG module

[Julien Fischer]

For review by anyone.

------------------------

Document and announce the system RNG module.

library/random.system_rng.m:
     Document what sources of randomness are used by the C backends.

library/MODULES_DOC:
library/MODULES_UNDOC:
     Include random.system_rng module in the library documentation.

NEWS:
     Announce the random.system_rng module.

Julien.

diff --git a/NEWS b/NEWS
index fc72880..65a1b37 100644
--- a/NEWS
+++ b/NEWS
@@ -18,6 +18,11 @@ Changes that may break compatibility
  Changes to the Mercury standard library
  ---------------------------------------

+### New module: `random.system_rng`
+
+* This module provides an interface to a platform specific cryptographically
+  secure random number generator that is seeded from the OS entropy pool.
+
  ### Changes to the `array` module

  * The following obsolete predicates and functions have been removed:
diff --git a/library/MODULES_DOC b/library/MODULES_DOC
index eab944f..fc10b3f 100644
--- a/library/MODULES_DOC
+++ b/library/MODULES_DOC
@@ -63,6 +63,7 @@ random.m
  random.sfc16.m
  random.sfc32.m
  random.sfc64.m
+random.system_rng.m
  ranges.m
  rational.m
  rbtree.m
diff --git a/library/MODULES_UNDOC b/library/MODULES_UNDOC
index 8d92c17..fa7cca7 100644
--- a/library/MODULES_UNDOC
+++ b/library/MODULES_UNDOC
@@ -4,7 +4,6 @@ mutvar.m
  par_builtin.m
  private_builtin.m
  profiling_builtin.m
-random.system_rng.m
  region_builtin.m
  robdd.m
  rtti_implementation.m
diff --git a/library/random.system_rng.m b/library/random.system_rng.m
index b16ce3b..abd4779 100644
--- a/library/random.system_rng.m
+++ b/library/random.system_rng.m
@@ -17,6 +17,15 @@
  % random number generators. It is not intended for generating large amounts
  % of random material.
  %
+% On the C backends, the system RNG depends on the operating system.
+% For macOS, Cygwin, OpenBSD, NetBSD and versions of FreeBSD from 12 onwards,
+% the arc4random() family of functions are used.
+% For Windows, the rand_s() function is used.
+% For Linux, AIX, Solaris and versions of FreeBSD before 12, randomness is read
+% from /dev/urandom; on these system each open system RNG handle will require
+% an open file descriptor.
+% On other operating systems the system RNG is not available.
+%
  % On the C# backend, the system RNG is an instance of the
  % System.Security.Cryptography.RandomNumberGenerator class that uses the
  % default cryptographic random number generator implementation.