Return to random.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen

Annotation of 43BSDReno/lib/libc/gen/random.3, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.