1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
<table class="head">
<tr>
<td class="head-ltitle">PRNG(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">PRNG(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">prng</code> — <span class="Nd">Kernel
pseudo-random number generators</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/prng.h</a>></code></p>
<p class="Pp"><var class="Ft">uint32_t</var>
<br/>
<code class="Fn">prng32</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p>
<p class="Pp"><var class="Ft">uint32_t</var>
<br/>
<code class="Fn">prng32_bounded</code>(<var class="Fa" style="white-space: nowrap;">uint32_t
bound</var>);</p>
<p class="Pp"><var class="Ft">uint64_t</var>
<br/>
<code class="Fn">prng64</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p>
<p class="Pp"><var class="Ft">uint64_t</var>
<br/>
<code class="Fn">prng64_bounded</code>(<var class="Fa" style="white-space: nowrap;">uint64_t
bound</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<section class="Ss">
<h2 class="Ss" id="GENERIC_PRNG_ROUTINES"><a class="permalink" href="#GENERIC_PRNG_ROUTINES">GENERIC
PRNG ROUTINES</a></h2>
<p class="Pp"><code class="Nm">prng</code> is a family of fast,
<a class="permalink" href="#non-cryptographic"><i class="Em" id="non-cryptographic">non-cryptographic</i></a>
pseudo-random number generators. Unlike <a class="Xr">random(9)</a>,
<a class="permalink" href="#prng32"><code class="Fn" id="prng32">prng32</code></a>(),
<a class="permalink" href="#prng32_bounded"><code class="Fn" id="prng32_bounded">prng32_bounded</code></a>(),
<a class="permalink" href="#prng64"><code class="Fn" id="prng64">prng64</code></a>(),
and
<a class="permalink" href="#prng64_bounded"><code class="Fn" id="prng64_bounded">prng64_bounded</code></a>()
avoid shared global state, removing unnecessary contention on SMP systems.
The routines are not explicitly tied to any specific implementation, and may
produce different specific sequences on different hosts, reboots, or
versions of <span class="Ux">FreeBSD</span>. Different CPUs in SMP systems
are guaranteed to produce different sequences of integers.</p>
<p class="Pp" id="cryptographically">For
<a class="permalink" href="#cryptographically"><i class="Em">cryptographically
secure</i></a> random numbers generated by the <a class="Xr">random(4)</a>
kernel cryptographically secure random number generator subsystem, see
<a class="Xr">arc4random(9)</a>.</p>
<dl class="Bl-tag">
<dt id="prng32~2"><a class="permalink" href="#prng32~2"><code class="Fn">prng32</code></a>()</dt>
<dd>Generate a 32-bit integer uniformly distributed in [0, 2^32-1].</dd>
<dt id="prng32_bounded~2"><a class="permalink" href="#prng32_bounded~2"><code class="Fn">prng32_bounded</code></a>(<var class="Fa">bound</var>)</dt>
<dd>Generate an integer uniformly in the range [0, bound-1].</dd>
<dt id="prng64~2"><a class="permalink" href="#prng64~2"><code class="Fn">prng64</code></a>()</dt>
<dd>Generate a 64-bit integer uniformly distributed in [0, 2^64-1].</dd>
<dt id="prng64_bounded~2"><a class="permalink" href="#prng64_bounded~2"><code class="Fn">prng64_bounded</code></a>(<var class="Fa">bound</var>)</dt>
<dd>Generate an integer uniformly in the range [0, bound-1].</dd>
</dl>
<p class="Pp">These routines are not reentrant; they are not safe to use in
interrupt handlers ("interrupt filters" in
<a class="Xr">bus_setup_intr(9)</a> terminology). They are safe to use in
all other kernel contexts, including interrupt threads
("ithreads").</p>
</section>
<section class="Ss">
<h2 class="Ss" id="REPRODUCIBLE_PRNG_APIS"><a class="permalink" href="#REPRODUCIBLE_PRNG_APIS">REPRODUCIBLE
PRNG APIS</a></h2>
<p class="Pp">In addition to these per-CPU helpers, the
<code class="In"><<a class="In">sys/prng.h</a>></code> header also
exposes the entire API of the PCG family of PRNGs as inline functions. The
PCG-C API is described in full at
<a class="Lk" href="https://www.pcg-random.org/using-pcg-c.html">https://www.pcg-random.org/using-pcg-c.html</a>.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp"><code class="Nm">prng</code> was introduced in
<span class="Ux">FreeBSD 13</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">August 5, 2020</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
