initstate(3)

1random(3)                  Library Functions Manual                  random(3)
2
3
4

NAME

6       random, srandom, initstate, setstate - random number generator
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <stdlib.h>
13
14       long random(void);
15       void srandom(unsigned int seed);
16
17       char *initstate(unsigned int seed, char state[.n], size_t n);
18       char *setstate(char *state);
19
20   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
21
22       random(), srandom(), initstate(), setstate():
23           _XOPEN_SOURCE >= 500
24               || /* glibc >= 2.19: */ _DEFAULT_SOURCE
25               || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
26

DESCRIPTION

28       The  random() function uses a nonlinear additive feedback random number
29       generator employing a default table of size 31 long integers to  return
30       successive  pseudo-random numbers in the range from 0 to 2^31 - 1.  The
31       period of this random number generator  is  very  large,  approximately
32       16 * ((2^31) - 1).
33
34       The srandom() function sets its argument as the seed for a new sequence
35       of pseudo-random integers to be returned by random().  These  sequences
36       are  repeatable  by  calling srandom() with the same seed value.  If no
37       seed value is provided, the random() function is  automatically  seeded
38       with a value of 1.
39
40       The  initstate()  function allows a state array state to be initialized
41       for use by random().  The size of the state array n is  used  by  init‐
42       state() to decide how sophisticated a random number generator it should
43       use—the larger the state array, the better the random numbers will  be.
44       Current  "optimal"  values for the size of the state array n are 8, 32,
45       64, 128, and 256 bytes; other amounts will be rounded down to the near‐
46       est  known  amount.  Using less than 8 bytes results in an error.  seed
47       is the seed for the initialization, which specifies  a  starting  point
48       for the random number sequence, and provides for restarting at the same
49       point.
50
51       The setstate() function changes the state array used  by  the  random()
52       function.   The  state array state is used for random number generation
53       until the next call to initstate() or  setstate().   state  must  first
54       have  been initialized using initstate() or be the result of a previous
55       call of setstate().
56

RETURN VALUE

58       The random() function returns a value between 0  and  (2^31) - 1.   The
59       srandom() function returns no value.
60
61       The initstate() function returns a pointer to the previous state array.
62       On failure, it returns NULL, and errno is set to indicate the error.
63
64       On success, setstate() returns a pointer to the previous  state  array.
65       On failure, it returns NULL, and errno is set to indicate the error.
66

ERRORS

68       EINVAL The state argument given to setstate() was NULL.
69
70       EINVAL A state array of less than 8 bytes was specified to initstate().
71

ATTRIBUTES

73       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
74       tributes(7).
75
76       ┌────────────────────────────────────────────┬───────────────┬─────────┐
77       │Interface                                   │ Attribute     │ Value   │
78       ├────────────────────────────────────────────┼───────────────┼─────────┤
79       │random(), srandom(), initstate(),           │ Thread safety │ MT-Safe │
80       │setstate()                                  │               │         │
81       └────────────────────────────────────────────┴───────────────┴─────────┘
82

STANDARDS

84       POSIX.1-2008.
85

HISTORY

87       POSIX.1-2001, 4.3BSD.
88

NOTES

90       Random-number  generation  is a complex topic.  Numerical Recipes in C:
91       The Art of Scientific Computing (William H. Press, Brian  P.  Flannery,
92       Saul   A.   Teukolsky,  William  T.  Vetterling;  New  York:  Cambridge
93       University Press, 2007, 3rd ed.)  provides an excellent  discussion  of
94       practical   random-number   generation  issues  in  Chapter  7  (Random
95       Numbers).
96
97       For a more theoretical discussion  which  also  covers  many  practical
98       issues  in  depth,  see Chapter 3 (Random Numbers) in Donald E. Knuth's
99       The Art of Computer Programming, volume 2  (Seminumerical  Algorithms),
100       2nd  ed.;  Reading,  Massachusetts:  Addison-Wesley Publishing Company,
101       1981.
102

CAVEATS

104       The random() function should not  be  used  in  multithreaded  programs
105       where  reproducible  behavior  is  required.   Use random_r(3) for that
106       purpose.
107

BUGS

109       According to POSIX, initstate() should return NULL on  error.   In  the
110       glibc  implementation,  errno  is  (as specified) set on error, but the
111       function does not return NULL.
112