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
11

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

65   Generating a Pseudo-Random Number Sequence
66       The  following  example  demonstrates  how  to  generate  a sequence of
67       pseudo-random numbers.
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           static unsigned long next = 1;
100           int myrand(void)  /* RAND_MAX assumed to be 32767. */
101           {
102               next = next * 1103515245 + 12345;
103               return((unsigned)(next/65536) % 32768);
104           }
105
106           void mysrand(unsigned seed)
107           {
108               next = seed;
109           }
110

APPLICATION USAGE

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

RATIONALE

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

FUTURE DIRECTIONS

147       The rand_r() function may be removed in a future version.
148

SEE ALSO

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