1RAND(3P)                   POSIX Programmer's Manual                  RAND(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       rand, rand_r, srand — pseudo-random number generator
13

SYNOPSIS

15       #include <stdlib.h>
16
17       int rand(void);
18       int rand_r(unsigned *seed);
19       void srand(unsigned seed);
20

DESCRIPTION

22       For rand() and srand(): The functionality described on  this  reference
23       page  is  aligned  with  the  ISO C  standard. Any conflict between the
24       requirements described here and the ISO C  standard  is  unintentional.
25       This volume of POSIX.1‐2017 defers to the ISO C standard.
26
27       The  rand() function shall compute a sequence of pseudo-random integers
28       in the range [0,{RAND_MAX}] with a period of at least 232.
29
30       The rand() function need not be thread-safe.
31
32       The rand_r() function shall compute a sequence of  pseudo-random  inte‐
33       gers  in  the range [0,{RAND_MAX}].  (The value of the {RAND_MAX} macro
34       shall be at least 32767.)
35
36       If rand_r() is called with  the  same  initial  value  for  the  object
37       pointed  to  by seed and that object is not modified between successive
38       returns and calls to rand_r(), the same sequence shall be generated.
39
40       The srand() function uses the argument as a seed for a new sequence  of
41       pseudo-random numbers to be returned by subsequent calls to rand().  If
42       srand() is then called with  the  same  seed  value,  the  sequence  of
43       pseudo-random numbers shall be repeated. If rand() is called before any
44       calls to srand() are made, the same sequence shall be generated as when
45       srand() is first called with a seed value of 1.
46
47       The  implementation shall behave as if no function defined in this vol‐
48       ume of POSIX.1‐2017 calls rand() or srand().
49

RETURN VALUE

51       The rand() function shall return the next pseudo-random number  in  the
52       sequence.
53
54       The rand_r() function shall return a pseudo-random integer.
55
56       The srand() function shall not return a value.
57

ERRORS

59       No errors are defined.
60
61       The following sections are informative.
62

EXAMPLES

64   Generating a Pseudo-Random Number Sequence
65       The  following  example  demonstrates  how  to  generate  a sequence of
66       pseudo-random numbers.
67
68
69           #include <stdio.h>
70           #include <stdlib.h>
71           ...
72               long count, i;
73               char *keystr;
74               int elementlen, len;
75               char c;
76           ...
77           /* Initial random number generator. */
78               srand(1);
79
80               /* Create keys using only lowercase characters */
81               len = 0;
82               for (i=0; i<count; i++) {
83                   while (len < elementlen) {
84                       c = (char) (rand() % 128);
85                       if (islower(c))
86                           keystr[len++] = c;
87                   }
88
89                   keystr[len] = '\0';
90                   printf("%s Element%0*ld\n", keystr, elementlen, i);
91                   len = 0;
92               }
93
94   Generating the Same Sequence on Different Machines
95       The following code defines a pair of functions that could  be  incorpo‐
96       rated  into  applications  wishing  to ensure that the same sequence of
97       numbers is generated across different machines.
98
99
100           static unsigned long next = 1;
101           int myrand(void)  /* RAND_MAX assumed to be 32767. */
102           {
103               next = next * 1103515245 + 12345;
104               return((unsigned)(next/65536) % 32768);
105           }
106
107           void mysrand(unsigned seed)
108           {
109               next = seed;
110           }
111

APPLICATION USAGE

113       The drand48()  and  random()  functions  provide  much  more  elaborate
114       pseudo-random number generators.
115
116       The  limitations on the amount of state that can be carried between one
117       function call and another mean  the  rand_r()  function  can  never  be
118       implemented  in  a  way  which  satisfies  all of the requirements on a
119       pseudo-random number generator.
120
121       These functions should be  avoided  whenever  non-trivial  requirements
122       (including safety) have to be fulfilled.
123

RATIONALE

125       The  ISO C  standard  rand()  and  srand()  functions allow per-process
126       pseudo-random streams shared by all threads. Those two  functions  need
127       not  change,  but there has to be mutual-exclusion that prevents inter‐
128       ference between two threads concurrently accessing  the  random  number
129       generator.
130
131       With  regard  to  rand(), there are two different behaviors that may be
132       wanted in a multi-threaded program:
133
134        1. A single per-process sequence  of  pseudo-random  numbers  that  is
135           shared by all threads that call rand()
136
137        2. A  different sequence of pseudo-random numbers for each thread that
138           calls rand()
139
140       This is provided by the modified thread-safe function based on  whether
141       the seed value is global to the entire process or local to each thread.
142
143       This  does  not  address  the known deficiencies of the rand() function
144       implementations, which have been approached by maintaining more  state.
145       In  effect,  this  specifies new thread-safe forms of a deficient func‐
146       tion.
147

FUTURE DIRECTIONS

149       The rand_r() function may be removed in a future version.
150

SEE ALSO

152       drand48(), initstate()
153
154       The Base Definitions volume of POSIX.1‐2017, <stdlib.h>
155
157       Portions of this text are reprinted and reproduced in  electronic  form
158       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
159       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
160       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
161       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
162       event of any discrepancy between this version and the original IEEE and
163       The Open Group Standard, the original IEEE and The Open Group  Standard
164       is  the  referee document. The original Standard can be obtained online
165       at http://www.opengroup.org/unix/online.html .
166
167       Any typographical or formatting errors that appear  in  this  page  are
168       most likely to have been introduced during the conversion of the source
169       files to man page format. To report such errors,  see  https://www.ker
170       nel.org/doc/man-pages/reporting_bugs.html .
171
172
173
174IEEE/The Open Group                  2017                             RAND(3P)
Impressum