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

rand.3p (6151B)


  1. '\" et
  2. .TH RAND "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. .SH NAME
  11. rand,
  12. rand_r,
  13. srand
  14. \(em pseudo-random number generator
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <stdlib.h>
  19. .P
  20. int rand(void);
  21. int rand_r(unsigned *\fIseed\fP);
  22. void srand(unsigned \fIseed\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. For
  26. \fIrand\fR()
  27. and
  28. \fIsrand\fR():
  29. The functionality described on this reference page is aligned with the
  30. ISO\ C standard. Any conflict between the requirements described here and the
  31. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  32. .P
  33. The
  34. \fIrand\fR()
  35. function shall compute a sequence of pseudo-random integers in the
  36. range [0,\c
  37. {RAND_MAX}]
  38. with a period of at least 2\u\s-332\s0\d.
  39. .P
  40. The
  41. \fIrand\fR()
  42. function need not be thread-safe.
  43. .P
  44. The
  45. \fIrand_r\fR()
  46. function shall compute a sequence of pseudo-random integers in
  47. the range [0,\c
  48. {RAND_MAX}].
  49. (The value of the
  50. {RAND_MAX}
  51. macro shall be at least 32\|767.)
  52. .P
  53. If
  54. \fIrand_r\fR()
  55. is called with the same initial value for the object pointed to by
  56. .IR seed
  57. and that object is not modified between successive returns and calls to
  58. \fIrand_r\fR(),
  59. the same sequence shall be generated.
  60. .P
  61. The
  62. \fIsrand\fR()
  63. function uses the argument as a seed for a new sequence of
  64. pseudo-random numbers to be returned by subsequent calls to
  65. \fIrand\fR().
  66. If
  67. \fIsrand\fR()
  68. is then called with the same seed value, the sequence of pseudo-random
  69. numbers shall be repeated. If
  70. \fIrand\fR()
  71. is called before any calls to
  72. \fIsrand\fR()
  73. are made, the same sequence shall be generated as when
  74. \fIsrand\fR()
  75. is first called with a seed value of 1.
  76. .P
  77. The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017
  78. calls
  79. \fIrand\fR()
  80. or
  81. \fIsrand\fR().
  82. .SH "RETURN VALUE"
  83. The
  84. \fIrand\fR()
  85. function shall return the next pseudo-random number in the sequence.
  86. .P
  87. The
  88. \fIrand_r\fR()
  89. function shall return a pseudo-random integer.
  90. .P
  91. The
  92. \fIsrand\fR()
  93. function shall not return a value.
  94. .SH ERRORS
  95. No errors are defined.
  96. .LP
  97. .IR "The following sections are informative."
  98. .SH EXAMPLES
  99. .SS "Generating a Pseudo-Random Number Sequence"
  100. .P
  101. The following example demonstrates how to generate a sequence of
  102. pseudo-random numbers.
  103. .sp
  104. .RS 4
  105. .nf
  106. #include <stdio.h>
  107. #include <stdlib.h>
  108. \&...
  109. long count, i;
  110. char *keystr;
  111. int elementlen, len;
  112. char c;
  113. \&...
  114. /* Initial random number generator. */
  115. srand(1);
  116. .P
  117. /* Create keys using only lowercase characters */
  118. len = 0;
  119. for (i=0; i<count; i++) {
  120. while (len < elementlen) {
  121. c = (char) (rand() % 128);
  122. if (islower(c))
  123. keystr[len++] = c;
  124. }
  125. .P
  126. keystr[len] = \(aq\e0\(aq;
  127. printf("%s Element%0*ld\en", keystr, elementlen, i);
  128. len = 0;
  129. }
  130. .fi
  131. .P
  132. .RE
  133. .SS "Generating the Same Sequence on Different Machines"
  134. .P
  135. The following code defines a pair of functions that could be
  136. incorporated into applications wishing to ensure that the same sequence
  137. of numbers is generated across different machines.
  138. .sp
  139. .RS 4
  140. .nf
  141. static unsigned long next = 1;
  142. int myrand(void) /* RAND_MAX assumed to be 32767. */
  143. {
  144. next = next * 1103515245 + 12345;
  145. return((unsigned)(next/65536) % 32768);
  146. }
  147. .P
  148. void mysrand(unsigned seed)
  149. {
  150. next = seed;
  151. }
  152. .fi
  153. .P
  154. .RE
  155. .SH "APPLICATION USAGE"
  156. The
  157. \fIdrand48\fR()
  158. and
  159. \fIrandom\fR()
  160. functions provide much more elaborate pseudo-random number generators.
  161. .P
  162. The limitations on the amount of state that can be carried between one
  163. function call and another mean the
  164. \fIrand_r\fR()
  165. function can never be implemented in a way which satisfies all of the
  166. requirements on a pseudo-random number generator.
  167. .P
  168. These functions should be avoided whenever non-trivial requirements
  169. (including safety) have to be fulfilled.
  170. .SH RATIONALE
  171. The ISO\ C standard
  172. \fIrand\fR()
  173. and
  174. \fIsrand\fR()
  175. functions allow per-process pseudo-random streams shared by all
  176. threads. Those two functions need not change, but there
  177. has to be mutual-exclusion that prevents interference between two
  178. threads concurrently accessing the random number generator.
  179. .P
  180. With regard to
  181. \fIrand\fR(),
  182. there are two different behaviors that may be wanted in a multi-threaded
  183. program:
  184. .IP " 1." 4
  185. A single per-process sequence of pseudo-random numbers that is shared
  186. by all threads that call
  187. \fIrand\fR()
  188. .IP " 2." 4
  189. A different sequence of pseudo-random numbers for each thread that
  190. calls
  191. \fIrand\fR()
  192. .P
  193. This is provided by the modified thread-safe function based on whether
  194. the seed value is global to the entire process or local to each
  195. thread.
  196. .P
  197. This does not address the known deficiencies of the
  198. \fIrand\fR()
  199. function implementations, which have been approached by maintaining
  200. more state. In effect, this specifies new thread-safe forms of a
  201. deficient function.
  202. .SH "FUTURE DIRECTIONS"
  203. The
  204. \fIrand_r\fR()
  205. function may be removed in a future version.
  206. .SH "SEE ALSO"
  207. .IR "\fIdrand48\fR\^(\|)",
  208. .IR "\fIinitstate\fR\^(\|)"
  209. .P
  210. The Base Definitions volume of POSIX.1\(hy2017,
  211. .IR "\fB<stdlib.h>\fP"
  212. .\"
  213. .SH COPYRIGHT
  214. Portions of this text are reprinted and reproduced in electronic form
  215. from IEEE Std 1003.1-2017, Standard for Information Technology
  216. -- Portable Operating System Interface (POSIX), The Open Group Base
  217. Specifications Issue 7, 2018 Edition,
  218. Copyright (C) 2018 by the Institute of
  219. Electrical and Electronics Engineers, Inc and The Open Group.
  220. In the event of any discrepancy between this version and the original IEEE and
  221. The Open Group Standard, the original IEEE and The Open Group Standard
  222. is the referee document. The original Standard can be obtained online at
  223. http://www.opengroup.org/unix/online.html .
  224. .PP
  225. Any typographical or formatting errors that appear
  226. in this page are most likely
  227. to have been introduced during the conversion of the source files to
  228. man page format. To report such errors, see
  229. https://www.kernel.org/doc/man-pages/reporting_bugs.html .