Google Git
Sign in
plan9port / plan9 / 1ac1981659ba7abcc1c76436e4b4dfc2bc616d2a / . / man / man3 / rand.html
blob: 0601c6bf39d8fc0f27552d88969daa254e353580 [file] [log] [blame]
<head>
<title>rand(3) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>RAND(3)</b><td align=right><b>RAND(3)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand,
fastrand, nfastrand &ndash; random number generator<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>#include &lt;u.h&gt;<br>
#include &lt;libc.h&gt;
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;rand(void)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>long &nbsp;&nbsp;&nbsp;&nbsp;lrand(void)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>double frand(void)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;nrand(int val)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>long &nbsp;&nbsp;&nbsp;&nbsp;lnrand(long val)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void &nbsp;&nbsp;&nbsp;&nbsp;srand(long seed)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>ulong &nbsp;&nbsp;&nbsp;truerand(void)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>ulong &nbsp;&nbsp;&nbsp;ntruerand(ulong val)<br>
#include &lt;mp.h&gt;<br>
#include &lt;libsec.h&gt;
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void &nbsp;&nbsp;&nbsp;&nbsp;genrandom(uchar *buf, int nbytes)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void &nbsp;&nbsp;&nbsp;&nbsp;prng(uchar *buf, int nbytes)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>ulong &nbsp;&nbsp;&nbsp;fastrand(void)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>ulong &nbsp;&nbsp;&nbsp;nfastrand(ulong val)<br>
</font></tt>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Rand</i> returns a uniform pseudo-random number <i>x</i>, 0&le;<i>x</i>&lt;215.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Lrand</i> returns a uniform <tt><font size=+1>long</font></tt> <i>x</i>, 0&le;<i>x</i>&lt;231.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Frand</i> returns a uniform <tt><font size=+1>double</font></tt> <i>x</i>, 0.0&le;<i>x</i>&lt;1.0, This function calls
<i>lrand</i> twice to generate a number with as many as 62 significant
bits of mantissa.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Nrand</i> returns a uniform integer <i>x</i>, 0&le;<i>x</i>&lt;<i>val. Lnrand</i> is the same,
but returns a <tt><font size=+1>long</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The algorithm is additive feedback with:<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
x[n] = (x[n-273] + x[n-607]) mod 231
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</table>
giving a period of 230 &#215; (2607 &ndash; 1).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The generators are initialized by calling <i>srand</i> with whatever
you like as argument. To get a different starting value each time,<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>srand(time(0))
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
</table>
will work as long as it is not called more often than once per
second. Calling<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>srand(1)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
</table>
will initialize the generators to their starting state.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Truerand</i> returns a random unsigned long read from <tt><font size=+1>/dev/random</font></tt>.
Due to the nature of <tt><font size=+1>/dev/random</font></tt>, truerand can only return a few
hundred bits a second.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Ntruerand</i> returns a uniform random integer <i>x</i>, 0&le;<i>x</i>&lt;<i>val</i>&le;<i>232-1.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</i>
<i>Genrandom</i> fills a buffer with bytes from the X9.17 pseudo-random
number generator. The X9.17 generator is seeded by 24 truly random
bytes read from <tt><font size=+1>/dev/random</font></tt>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Prng</i> uses the native <a href="../man3/rand.html"><i>rand</i>(3)</a> pseudo-random number generator to
fill the buffer. Used with <i>srand</i>, this function can produce a
reproducible stream of pseudo random numbers useful in testing.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Both <i>genrandom</i> and <i>prng</i> may be passed to <i>mprand</i> (see <a href="../man3/mp.html"><i>mp</i>(3)</a>).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Fastrand</i> uses <i>genrandom</i> to return a uniform <tt><font size=+1>unsigned long</font></tt> <i>x</i>, 0&le;<i>x</i>&lt;<i>232-1.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</i>
<i>Nfastrand</i> uses <i>genrandom</i> to return a uniform <tt><font size=+1>unsigned long</font></tt> <i>x</i>,
0&le;<i>x</i>&lt;<i>val</i>&le;<i>232-1.<br>
</i>
</table>
<p><font size=+1><b>SOURCE </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>/usr/local/plan9/src/lib9<br>
/usr/local/plan9/src/libsec/port<br>
</font></tt>
</table>
<p><font size=+1><b>SEE ALSO </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<a href="../man3/mp.html"><i>mp</i>(3)</a><br>
</table>
<p><font size=+1><b>BUGS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Truerand</i> and <i>ntruerand</i> maintain a static file descriptor.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
To avoid name conflicts with the underlying system, <i>rand</i>, <i>lrand</i>,
<i>frand</i>, <i>nrand</i>, <i>lnrand</i>, and <i>srand</i> are preprocessor macros defined
as <i>p9rand</i>, <i>p9lrand</i>, and so on; see <a href="../man3/intro.html"><i>intro</i>(3)</a>.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>