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 Universi‐
93       ty Press, 2007, 3rd ed.)  provides an excellent discussion of practical
94       random-number generation issues in Chapter 7 (Random Numbers).
95
96       For  a more theoretical discussion which also covers many practical is‐
97       sues in depth, see Chapter 3 (Random Numbers) in Donald E. Knuth's  The
98       Art  of  Computer Programming, volume 2 (Seminumerical Algorithms), 2nd
99       ed.; Reading, Massachusetts: Addison-Wesley Publishing Company, 1981.
100

CAVEATS

102       The random() function should not  be  used  in  multithreaded  programs
103       where reproducible behavior is required.  Use random_r(3) for that pur‐
104       pose.
105

BUGS

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