Annotation of src/lib/libc/stdlib/random.3, Revision 1.14
1.14 ! ross 1: .\" $NetBSD: random.3,v 1.13 2002/01/08 02:19:56 thorpej Exp $
1.4 thorpej 2: .\"
1.5 perry 3: .\" Copyright (c) 1983, 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
14: .\" 3. All advertising materials mentioning features or use of this software
15: .\" must display the following acknowledgement:
16: .\" This product includes software developed by the University of
17: .\" California, Berkeley and its contributors.
18: .\" 4. Neither the name of the University nor the names of its contributors
19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
1.5 perry 34: .\" from: @(#)random.3 8.1 (Berkeley) 6/4/93
1.1 cgd 35: .\"
1.5 perry 36: .Dd June 4, 1993
1.1 cgd 37: .Dt RANDOM 3
1.9 garbled 38: .Os
1.1 cgd 39: .Sh NAME
40: .Nm random ,
41: .Nm srandom ,
42: .Nm initstate ,
43: .Nm setstate
44: .Nd better random number generator; routines for changing generators
1.7 perry 45: .Sh LIBRARY
46: .Lb libc
1.1 cgd 47: .Sh SYNOPSIS
1.14 ! ross 48: .Fd #include \*[Lt]stdlib.h\*[Gt]
1.8 fair 49: .Ft long
1.1 cgd 50: .Fn random void
51: .Ft void
1.10 itojun 52: .Fn srandom "unsigned long seed"
1.1 cgd 53: .Ft char *
1.10 itojun 54: .Fn initstate "unsigned long seed" "char *state" "size_t n"
1.1 cgd 55: .Ft char *
56: .Fn setstate "char *state"
57: .Sh DESCRIPTION
58: The
59: .Fn random
60: function
61: uses a non-linear additive feedback random number generator employing a
62: default table of size 31 long integers to return successive pseudo-random
63: numbers in the range from 0 to
64: .if t 2\u\s731\s10\d\(mi1.
65: .if n (2**31)\(mi1.
66: The period of this random number generator is very large, approximately
67: .if t 16\(mu(2\u\s731\s10\d\(mi1).
68: .if n 16*((2**31)\(mi1).
69: .Pp
70: The
1.8 fair 71: .Fn random
72: and
73: .Fn srandom
1.1 cgd 74: have (almost) the same calling sequence and initialization properties as
1.8 fair 75: .Xr rand 3
76: and
77: .Xr srand 3 .
1.1 cgd 78: The difference is that
1.8 fair 79: .Xr rand 3
1.1 cgd 80: produces a much less random sequence \(em in fact, the low dozen bits
1.8 fair 81: generated by
82: .Xr rand 3
83: go through a cyclic pattern.
84: All the bits generated by
1.1 cgd 85: .Fn random
1.8 fair 86: are usable.
87: For example,
1.14 ! ross 88: .Sq Li random()&01
1.8 fair 89: will produce a random binary value.
1.1 cgd 90: .Pp
1.8 fair 91: Like
1.1 cgd 92: .Xr rand 3 ,
93: .Fn random
94: will by default produce a sequence of numbers that can be duplicated
95: by calling
96: .Fn srandom
1.8 fair 97: with
1.1 cgd 98: .Ql 1
99: as the seed.
100: .Pp
101: The
102: .Fn initstate
103: routine allows a state array, passed in as an argument, to be initialized
1.8 fair 104: for future use.
105: The size of the state array (in bytes) is used by
1.1 cgd 106: .Fn initstate
107: to decide how sophisticated a random number generator it should use \(em the
108: more state, the better the random numbers will be.
109: (Current "optimal" values for the amount of state information are
110: 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
1.8 fair 111: the nearest known amount.
112: Using less than 8 bytes will cause an error).
1.1 cgd 113: The seed for the initialization (which specifies a starting point for
114: the random number sequence, and provides for restarting at the same
1.13 thorpej 115: point) is also an argument. The state array passed to
116: .Fn initstate
117: must be aligned to a 32-bit boundary. This can be achieved by using
118: a suitably-sized array of ints, and casting the array to char * when
119: passing it to
120: .Fn initstate .
1.1 cgd 121: The
122: .Fn initstate
123: function
124: returns a pointer to the previous state information array.
125: .Pp
126: Once a state has been initialized, the
127: .Fn setstate
128: routine provides for rapid switching between states.
129: The
130: .Fn setstate
131: function
132: returns a pointer to the previous state array; its
133: argument state array is used for further random number generation
134: until the next call to
135: .Fn initstate
136: or
137: .Fn setstate .
138: .Pp
139: Once a state array has been initialized, it may be restarted at a
140: different point either by calling
141: .Fn initstate
142: (with the desired seed, the state array, and its size) or by calling
143: both
144: .Fn setstate
145: (with the state array) and
146: .Fn srandom
147: (with the desired seed).
148: The advantage of calling both
149: .Fn setstate
150: and
151: .Fn srandom
152: is that the size of the state array does not have to be remembered after
153: it is initialized.
154: .Pp
155: With 256 bytes of state information, the period of the random number
156: generator is greater than
157: .if t 2\u\s769\s10\d,
158: .if n 2**69
159: which should be sufficient for most purposes.
160: .Sh DIAGNOSTICS
161: If
162: .Fn initstate
163: is called with less than 8 bytes of state information, or if
164: .Fn setstate
165: detects that the state information has been garbled, error
166: messages are printed on the standard error output.
167: .Sh SEE ALSO
1.8 fair 168: .Xr rand 3 ,
169: .Xr srand 3 ,
170: .Xr rnd 4 ,
171: .Xr rnd 9
1.1 cgd 172: .Sh HISTORY
173: These
1.8 fair 174: functions appeared in
1.1 cgd 175: .Bx 4.2 .
1.12 wiz 176: .Sh AUTHORS
177: .An Earl T. Cohen
1.1 cgd 178: .Sh BUGS
179: About 2/3 the speed of
180: .Xr rand 3 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to random.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / stdlib