src/randomkit.h

   1 /* Random kit 1.3 */
   2
   3 /*
   4  * Copyright (c) 2003-2005, Jean-Sebastien Roy (js@jeannot.org)
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a
   7  * copy of this software and associated documentation files (the
   8  * "Software"), to deal in the Software without restriction, including
   9  * without limitation the rights to use, copy, modify, merge, publish,
  10  * distribute, sublicense, and/or sell copies of the Software, and to
  11  * permit persons to whom the Software is furnished to do so, subject to
  12  * the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included
  15  * in all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  18  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  19  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  20  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  21  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  22  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  23  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  24  */
  25
  26 /* @(#) $Jeannot: randomkit.h,v 1.24 2005/07/21 22:14:09 js Exp $ */
  27
  28 /*
  29  * Typical use:
  30  *
  31  * {
  32  *  rk_state state;
  33  *  unsigned long seed = 1, random_value;
  34  *
  35  *  rk_seed(seed, &state); // Initialize the RNG
  36  *  ...
  37  *  random_value = rk_random(&state); // Generate random values in [0..RK_MAX]
  38  * }
  39  *
  40  * Instead of rk_seed, you can use rk_randomseed which will get a random seed
  41  * from /dev/urandom (or the clock, if /dev/urandom is unavailable):
  42  *
  43  * {
  44  *  rk_state state;
  45  *  unsigned long random_value;
  46  *
  47  *  rk_randomseed(&state); // Initialize the RNG with a random seed
  48  *  ...
  49  *  random_value = rk_random(&state); // Generate random values in [0..RK_MAX]
  50  * }
  51  */
  52
  53 /*
  54  * Useful macro:
  55  *  RK_DEV_RANDOM: the device used for random seeding.
  56  *                 defaults to "/dev/urandom"
  57  */
  58
  59 #include <stddef.h>
  60
  61 #ifndef _RANDOMKIT_
  62 #define _RANDOMKIT_
  63
  64 #define RK_STATE_LEN 624
  65
  66 typedef struct rk_state_
  67 {
  68     unsigned long key[RK_STATE_LEN];
  69     int pos;
  70     int has_gauss; /* !=0: gauss contains a gaussian deviate */
  71     double gauss;
  72
  73     /* The rk_state structure has been extended to store the following
  74      * information for the binomial generator. If the input values of n or p
  75      * are different than nsave and psave, then the other parameters will be.
  76      * recomputed. RTK 2005-09-02 */
  77
  78     int has_binomial; /* !=0: following parameters initialized for.
  79                               binomial */
  80     double psave;
  81     long nsave;
  82     double r;
  83     double q;
  84     double fm;
  85     long m;
  86     double p1;
  87     double xm;
  88     double xl;
  89     double xr;
  90     double c;
  91     double laml;
  92     double lamr;
  93     double p2;
  94     double p3;
  95     double p4;
  96
  97 }
  98 rk_state;
  99
 100 typedef enum {
 101     RK_NOERR = 0, /* no error */
 102     RK_ENODEV = 1, /* no RK_DEV_RANDOM device */
 103     RK_ERR_MAX = 2
 104 } rk_error;
 105
 106 /* error strings */
 107 extern char *rk_strerror[RK_ERR_MAX];
 108
 109 /* Maximum generated random value */
 110 #define RK_MAX 0xFFFFFFFFUL
 111
 112 #ifdef __cplusplus
 113 extern "C" {
 114 #endif
 115
 116 /**
 117  * Initialize the RNG state using the given seed.
 118  */
 119 extern void rk_seed(unsigned long seed, rk_state *state);
 120
 121 /*
 122  * Initialize the RNG state using a random seed.
 123  * Uses /dev/random or, when unavailable, the clock (see randomkit.c).
 124  * Returns RK_NOERR when no errors occurs.
 125  * Returns RK_ENODEV when the use of RK_DEV_RANDOM failed (for example because
 126  * there is no such device). In this case, the RNG was initialized using the
 127  * clock.
 128  */
 129 extern rk_error rk_randomseed(rk_state *state);
 130
 131 /*
 132  * Returns a random unsigned long between 0 and RK_MAX inclusive
 133  */
 134 extern unsigned long rk_random(rk_state *state);
 135
 136 /*
 137  * Returns a random long between 0 and LONG_MAX inclusive
 138  */
 139 extern long rk_long(rk_state *state);
 140
 141 /*
 142  * Returns a random unsigned long between 0 and ULONG_MAX inclusive
 143  */
 144 extern unsigned long rk_ulong(rk_state *state);
 145
 146 /*
 147  * Returns a random unsigned long between 0 and max inclusive.
 148  */
 149 extern unsigned long rk_interval(unsigned long max, rk_state *state);
 150
 151 /**
 152  * Returns a random double between 0.0 and 1.0, 1.0 excluded.
 153  */
 154 extern double rk_double(rk_state *state);
 155
 156 /*
 157  * fill the buffer with size random bytes
 158  */
 159 extern void rk_fill(void *buffer, size_t size, rk_state *state);
 160
 161 /*
 162  * fill the buffer with randombytes from the random device
 163  * Returns RK_ENODEV if the device is unavailable, or RK_NOERR if it is
 164  * On Unix, if strong is defined, RK_DEV_RANDOM is used. If not, RK_DEV_URANDOM
 165  * is used instead. This parameter has no effect on Windows.
 166  * Warning: on most unixes RK_DEV_RANDOM will wait for enough entropy to answer
 167  * which can take a very long time on quiet systems.
 168  */
 169 extern rk_error rk_devfill(void *buffer, size_t size, int strong);
 170
 171 /*
 172  * fill the buffer using rk_devfill if the random device is available and using
 173  * rk_fill if is is not
 174  * parameters have the same meaning as rk_fill and rk_devfill.
 175  * Returns RK_ENODEV if the device is unavailable, or RK_NOERR if it is
 176  */
 177 extern rk_error rk_altfill(void *buffer, size_t size, int strong,
 178                             rk_state *state);
 179
 180 /**
 181  * return a random gaussian deviate with variance unity and zero mean.
 182  */
 183 extern double rk_gauss(rk_state *state);
 184
 185 /**
 186  * fill a double buffer with gaussian numbers
 187  */
 188 extern void rk_gauss_fill(rk_state *state, int nx, double *x);
 189
 190 #ifdef __cplusplus
 191 }
 192 #endif
 193
 194 #endif /* _RANDOMKIT_ */