RANDOM(3C) Standard C Library Functions RANDOM(3C)

## NAME

random, srandom, initstate, setstate - pseudorandom number functions

## SYNOPSIS

#include <stdlib.h>

**long random**(**void**);

**void srandom**(**unsigned int **__seed__);

**char *initstate**(**unsigned int **__seed__, **char **__*state__, **size_t **__size__);

**char *setstate**(**const char ***__state__);

## DESCRIPTION

The**random() **function uses a nonlinear additive feedback random-number

generator employing a default state array size of 31 long integers to

return successive pseudo-random numbers in the range from 0 to 2^31 -1.

The period of this random-number generator is approximately 16 x (2^31

-1). The size of the state array determines the period of the random-

number generator. Increasing the state array size increases the period.

The**srandom() **function initializes the current state array using the

value of__seed__.

The**random() **and **srandom() **functions have (almost) the same calling

sequence and initialization properties as**rand() **and **srand() **(see

rand(3C)). The difference is that rand(3C) produces a much less random

sequence--in fact, the low dozen bits generated by rand go through a

cyclic pattern. All the bits generated by**random() **are usable.

The algorithm from**rand() **is used by **srandom() **to generate the 31 state

integers. Because of this, different**srandom() **seeds often produce,

within an offset, the same sequence of low order bits from**random()**. If

low order bits are used directly,**random() **should be initialized with

**setstate() **using high quality random values.

Unlike**srand()**, **srandom() **does not return the old seed because the amount

of state information used is much more than a single word. Two other

routines are provided to deal with restarting/changing random number

generators. With 256 bytes of state information, the period of the

random-number generator is greater than 2^69, which should be sufficient

for most purposes.

Like rand(3C),**random() **produces by default a sequence of numbers that

can be duplicated by calling**srandom() **with 1 as the seed.

The**initstate() **and **setstate() **functions handle restarting and changing

random-number generators. The**initstate() **function allows a state array,

pointed to by the__state__ argument, to be initialized for future use. The

**size **argument, which specifies the size in bytes of the state array, is

used by**initstate() **to decide what type of random-number generator to

use; the larger the state array, the more random the numbers. Values for

the amount of state information are 8, 32, 64, 128, and 256 bytes. Other

values greater than 8 bytes are rounded down to the nearest one of these

values. For values smaller than 8,**random() **uses a simple linear

congruential random number generator. The__seed__ argument specifies a

starting point for the random-number sequence and provides for restarting

at the same point. The**initstate() **function returns a pointer to the

previous state information array.

If**initstate() **has not been called, then **random() **behaves as though

**initstate() **had been called with __seed__=1 and __size__=128.

If**initstate() **is called with __size__<8, then **random() **uses a simple linear

congruential random number generator.

Once a state has been initialized,**setstate() **allows switching between

state arrays. The array defined by the__state__ argument is used for further

random-number generation until**initstate() **is called or **setstate() **is

called again. The**setstate() **function returns a pointer to the previous

state array.

For a more powerful random number generator, see arc4random(3C).

## RETURN VALUES

The**random() **function returns the generated pseudo-random number.

The**srandom() **function returns no value.

Upon successful completion,**initstate() **and **setstate() **return a pointer

to the previous state array. Otherwise, a null pointer is returned.

## ERRORS

No errors are defined.

## USAGE

After initialization, a state array can be restarted at a different point

in one of two ways:

o The**initstate() **function can be used, with the desired seed,

state array, and size of the array.

o The**setstate() **function, with the desired state, can be used,

followed by**srandom() **with the desired seed. The advantage of

using both of these functions is that the size of the state

array does not have to be saved once it is initialized.

## EXAMPLES

#### Example 1: Initialize an array.

The following example demonstrates the use of**initstate() **to intialize an

array. It also demonstrates how to initialize an array and pass it to

**setstate()**.

# include <stdlib.h>

static unsigned int state0[32];

static unsigned int state1[32] = {

3,

0x9a319039, 0x32d9c024, 0x9b663182, 0x5da1f342,

0x7449e56b, 0xbeb1dbb0, 0xab5c5918, 0x946554fd,

0x8c2e680f, 0xeb3d799f, 0xb11ee0b7, 0x2d436b86,

0xda672e2a, 0x1588ca88, 0xe369735d, 0x904f35f7,

0xd7158fd6, 0x6fa6f051, 0x616e6b96, 0xac94efdc,

0xde3b81e0, 0xdf0a6fb5, 0xf103bc02, 0x48f340fb,

0x36413f93, 0xc622c298, 0xf5a42ab8, 0x8a88d77b,

0xf5ad9d0e, 0x8999220b, 0x27fb47b9

};

main() {

unsigned seed;

int n;

seed = 1;

n = 128;

(void)initstate(seed, (char *)state0, n);

printf("random() = %d0\n", random());

(void)setstate((char *)state1);

printf("random() = %d0\n", random());

}

## ATTRIBUTES

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

+--------------------+------------------+

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

+--------------------+------------------+

|Interface Stability | Standard |

+--------------------+------------------+

|MT-Level | See**NOTES **below. |

+--------------------+------------------+

## SEE ALSO

arc4random(3C), drand48(3C), rand(3C), attributes(7), standards(7)

## NOTES

The**random() **and **srandom() **functions are unsafe in multithreaded

applications.

Use of these functions in multithreaded applications is unsupported.

For**initstate() **and **setstate()**, the __state__ argument must be aligned on an

**int **boundary.

arc4random(3C) is a newer and better performing random number generator.

Use it instead.

illumos August 14, 2002 RANDOM(3C)

random, srandom, initstate, setstate - pseudorandom number functions

#include <stdlib.h>

The

generator employing a default state array size of 31 long integers to

return successive pseudo-random numbers in the range from 0 to 2^31 -1.

The period of this random-number generator is approximately 16 x (2^31

-1). The size of the state array determines the period of the random-

number generator. Increasing the state array size increases the period.

The

value of

The

sequence and initialization properties as

rand(3C)). The difference is that rand(3C) produces a much less random

sequence--in fact, the low dozen bits generated by rand go through a

cyclic pattern. All the bits generated by

The algorithm from

integers. Because of this, different

within an offset, the same sequence of low order bits from

low order bits are used directly,

Unlike

of state information used is much more than a single word. Two other

routines are provided to deal with restarting/changing random number

generators. With 256 bytes of state information, the period of the

random-number generator is greater than 2^69, which should be sufficient

for most purposes.

Like rand(3C),

can be duplicated by calling

The

random-number generators. The

pointed to by the

used by

use; the larger the state array, the more random the numbers. Values for

the amount of state information are 8, 32, 64, 128, and 256 bytes. Other

values greater than 8 bytes are rounded down to the nearest one of these

values. For values smaller than 8,

congruential random number generator. The

starting point for the random-number sequence and provides for restarting

at the same point. The

previous state information array.

If

If

congruential random number generator.

Once a state has been initialized,

state arrays. The array defined by the

random-number generation until

called again. The

state array.

For a more powerful random number generator, see arc4random(3C).

The

The

Upon successful completion,

to the previous state array. Otherwise, a null pointer is returned.

No errors are defined.

After initialization, a state array can be restarted at a different point

in one of two ways:

o The

state array, and size of the array.

o The

followed by

using both of these functions is that the size of the state

array does not have to be saved once it is initialized.

The following example demonstrates the use of

array. It also demonstrates how to initialize an array and pass it to

# include <stdlib.h>

static unsigned int state0[32];

static unsigned int state1[32] = {

3,

0x9a319039, 0x32d9c024, 0x9b663182, 0x5da1f342,

0x7449e56b, 0xbeb1dbb0, 0xab5c5918, 0x946554fd,

0x8c2e680f, 0xeb3d799f, 0xb11ee0b7, 0x2d436b86,

0xda672e2a, 0x1588ca88, 0xe369735d, 0x904f35f7,

0xd7158fd6, 0x6fa6f051, 0x616e6b96, 0xac94efdc,

0xde3b81e0, 0xdf0a6fb5, 0xf103bc02, 0x48f340fb,

0x36413f93, 0xc622c298, 0xf5a42ab8, 0x8a88d77b,

0xf5ad9d0e, 0x8999220b, 0x27fb47b9

};

main() {

unsigned seed;

int n;

seed = 1;

n = 128;

(void)initstate(seed, (char *)state0, n);

printf("random() = %d0\n", random());

(void)setstate((char *)state1);

printf("random() = %d0\n", random());

}

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

+--------------------+------------------+

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

+--------------------+------------------+

|Interface Stability | Standard |

+--------------------+------------------+

|MT-Level | See

+--------------------+------------------+

arc4random(3C), drand48(3C), rand(3C), attributes(7), standards(7)

The

applications.

Use of these functions in multithreaded applications is unsupported.

For

arc4random(3C) is a newer and better performing random number generator.

Use it instead.

illumos August 14, 2002 RANDOM(3C)