usr/src/man/man3c/random.3c

   1 '\" te
   2 .\"  Copyright (c) 1983 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement specifies the terms and conditions for redistribution.  Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved  Portions Copyright (c) 1992,
   3 .\" X/Open Company Limited  All Rights Reserved
   4 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   7 .\"  This notice shall appear on any product containing this material.
   8 .TH RANDOM 3C "Aug 14, 2002"
   9 .SH NAME
  10 random, srandom, initstate, setstate \- pseudorandom number functions
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <stdlib.h>
  15
  16 \fBlong\fR \fBrandom\fR(\fBvoid\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid\fR \fBsrandom\fR(\fBunsigned int\fR \fIseed\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBchar *\fR\fBinitstate\fR(\fBunsigned int\fR \fIseed\fR, \fBchar\fR \fI*state\fR, \fBsize_t\fR \fIsize\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBchar *\fR\fBsetstate\fR(\fBconst char *\fR\fIstate\fR);
  32 .fi
  33
  34 .SH DESCRIPTION
  35 .LP
  36 The \fBrandom()\fR function uses a nonlinear additive feedback random-number
  37 generator employing a default state array size of 31 long integers to return
  38 successive pseudo-random numbers in the range from 0 to 2^31 \(mi1. The period
  39 of this random-number generator is approximately 16 x (2^31 \(mi1). The size of
  40 the state array determines the period of the random-number generator.
  41 Increasing the state array size increases the period.
  42 .sp
  43 .LP
  44 The \fBsrandom()\fR function initializes the current state array using the
  45 value of \fIseed\fR.
  46 .sp
  47 .LP
  48 The \fBrandom()\fR and \fBsrandom()\fR functions have (almost) the same calling
  49 sequence and initialization properties as \fBrand()\fR and \fBsrand()\fR (see
  50 \fBrand\fR(3C)). The difference is that \fBrand\fR(3C) produces a much less
  51 random sequence\(emin fact, the low dozen bits generated by rand go through a
  52 cyclic pattern. All the bits generated by \fBrandom()\fR are usable.
  53 .sp
  54 .LP
  55 The algorithm from \fBrand()\fR is used by \fBsrandom()\fR to generate the 31
  56 state integers. Because of this, different \fBsrandom()\fR seeds often produce,
  57 within an offset, the same sequence of low order bits from \fBrandom()\fR. If
  58 low order bits are used directly, \fBrandom()\fR should be initialized with
  59 \fBsetstate()\fR using high quality random values.
  60 .sp
  61 .LP
  62 Unlike \fBsrand()\fR, \fBsrandom()\fR does not return the old seed because the
  63 amount of state information used is much more than a single word. Two other
  64 routines are provided to deal with restarting/changing random number
  65 generators. With 256 bytes of state information, the period of the
  66 random-number generator is greater than 2^69, which should be sufficient for
  67 most purposes.
  68 .sp
  69 .LP
  70 Like \fBrand\fR(3C), \fBrandom()\fR produces by default a sequence of numbers
  71 that can be duplicated by calling \fBsrandom()\fR with 1 as the seed.
  72 .sp
  73 .LP
  74 The \fBinitstate()\fR and \fBsetstate()\fR functions handle restarting and
  75 changing random-number generators.  The \fBinitstate()\fR function allows a
  76 state array, pointed to by the \fIstate\fR argument, to be initialized for
  77 future use. The \fBsize\fR argument, which specifies the size in bytes of the
  78 state array, is used by \fBinitstate()\fR to decide what type of random-number
  79 generator to use; the larger the state array, the more random the numbers.
  80 Values for the amount of state information are 8, 32, 64, 128, and 256 bytes.
  81 Other values greater than 8 bytes are rounded down to the nearest one of these
  82 values.  For values smaller than 8, \fBrandom()\fR uses a simple linear
  83 congruential random number generator.  The \fIseed\fR argument specifies a
  84 starting point for the random-number sequence and provides for restarting at
  85 the same point.  The \fBinitstate()\fR function returns a pointer to the
  86 previous state information array.
  87 .sp
  88 .LP
  89 If \fBinitstate()\fR has not been called, then \fBrandom()\fR behaves as though
  90 \fBinitstate()\fR had been called with \fIseed\fR\|=\|1 and \fIsize\fR\|=\|128.
  91 .sp
  92 .LP
  93 If \fBinitstate()\fR is called with \fIsize\fR\|<\|8, then \fBrandom()\fR uses
  94 a simple linear congruential random number generator.
  95 .sp
  96 .LP
  97 Once a state has been initialized, \fBsetstate()\fR allows switching between
  98 state arrays. The array defined by the \fIstate\fR argument is used for further
  99 random-number generation until \fBinitstate()\fR is called or \fBsetstate()\fR
 100 is called again. The \fBsetstate()\fR function returns a pointer to the
 101 previous state array.
 102 .sp
 103 .LP
 104 For a more powerful random number generator, see \fBarc4random\fR(3C).
 105 .SH RETURN VALUES
 106 .LP
 107 The \fBrandom()\fR function returns the generated pseudo-random number.
 108 .sp
 109 .LP
 110 The \fBsrandom()\fR function returns no value.
 111 .sp
 112 .LP
 113 Upon successful completion, \fBinitstate()\fR and \fBsetstate()\fR return a
 114 pointer to the previous state array.  Otherwise, a null pointer is returned.
 115 .SH ERRORS
 116 .LP
 117 No errors are defined.
 118 .SH USAGE
 119 .LP
 120 After initialization, a state array can be restarted at a different point in
 121 one of two ways:
 122 .RS +4
 123 .TP
 124 .ie t \(bu
 125 .el o
 126 The \fBinitstate()\fR function can be used, with the desired seed, state array,
 127 and size of the array.
 128 .RE
 129 .RS +4
 130 .TP
 131 .ie t \(bu
 132 .el o
 133 The \fBsetstate()\fR function, with the desired state, can be used, followed by
 134 \fBsrandom()\fR with the desired seed. The advantage of using both of these
 135 functions is that the size of the state array does not have to be saved once it
 136 is initialized.
 137 .RE
 138 .SH EXAMPLES
 139 .LP
 140 \fBExample 1 \fRInitialize an array.
 141 .sp
 142 .LP
 143 The following example demonstrates the use of \fBinitstate()\fR to intialize an
 144 array. It also demonstrates how to initialize an array and pass it to
 145 \fBsetstate()\fR.
 146
 147 .sp
 148 .in +2
 149 .nf
 150 # include <stdlib.h>
 151 static unsigned int state0[32];
 152 static unsigned int state1[32] = {
 153      3,
 154      0x9a319039, 0x32d9c024, 0x9b663182, 0x5da1f342,
 155      0x7449e56b, 0xbeb1dbb0, 0xab5c5918, 0x946554fd,
 156      0x8c2e680f, 0xeb3d799f, 0xb11ee0b7, 0x2d436b86,
 157      0xda672e2a, 0x1588ca88, 0xe369735d, 0x904f35f7,
 158      0xd7158fd6, 0x6fa6f051, 0x616e6b96, 0xac94efdc,
 159      0xde3b81e0, 0xdf0a6fb5, 0xf103bc02, 0x48f340fb,
 160      0x36413f93, 0xc622c298, 0xf5a42ab8, 0x8a88d77b,
 161      0xf5ad9d0e, 0x8999220b, 0x27fb47b9
 162      };
 163 main() {
 164      unsigned seed;
 165      int n;
 166      seed = 1;
 167      n = 128;
 168      (void)initstate(seed, (char *)state0, n);
 169      printf("random() = %d0\en", random());
 170      (void)setstate((char *)state1);
 171      printf("random() = %d0\en", random());
 172 }
 173 .fi
 174 .in -2
 175
 176 .SH ATTRIBUTES
 177 .LP
 178 See \fBattributes\fR(5) for descriptions of the following attributes:
 179 .sp
 180
 181 .sp
 182 .TS
 183 box;
 184 c | c
 185 l | l .
 186 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 187 _
 188 Interface Stability     Standard
 189 _
 190 MT-Level        See \fBNOTES\fR below.
 191 .TE
 192
 193 .SH SEE ALSO
 194 .LP
 195 \fBarc4random\fR(3C), \fBdrand48\fR(3C), \fBrand\fR(3C), \fBattributes\fR(5),
 196 \fBstandards\fR(5)
 197 .SH NOTES
 198 .LP
 199 The \fBrandom()\fR and \fBsrandom()\fR functions are unsafe in multithreaded
 200 applications.
 201 .sp
 202 .LP
 203 Use of these functions in multithreaded applications is unsupported.
 204 .sp
 205 .LP
 206 For \fBinitstate()\fR and \fBsetstate()\fR, the \fIstate\fR argument must be
 207 aligned on an \fBint\fR boundary.
 208 .sp
 209 .LP
 210 \fBarc4random\fR(3C) is a newer and better performing random number generator.
 211 Use it instead.