man3/random_r.3

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