setstate()

Reset the state of a pseudo-random number generator

Synopsis:

#include <stdlib.h>

char *setstate( const char *state );

Arguments:

state: A pointer to the state array that you want to use.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Note: This function is in libc.a, but not in libc.so (in order to save space).

Description:

Once the state of the pseudo-random number generator 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.

This function is used in conjunction with the following:

initstate(): Initialize the state of the pseudo-random number generator.
random(): Generate a pseudo-random number using a default state.
srandom(): Set the seed used by the pseudo-random number generator.

After initialization, you can restart a state array at a different point in one of two ways:

Call initstate() with the desired seed, state array, and size of the array.
Call setstate() with the desired state, then call srandom() with the desired seed. The advantage of using both of these functions is that the size of the state array doesn't have to be saved once it's initialized.

Returns:

A pointer to the previous state array, or NULL if an error occurred.

Examples:

See initstate().

Classification:

POSIX 1003.1

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	No