initstate(3)

1RANDOM(3)                  Linux Programmer's Manual                 RANDOM(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

65       EINVAL The state argument given to setstate() was NULL.
66
67       EINVAL A state array of less than 8 bytes was specified to initstate().
68

ATTRIBUTES

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

CONFORMING TO

81       POSIX.1-2001, POSIX.1-2008, 4.3BSD.
82

NOTES

84       The  random()  function  should  not  be used in multithreaded programs
85       where reproducible behavior is required.  Use random_r(3) for that pur‐
86       pose.
87
88       Random-number  generation  is a complex topic.  Numerical Recipes in C:
89       The Art of Scientific Computing (William H. Press, Brian  P.  Flannery,
90       Saul A. Teukolsky, William T. Vetterling; New York: Cambridge Universi‐
91       ty Press, 2007, 3rd ed.)  provides an excellent discussion of practical
92       random-number generation issues in Chapter 7 (Random Numbers).
93
94       For  a more theoretical discussion which also covers many practical is‐
95       sues in depth, see Chapter 3 (Random Numbers) in Donald E. Knuth's  The
96       Art  of  Computer Programming, volume 2 (Seminumerical Algorithms), 2nd
97       ed.; Reading, Massachusetts: Addison-Wesley Publishing Company, 1981.
98

BUGS

100       According to POSIX, initstate() should return NULL on  error.   In  the
101       glibc  implementation,  errno  is  (as specified) set on error, but the
102       function does not return NULL.
103

COLOPHON

108       This page is part of release 5.13 of the Linux  man-pages  project.   A
109       description  of  the project, information about reporting bugs, and the
110       latest    version    of    this    page,    can     be     found     at
111       https://www.kernel.org/doc/man-pages/.
112
113
114
115GNU                               2021-03-22                         RANDOM(3)