man3/random_r.3

   1 .\" Copyright 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\"
   6 .TH random_r 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 random_r, srandom_r, initstate_r, setstate_r \- reentrant
   9 random number generator
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <stdlib.h>
  16 .PP
  17 .BI "int random_r(struct random_data *restrict " buf ,
  18 .BI "             int32_t *restrict " result );
  19 .BI "int srandom_r(unsigned int " seed ", struct random_data *" buf );
  20 .PP
  21 .BI "int initstate_r(unsigned int " seed ", char *restrict " statebuf ,
  22 .BI "             size_t " statelen ", struct random_data *restrict " buf );
  23 .BI "int setstate_r(char *restrict " statebuf ,
  24 .BI "             struct random_data *restrict " buf );
  25 .fi
  26 .PP
  27 .RS -4
  28 Feature Test Macro Requirements for glibc (see
  29 .BR feature_test_macros (7)):
  30 .RE
  31 .PP
  32 .BR random_r (),
  33 .BR srandom_r (),
  34 .BR initstate_r (),
  35 .BR setstate_r ():
  36 .nf
  37     /* Glibc since 2.19: */ _DEFAULT_SOURCE
  38         || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
  39 .fi
  40 .SH DESCRIPTION
  41 These functions are the reentrant equivalents
  42 of the functions described in
  43 .BR random (3).
  44 They are suitable for use in multithreaded programs where each thread
  45 needs to obtain an independent, reproducible sequence of random numbers.
  46 .PP
  47 The
  48 .BR random_r ()
  49 function is like
  50 .BR random (3),
  51 except that instead of using state information maintained
  52 in a global variable,
  53 it uses the state information in the argument pointed to by
  54 .IR buf ,
  55 which must have been previously initialized by
  56 .BR initstate_r ().
  57 The generated random number is returned in the argument
  58 .IR result .
  59 .PP
  60 The
  61 .BR srandom_r ()
  62 function is like
  63 .BR srandom (3),
  64 except that it initializes the seed for the random number generator
  65 whose state is maintained in the object pointed to by
  66 .IR buf ,
  67 which must have been previously initialized by
  68 .BR initstate_r (),
  69 instead of the seed associated with the global state variable.
  70 .PP
  71 The
  72 .BR initstate_r ()
  73 function is like
  74 .BR initstate (3)
  75 except that it initializes the state in the object pointed to by
  76 .IR buf ,
  77 rather than initializing the global state variable.
  78 Before calling this function, the
  79 .I buf.state
  80 field must be initialized to NULL.
  81 The
  82 .BR initstate_r ()
  83 function records a pointer to the
  84 .I statebuf
  85 argument inside the structure pointed to by
  86 .IR buf .
  87 Thus,
  88 .I statebuf
  89 should not be deallocated so long as
  90 .I buf
  91 is still in use.
  92 (So,
  93 .I statebuf
  94 should typically be allocated as a static variable,
  95 or allocated on the heap using
  96 .BR malloc (3)
  97 or similar.)
  98 .PP
  99 The
 100 .BR setstate_r ()
 101 function is like
 102 .BR setstate (3)
 103 except that it modifies the state in the object pointed to by
 104 .IR buf ,
 105 rather than modifying the global state variable.
 106 \fIstate\fP must first have been initialized
 107 using
 108 .BR initstate_r ()
 109 or be the result of a previous call of
 110 .BR setstate_r ().
 111 .SH RETURN VALUE
 112 All of these functions return 0 on success.
 113 On error, \-1 is returned, with
 114 .I errno
 115 set to indicate the error.
 116 .SH ERRORS
 117 .TP
 118 .B EINVAL
 119 A state array of less than 8 bytes was specified to
 120 .BR initstate_r ().
 121 .TP
 122 .B EINVAL
 123 The
 124 .I statebuf
 125 or
 126 .I buf
 127 argument to
 128 .BR setstate_r ()
 129 was NULL.
 130 .TP
 131 .B EINVAL
 132 The
 133 .I buf
 134 or
 135 .I result
 136 argument to
 137 .BR random_r ()
 138 was NULL.
 139 .SH ATTRIBUTES
 140 For an explanation of the terms used in this section, see
 141 .BR attributes (7).
 142 .ad l
 143 .nh
 144 .TS
 145 allbox;
 146 lbx lb lb
 147 l l l.
 148 Interface       Attribute       Value
 149 T{
 150 .BR random_r (),
 151 .BR srandom_r (),
 152 .BR initstate_r (),
 153 .BR setstate_r ()
 154 T}      Thread safety   MT-Safe race:buf
 155 .TE
 156 .hy
 157 .ad
 158 .sp 1
 159 .SH STANDARDS
 160 These functions are nonstandard glibc extensions.
 161 .\" These functions appear to be on Tru64, but don't seem to be on
 162 .\" Solaris, HP-UX, or FreeBSD.
 163 .SH BUGS
 164 The
 165 .BR initstate_r ()
 166 interface is confusing.
 167 .\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=3662
 168 It appears that the
 169 .I random_data
 170 type is intended to be opaque,
 171 but the implementation requires the user to either initialize the
 172 .I buf.state
 173 field to NULL or zero out the entire structure before the call.
 174 .SH SEE ALSO
 175 .BR drand48 (3),
 176 .BR rand (3),
 177 .BR random (3)