diff options
Diffstat (limited to 'man/man3/rand.3')
| -rw-r--r-- | man/man3/rand.3 | 240 |
1 files changed, 240 insertions, 0 deletions
diff --git a/man/man3/rand.3 b/man/man3/rand.3 new file mode 100644 index 000000000..9f63ee9a1 --- /dev/null +++ b/man/man3/rand.3 @@ -0,0 +1,240 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-04-28, Lars Wirzenius +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-05-18, Rik Faith (faith@cs.unc.edu) to add +.\" better discussion of problems with rand on other systems. +.\" (Thanks to Esa Hyyti{ (ehyytia@snakemail.hut.fi).) +.\" Modified 1998-04-10, Nicolás Lichtmaier <nick@debian.org> +.\" with contribution from Francesco Potorti <F.Potorti@cnuce.cnr.it> +.\" Modified 2003-11-15, aeb, added rand_r +.\" 2010-09-13, mtk, added example program +.\" +.TH rand 3 (date) "Linux man-pages (unreleased)" +.SH NAME +rand, rand_r, srand \- pseudo-random number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.B int rand(void); +.BI "void srand(unsigned int " seed ); +.P +.BI "[[deprecated]] int rand_r(unsigned int *" seedp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR rand_r (): +.nf + Since glibc 2.24: + _POSIX_C_SOURCE >= 199506L + glibc 2.23 and earlier + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The +.BR rand () +function returns a pseudo-random integer in the range 0 to +.B RAND_MAX +inclusive (i.e., the mathematical range [0,\ \fBRAND_MAX\fR]). +.P +The +.BR srand () +function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by +.BR rand (). +These sequences are repeatable by calling +.BR srand () +with the same seed value. +.P +If no seed value is provided, the +.BR rand () +function is automatically seeded with a value of 1. +.P +The function +.BR rand () +is not reentrant, since it +uses hidden state that is modified on each call. +This might just be the seed value to be used by the next call, +or it might be something more elaborate. +In order to get reproducible behavior in a threaded +application, this state must be made explicit; +this can be done using the reentrant function +.BR rand_r (). +.P +Like +.BR rand (), +.BR rand_r () +returns a pseudo-random integer in the range [0,\ \fBRAND_MAX\fR]. +The +.I seedp +argument is a pointer to an +.I unsigned int +that is used to store state between calls. +If +.BR rand_r () +is called with the same initial value for the integer pointed to by +.IR seedp , +and that value is not modified between calls, +then the same pseudo-random sequence will result. +.P +The value pointed to by the +.I seedp +argument of +.BR rand_r () +provides only a very small amount of state, +so this function will be a weak pseudo-random generator. +Try +.BR drand48_r (3) +instead. +.SH RETURN VALUE +The +.BR rand () +and +.BR rand_r () +functions return a value between 0 and +.B RAND_MAX +(inclusive). +The +.BR srand () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rand (), +.BR rand_r (), +.BR srand () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The versions of +.BR rand () +and +.BR srand () +in the Linux C Library use the same random number generator as +.BR random (3) +and +.BR srandom (3), +so the lower-order bits should be as random as the higher-order bits. +However, on older +.BR rand () +implementations, and on current implementations on different systems, +the lower-order bits are much less random than the higher-order bits. +Do not use this function in applications intended to be portable +when good randomness is needed. +(Use +.BR random (3) +instead.) +.SH STANDARDS +.TP +.BR rand () +.TQ +.BR srand () +C11, POSIX.1-2008. +.TP +.BR rand_r () +POSIX.1-2008. +.SH HISTORY +.TP +.BR rand () +.TQ +.BR srand () +SVr4, 4.3BSD, C89, POSIX.1-2001. +.TP +.BR rand_r () +POSIX.1-2001. +Obsolete in POSIX.1-2008. +.SH EXAMPLES +POSIX.1-2001 gives the following example of an implementation of +.BR rand () +and +.BR srand (), +possibly useful when one needs the same sequence on two different machines. +.P +.in +4n +.EX +static unsigned long next = 1; +\& +/* RAND_MAX assumed to be 32767 */ +int myrand(void) { + next = next * 1103515245 + 12345; + return((unsigned)(next/65536) % 32768); +} +\& +void mysrand(unsigned int seed) { + next = seed; +} +.EE +.in +.P +The following program can be used to display the +pseudo-random sequence produced by +.BR rand () +when given a particular seed. +When the seed is +.IR \-1 , +the program uses a random seed. +.P +.in +4n +.\" SRC BEGIN (rand.c) +.EX +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + int r; + unsigned int seed, nloops; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s <seed> <nloops>\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + seed = atoi(argv[1]); + nloops = atoi(argv[2]); +\& + if (seed == \-1) { + seed = arc4random(); + printf("seed: %u\en", seed); + } +\& + srand(seed); + for (unsigned int j = 0; j < nloops; j++) { + r = rand(); + printf("%d\en", r); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR drand48 (3), +.BR random (3) |