logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

drand48.3p (7103B)


  1. '\" et
  2. .TH DRAND48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .EQ
  11. delim $$
  12. .EN
  13. .SH NAME
  14. drand48,
  15. erand48,
  16. jrand48,
  17. lcong48,
  18. lrand48,
  19. mrand48,
  20. nrand48,
  21. seed48,
  22. srand48
  23. \(em generate uniformly distributed pseudo-random numbers
  24. .SH SYNOPSIS
  25. .LP
  26. .nf
  27. #include <stdlib.h>
  28. .P
  29. double drand48(void);
  30. double erand48(unsigned short \fIxsubi\fP[3]);
  31. long jrand48(unsigned short \fIxsubi\fP[3]);
  32. void lcong48(unsigned short \fIparam\fP[7]);
  33. long lrand48(void);
  34. long mrand48(void);
  35. long nrand48(unsigned short \fIxsubi\fP[3]);
  36. unsigned short *seed48(unsigned short \fIseed16v\fP[3]);
  37. void srand48(long \fIseedval\fP);
  38. .fi
  39. .SH DESCRIPTION
  40. This family of functions shall generate pseudo-random numbers using
  41. a linear congruential algorithm and 48-bit integer arithmetic.
  42. .P
  43. The
  44. \fIdrand48\fR()
  45. and
  46. \fIerand48\fR()
  47. functions shall return non-negative, double-precision, floating-point
  48. values, uniformly distributed over the interval [0.0,1.0).
  49. .P
  50. The
  51. \fIlrand48\fR()
  52. and
  53. \fInrand48\fR()
  54. functions shall return non-negative, long integers, uniformly
  55. distributed over the interval [0,2\u\s-331\s+3\d).
  56. .P
  57. The
  58. \fImrand48\fR()
  59. and
  60. \fIjrand48\fR()
  61. functions shall return signed long integers uniformly distributed over
  62. the interval [\-2\u\s-331\s+3\d,2\u\s-331\s+3\d).
  63. .P
  64. The
  65. \fIsrand48\fR(),
  66. \fIseed48\fR(),
  67. and
  68. \fIlcong48\fR()
  69. functions are initialization entry points, one of which should be
  70. invoked before either
  71. \fIdrand48\fR(),
  72. \fIlrand48\fR(),
  73. or
  74. \fImrand48\fR()
  75. is called. (Although it is not recommended practice, constant default
  76. initializer values shall be supplied automatically if
  77. \fIdrand48\fR(),
  78. \fIlrand48\fR(),
  79. or
  80. \fImrand48\fR()
  81. is called without a prior call to an initialization entry point.) The
  82. \fIerand48\fR(),
  83. \fInrand48\fR(),
  84. and
  85. \fIjrand48\fR()
  86. functions do not require an initialization entry point to be called
  87. first.
  88. .P
  89. All the routines work by generating a sequence of 48-bit integer
  90. values, $X_ i" " ,$ according to the linear congruential formula:
  91. .sp
  92. .RS
  93. $X sub{n+1} " " = " " (aX_ n" "^+^c) sub{roman mod " " m} " " " " " " " " " " " " " " " " n>= " " 0$
  94. .RE
  95. .P
  96. The parameter $m^=^2"^" 48$; hence 48-bit integer arithmetic is
  97. performed. Unless
  98. \fIlcong48\fR()
  99. is invoked, the multiplier value $a$ and the addend value $c$ are given
  100. by:
  101. .sp
  102. .RS
  103. $a " " mark = " " roman "5DEECE66D"^sub 16 " " = " " roman 273673163155^sub 8$
  104. .P
  105. $c " " lineup = " " roman B^sub 16 " " = " " roman 13^sub 8$
  106. .RE
  107. .P
  108. The value returned by any of the
  109. \fIdrand48\fR(),
  110. \fIerand48\fR(),
  111. \fIjrand48\fR(),
  112. \fIlrand48\fR(),
  113. \fImrand48\fR(),
  114. or
  115. \fInrand48\fR()
  116. functions is computed by first generating the next 48-bit $X_ i$ in
  117. the sequence. Then the appropriate number of bits, according to the
  118. type of data item to be returned, are copied from the high-order
  119. (leftmost) bits of $X_ i$ and transformed into the returned value.
  120. .P
  121. The
  122. \fIdrand48\fR(),
  123. \fIlrand48\fR(),
  124. and
  125. \fImrand48\fR()
  126. functions store the last 48-bit $X_ i$ generated in an internal
  127. buffer; that is why the application shall ensure that these are
  128. initialized prior to being invoked. The
  129. \fIerand48\fR(),
  130. \fInrand48\fR(),
  131. and
  132. \fIjrand48\fR()
  133. functions require the calling program to provide storage for the
  134. successive $X_ i$ values in the array specified as an argument when
  135. the functions are invoked. That is why these routines do not have to
  136. be initialized; the calling program merely has to place the desired
  137. initial value of $X_ i$ into the array and pass it as an argument.
  138. By using different arguments,
  139. \fIerand48\fR(),
  140. \fInrand48\fR(),
  141. and
  142. \fIjrand48\fR()
  143. allow separate modules of a large program to generate several
  144. .IR independent
  145. streams of pseudo-random numbers; that is, the sequence of numbers in
  146. each stream shall
  147. .IR not
  148. depend upon how many times the routines are called to generate numbers
  149. for the other streams.
  150. .P
  151. The initializer function
  152. \fIsrand48\fR()
  153. sets the high-order 32 bits of $X_ i$ to the low-order 32 bits
  154. contained in its argument. The low-order 16 bits of $X_ i$ are set
  155. to the arbitrary value $roman 330E_ 16" " .$
  156. .P
  157. The initializer function
  158. \fIseed48\fR()
  159. sets the value of $X_ i$ to the 48-bit value specified in the
  160. argument array. The low-order 16 bits of $X_ i$ are set to the
  161. low-order 16 bits of
  162. .IR seed16v [ 0 ].
  163. The mid-order 16 bits of $X_ i$ are set to the low-order 16 bits of
  164. .IR seed16v [ 1 ].
  165. The high-order 16 bits of $X_ i$ are set to the low-order 16 bits of
  166. .IR seed16v [ 2 ].
  167. In addition, the previous value of $X_ i$ is copied into a 48-bit
  168. internal buffer, used only by
  169. \fIseed48\fR(),
  170. and a pointer to this buffer is the value returned by
  171. \fIseed48\fR().
  172. This returned pointer, which can just be ignored if not needed, is
  173. useful if a program is to be restarted from a given point at some
  174. future time\(emuse the pointer to get at and store the last $X_ i$
  175. value, and then use this value to reinitialize via
  176. \fIseed48\fR()
  177. when the program is restarted.
  178. .P
  179. The initializer function
  180. \fIlcong48\fR()
  181. allows the user to specify the initial $X_ i" " ,$ the multiplier value
  182. $a,$ and the addend value $c.$ Argument array elements
  183. .IR param [ 0-2 ]
  184. specify $X_ i" " ,$
  185. .IR param [ 3-5 ]
  186. specify the multiplier $a,$ and
  187. .IR param [ 6 ]
  188. specifies the 16-bit addend $c.$ After
  189. \fIlcong48\fR()
  190. is called, a subsequent call to either
  191. \fIsrand48\fR()
  192. or
  193. \fIseed48\fR()
  194. shall restore the standard multiplier and addend values,
  195. .IR a
  196. and
  197. .IR c,
  198. specified above.
  199. .P
  200. The
  201. \fIdrand48\fR(),
  202. \fIlrand48\fR(),
  203. and
  204. \fImrand48\fR()
  205. functions need not be thread-safe.
  206. .SH "RETURN VALUE"
  207. As described in the DESCRIPTION above.
  208. .SH ERRORS
  209. No errors are defined.
  210. .LP
  211. .IR "The following sections are informative."
  212. .SH EXAMPLES
  213. None.
  214. .SH "APPLICATION USAGE"
  215. These functions should be avoided whenever non-trivial
  216. requirements (including safety) have to be fulfilled.
  217. .SH RATIONALE
  218. None.
  219. .SH "FUTURE DIRECTIONS"
  220. None.
  221. .SH "SEE ALSO"
  222. .IR "\fIinitstate\fR\^(\|)",
  223. .IR "\fIrand\fR\^(\|)"
  224. .P
  225. The Base Definitions volume of POSIX.1\(hy2017,
  226. .IR "\fB<stdlib.h>\fP"
  227. .\"
  228. .SH COPYRIGHT
  229. Portions of this text are reprinted and reproduced in electronic form
  230. from IEEE Std 1003.1-2017, Standard for Information Technology
  231. -- Portable Operating System Interface (POSIX), The Open Group Base
  232. Specifications Issue 7, 2018 Edition,
  233. Copyright (C) 2018 by the Institute of
  234. Electrical and Electronics Engineers, Inc and The Open Group.
  235. In the event of any discrepancy between this version and the original IEEE and
  236. The Open Group Standard, the original IEEE and The Open Group Standard
  237. is the referee document. The original Standard can be obtained online at
  238. http://www.opengroup.org/unix/online.html .
  239. .PP
  240. Any typographical or formatting errors that appear
  241. in this page are most likely
  242. to have been introduced during the conversion of the source files to
  243. man page format. To report such errors, see
  244. https://www.kernel.org/doc/man-pages/reporting_bugs.html .