Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

arc4random_uniform(3C)

Name

arc4random, arc4random_buf, arc4random_uniform, arc4random_stir, arc4random_addrandom - strong random number generator

Synopsis

#include <stdlib.h>

uint32_t arc4random(void);

void arc4random_buf(void *buf, size_t nbytes);

uint32_t arc4random_uniform(uint32_t upper_bound);

void arc4random_stir(void);

void arc4random_addrandom(unsigned char *dat, int datlen);

Description

These functions provide applications with data from the kernel random pool (see random(4D)).

The arc4random() function returns random numbers in the range of 0 to (232)−1. This is a larger range than offered by either rand(3C) or random(3C).

The arc4random_buf() function fills the region buf of length nbytes with pseudo-random data.

The arc4random_uniform() function returns a uniformly distributed random number less than the upper_bound. The arc4random_uniform() function is recommended over constructions such as arc4random() % upper_bound as it avoids modulo bias when the upper_bound is not a power of two.

The arc4random_stir() and arc4random_addrandom() are empty functions, provided for compatibility with older code. To provide input to the random number generator, data may be written to /dev/random or /dev/urandom as described in random(4D).

Examples

The following produces a drop-in replacement for the traditional rand() and random() functions using arc4random() function:

#define foo4random() (arc4random() % ((unsigned)RAND_MAX + 1))

Usage

These functions are provided for compatibility with existing software that already uses them. Programmers should use /dev/urandom or /dev/random for most random-number generation, especially for cryptographic purposes. See getrandom(2) and random(4D).

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Safe

See Also

getrandom(2), rand(3C), random(3C), random(4D)

History

These functions were first added to Oracle Solaris in the 11.3.9 release, and originally used the key stream generator employed by the ARC4 cipher, but were modified to use the getrandom(2) system call in Oracle Solaris 11.3.14 and later releases.