# RANDOMKIT, Version 1.3
# Copyright J.S. Roy (js@jeannot.org), 2003-2005
# See the LICENSE file for copyright information.
# @(#) $Jeannot: README,v 1.12 2005/07/21 22:14:09 js Exp $

Randomkit is a simple set of C functions to generate random numbers, using the
Mersenne Twister RNG.
The last version (and other software) is available at the URL :
http://www.jeannot.org/~js/code/index.en.html

Original design and code for the Mersenne Twister RNG:
A C-program for MT19937, with initialization improved 2002/1/26.
Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
The reference implementation and high performance implementations are
available at the following URL :
http://www.math.keio.ac.jp/~matumoto/emt.html

On Unix, if you have a random number generator device not located at
/dev/urandom, you should define the RK_DEV_URANDOM macro accordingy. I.e.:
CFLAGS += -DRK_DEV_URANDOM="/dev/myrandomdevice"
The same applies to RK_DEV_RANDOM which defaults to /dev/random.

On Windows, if you do not have access to the Windows crypto API, you should
define the RK_NO_WINCRYPT macro.

A Makefile is provided to test the correctness of the RNG. The 'test' target
should execute, check if the random device is found (or not) and return "Test
successful." if the RNG unit tests passed.

Typical use:

{
	rk_state state;
	unsigned long seed = 1, random_value;
	
	rk_seed(seed, &state); // Initialize the RNG
	...
	random_value = rk_random(&state); // Generate random values in [0..RK_MAX]
}

Instead of rk_seed, you can use rk_randomseed which will get a random seed
from /dev/urandom (or the WinCrypt API on Windows), or the clock/pid/ticks,
if /dev/urandom (resp. WinCrypt) is unavailable:

{
	rk_state state;
	unsigned long random_value;
	
	rk_randomseed(&state); // Initialize the RNG with a random seed
	...
	random_value = rk_random(&state); // Generate random values in [0..RK_MAX]
}

Additionnaly, the following functions are provided :

rk_long : returns a random long between 0 and LONG_MAX inclusive.
rk_ulong : returns a random unsigned long between 0 and ULONG_MAX, inclusive.
rk_interval : returns a random unsigned long between 0 and a user supplied
maximum integer, inclusive.
rk_double : returns a random double between 0.0 and 1.0, 1.0 excluded.
rk_fill : fill a buffer with random bytes.
rk_devfill : fill a buffer using random bytes from the random device.
rk_altfill : fill a buffer using rk_devfill if possible or rk_fill if it is not.
rk_gauss : return a gaussian deviate (zero mean, variance unity)

See randomkit.h for the precise interface.
