Changeset View
Changeset View
Standalone View
Standalone View
head/share/man/man9/prng.9
Property | Old Value | New Value |
---|---|---|
svn:eol-style | null | native \ No newline at end of property |
svn:keywords | null | FreeBSD=%H \ No newline at end of property |
svn:mime-type | null | text/plain \ No newline at end of property |
.\"- | |||||
.\" Copyright 2020 Conrad Meyer <cem@FreeBSD.org>. All rights reserved. | |||||
.\" | |||||
.\" Redistribution and use in source and binary forms, with or without | |||||
.\" modification, are permitted provided that the following conditions | |||||
.\" are met: | |||||
.\" 1. Redistributions of source code must retain the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer. | |||||
.\" 2. Redistributions in binary form must reproduce the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer in the | |||||
.\" documentation and/or other materials provided with the distribution. | |||||
.\" | |||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | |||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | |||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||
.\" SUCH DAMAGE. | |||||
.\" | |||||
.\" $FreeBSD$ | |||||
.\" | |||||
.Dd August 5, 2020 | |||||
.Dt PRNG 9 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm prng | |||||
.Nd "Kernel pseudo-random number generators" | |||||
.Sh SYNOPSIS | |||||
.In sys/prng.h | |||||
.Ft uint32_t | |||||
.Fn prng32 void | |||||
.Ft uint32_t | |||||
.Fn prng32_bounded "uint32_t bound" | |||||
.Ft uint64_t | |||||
.Fn prng64 void | |||||
.Ft uint64_t | |||||
.Fn prng64_bounded "uint64_t bound" | |||||
.Sh DESCRIPTION | |||||
.Ss GENERIC PRNG ROUTINES | |||||
.Nm | |||||
is a family of fast, | |||||
.Em non-cryptographic | |||||
pseudo-random number generators. | |||||
Unlike | |||||
.Xr random 9 , | |||||
.Fn prng32 , | |||||
.Fn prng32_bounded , | |||||
.Fn prng64 , | |||||
and | |||||
.Fn prng64_bounded | |||||
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 | |||||
.Fx . | |||||
Different CPUs in SMP systems are guaranteed to produce different sequences of | |||||
integers. | |||||
.Pp | |||||
For | |||||
.Em cryptographically secure | |||||
random numbers generated by the | |||||
.Xr random 4 | |||||
kernel cryptographically secure random number generator subsystem, see | |||||
.Xr arc4random 9 . | |||||
.Pp | |||||
.Bl -tag -width indent | |||||
.It Fn prng32 | |||||
Generate a 32-bit integer uniformly distributed in [0, 2^32-1]. | |||||
.It Fn prng32_bounded bound | |||||
Generate an integer uniformly in the range [0, bound-1]. | |||||
.It Fn prng64 | |||||
Generate a 64-bit integer uniformly distributed in [0, 2^64-1]. | |||||
.It Fn prng64_bounded bound | |||||
Generate an integer uniformly in the range [0, bound-1]. | |||||
.El | |||||
.Pp | |||||
These routines are not reentrant; they are not safe to use in interrupt | |||||
handlers ("interrupt filters" in | |||||
.Xr bus_setup_intr 9 | |||||
terminology). | |||||
They are safe to use in all other kernel contexts, including interrupt threads | |||||
("ithreads"). | |||||
.Ss REPRODUCIBLE PRNG APIS | |||||
In addition to these per-CPU helpers, the | |||||
.In sys/prng.h | |||||
header also exposes the entire API of the PCG family of PRNGs as inline | |||||
functions. | |||||
The PCG-C API is described in full at | |||||
.Lk https://www.pcg-random.org/using-pcg-c.html . | |||||
.Sh HISTORY | |||||
.Nm | |||||
was introduced in | |||||
.Fx 13 . |