diff options
Diffstat (limited to 'man3/rand.3')
| -rw-r--r-- | man3/rand.3 | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/man3/rand.3 b/man3/rand.3 new file mode 100644 index 000000000..b13076bc0 --- /dev/null +++ b/man3/rand.3 @@ -0,0 +1,167 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 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 +.\" +.TH RAND 3 2003-11-15 "" "Linux Programmer's Manual" +.SH NAME +rand, rand_r, srand \- pseudo-random number generator +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.sp +.B int rand(void); +.sp +.BI "int rand_r(unsigned int *" seedp ); +.sp +.BI "void srand(unsigned int " seed ); +.fi +.SH DESCRIPTION +The \fBrand()\fP function returns a pseudo-random integer between 0 +and \fBRAND_MAX\fR. +.PP +The \fBsrand()\fP function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by \fBrand()\fP. +These sequences are repeatable by calling \fBsrand()\fP with the same +seed value. +.PP +If no seed value is provided, the \fBrand()\fP function is automatically +seeded with a value of 1. +.PP +The function +.B rand() +is not reentrant or thread-safe, 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 behaviour in a threaded +application, this state must be made explicit. The function +.B rand_r() +is supplied with a pointer to an unsigned int, to be used as state. +This is 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 \fBrand()\fP and \fBrand_r()\fP functions return a value +between 0 and RAND_MAX. +The \fBsrand()\fP function returns no value. +.SH EXAMPLE +POSIX 1003.1-2003 gives the following example of an implementation of +.B rand() +and +.BR srand() , +possibly useful when one needs the same sequence on two different machines. +.sp +.nf + 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 seed) { + next = seed; + } +.fi +.SH NOTES +The versions of \fBrand()\fP and \fBsrand()\fP in the Linux C Library use +the same random number generator as \fBrandom()\fP and \fBsrandom()\fP, so +the lower-order bits should be as random as the higher-order bits. +However, on older +.B 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. +.PP +FreeBSD adds a function +.sp +.in +5 +.B void sranddev(void); +.in +.sp +that initializes the seed for their bad random generator +.B rand() +with a value obtained from their good random generator +.BR random() . +Strange. +.PP +In +.I 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, 1992 (2nd ed., +p. 277)), the following comments are made: +.RS +"If you want to generate a random integer between 1 and 10, you should +always do it by using high-order bits, as in +.RS +.sp +j=1+(int) (10.0*rand()/(RAND_MAX+1.0)); +.sp +.RE +and never by anything resembling +.RS +.sp +j=1+(rand() % 10); +.sp +.RE +(which uses lower-order bits)." +.RE +.PP +Random-number generation is a complex topic. The +.I Numerical Recipes in C +book (see reference above) +provides an excellent discussion of practical random-number generation +issues in Chapter 7 (Random Numbers). +.PP +For a more theoretical discussion which also covers many practical issues +in depth, please see Chapter 3 (Random Numbers) in Donald E. Knuth's +.IR "The Art of Computer Programming" , +volume 2 (Seminumerical Algorithms), 2nd ed.; Reading, Massachusetts: +Addison-Wesley Publishing Company, 1981. +.SH "CONFORMING TO" +The functions +.B rand() +and +.B srand() +conform to SVID 3, BSD 4.3, ISO 9899, POSIX 1003.1-2003. +The function +.B rand_r() +is from POSIX 1003.1-2003. +.SH "SEE ALSO" +.BR drand48 (3), +.BR random (3) |