man3/random_r.3

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