1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>skalibs: the random library interface</title
<meta name="Description" content="skalibs: the random library interface" />
<meta name="Keywords" content="skalibs library random librandom random.h" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="../libskarnet.html">libskarnet</a><br />
<a href="../index.html">skalibs</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>random</tt> library interface </h1>
<p>
<tt>librandom</tt> is a small library designed to provide an
interface to some reasonable-quality pseudorandom number
generation. <tt>librandom</tt> uses arc4random when available,
or getrandom - else it defaults to <tt>/dev/urandom</tt> and a
a SURF PRNG.
</p>
<h2> Compiling </h2>
<ul>
<li> Use <tt>#include <skalibs/random.h></tt> </li>
</ul>
<h2> Programming </h2>
<p>
You should refer to the <tt>skalibs/random.h</tt> header for the exact
function prototypes.
</p>
<h3> Basic functions </h3>
<pre>
unsigned char c ;
uint32_t max ;
uint32_t n ;
size_t b ;
char data[at least b] ;
int r ;
r = random_init() ;
c = random_char() ;
n = random_uint32(max) ;
random_string(data, b) ;
random_finish() ;
</pre>
<p>
<tt>random_init()</tt> must be called before any other function in
the random library. It returns 0 (and sets errno) on failure, and
nonzero on success.
</p>
<p>
It is recommended that you let the library perform cleanups after you
are done using it, by calling <tt>random_finish()</tt> - unless your
process exits right away.
</p>
<ul>
<li> <tt>random_char()</tt> returns a random character. </li>
<li> <tt>random_uint32(<em>max</em>)</tt> returns a random integer
between 0 and <em>max</em>-1. </li>
<li> <tt>random_string(<em>data</em>, <em>b</em>)</tt> fills
<em>b</em> bytes in <em>data</em> (which must be preallocated)
with random data. </li>
</ul>
<h3> Advanced functions </h3>
<p>
<code> void random_unsort (char *s, unsigned int n, unsigned int chunksize) </code> <br />
Shuffles the array <em>s</em> (of size at least <em>n</em>*<em>chunksize</em>) by
performing a random permutation of the <em>n</em> blocks of <em>chunksize</em> bytes.
Bytes are not permuted inside chunks.
</p>
<p>
<code> void random_name (char *s, size_t n) </code> <br />
Writes <em>n</em> random readable ASCII characters into <em>s</em>:
letters, numbers, hyphens or underscores. Does not terminate with a
null character.
</p>
<p>
<code> int random_sauniquename (stralloc *sa, unsigned int n) </code> <br />
Appends a (non-null-terminated) unique, unpredictable ASCII name to the
<a href="../libstddjb/stralloc.html">stralloc</a> <em>*sa</em>. That
name includes <em>n</em> randomly generated ASCII characters.
</p>
<h2> Notes </h2>
<ul>
<li> The <tt>random</tt> library is a thin wrapper around the best
available random generator provided by the underlying system. By
decreasing order of preference, it will use the following
implementations if available:
<ul>
<li> <a href="https://man.openbsd.org/arc4random.3">arc4random()</a> </li>
<li> <a href="https://man7.org/linux/man-pages/man2/getrandom.2.html">getrandom()</a> </li>
<li> <tt>/dev/urandom</tt> </li>
<li> a basic <a href="https://cr.yp.to/papers/surf.pdf">SURF</a> pseudo-random generator</li>
</ul> </li>
<li> The <tt>random_init()</tt> function tries to automatically add some
reasonably random data to the underlying random generator's entropy pool.
However, that pseudorandom data is not 100% unpredictable, so it will not
replace proper seeding of the random generator at boot time. </li>
</ul>
</body>
</html>
|
