rand 2.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175
  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. .RI 0≤ x <2\u\s715\s10\d.
  55. .PP
  56. .I Lrand
  57. returns a uniform
  58. .B long
  59. .IR x ,
  60. .RI 0≤ x <2\u\s731\s10\d.
  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. Due to the nature of
  111. .BR /dev/random ,
  112. truerand can only return a few hundred bits a
  113. second.
  114. .PP
  115. .I Ntruerand
  116. returns a uniform random integer
  117. .IR x ,
  118. .RI 0≤ x < val ≤ 2\u\s732\s10\d-1.
  119. .PP
  120. .I Genrandom
  121. fills a buffer with bytes from the X9.17 pseudo-random
  122. number generator. The X9.17 generator is seeded by 24
  123. truly random bytes read from
  124. .BR /dev/random .
  125. .PP
  126. .I Prng
  127. uses the native
  128. .IR rand (2)
  129. pseudo-random number generator to fill the buffer. Used with
  130. .IR srand ,
  131. this function can produce a reproducible stream of pseudo random
  132. numbers useful in testing.
  133. .PP
  134. Both
  135. .I genrandom
  136. and
  137. .I prng
  138. may be passed to
  139. .I mprand
  140. (see
  141. .IR mp (2)).
  142. .PP
  143. .I Fastrand
  144. uses
  145. .I genrandom
  146. to return a uniform
  147. .B "unsigned long
  148. .IR x ,
  149. .RI 0≤ x < 2\u\s732\s10\d-1.
  150. .PP
  151. .I Nfastrand
  152. uses
  153. .I genrandom
  154. to return a uniform
  155. .B "unsigned long
  156. .IR x ,
  157. .RI 0≤ x < val ≤ 2\u\s732\s10\d-1.
  158. .SH SOURCE
  159. .B /sys/src/libc/port/*rand.c
  160. .br
  161. .B /sys/src/libc/9sys/truerand.c
  162. .br
  163. .B /sys/src/libsec/port/genrandom.c
  164. .br
  165. .B /sys/src/libsec/port/prng.c
  166. .br
  167. .B /sys/src/libsec/port/*fastrand.c
  168. .SH "SEE ALSO
  169. .IR cons (3),
  170. .IR mp (2)
  171. .SH BUGS
  172. .I Truerand
  173. and
  174. .I ntruerand
  175. maintain a static file descriptor.