diff options
Diffstat (limited to 'upstream/archlinux/man3p/drand48.3p')
| -rw-r--r-- | upstream/archlinux/man3p/drand48.3p | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/drand48.3p b/upstream/archlinux/man3p/drand48.3p new file mode 100644 index 00000000..71579711 --- /dev/null +++ b/upstream/archlinux/man3p/drand48.3p @@ -0,0 +1,244 @@ +'\" et +.TH DRAND48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.EQ +delim $$ +.EN +.SH NAME +drand48, +erand48, +jrand48, +lcong48, +lrand48, +mrand48, +nrand48, +seed48, +srand48 +\(em generate uniformly distributed pseudo-random numbers +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> +.P +double drand48(void); +double erand48(unsigned short \fIxsubi\fP[3]); +long jrand48(unsigned short \fIxsubi\fP[3]); +void lcong48(unsigned short \fIparam\fP[7]); +long lrand48(void); +long mrand48(void); +long nrand48(unsigned short \fIxsubi\fP[3]); +unsigned short *seed48(unsigned short \fIseed16v\fP[3]); +void srand48(long \fIseedval\fP); +.fi +.SH DESCRIPTION +This family of functions shall generate pseudo-random numbers using +a linear congruential algorithm and 48-bit integer arithmetic. +.P +The +\fIdrand48\fR() +and +\fIerand48\fR() +functions shall return non-negative, double-precision, floating-point +values, uniformly distributed over the interval [0.0,1.0). +.P +The +\fIlrand48\fR() +and +\fInrand48\fR() +functions shall return non-negative, long integers, uniformly +distributed over the interval [0,2\u\s-331\s+3\d). +.P +The +\fImrand48\fR() +and +\fIjrand48\fR() +functions shall return signed long integers uniformly distributed over +the interval [\-2\u\s-331\s+3\d,2\u\s-331\s+3\d). +.P +The +\fIsrand48\fR(), +\fIseed48\fR(), +and +\fIlcong48\fR() +functions are initialization entry points, one of which should be +invoked before either +\fIdrand48\fR(), +\fIlrand48\fR(), +or +\fImrand48\fR() +is called. (Although it is not recommended practice, constant default +initializer values shall be supplied automatically if +\fIdrand48\fR(), +\fIlrand48\fR(), +or +\fImrand48\fR() +is called without a prior call to an initialization entry point.) The +\fIerand48\fR(), +\fInrand48\fR(), +and +\fIjrand48\fR() +functions do not require an initialization entry point to be called +first. +.P +All the routines work by generating a sequence of 48-bit integer +values, $X_ i" " ,$ according to the linear congruential formula: +.sp +.RS +$X sub{n+1} " " = " " (aX_ n" "^+^c) sub{roman mod " " m} " " " " " " " " " " " " " " " " n>= " " 0$ +.RE +.P +The parameter $m^=^2"^" 48$; hence 48-bit integer arithmetic is +performed. Unless +\fIlcong48\fR() +is invoked, the multiplier value $a$ and the addend value $c$ are given +by: +.sp +.RS +$a " " mark = " " roman "5DEECE66D"^sub 16 " " = " " roman 273673163155^sub 8$ +.P +$c " " lineup = " " roman B^sub 16 " " = " " roman 13^sub 8$ +.RE +.P +The value returned by any of the +\fIdrand48\fR(), +\fIerand48\fR(), +\fIjrand48\fR(), +\fIlrand48\fR(), +\fImrand48\fR(), +or +\fInrand48\fR() +functions is computed by first generating the next 48-bit $X_ i$ in +the sequence. Then the appropriate number of bits, according to the +type of data item to be returned, are copied from the high-order +(leftmost) bits of $X_ i$ and transformed into the returned value. +.P +The +\fIdrand48\fR(), +\fIlrand48\fR(), +and +\fImrand48\fR() +functions store the last 48-bit $X_ i$ generated in an internal +buffer; that is why the application shall ensure that these are +initialized prior to being invoked. The +\fIerand48\fR(), +\fInrand48\fR(), +and +\fIjrand48\fR() +functions require the calling program to provide storage for the +successive $X_ i$ values in the array specified as an argument when +the functions are invoked. That is why these routines do not have to +be initialized; the calling program merely has to place the desired +initial value of $X_ i$ into the array and pass it as an argument. +By using different arguments, +\fIerand48\fR(), +\fInrand48\fR(), +and +\fIjrand48\fR() +allow separate modules of a large program to generate several +.IR independent +streams of pseudo-random numbers; that is, the sequence of numbers in +each stream shall +.IR not +depend upon how many times the routines are called to generate numbers +for the other streams. +.P +The initializer function +\fIsrand48\fR() +sets the high-order 32 bits of $X_ i$ to the low-order 32 bits +contained in its argument. The low-order 16 bits of $X_ i$ are set +to the arbitrary value $roman 330E_ 16" " .$ +.P +The initializer function +\fIseed48\fR() +sets the value of $X_ i$ to the 48-bit value specified in the +argument array. The low-order 16 bits of $X_ i$ are set to the +low-order 16 bits of +.IR seed16v [ 0 ]. +The mid-order 16 bits of $X_ i$ are set to the low-order 16 bits of +.IR seed16v [ 1 ]. +The high-order 16 bits of $X_ i$ are set to the low-order 16 bits of +.IR seed16v [ 2 ]. +In addition, the previous value of $X_ i$ is copied into a 48-bit +internal buffer, used only by +\fIseed48\fR(), +and a pointer to this buffer is the value returned by +\fIseed48\fR(). +This returned pointer, which can just be ignored if not needed, is +useful if a program is to be restarted from a given point at some +future time\(emuse the pointer to get at and store the last $X_ i$ +value, and then use this value to reinitialize via +\fIseed48\fR() +when the program is restarted. +.P +The initializer function +\fIlcong48\fR() +allows the user to specify the initial $X_ i" " ,$ the multiplier value +$a,$ and the addend value $c.$ Argument array elements +.IR param [ 0-2 ] +specify $X_ i" " ,$ +.IR param [ 3-5 ] +specify the multiplier $a,$ and +.IR param [ 6 ] +specifies the 16-bit addend $c.$ After +\fIlcong48\fR() +is called, a subsequent call to either +\fIsrand48\fR() +or +\fIseed48\fR() +shall restore the standard multiplier and addend values, +.IR a +and +.IR c, +specified above. +.P +The +\fIdrand48\fR(), +\fIlrand48\fR(), +and +\fImrand48\fR() +functions need not be thread-safe. +.SH "RETURN VALUE" +As described in the DESCRIPTION above. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions should be avoided whenever non-trivial +requirements (including safety) have to be fulfilled. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIinitstate\fR\^(\|)", +.IR "\fIrand\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<stdlib.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |