summaryrefslogtreecommitdiffstats
path: root/man3/drand48.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/drand48.3263
1 files changed, 263 insertions, 0 deletions
diff --git a/man3/drand48.3 b/man3/drand48.3
new file mode 100644
index 0000000..b768d0d
--- /dev/null
+++ b/man3/drand48.3
@@ -0,0 +1,263 @@
+'\" t
+.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" References consulted:
+.\" Linux libc source code
+.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
+.\" 386BSD man pages
+.\" Modified Sat Jul 24 19:46:03 1993 by Rik Faith (faith@cs.unc.edu)
+.TH drand48 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48,
+lcong48 \- generate uniformly distributed pseudo-random numbers
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.PP
+.B double drand48(void);
+.BI "double erand48(unsigned short " xsubi [3]);
+.PP
+.B long lrand48(void);
+.BI "long nrand48(unsigned short " xsubi [3]);
+.PP
+.B long mrand48(void);
+.BI "long jrand48(unsigned short " xsubi [3]);
+.PP
+.BI "void srand48(long " seedval );
+.BI "unsigned short *seed48(unsigned short " seed16v [3]);
+.BI "void lcong48(unsigned short " param [7]);
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+All functions shown above:
+.\" .BR drand48 (),
+.\" .BR erand48 (),
+.\" .BR lrand48 (),
+.\" .BR nrand48 (),
+.\" .BR mrand48 (),
+.\" .BR jrand48 (),
+.\" .BR srand48 (),
+.\" .BR seed48 (),
+.\" .BR lcong48 ():
+.nf
+ _XOPEN_SOURCE
+ || /* glibc >= 2.19: */ _DEFAULT_SOURCE
+ || /* glibc <= 2.19: */ _SVID_SOURCE
+.fi
+.SH DESCRIPTION
+These functions generate pseudo-random numbers using the linear congruential
+algorithm and 48-bit integer arithmetic.
+.PP
+The
+.BR drand48 ()
+and
+.BR erand48 ()
+functions return nonnegative
+double-precision floating-point values uniformly distributed over the interval
+[0.0,\ 1.0).
+.PP
+The
+.BR lrand48 ()
+and
+.BR nrand48 ()
+functions return nonnegative
+long integers uniformly distributed over the interval [0,\ 2\[ha]31).
+.PP
+The
+.BR mrand48 ()
+and
+.BR jrand48 ()
+functions return signed long
+integers uniformly distributed over the interval [\-2\[ha]31,\ 2\[ha]31).
+.PP
+The
+.BR srand48 (),
+.BR seed48 (),
+and
+.BR lcong48 ()
+functions are
+initialization functions, one of which should be called before using
+.BR drand48 (),
+.BR lrand48 (),
+or
+.BR mrand48 ().
+The functions
+.BR erand48 (),
+.BR nrand48 (),
+and
+.BR jrand48 ()
+do not require
+an initialization function to be called first.
+.PP
+All the functions work by generating a sequence of 48-bit integers,
+.IR Xi ,
+according to the linear congruential formula:
+.PP
+.in +4n
+.EX
+.B Xn+1 = (aXn + c) mod m, where n >= 0
+.EE
+.in
+.PP
+The parameter
+.I m
+= 2\[ha]48, hence 48-bit integer arithmetic is performed.
+Unless
+.BR lcong48 ()
+is called,
+.I a
+and
+.I c
+are given by:
+.PP
+.in +4n
+.EX
+.B a = 0x5DEECE66D
+.B c = 0xB
+.EE
+.in
+.PP
+The value returned by any of the functions
+.BR drand48 (),
+.BR erand48 (),
+.BR lrand48 (),
+.BR nrand48 (),
+.BR mrand48 (),
+or
+.BR jrand48 ()
+is
+computed by first generating the next 48-bit
+.I Xi
+in the sequence.
+Then the appropriate number of bits, according to the type of data item to
+be returned, is copied from the high-order bits of
+.I Xi
+and transformed
+into the returned value.
+.PP
+The functions
+.BR drand48 (),
+.BR lrand48 (),
+and
+.BR mrand48 ()
+store
+the last 48-bit
+.I Xi
+generated in an internal buffer.
+The functions
+.BR erand48 (),
+.BR nrand48 (),
+and
+.BR jrand48 ()
+require the calling
+program to provide storage for the successive
+.I Xi
+values in the array
+argument
+.IR xsubi .
+The functions are initialized by placing the initial
+value of
+.I Xi
+into the array before calling the function for the first
+time.
+.PP
+The initializer function
+.BR srand48 ()
+sets the high order 32-bits of
+.I Xi
+to the argument
+.IR seedval .
+The low order 16-bits are set
+to the arbitrary value 0x330E.
+.PP
+The initializer function
+.BR seed48 ()
+sets the value of
+.I Xi
+to
+the 48-bit value specified in the array argument
+.IR seed16v .
+The
+previous value of
+.I Xi
+is copied into an internal buffer and a
+pointer to this buffer is returned by
+.BR seed48 ().
+.PP
+The initialization function
+.BR lcong48 ()
+allows the user to specify
+initial values for
+.IR Xi ,
+.IR a ,
+and
+.IR c .
+Array argument
+elements
+.I param[0\-2]
+specify
+.IR Xi ,
+.I param[3\-5]
+specify
+.IR a ,
+and
+.I param[6]
+specifies
+.IR c .
+After
+.BR lcong48 ()
+has been called, a subsequent call to either
+.BR srand48 ()
+or
+.BR seed48 ()
+will restore the standard values of
+.I a
+and
+.IR c .
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR drand48 (),
+.BR erand48 (),
+.BR lrand48 (),
+.BR nrand48 (),
+.BR mrand48 (),
+.BR jrand48 (),
+.BR srand48 (),
+.BR seed48 (),
+.BR lcong48 ()
+T} Thread safety T{
+.na
+.nh
+MT-Unsafe race:drand48
+T}
+.TE
+.sp 1
+.PP
+The above
+functions record global state information for the random number generator,
+so they are not thread-safe.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4.
+.SH SEE ALSO
+.BR rand (3),
+.BR random (3)