initstate()

Updated: April 19, 2023

Initialize a pseudo-random number generator

Synopsis:

#include <stdlib.h>

char* initstate( unsigned int seed,
                 char* state,
                 size_t size );

Arguments:

seed
A starting point for the random-number sequence. This lets you restart the sequence at the same point.
state
The state array that you want to initialize.
size
The size, in bytes, of the state array; see below.

Library:

libc

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

Description:

The initstate() initializes the given state array for future use when generating pseudo-random numbers.

This function uses the size argument to determine 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.

Use this function in conjunction with the following:

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

If you haven't called initstate(), random() behaves as though you had called initstate() with a seed of 1 and a size of 128.

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

Returns:

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

Examples:

#include <stdlib.h>
#include <stdio.h>
#include <time.h>

static char state1[32];

int main() {
   initstate( time(NULL), state1, sizeof(state1));
   setstate(state1);
   printf("%d0\n", random());
   return EXIT_SUCCESS;
}

Classification:

POSIX 1003.1

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