Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 56 insertions, 0 deletions

diff --git a/docs/nspr/reference/pr_getrandomnoise.rst b/docs/nspr/reference/pr_getrandomnoise.rst
new file mode 100644
index 0000000000..1d482572f1
--- /dev/null
+++ b/docs/nspr/reference/pr_getrandomnoise.rst
@@ -0,0 +1,56 @@
+PR_GetRandomNoise
+=================
+
+Produces a random value for use as a seed value for another random
+number generator.
+
+
+Syntax
+------
+
+.. code::
+
+   #include <prrng.h>
+
+   NSPR_API(PRSize) PR_GetRandomNoise(
+      void    *buf,
+      PRSize  size
+   );
+
+
+Parameters
+~~~~~~~~~~
+
+The function has these parameters:
+
+``buf``
+   A pointer to a caller-supplied buffer to contain the generated random
+   number. ``buf`` must be at least as large as specified in ``size``.
+
+``size``
+   The size, in bytes, of the requested random number.
+
+
+Returns
+~~~~~~~
+
+:ref:`PRSize` value equal to the size of the random number actually
+generated, or zero. The generated size may be less than the size
+requested. A return value of zero means that :ref:`PR_GetRandomNoise` is
+not implemented on this platform, or there is no available noise to be
+returned at the time of the call.
+
+
+Description
+-----------
+
+:ref:`PR_GetRandomNoise` provides a random value, depending on platform.
+The length of the random value is dependent on the platform and its
+ability to provide a random value at that moment.
+
+:ref:`PR_GetRandomNoise` is intended to provide a "seed" value for a
+another random number generator that may be suitable for cryptographic
+operations. This implies that the random value provided may not be, by
+itself, cryptographically secure. The value generated by
+:ref:`PR_GetRandomNoise` is at best, extremely difficult to predict and is
+as nondeterministic as the underlying platform permits.