19d12795fSRobert Mustacchi.\" $OpenBSD: arc4random.3,v 1.35 2014/11/25 16:45:24 millert Exp $ 29d12795fSRobert Mustacchi.\" 39d12795fSRobert Mustacchi.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de> 49d12795fSRobert Mustacchi.\" All rights reserved. 59d12795fSRobert Mustacchi.\" 69d12795fSRobert Mustacchi.\" Redistribution and use in source and binary forms, with or without 79d12795fSRobert Mustacchi.\" modification, are permitted provided that the following conditions 89d12795fSRobert Mustacchi.\" are met: 99d12795fSRobert Mustacchi.\" 1. Redistributions of source code must retain the above copyright 109d12795fSRobert Mustacchi.\" notice, this list of conditions and the following disclaimer. 119d12795fSRobert Mustacchi.\" 2. Redistributions in binary form must reproduce the above copyright 129d12795fSRobert Mustacchi.\" notice, this list of conditions and the following disclaimer in the 139d12795fSRobert Mustacchi.\" documentation and/or other materials provided with the distribution. 149d12795fSRobert Mustacchi.\" 3. All advertising materials mentioning features or use of this software 159d12795fSRobert Mustacchi.\" must display the following acknowledgement: 169d12795fSRobert Mustacchi.\" This product includes software developed by Niels Provos. 179d12795fSRobert Mustacchi.\" 4. The name of the author may not be used to endorse or promote products 189d12795fSRobert Mustacchi.\" derived from this software without specific prior written permission. 199d12795fSRobert Mustacchi.\" 209d12795fSRobert Mustacchi.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 219d12795fSRobert Mustacchi.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 229d12795fSRobert Mustacchi.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 239d12795fSRobert Mustacchi.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 249d12795fSRobert Mustacchi.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 259d12795fSRobert Mustacchi.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 269d12795fSRobert Mustacchi.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 279d12795fSRobert Mustacchi.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 289d12795fSRobert Mustacchi.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 299d12795fSRobert Mustacchi.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 309d12795fSRobert Mustacchi.\" 319d12795fSRobert Mustacchi.\" Manual page, using -mandoc macros 329d12795fSRobert Mustacchi.\" 339d12795fSRobert Mustacchi.Dd "Dec 31, 2014" 349d12795fSRobert Mustacchi.Dt ARC4RANDOM 3C 359d12795fSRobert Mustacchi.Os 369d12795fSRobert Mustacchi.Sh NAME 379d12795fSRobert Mustacchi.Nm arc4random , 389d12795fSRobert Mustacchi.Nm arc4random_buf , 399d12795fSRobert Mustacchi.Nm arc4random_uniform 409d12795fSRobert Mustacchi.Nd random number generator 419d12795fSRobert Mustacchi.Sh SYNOPSIS 429d12795fSRobert Mustacchi.In stdlib.h 439d12795fSRobert Mustacchi.Ft uint32_t 449d12795fSRobert Mustacchi.Fn arc4random "void" 459d12795fSRobert Mustacchi.Ft void 469d12795fSRobert Mustacchi.Fn arc4random_buf "void *buf" "size_t nbytes" 479d12795fSRobert Mustacchi.Ft uint32_t 489d12795fSRobert Mustacchi.Fn arc4random_uniform "uint32_t upper_bound" 499d12795fSRobert Mustacchi.Sh DESCRIPTION 509d12795fSRobert MustacchiThis family of functions provides higher quality data than those 519d12795fSRobert Mustacchidescribed in 529d12795fSRobert Mustacchi.Xr rand 3C , 539d12795fSRobert Mustacchi.Xr random 3C , 549d12795fSRobert Mustacchiand 559d12795fSRobert Mustacchi.Xr rand48 3C . 569d12795fSRobert Mustacchi.Pp 579d12795fSRobert MustacchiUse of these functions is encouraged for almost all random number 589d12795fSRobert Mustacchiconsumption because the other interfaces are deficient in either 599d12795fSRobert Mustacchiquality, portability, standardization, or availability. 609d12795fSRobert MustacchiThese functions can be called in almost all coding environments, 619d12795fSRobert Mustacchiincluding 62*bbf21555SRichard Lowe.Xr pthreads 7 639d12795fSRobert Mustacchiand 649d12795fSRobert Mustacchi.Xr chroot 2 . 659d12795fSRobert Mustacchi.Pp 669d12795fSRobert MustacchiHigh quality 32-bit pseudo-random numbers are generated very quickly. 679d12795fSRobert MustacchiOn each call, a cryptographic pseudo-random number generator is used 689d12795fSRobert Mustacchito generate a new result. 699d12795fSRobert MustacchiOne data pool is used for all consumers in a process, so that consumption 709d12795fSRobert Mustacchiunder program flow can act as additional stirring. 719d12795fSRobert MustacchiThe subsystem is re-seeded from the kernel random number subsystem using 72b31ca922SChris Fraire.Xr getentropy 3C 739d12795fSRobert Mustacchion a regular basis, and also upon 749d12795fSRobert Mustacchi.Xr fork 2 . 759d12795fSRobert Mustacchi.Pp 769d12795fSRobert MustacchiThe 779d12795fSRobert Mustacchi.Fn arc4random 789d12795fSRobert Mustacchifunction returns a single 32-bit value. 799d12795fSRobert Mustacchi.Pp 809d12795fSRobert Mustacchi.Fn arc4random_buf 819d12795fSRobert Mustacchifills the region 829d12795fSRobert Mustacchi.Fa buf 839d12795fSRobert Mustacchiof length 849d12795fSRobert Mustacchi.Fa nbytes 859d12795fSRobert Mustacchiwith random data. 869d12795fSRobert Mustacchi.Pp 879d12795fSRobert Mustacchi.Fn arc4random_uniform 889d12795fSRobert Mustacchiwill return a single 32-bit value, uniformly distributed but less than 899d12795fSRobert Mustacchi.Fa upper_bound . 909d12795fSRobert MustacchiThis is recommended over constructions like 919d12795fSRobert Mustacchi.Dq Li arc4random() % upper_bound 929d12795fSRobert Mustacchias it avoids "modulo bias" when the upper bound is not a power of two. 939d12795fSRobert MustacchiIn the worst case, this function may consume multiple iterations 949d12795fSRobert Mustacchito ensure uniformity; see the source code to understand the problem 959d12795fSRobert Mustacchiand solution. 969d12795fSRobert Mustacchi.Sh RETURN VALUES 979d12795fSRobert MustacchiThese functions are always successful, and no return value is 989d12795fSRobert Mustacchireserved to indicate an error. 999d12795fSRobert Mustacchi.Sh INTERFACE STABILITY 1009d12795fSRobert Mustacchi.Sy Committed 1019d12795fSRobert Mustacchi.Sh MT-LEVEL 1029d12795fSRobert Mustacchi.Sy MT-Safe 1039d12795fSRobert Mustacchi.Sh SEE ALSO 1049d12795fSRobert Mustacchi.Xr rand 3C , 1059d12795fSRobert Mustacchi.Xr rand48 3C , 1069d12795fSRobert Mustacchi.Xr random 3C 107