| .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" 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. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2021-03-22 "" "Linux Programmer's Manual" |
| .SH NAME |
| rand, rand_r, srand \- pseudo-random number generator |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdlib.h> |
| .PP |
| .B int rand(void); |
| .BI "int rand_r(unsigned int *" seedp ); |
| .BI "void srand(unsigned int " seed ); |
| .fi |
| .PP |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .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 |
| .BR RAND_MAX |
| inclusive (i.e., the mathematical range [0,\ \fBRAND_MAX\fR]). |
| .PP |
| 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. |
| .PP |
| If no seed value is provided, the |
| .BR rand () |
| function is automatically seeded with a value of 1. |
| .PP |
| 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 (). |
| .PP |
| 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 |
| .IR "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. |
| .PP |
| 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 |
| .BR 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). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lbx lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR rand (), |
| .BR rand_r (), |
| .BR srand () |
| T} Thread safety MT-Safe |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .SH CONFORMING TO |
| The functions |
| .BR rand () |
| and |
| .BR srand () |
| conform to SVr4, 4.3BSD, C89, C99, POSIX.1-2001. |
| The function |
| .BR rand_r () |
| is from POSIX.1-2001. |
| POSIX.1-2008 marks |
| .BR rand_r () |
| as obsolete. |
| .SH NOTES |
| 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 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. |
| .PP |
| .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 |
| .PP |
| The following program can be used to display the |
| pseudo-random sequence produced by |
| .BR rand () |
| when given a particular seed. |
| .PP |
| .in +4n |
| .EX |
| #include <stdlib.h> |
| #include <stdio.h> |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| int r, nloops; |
| unsigned int seed; |
| |
| if (argc != 3) { |
| fprintf(stderr, "Usage: %s <seed> <nloops>\en", argv[0]); |
| exit(EXIT_FAILURE); |
| } |
| |
| seed = atoi(argv[1]); |
| nloops = atoi(argv[2]); |
| |
| srand(seed); |
| for (int j = 0; j < nloops; j++) { |
| r = rand(); |
| printf("%d\en", r); |
| } |
| |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .in |
| .SH SEE ALSO |
| .BR drand48 (3), |
| .BR random (3) |