[unix-history] / usr / src / lib / libc / stdlib / random.3

.\" Copyright (c) 1983 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms are permitted
.\" provided that the above copyright notice and this paragraph are
.\" duplicated in all such forms and that any documentation,
.\" advertising materials, and other materials related to such
.\" distribution and use acknowledge that the software was developed
.\" by the University of California, Berkeley.  The name of the
.\" University may not be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\"	@(#)random.3	6.3 (Berkeley) %G%
.\"
.UC 7
.TH RANDOM 3 ""
.UC 5
.SH NAME
random, srandom, initstate, setstate \- better random number generator; routines for changing generators
.SH SYNOPSIS
.nf
.B long  random()
.PP
.B srandom(seed)
.B int  seed;
.PP
.B char  *initstate(seed, state, n)
.B unsigned  seed;
.B char  *state;
.B int  n;
.PP
.B char  *setstate(state)
.B char  *state;
.fi
.SH DESCRIPTION
.PP
.I Random
uses a non-linear 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
.if t 2\u\s731\s10\d\(mi1.
.if n (2**31)\(mi1.
The period of this random number generator is very large, approximately
.if t 16\(mu(2\u\s731\s10\d\(mi1).
.if n 16*((2**31)\(mi1).
.PP
.I Random/srandom
have (almost) the same calling sequence and initialization properties as
.I rand/srand.
The difference is that
.IR rand (3)
produces a much less random sequence \(em in fact, the low dozen bits
generated by rand go through a cyclic pattern.  All the bits generated by
.I random
are usable.  For example, ``random()&01'' will produce a random binary
value.
.PP
Unlike
.IR srand ,
.I srandom
does not return the old seed; the reason for this is that the amount of
state information used is much more than a single word.  (Two other
routines are provided to deal with restarting/changing random
number generators).  Like
.IR rand (3),
however,
.I random
will by default produce a sequence of numbers that can be duplicated
by calling
.I srandom
with 
.I 1
as the seed.
.PP
The
.I initstate
routine allows a state array, passed in as an argument, to be initialized
for future use.  The size of the state array (in bytes) is used by
.I initstate
to decide how sophisticated a random number generator it should use -- the
more state, the better the random numbers will be.
(Current "optimal" values for the amount of state information are
8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
the nearest known amount.  Using less than 8 bytes will cause an error).
The seed for the initialization (which specifies a starting point for
the random number sequence, and provides for restarting at the same
point) is also an argument.
.I Initstate
returns a pointer to the previous state information array.
.PP
Once a state has been initialized, the
.I setstate
routine provides for rapid switching between states.
.I Setstate
returns a pointer to the previous state array; its
argument state array is used for further random number generation
until the next call to
.I initstate
or
.I setstate.
.PP
Once a state array has been initialized, it may be restarted at a
different point either by calling
.I initstate
(with the desired seed, the state array, and its size) or by calling
both
.I setstate
(with the state array) and
.I srandom
(with the desired seed).
The advantage of calling both
.I setstate
and
.I srandom
is that the size of the state array does not have to be remembered after
it is initialized.
.PP
With 256 bytes of state information, the period of the random number
generator is greater than
.if t 2\u\s769\s10\d,
.if n 2**69
which should be sufficient for most purposes.
.SH AUTHOR
Earl T. Cohen
.SH DIAGNOSTICS
.PP
If
.I initstate
is called with less than 8 bytes of state information, or if
.I setstate
detects that the state information has been garbled, error
messages are printed on the standard error output.
.SH "SEE ALSO"
rand(3)
.SH BUGS
About 2/3 the speed of
.IR rand (3C).
Commit	Line	Data
02c81f9a KB	1	.\" Copyright (c) 1983 The Regents of the University of California.
02c81f9a KB	2	.\" All rights reserved.
7db0d200	3	.\"
02c81f9a KB	4	.\" Redistribution and use in source and binary forms are permitted
	5	.\" provided that the above copyright notice and this paragraph are
	6	.\" duplicated in all such forms and that any documentation,
	7	.\" advertising materials, and other materials related to such
	8	.\" distribution and use acknowledge that the software was developed
	9	.\" by the University of California, Berkeley. The name of the
	10	.\" University may not be used to endorse or promote products derived
	11	.\" from this software without specific prior written permission.
	12	.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
	13	.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
	14	.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
7db0d200	15	.\"
02c81f9a KB	16	.\" @(#)random.3 6.3 (Berkeley) %G%
	17	.\"
	18	.UC 7
0b373d97	19	.TH RANDOM 3 ""
7db0d200 KM	20	.UC 5
	21	.SH NAME
	22	random, srandom, initstate, setstate \- better random number generator; routines for changing generators
	23	.SH SYNOPSIS
	24	.nf
	25	.B long random()
	26	.PP
	27	.B srandom(seed)
	28	.B int seed;
	29	.PP
	30	.B char *initstate(seed, state, n)
	31	.B unsigned seed;
	32	.B char *state;
	33	.B int n;
	34	.PP
	35	.B char *setstate(state)
	36	.B char *state;
	37	.fi
	38	.SH DESCRIPTION
	39	.PP
	40	.I Random
	41	uses a non-linear additive feedback random number generator employing a
	42	default table of size 31 long integers to return successive pseudo-random
2bae4d9a KM	43	numbers in the range from 0 to
	44	.if t 2\u\s731\s10\d\(mi1.
	45	.if n (2**31)\(mi1.
	46	The period of this random number generator is very large, approximately
	47	.if t 16\(mu(2\u\s731\s10\d\(mi1).
	48	.if n 16((2*31)\(mi1).
7db0d200 KM	49	.PP
	50	.I Random/srandom
	51	have (almost) the same calling sequence and initialization properties as
	52	.I rand/srand.
	53	The difference is that
	54	.IR rand (3)
2bae4d9a	55	produces a much less random sequence \(em in fact, the low dozen bits
7db0d200 KM	56	generated by rand go through a cyclic pattern. All the bits generated by
7db0d200 KM	57	.I random
2bae4d9a	58	are usable. For example, ``random()&01'' will produce a random binary
7db0d200 KM	59	value.
	60	.PP
	61	Unlike
	62	.IR srand ,
	63	.I srandom
	64	does not return the old seed; the reason for this is that the amount of
	65	state information used is much more than a single word. (Two other
	66	routines are provided to deal with restarting/changing random
	67	number generators). Like
	68	.IR rand (3),
	69	however,
	70	.I random
	71	will by default produce a sequence of numbers that can be duplicated
	72	by calling
	73	.I srandom
	74	with
	75	.I 1
	76	as the seed.
	77	.PP
	78	The
	79	.I initstate
	80	routine allows a state array, passed in as an argument, to be initialized
	81	for future use. The size of the state array (in bytes) is used by
	82	.I initstate
	83	to decide how sophisticated a random number generator it should use -- the
	84	more state, the better the random numbers will be.
	85	(Current "optimal" values for the amount of state information are
	86	8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to
	87	the nearest known amount. Using less than 8 bytes will cause an error).
	88	The seed for the initialization (which specifies a starting point for
	89	the random number sequence, and provides for restarting at the same
	90	point) is also an argument.
	91	.I Initstate
	92	returns a pointer to the previous state information array.
	93	.PP
	94	Once a state has been initialized, the
	95	.I setstate
	96	routine provides for rapid switching between states.
0b373d97 KM	97	.I Setstate
0b373d97 KM	98	returns a pointer to the previous state array; its
7db0d200 KM	99	argument state array is used for further random number generation
	100	until the next call to
	101	.I initstate
	102	or
	103	.I setstate.
	104	.PP
	105	Once a state array has been initialized, it may be restarted at a
	106	different point either by calling
	107	.I initstate
	108	(with the desired seed, the state array, and its size) or by calling
	109	both
	110	.I setstate
	111	(with the state array) and
	112	.I srandom
	113	(with the desired seed).
	114	The advantage of calling both
	115	.I setstate
	116	and
	117	.I srandom
	118	is that the size of the state array does not have to be remembered after
	119	it is initialized.
	120	.PP
	121	With 256 bytes of state information, the period of the random number
2bae4d9a KM	122	generator is greater than
	123	.if t 2\u\s769\s10\d,
	124	.if n 2**69
	125	which should be sufficient for most purposes.
7db0d200 KM	126	.SH AUTHOR
	127	Earl T. Cohen
	128	.SH DIAGNOSTICS
	129	.PP
	130	If
	131	.I initstate
	132	is called with less than 8 bytes of state information, or if
	133	.I setstate
	134	detects that the state information has been garbled, error
	135	messages are printed on the standard error output.
	136	.SH "SEE ALSO"
	137	rand(3)
	138	.SH BUGS
	139	About 2/3 the speed of
	140	.IR rand (3C).