sys/man/2/rand

   1 .TH RAND 2
   2 .SH NAME
   3 rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand, genrandom, prng, fastrand, nfastrand \- random number generators
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .ta \w'\fLdouble 'u
  10 .B
  11 int     rand(void)
  12 .PP
  13 .B
  14 long    lrand(void)
  15 .PP
  16 .B
  17 double  frand(void)
  18 .PP
  19 .B
  20 int     nrand(int val)
  21 .PP
  22 .B
  23 long    lnrand(long val)
  24 .PP
  25 .B
  26 void    srand(long seed)
  27 .PP
  28 .B
  29 ulong   truerand(void)
  30 .PP
  31 .B
  32 ulong   ntruerand(ulong val)
  33 .sp
  34 .B #include <mp.h>
  35 .br
  36 .B #include <libsec.h>
  37 .PP
  38 .B
  39 void    genrandom(uchar *buf, int nbytes)
  40 .PP
  41 .B
  42 void    prng(uchar *buf, int nbytes)
  43 .PP
  44 .B
  45 ulong   fastrand(void)
  46 .PP
  47 .B
  48 ulong   nfastrand(ulong val)
  49 .SH DESCRIPTION
  50 .I Rand
  51 returns a uniform pseudo-random
  52 number
  53 .IR x ,
  54 .if t 0≤ \fIx\fR <2\u\s715\s10\d.
  55 .if n 0≤ x <2^15.
  56 .PP
  57 .I Lrand
  58 returns a uniform
  59 .B long
  60 .IR x ,
  61 .if t 0≤ \fIx\fR <2\u\s731\s10\d.
  62 .if n 0≤ x <2^31.
  63 .PP
  64 .I Frand
  65 returns a uniform
  66 .B double
  67 .IR x ,
  68 .RI 0.0≤ x <1.0,
  69 This function calls
  70 .I lrand
  71 twice to generate a number with as many as 62 significant bits of mantissa.
  72 .PP
  73 .I Nrand
  74 returns a uniform integer
  75 .IR x ,
  76 .RI 0≤ x < val.
  77 .I Lnrand
  78 is the same, but returns a
  79 .BR long .
  80 .PP
  81 The algorithm is additive feedback with:
  82 .IP
  83 x[n] = (x[n\(mi273] + x[n\(mi607]) mod
  84 .if t 2\u\s731\s0\d
  85 .if n 2^31
  86 .LP
  87 giving a period of
  88 .if t 2\u\s730\s10\d \(mu (2\u\s7607\s10\d \- 1).
  89 .if n 2^30 × (2^607 - 1).
  90 .PP
  91 The generators are initialized by calling
  92 .I srand
  93 with whatever you like as argument.
  94 To get a different starting value each time,
  95 .IP
  96 .L
  97 srand(time(0))
  98 .LP
  99 will work as long as it is not called more often
 100 than once per second.
 101 Calling
 102 .IP
 103 .L
 104 srand(1)
 105 .LP
 106 will initialize the generators to their
 107 starting state.
 108 .PP
 109 .I Truerand
 110 returns a random unsigned long read from
 111 .BR /dev/random .
 112 Due to the nature of
 113 .BR /dev/random ,
 114 truerand can only return a few hundred bits a
 115 second.
 116 .PP
 117 .I Ntruerand
 118 returns a uniform random integer
 119 .IR x ,
 120 .if t 0≤ \fIx\fR < \fIval\fR ≤ 2\u\s732\s10\d-1.
 121 .if n 0≤ x < val ≤ 2^32-1.
 122 .PP
 123 .I Genrandom
 124 fills a buffer with bytes from the X9.17 pseudo-random
 125 number generator.  The X9.17 generator is seeded by 24
 126 truly random bytes read from
 127 .BR /dev/random .
 128 .PP
 129 .I Prng
 130 uses the native
 131 .IR rand (2)
 132 pseudo-random number generator to fill the buffer.  Used with
 133 .IR srand ,
 134 this function can produce a reproducible stream of pseudo random
 135 numbers useful in testing.
 136 .PP
 137 Both
 138 .I genrandom
 139 and
 140 .I prng
 141 may be passed to
 142 .I mprand
 143 (see
 144 .IR mp (2)).
 145 .PP
 146 .I Fastrand
 147 uses
 148 .I genrandom
 149 to return a uniform
 150 .B "unsigned long
 151 .IR x ,
 152 .if t 0≤ \fIx\fR <2\u\s732\s10\d-1.
 153 .if n 0≤ x <2^32-1.
 154 .PP
 155 .I Nfastrand
 156 uses
 157 .I genrandom
 158 to return a uniform
 159 .B "unsigned long
 160 .IR x ,
 161 .if t 0≤ \fIx\fR < \fIval\fR ≤ 2\u\s732\s10\d-1.
 162 .if n 0≤ x < val ≤ 2^32-1.
 163 .SH SOURCE
 164 .B /sys/src/libc/port/*rand.c
 165 .br
 166 .B /sys/src/libc/9sys/truerand.c
 167 .br
 168 .B /sys/src/libsec/port/genrandom.c
 169 .br
 170 .B /sys/src/libsec/port/prng.c
 171 .br
 172 .B /sys/src/libsec/port/*fastrand.c
 173 .SH "SEE ALSO
 174 .IR cons (3),
 175 .IR mp (2)
 176 .SH BUGS
 177 .I Truerand
 178 and
 179 .I ntruerand
 180 maintain a static file descriptor.