random(3) — Linux manual page

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | STANDARDS | HISTORY | NOTES | CAVEATS | BUGS | SEE ALSO | COLOPHON

random(3)               Library Functions Manual               random(3)

NAME         top

       random, srandom, initstate, setstate - random number generator

LIBRARY         top

       Standard C library (libc, -lc)

SYNOPSIS         top

       #include <stdlib.h>

       long random(void);
       void srandom(unsigned int seed);

       char *initstate(unsigned int seed, char state[.n], size_t n);
       char *setstate(char *state);

   Feature Test Macro Requirements for glibc (see
   feature_test_macros(7)):

       random(), srandom(), initstate(), setstate():
           _XOPEN_SOURCE >= 500
               || /* glibc >= 2.19: */ _DEFAULT_SOURCE
               || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE

DESCRIPTION         top

       The random() function uses a nonlinear additive feedback random
       number generator employing a default table of size 31 long
       integers to return successive pseudo-random numbers in the range
       from 0 to 2^31 - 1.  The period of this random number generator
       is very large, approximately 16 * ((2^31) - 1).

       The srandom() function sets its argument as the seed for a new
       sequence of pseudo-random integers to be returned by random().
       These sequences are repeatable by calling srandom() with the same
       seed value.  If no seed value is provided, the random() function
       is automatically seeded with a value of 1.

       The initstate() function allows a state array state to be
       initialized for use by random().  The size of the state array n
       is used by initstate() to decide how sophisticated a random
       number generator it should use—the larger the state array, the
       better the random numbers will be.  Current "optimal" values for
       the size of the state array n are 8, 32, 64, 128, and 256 bytes;
       other amounts will be rounded down to the nearest known amount.
       Using less than 8 bytes results in an error.  seed is the seed
       for the initialization, which specifies a starting point for the
       random number sequence, and provides for restarting at the same
       point.

       The setstate() function changes the state array used by the
       random() function.  The state array state is used for random
       number generation until the next call to initstate() or
       setstate().  state must first have been initialized using
       initstate() or be the result of a previous call of setstate().

RETURN VALUE         top

       The random() function returns a value between 0 and (2^31) - 1.
       The srandom() function returns no value.

       The initstate() function returns a pointer to the previous state
       array.  On failure, it returns NULL, and errno is set to indicate
       the error.

       On success, setstate() returns a pointer to the previous state
       array.  On failure, it returns NULL, and errno is set to indicate
       the error.

ERRORS         top

       EINVAL The state argument given to setstate() was NULL.

       EINVAL A state array of less than 8 bytes was specified to
              initstate().

ATTRIBUTES         top

       For an explanation of the terms used in this section, see
       attributes(7).
       ┌─────────────────────────────────────┬───────────────┬─────────┐
       │ Interface                           Attribute     Value   │
       ├─────────────────────────────────────┼───────────────┼─────────┤
       │ random(), srandom(), initstate(),   │ Thread safety │ MT-Safe │
       │ setstate()                          │               │         │
       └─────────────────────────────────────┴───────────────┴─────────┘

STANDARDS         top

       POSIX.1-2008.

HISTORY         top

       POSIX.1-2001, 4.3BSD.

NOTES         top

       Random-number generation is a complex topic.  Numerical Recipes
       in C: The Art of Scientific Computing (William H. Press, Brian P.
       Flannery, Saul A. Teukolsky, William T. Vetterling; New York:
       Cambridge University Press, 2007, 3rd ed.)  provides an excellent
       discussion of practical random-number generation issues in
       Chapter 7 (Random Numbers).

       For a more theoretical discussion which also covers many
       practical issues in depth, see Chapter 3 (Random Numbers) in
       Donald E. Knuth's The Art of Computer Programming, volume 2
       (Seminumerical Algorithms), 2nd ed.; Reading, Massachusetts:
       Addison-Wesley Publishing Company, 1981.

CAVEATS         top

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

BUGS         top

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

SEE ALSO         top

       getrandom(2), drand48(3), rand(3), random_r(3), srand(3)

COLOPHON         top

       This page is part of the man-pages (Linux kernel and C library
       user-space interface documentation) project.  Information about
       the project can be found at 
       ⟨https://www.kernel.org/doc/man-pages/⟩.  If you have a bug report
       for this manual page, see
       ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.
       This page was obtained from the tarball man-pages-6.9.1.tar.gz
       fetched from
       ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on
       2024-06-26.  If you discover any rendering problems in this HTML
       version of the page, or you believe there is a better or more up-
       to-date source for the page, or you have corrections or
       improvements to the information in this COLOPHON (which is not
       part of the original manual page), send a mail to
       [email protected]

Linux man-pages 6.9.1          2024-05-02                      random(3)

Pages that refer to this page: drand48(3)drand48_r(3)rand(3)random_r(3)