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

   1 '\" te
   2 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH DRAND48 3C "Feb 11, 2015"
   8 .SH NAME
   9 drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48
  10 \- generate uniformly distributed pseudo-random numbers
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <stdlib.h>
  15
  16 \fBdouble\fR \fBdrand48\fR(void)
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBdouble\fR \fBerand48\fR(\fBunsigned short\fR \fIx\fR(i)[3]);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBlong\fR \fBlrand48\fR(void)
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBlong\fR \fBnrand48\fR(\fBunsigned short\fR \fIx\fR(i)[3]);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBlong\fR \fBmrand48\fR(void)
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBlong\fR \fBjrand48\fR(\fBunsigned short\fR \fIx\fR(i)[3]);
  42 .fi
  43
  44 .LP
  45 .nf
  46 \fBvoid\fR \fBsrand48\fR(\fBlong\fR \fIseedval\fR);
  47 .fi
  48
  49 .LP
  50 .nf
  51 \fBunsigned short *\fR\fBseed48\fR(\fBunsigned short\fR \fIseed16v\fR[3]);
  52 .fi
  53
  54 .LP
  55 .nf
  56 \fBvoid\fR \fBlcong48\fR(\fBunsigned short\fR \fIparam\fR[7]);
  57 .fi
  58
  59 .SH DESCRIPTION
  60 .LP
  61 This family of functions generates pseudo-random numbers using the well-known
  62 linear congruential algorithm and 48-bit integer arithmetic.
  63 .sp
  64 .LP
  65 Functions \fBdrand48()\fR and \fBerand48()\fR return non-negative
  66 double-precision floating-point values uniformly distributed over the interval
  67 [0.0, 1.0).
  68 .sp
  69 .LP
  70 Functions \fBlrand48()\fR and \fBnrand48()\fR return non-negative long integers
  71 uniformly distributed over the interval [0, 2  ^31 ].
  72 .sp
  73 .LP
  74 Functions \fBmrand48()\fR and \fBjrand48()\fR return signed long integers
  75 uniformly distributed over the interval [-2 ^31  , 2 ^31  ].
  76 .sp
  77 .LP
  78 Functions \fBsrand48()\fR, \fBseed48()\fR, and \fBlcong48()\fR are
  79 initialization entry points, one of which should be invoked before either
  80 \fBdrand48()\fR, \fBlrand48()\fR, or \fBmrand48()\fR is called. (Although it is
  81 not recommended practice, constant default initializer values will be supplied
  82 automatically if \fBdrand48()\fR, \fBlrand48()\fR, or \fBmrand48()\fR is called
  83 without a prior call to an initialization entry point.) Functions
  84 \fBerand48(\|),\fR \fBnrand48(\|),\fR and \fBjrand48()\fR do not require an
  85 initialization entry point to be called first.
  86 .sp
  87 .LP
  88 All the routines work by generating a sequence of 48-bit integer values, X(i ),
  89 according to the linear congruential formula
  90 .sp
  91 .LP
  92 X(n+1)= (aX (n)+c)(mod m) n>=0.
  93 .sp
  94 .LP
  95 The parameter \fIm\fR = 2^48; hence 48-bit integer arithmetic is performed.
  96 Unless \fBlcong48()\fR has been invoked, the multiplier value \fIa\fRand the
  97 addend value \fIc\fRare given by
  98 .br
  99 .in +2
 100 \fIa\fR = 5DEECE66D(16) = 273673163155(8)
 101 .in -2
 102 .br
 103 .in +2
 104 \fIc\fR = B(16) = 13(8)
 105 .in -2
 106 .sp
 107 .LP
 108 The value returned by any of the functions \fBdrand48()\fR, \fBerand48()\fR,
 109 \fBlrand48()\fR, \fBnrand48()\fR, \fBmrand48()\fR, or \fBjrand48()\fR is
 110 computed by first generating the next 48-bit X(i) in the sequence. Then the
 111 appropriate number of bits, according to the type of data item to be returned,
 112 are copied from the high-order (leftmost) bits of X(i) and transformed into the
 113 returned value.
 114 .sp
 115 .LP
 116 The functions \fBdrand48()\fR, \fBlrand48()\fR, and \fBmrand48()\fR store the
 117 last 48-bit X(i) generated in an internal buffer. X(i) must be initialized
 118 prior to being invoked. The functions \fBerand48()\fR, \fBnrand48()\fR, and
 119 \fBjrand48()\fR require the calling program to provide storage for the
 120 successive X(i) values in the array specified as an argument when the functions
 121 are invoked. These routines do not have to be initialized; the calling program
 122 must place the desired initial value of X(i) into the array and pass it as an
 123 argument. By using different arguments, functions \fBerand48()\fR,
 124 \fBnrand48()\fR, and \fBjrand48()\fR allow separate modules of a large program
 125 to generate several \fIindependent\fR streams of pseudo-random numbers, that
 126 is, the sequence of numbers in each stream will \fInot\fR depend upon how many
 127 times the routines have been called to generate numbers for the other streams.
 128 .sp
 129 .LP
 130 The initializer function \fBsrand48()\fR sets the high-order 32 bits of X(i) to
 131 the 32 bits contained in its argument. The low-order 16 bits of X(i) are set to
 132 the arbitrary value 330E(16) .
 133 .sp
 134 .LP
 135 The initializer function \fBseed48()\fR sets the value of X(i) to the 48-bit
 136 value specified in the argument array. In addition, the previous value of X(i)
 137 is copied into a 48-bit internal buffer, used only by \fBseed48()\fR, and a
 138 pointer to this buffer is the value returned by \fBseed48()\fR. This returned
 139 pointer, which can just be ignored if not needed, is useful if a program is to
 140 be restarted from a given point at some future time \(em use the pointer to get
 141 at and store the last X(i) value, and then use this value to reinitialize using
 142 \fBseed48()\fR when the program is restarted.
 143 .sp
 144 .LP
 145 The initialization function \fBlcong48()\fR allows the user to specify the
 146 initial X(i) the multiplier value \fIa\fR, and the addend value \fIc\fR.
 147 Argument array elements \fIparam[0-2]\fR specify X(i), \fIparam[3-5]\fR specify
 148 the multiplier \fIa\fR, and \fIparam\fR[6] specifies the 16-bit addend \fIc\fR.
 149 After \fBlcong48()\fR has been called, a subsequent call to either
 150 \fBsrand48()\fR or \fBseed48()\fR will restore the ``standard'' multiplier and
 151 addend values, \fIa\fR and \fIc\fR, specified above.
 152 .sp
 153 .LP
 154 For a more powerful random number generator, see \fBarc4random\fR(3C).
 155 .SH ATTRIBUTES
 156 .LP
 157 See \fBattributes\fR(5) for descriptions of the following attributes:
 158 .sp
 159
 160 .sp
 161 .TS
 162 box;
 163 c | c
 164 l | l .
 165 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 166 _
 167 Interface Stability     Standard
 168 _
 169 MT-Level        Safe
 170 .TE
 171
 172 .SH SEE ALSO
 173 .LP
 174 \fBarc4random\fR(3C), \fBrand\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)