aboutsummaryrefslogtreecommitdiff
path: root/libstdc++-v3/doc
diff options
context:
space:
mode:
authorJonathan Wakely <jwakely@redhat.com>2019-05-29 15:45:35 +0100
committerJonathan Wakely <redi@gcc.gnu.org>2019-05-29 15:45:35 +0100
commitb0c0d878a8b5bf39dbea4c192fed26d340524439 (patch)
tree0fe0e765cf8c296b2c62be34aa53081dbb7e80a1 /libstdc++-v3/doc
parent0617e23c9531373d3b232152c0d81a2c707858d9 (diff)
downloadgcc-b0c0d878a8b5bf39dbea4c192fed26d340524439.zip
gcc-b0c0d878a8b5bf39dbea4c192fed26d340524439.tar.gz
gcc-b0c0d878a8b5bf39dbea4c192fed26d340524439.tar.bz2
PR libstdc++/85494 use rdseed and rand_s in std::random_device
Add support for additional sources of randomness to std::random_device, to allow using RDSEED for Intel CPUs and rand_s for Windows. When supported these can be selected using the tokens "rdseed" and "rand_s". For *-w64-mingw32 targets the "default" token will now use rand_s, and for other i?86-*-* and x86_64-*-* targets it will try to use "rdseed" first, then "rdrand", and finally "/dev/urandom". To simplify the declaration of std::random_device in <bits/random.h> the constructors now unconditionally call _M_init instead of _M_init_pretr1, and the function call operator now unconditionally calls _M_getval. The library code now decides whether _M_init and _M_getval should use a real source of randomness or the mt19937 engine. Existing code compiled against old libstdc++ headers will still call _M_init_pretr1 and _M_getval_pretr1, but those functions now forward to _M_init and _M_getval if a real source of randomness is available. This means existing code compiled for mingw-w64 will start to use rand_s just by linking to a new libstdc++.dll. * acinclude.m4 (GLIBCXX_CHECK_X86_RDSEED): Define macro to check if the assembler supports rdseed. * config.h.in: Regenerate. * configure: Regenerate. * configure.ac: Use GLIBCXX_CHECK_X86_RDSEED. * config/os/mingw32-w64/os_defines.h (_GLIBCXX_USE_CRT_RAND_S): Define. * doc/html/*: Regenerate. * doc/xml/manual/status_cxx2011.xml: Document new tokens. * include/bits/random.h (random_device::random_device()): Always call _M_init rather than _M_init_pretr1. (random_device::random_device(const string&)): Likewise. (random_device::operator()()): Always call _M_getval(). (random_device::_M_file): Replace first member of union with an anonymous struct, with _M_file as its first member. * src/c++11/random.cc [_GLIBCXX_X86_RDRAND] (USE_RDRAND): Define. [_GLIBCXX_X86_RDSEED] (USE_RDSEED): Define. (USE_MT19937): Define if none of the above are defined. (USE_POSIX_FILE_IO): Define. (_M_strtoul): Remove. [USE_RDSEED] (__x86_rdseed): Define new function. [_GLIBCXX_USE_CRT_RAND_S] (__winxp_rand_s): Define new function. (random_device::_M_init(const string&)): Initialize new union members. Add support for "rdseed" and "rand_s" tokens. Decide what the "default" token does according to which USE_* macros are defined. [USE_POSIX_FILE_IO]: Store a file descriptor. [USE_MT19937]: Forward to _M_init_pretr1 instead. (random_device::_M_init_pretr1(const string&)) [USE_MT19937]: Inline code from _M_strtoul. [!USE_MT19937]: Call _M_init, transforming the old default token or numeric tokens to "default". (random_device::_M_fini()) [USE_POSIX_FILE_IO]: Use close not fclose. (random_device::_M_getval()): Use new union members to obtain a random number from the stored function pointer or file descriptor. [USE_MT19937]: Obtain a value from the mt19937 engine. (random_device::_M_getval_pretr1()): Call _M_getval(). (random_device::_M_getentropy()) [USE_POSIX_FILE_IO]: Use _M_fd instead of fileno. [!USE_MT19937] (mersenne_twister): Do not instantiate when not needed. * testsuite/26_numerics/random/random_device/85494.cc: New test. From-SVN: r271740
Diffstat (limited to 'libstdc++-v3/doc')
-rw-r--r--libstdc++-v3/doc/html/manual/appendix_contributing.html2
-rw-r--r--libstdc++-v3/doc/html/manual/status.html42
-rw-r--r--libstdc++-v3/doc/xml/manual/status_cxx2011.xml66
3 files changed, 87 insertions, 23 deletions
diff --git a/libstdc++-v3/doc/html/manual/appendix_contributing.html b/libstdc++-v3/doc/html/manual/appendix_contributing.html
index ca8ae87..7c7bd5a 100644
--- a/libstdc++-v3/doc/html/manual/appendix_contributing.html
+++ b/libstdc++-v3/doc/html/manual/appendix_contributing.html
@@ -26,7 +26,7 @@
organization. In the USA, this national standards
organization is
<a class="link" href="https://www.ansi.org" target="_top">ANSI</a>.
- (And if you've already registered with them you can <a class="link" href="https://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2fIEC+14882%3a2014" target="_top">buy
+ (And if you've already registered with them you can <a class="link" href="https://webstore.ansi.org/Standards/ISO/ISOIEC148822014" target="_top">buy
the standard on-line</a>.)
</p></li><li class="listitem"><p>
The library working group bugs, and known defects, can
diff --git a/libstdc++-v3/doc/html/manual/status.html b/libstdc++-v3/doc/html/manual/status.html
index 3840019..398a9490 100644
--- a/libstdc++-v3/doc/html/manual/status.html
+++ b/libstdc++-v3/doc/html/manual/status.html
@@ -303,18 +303,38 @@ particular release.
<code class="classname">minstd_rand0</code>.
</p><p>
<span class="emphasis"><em> 26.5.6 [rand.device] </em></span>
- The default <code class="code">token</code> argument to the
- <code class="classname">random_device</code> constructor is
- <code class="literal">"default"</code>. Other valid arguments are
- <code class="literal">"/dev/random"</code> and <code class="literal">"/dev/urandom"</code>,
- which determine the character special file to read random bytes from.
- The <code class="literal">"default"</code> token will read bytes from a hardware
- RNG if available (currently this only supports the IA-32 RDRAND
- instruction) otherwise it is equivalent to
- <code class="literal">"/dev/urandom"</code>.
+ The <code class="code">token</code> parameter of the
+ <code class="classname">random_device</code> constructor can be used to select
+ a specific source of random bytes. The valid token values are shown
+ in the list below.
+ The default constructor uses the token <code class="literal">"default"</code>.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">"default"</code></span></dt><dd>
+ Select the first available source from the other entries below.
+ This is the only token that is always valid.
+ </dd><dt><span class="term"><code class="literal">"rand_s"</code></span></dt><dd>
+ Use the MSVCRT <code class="function">rand_s</code> function.
+ This token is only valid for mingw-w64 targets.
+ </dd><dt><span class="term"><code class="literal">"rdseed"</code>, </span><span class="term"><code class="literal">"rdrand"</code> or <code class="literal">"rdrnd"</code></span></dt><dd>
+ Use the IA-32 <code class="literal">RDSEED</code> or <code class="literal">RDRAND</code>
+ instruction to read from an on-chip hardware random number generator.
+ These tokens are only valid for x86 and x86_64 targets when both
+ the assembler and CPU support the corresponding instruction.
+ </dd><dt><span class="term"><code class="literal">"/dev/urandom"</code>, </span><span class="term"><code class="literal">"/dev/random"</code></span></dt><dd>
+ Use the named character special file to read random bytes from.
+ These tokens are only valid when the device files are present
+ and readable by the current user.
+ </dd><dt><span class="term"><code class="literal">"mt19937"</code>, </span><span class="term">seed value</span></dt><dd>
+ When no source of nondeterministic random numbers is available a
+ <code class="classname">mersenne_twister_engine</code> will be used.
+ An integer seed value can be used as the token and will be converted
+ to an <code class="code">unsigned long</code> using <code class="function">strtoul</code>.
+ These tokens are only valid when no other source of random bytes
+ is available.
+ </dd></dl></div><p>
An exception of type <code class="classname">runtime_error</code> will be
- thrown if a <code class="classname">random_device</code> object cannot open
- or read from the source of random bytes.
+ thrown if a <code class="classname">random_device</code> object is constructed
+ with an invalid token, or if it cannot open or read from the source
+ of random bytes.
</p><p>
<span class="emphasis"><em>26.5.8.1 [rand.dist.general]</em></span>
The algorithms used by the distributions should be documented here.
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2011.xml b/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
index 0fa4bc0..9c25b8f 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
@@ -2682,18 +2682,62 @@ particular release.
<para>
<emphasis> 26.5.6 [rand.device] </emphasis>
- The default <code>token</code> argument to the
- <classname>random_device</classname> constructor is
- <literal>"default"</literal>. Other valid arguments are
- <literal>"/dev/random"</literal> and <literal>"/dev/urandom"</literal>,
- which determine the character special file to read random bytes from.
- The <literal>"default"</literal> token will read bytes from a hardware
- RNG if available (currently this only supports the IA-32 RDRAND
- instruction) otherwise it is equivalent to
- <literal>"/dev/urandom"</literal>.
+ The <code>token</code> parameter of the
+ <classname>random_device</classname> constructor can be used to select
+ a specific source of random bytes. The valid token values are shown
+ in the list below.
+ The default constructor uses the token <literal>"default"</literal>.
+ <variablelist>
+ <varlistentry>
+ <term><literal>"default"</literal></term>
+ <listitem>
+ Select the first available source from the other entries below.
+ This is the only token that is always valid.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>"rand_s"</literal></term>
+ <listitem>
+ Use the MSVCRT <function>rand_s</function> function.
+ This token is only valid for mingw-w64 targets.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>"rdseed"</literal></term>
+ <term><literal>"rdrand"</literal> or <literal>"rdrnd"</literal></term>
+ <listitem>
+ Use the IA-32 <literal>RDSEED</literal> or <literal>RDRAND</literal>
+ instruction to read from an on-chip hardware random number generator.
+ These tokens are only valid for x86 and x86_64 targets when both
+ the assembler and CPU support the corresponding instruction.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>"/dev/urandom"</literal></term>
+ <term><literal>"/dev/random"</literal></term>
+ <listitem>
+ Use the named character special file to read random bytes from.
+ These tokens are only valid when the device files are present
+ and readable by the current user.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>"mt19937"</literal></term>
+ <term>seed value</term>
+ <listitem>
+ When no source of nondeterministic random numbers is available a
+ <classname>mersenne_twister_engine</classname> will be used.
+ An integer seed value can be used as the token and will be converted
+ to an <code>unsigned long</code> using <function>strtoul</function>.
+ These tokens are only valid when no other source of random bytes
+ is available.
+ </listitem>
+ </varlistentry>
+ </variablelist>
An exception of type <classname>runtime_error</classname> will be
- thrown if a <classname>random_device</classname> object cannot open
- or read from the source of random bytes.
+ thrown if a <classname>random_device</classname> object is constructed
+ with an invalid token, or if it cannot open or read from the source
+ of random bytes.
</para>
<para>