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