forked from diesel-rs/diesel
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathlib.rs.html
More file actions
537 lines (530 loc) · 39.3 KB
/
Copy pathlib.rs.html
File metadata and controls
537 lines (530 loc) · 39.3 KB
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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Source of the Rust file `/home/runner/.cargo/registry/src/github.com-1ecc6299db9ec823/getrandom-0.2.7/src/lib.rs`."><meta name="keywords" content="rust, rustlang, rust-lang"><title>lib.rs - source</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" type="text/css" href="../../normalize.css"><link rel="stylesheet" type="text/css" href="../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../ayu.css" disabled><link rel="stylesheet" type="text/css" href="../../dark.css" disabled><link rel="stylesheet" type="text/css" href="../../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../../storage.js"></script><script defer src="../../source-script.js"></script><script defer src="../../source-files.js"></script><script defer src="../../main.js"></script><noscript><link rel="stylesheet" href="../../noscript.css"></noscript><link rel="icon" href="https://www.rust-lang.org/favicon.ico"></head><body class="rustdoc source"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">☰</button><a class="sidebar-logo" href="../../getrandom/index.html"><div class="logo-container"><img src="https://www.rust-lang.org/logos/rust-logo-128x128-blk.png" alt="logo"></div>
</a><h2 class="location"></h2>
</nav>
<nav class="sidebar"><a class="sidebar-logo" href="../../getrandom/index.html"><div class="logo-container">
<img src="https://www.rust-lang.org/logos/rust-logo-128x128-blk.png" alt="logo"></div>
</a></nav><main><div class="width-limiter"><div class="sub-container"><a class="sub-logo-container" href="../../getrandom/index.html">
<img src="https://www.rust-lang.org/logos/rust-logo-128x128-blk.png" alt="logo"></a><nav class="sub"><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><button type="button">?</button></div><div id="settings-menu" tabindex="-1">
<a href="../../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../../wheel.svg"></a></div>
</div></form></nav></div><section id="main-content" class="content"><div class="example-wrap"><pre class="line-numbers"><span id="1">1</span>
<span id="2">2</span>
<span id="3">3</span>
<span id="4">4</span>
<span id="5">5</span>
<span id="6">6</span>
<span id="7">7</span>
<span id="8">8</span>
<span id="9">9</span>
<span id="10">10</span>
<span id="11">11</span>
<span id="12">12</span>
<span id="13">13</span>
<span id="14">14</span>
<span id="15">15</span>
<span id="16">16</span>
<span id="17">17</span>
<span id="18">18</span>
<span id="19">19</span>
<span id="20">20</span>
<span id="21">21</span>
<span id="22">22</span>
<span id="23">23</span>
<span id="24">24</span>
<span id="25">25</span>
<span id="26">26</span>
<span id="27">27</span>
<span id="28">28</span>
<span id="29">29</span>
<span id="30">30</span>
<span id="31">31</span>
<span id="32">32</span>
<span id="33">33</span>
<span id="34">34</span>
<span id="35">35</span>
<span id="36">36</span>
<span id="37">37</span>
<span id="38">38</span>
<span id="39">39</span>
<span id="40">40</span>
<span id="41">41</span>
<span id="42">42</span>
<span id="43">43</span>
<span id="44">44</span>
<span id="45">45</span>
<span id="46">46</span>
<span id="47">47</span>
<span id="48">48</span>
<span id="49">49</span>
<span id="50">50</span>
<span id="51">51</span>
<span id="52">52</span>
<span id="53">53</span>
<span id="54">54</span>
<span id="55">55</span>
<span id="56">56</span>
<span id="57">57</span>
<span id="58">58</span>
<span id="59">59</span>
<span id="60">60</span>
<span id="61">61</span>
<span id="62">62</span>
<span id="63">63</span>
<span id="64">64</span>
<span id="65">65</span>
<span id="66">66</span>
<span id="67">67</span>
<span id="68">68</span>
<span id="69">69</span>
<span id="70">70</span>
<span id="71">71</span>
<span id="72">72</span>
<span id="73">73</span>
<span id="74">74</span>
<span id="75">75</span>
<span id="76">76</span>
<span id="77">77</span>
<span id="78">78</span>
<span id="79">79</span>
<span id="80">80</span>
<span id="81">81</span>
<span id="82">82</span>
<span id="83">83</span>
<span id="84">84</span>
<span id="85">85</span>
<span id="86">86</span>
<span id="87">87</span>
<span id="88">88</span>
<span id="89">89</span>
<span id="90">90</span>
<span id="91">91</span>
<span id="92">92</span>
<span id="93">93</span>
<span id="94">94</span>
<span id="95">95</span>
<span id="96">96</span>
<span id="97">97</span>
<span id="98">98</span>
<span id="99">99</span>
<span id="100">100</span>
<span id="101">101</span>
<span id="102">102</span>
<span id="103">103</span>
<span id="104">104</span>
<span id="105">105</span>
<span id="106">106</span>
<span id="107">107</span>
<span id="108">108</span>
<span id="109">109</span>
<span id="110">110</span>
<span id="111">111</span>
<span id="112">112</span>
<span id="113">113</span>
<span id="114">114</span>
<span id="115">115</span>
<span id="116">116</span>
<span id="117">117</span>
<span id="118">118</span>
<span id="119">119</span>
<span id="120">120</span>
<span id="121">121</span>
<span id="122">122</span>
<span id="123">123</span>
<span id="124">124</span>
<span id="125">125</span>
<span id="126">126</span>
<span id="127">127</span>
<span id="128">128</span>
<span id="129">129</span>
<span id="130">130</span>
<span id="131">131</span>
<span id="132">132</span>
<span id="133">133</span>
<span id="134">134</span>
<span id="135">135</span>
<span id="136">136</span>
<span id="137">137</span>
<span id="138">138</span>
<span id="139">139</span>
<span id="140">140</span>
<span id="141">141</span>
<span id="142">142</span>
<span id="143">143</span>
<span id="144">144</span>
<span id="145">145</span>
<span id="146">146</span>
<span id="147">147</span>
<span id="148">148</span>
<span id="149">149</span>
<span id="150">150</span>
<span id="151">151</span>
<span id="152">152</span>
<span id="153">153</span>
<span id="154">154</span>
<span id="155">155</span>
<span id="156">156</span>
<span id="157">157</span>
<span id="158">158</span>
<span id="159">159</span>
<span id="160">160</span>
<span id="161">161</span>
<span id="162">162</span>
<span id="163">163</span>
<span id="164">164</span>
<span id="165">165</span>
<span id="166">166</span>
<span id="167">167</span>
<span id="168">168</span>
<span id="169">169</span>
<span id="170">170</span>
<span id="171">171</span>
<span id="172">172</span>
<span id="173">173</span>
<span id="174">174</span>
<span id="175">175</span>
<span id="176">176</span>
<span id="177">177</span>
<span id="178">178</span>
<span id="179">179</span>
<span id="180">180</span>
<span id="181">181</span>
<span id="182">182</span>
<span id="183">183</span>
<span id="184">184</span>
<span id="185">185</span>
<span id="186">186</span>
<span id="187">187</span>
<span id="188">188</span>
<span id="189">189</span>
<span id="190">190</span>
<span id="191">191</span>
<span id="192">192</span>
<span id="193">193</span>
<span id="194">194</span>
<span id="195">195</span>
<span id="196">196</span>
<span id="197">197</span>
<span id="198">198</span>
<span id="199">199</span>
<span id="200">200</span>
<span id="201">201</span>
<span id="202">202</span>
<span id="203">203</span>
<span id="204">204</span>
<span id="205">205</span>
<span id="206">206</span>
<span id="207">207</span>
<span id="208">208</span>
<span id="209">209</span>
<span id="210">210</span>
<span id="211">211</span>
<span id="212">212</span>
<span id="213">213</span>
<span id="214">214</span>
<span id="215">215</span>
<span id="216">216</span>
<span id="217">217</span>
<span id="218">218</span>
<span id="219">219</span>
<span id="220">220</span>
<span id="221">221</span>
<span id="222">222</span>
<span id="223">223</span>
<span id="224">224</span>
<span id="225">225</span>
<span id="226">226</span>
<span id="227">227</span>
<span id="228">228</span>
<span id="229">229</span>
<span id="230">230</span>
<span id="231">231</span>
<span id="232">232</span>
<span id="233">233</span>
<span id="234">234</span>
<span id="235">235</span>
<span id="236">236</span>
<span id="237">237</span>
<span id="238">238</span>
<span id="239">239</span>
<span id="240">240</span>
<span id="241">241</span>
<span id="242">242</span>
<span id="243">243</span>
<span id="244">244</span>
<span id="245">245</span>
<span id="246">246</span>
<span id="247">247</span>
<span id="248">248</span>
<span id="249">249</span>
<span id="250">250</span>
<span id="251">251</span>
<span id="252">252</span>
<span id="253">253</span>
<span id="254">254</span>
<span id="255">255</span>
<span id="256">256</span>
<span id="257">257</span>
<span id="258">258</span>
<span id="259">259</span>
<span id="260">260</span>
<span id="261">261</span>
<span id="262">262</span>
<span id="263">263</span>
</pre><pre class="rust"><code><span class="comment">// Copyright 2019 Developers of the Rand project.</span>
<span class="comment">//</span>
<span class="comment">// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or</span>
<span class="comment">// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license</span>
<span class="comment">// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your</span>
<span class="comment">// option. This file may not be copied, modified, or distributed</span>
<span class="comment">// except according to those terms.</span>
<span class="doccomment">//! Interface to the operating system's random number generator.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! # Supported targets</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! | Target | Target Triple | Implementation</span>
<span class="doccomment">//! | ----------------- | ------------------ | --------------</span>
<span class="doccomment">//! | Linux, Android | `*‑linux‑*` | [`getrandom`][1] system call if available, otherwise [`/dev/urandom`][2] after successfully polling `/dev/random`</span>
<span class="doccomment">//! | Windows | `*‑windows‑*` | [`BCryptGenRandom`]</span>
<span class="doccomment">//! | macOS | `*‑apple‑darwin` | [`getentropy`][3] if available, otherwise [`/dev/random`][4] (identical to `/dev/urandom`)</span>
<span class="doccomment">//! | iOS | `*‑apple‑ios` | [`SecRandomCopyBytes`]</span>
<span class="doccomment">//! | FreeBSD | `*‑freebsd` | [`getrandom`][5] if available, otherwise [`kern.arandom`][6]</span>
<span class="doccomment">//! | OpenBSD | `*‑openbsd` | [`getentropy`][7]</span>
<span class="doccomment">//! | NetBSD | `*‑netbsd` | [`kern.arandom`][8]</span>
<span class="doccomment">//! | Dragonfly BSD | `*‑dragonfly` | [`getrandom`][9] if available, otherwise [`/dev/random`][10]</span>
<span class="doccomment">//! | Solaris, illumos | `*‑solaris`, `*‑illumos` | [`getrandom`][11] if available, otherwise [`/dev/random`][12]</span>
<span class="doccomment">//! | Fuchsia OS | `*‑fuchsia` | [`cprng_draw`]</span>
<span class="doccomment">//! | Redox | `*‑redox` | `/dev/urandom`</span>
<span class="doccomment">//! | Haiku | `*‑haiku` | `/dev/random` (identical to `/dev/urandom`)</span>
<span class="doccomment">//! | Hermit | `x86_64-*-hermit` | [`RDRAND`]</span>
<span class="doccomment">//! | SGX | `x86_64‑*‑sgx` | [`RDRAND`]</span>
<span class="doccomment">//! | VxWorks | `*‑wrs‑vxworks‑*` | `randABytes` after checking entropy pool initialization with `randSecure`</span>
<span class="doccomment">//! | ESP-IDF | `*‑espidf` | [`esp_fill_random`]</span>
<span class="doccomment">//! | Emscripten | `*‑emscripten` | `/dev/random` (identical to `/dev/urandom`)</span>
<span class="doccomment">//! | WASI | `wasm32‑wasi` | [`random_get`]</span>
<span class="doccomment">//! | Web Browser | `wasm32‑*‑unknown` | [`Crypto.getRandomValues`], see [WebAssembly support]</span>
<span class="doccomment">//! | Node.js | `wasm32‑*‑unknown` | [`crypto.randomBytes`], see [WebAssembly support]</span>
<span class="doccomment">//! | SOLID | `*-kmc-solid_*` | `SOLID_RNG_SampleRandomBytes`</span>
<span class="doccomment">//! | Nintendo 3DS | `armv6k-nintendo-3ds` | [`getrandom`][1]</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! There is no blanket implementation on `unix` targets that reads from</span>
<span class="doccomment">//! `/dev/urandom`. This ensures all supported targets are using the recommended</span>
<span class="doccomment">//! interface and respect maximum buffer sizes.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! Pull Requests that add support for new targets to `getrandom` are always welcome.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! ## Unsupported targets</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! By default, `getrandom` will not compile on unsupported targets, but certain</span>
<span class="doccomment">//! features allow a user to select a "fallback" implementation if no supported</span>
<span class="doccomment">//! implementation exists.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! All of the below mechanisms only affect unsupported</span>
<span class="doccomment">//! targets. Supported targets will _always_ use their supported implementations.</span>
<span class="doccomment">//! This prevents a crate from overriding a secure source of randomness</span>
<span class="doccomment">//! (either accidentally or intentionally).</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! ### RDRAND on x86</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! *If the `rdrand` Cargo feature is enabled*, `getrandom` will fallback to using</span>
<span class="doccomment">//! the [`RDRAND`] instruction to get randomness on `no_std` `x86`/`x86_64`</span>
<span class="doccomment">//! targets. This feature has no effect on other CPU architectures.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! ### WebAssembly support</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! This crate fully supports the</span>
<span class="doccomment">//! [`wasm32-wasi`](https://github.com/CraneStation/wasi) and</span>
<span class="doccomment">//! [`wasm32-unknown-emscripten`](https://www.hellorust.com/setup/emscripten/)</span>
<span class="doccomment">//! targets. However, the `wasm32-unknown-unknown` target (i.e. the target used</span>
<span class="doccomment">//! by `wasm-pack`) is not automatically</span>
<span class="doccomment">//! supported since, from the target name alone, we cannot deduce which</span>
<span class="doccomment">//! JavaScript interface is in use (or if JavaScript is available at all).</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! Instead, *if the `js` Cargo feature is enabled*, this crate will assume</span>
<span class="doccomment">//! that you are building for an environment containing JavaScript, and will</span>
<span class="doccomment">//! call the appropriate methods. Both web browser (main window and Web Workers)</span>
<span class="doccomment">//! and Node.js environments are supported, invoking the methods</span>
<span class="doccomment">//! [described above](#supported-targets) using the</span>
<span class="doccomment">//! [wasm-bindgen](https://github.com/rust-lang/rust-bindgen) toolchain.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! This feature has no effect on targets other than `wasm32-unknown-unknown`.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! ### Custom implementations</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! The [`register_custom_getrandom!`] macro allows a user to mark their own</span>
<span class="doccomment">//! function as the backing implementation for [`getrandom`]. See the macro's</span>
<span class="doccomment">//! documentation for more information about writing and registering your own</span>
<span class="doccomment">//! custom implementations.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! Note that registering a custom implementation only has an effect on targets</span>
<span class="doccomment">//! that would otherwise not compile. Any supported targets (including those</span>
<span class="doccomment">//! using `rdrand` and `js` Cargo features) continue using their normal</span>
<span class="doccomment">//! implementations even if a function is registered.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! ### Indirect Dependencies</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! If `getrandom` is not a direct dependency of your crate, you can still</span>
<span class="doccomment">//! enable any of the above fallback behaviors by enabling the relevant</span>
<span class="doccomment">//! feature in your root crate's `Cargo.toml`:</span>
<span class="doccomment">//! ```toml</span>
<span class="doccomment">//! [dependencies]</span>
<span class="doccomment">//! getrandom = { version = "0.2", features = ["js"] }</span>
<span class="doccomment">//! ```</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! ## Early boot</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! Sometimes, early in the boot process, the OS has not collected enough</span>
<span class="doccomment">//! entropy to securely seed its RNG. This is especially common on virtual</span>
<span class="doccomment">//! machines, where standard "random" events are hard to come by.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! Some operating system interfaces always block until the RNG is securely</span>
<span class="doccomment">//! seeded. This can take anywhere from a few seconds to more than a minute.</span>
<span class="doccomment">//! A few (Linux, NetBSD and Solaris) offer a choice between blocking and</span>
<span class="doccomment">//! getting an error; in these cases, we always choose to block.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! On Linux (when the `getrandom` system call is not available), reading from</span>
<span class="doccomment">//! `/dev/urandom` never blocks, even when the OS hasn't collected enough</span>
<span class="doccomment">//! entropy yet. To avoid returning low-entropy bytes, we first poll</span>
<span class="doccomment">//! `/dev/random` and only switch to `/dev/urandom` once this has succeeded.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! ## Error handling</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! We always choose failure over returning insecure "random" bytes. In general,</span>
<span class="doccomment">//! on supported platforms, failure is highly unlikely, though not impossible.</span>
<span class="doccomment">//! If an error does occur, then it is likely that it will occur on every call to</span>
<span class="doccomment">//! `getrandom`, hence after the first successful call one can be reasonably</span>
<span class="doccomment">//! confident that no errors will occur.</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! [1]: http://man7.org/linux/man-pages/man2/getrandom.2.html</span>
<span class="doccomment">//! [2]: http://man7.org/linux/man-pages/man4/urandom.4.html</span>
<span class="doccomment">//! [3]: https://www.unix.com/man-page/mojave/2/getentropy/</span>
<span class="doccomment">//! [4]: https://www.unix.com/man-page/mojave/4/random/</span>
<span class="doccomment">//! [5]: https://www.freebsd.org/cgi/man.cgi?query=getrandom&manpath=FreeBSD+12.0-stable</span>
<span class="doccomment">//! [6]: https://www.freebsd.org/cgi/man.cgi?query=random&sektion=4</span>
<span class="doccomment">//! [7]: https://man.openbsd.org/getentropy.2</span>
<span class="doccomment">//! [8]: https://man.netbsd.org/sysctl.7</span>
<span class="doccomment">//! [9]: https://leaf.dragonflybsd.org/cgi/web-man?command=getrandom</span>
<span class="doccomment">//! [10]: https://leaf.dragonflybsd.org/cgi/web-man?command=random&section=4</span>
<span class="doccomment">//! [11]: https://docs.oracle.com/cd/E88353_01/html/E37841/getrandom-2.html</span>
<span class="doccomment">//! [12]: https://docs.oracle.com/cd/E86824_01/html/E54777/random-7d.html</span>
<span class="doccomment">//!</span>
<span class="doccomment">//! [`BCryptGenRandom`]: https://docs.microsoft.com/en-us/windows/win32/api/bcrypt/nf-bcrypt-bcryptgenrandom</span>
<span class="doccomment">//! [`Crypto.getRandomValues`]: https://www.w3.org/TR/WebCryptoAPI/#Crypto-method-getRandomValues</span>
<span class="doccomment">//! [`RDRAND`]: https://software.intel.com/en-us/articles/intel-digital-random-number-generator-drng-software-implementation-guide</span>
<span class="doccomment">//! [`SecRandomCopyBytes`]: https://developer.apple.com/documentation/security/1399291-secrandomcopybytes?language=objc</span>
<span class="doccomment">//! [`cprng_draw`]: https://fuchsia.dev/fuchsia-src/zircon/syscalls/cprng_draw</span>
<span class="doccomment">//! [`crypto.randomBytes`]: https://nodejs.org/api/crypto.html#crypto_crypto_randombytes_size_callback</span>
<span class="doccomment">//! [`esp_fill_random`]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/random.html#_CPPv415esp_fill_randomPv6size_t</span>
<span class="doccomment">//! [`random_get`]: https://github.com/WebAssembly/WASI/blob/main/phases/snapshot/docs.md#-random_getbuf-pointeru8-buf_len-size---errno</span>
<span class="doccomment">//! [WebAssembly support]: #webassembly-support</span>
<span class="attribute">#![<span class="ident">doc</span>(
<span class="ident">html_logo_url</span> <span class="op">=</span> <span class="string">"https://www.rust-lang.org/logos/rust-logo-128x128-blk.png"</span>,
<span class="ident">html_favicon_url</span> <span class="op">=</span> <span class="string">"https://www.rust-lang.org/favicon.ico"</span>,
<span class="ident">html_root_url</span> <span class="op">=</span> <span class="string">"https://docs.rs/getrandom/0.2.7"</span>
)]</span>
<span class="attribute">#![<span class="ident">no_std</span>]</span>
<span class="attribute">#![<span class="ident">warn</span>(<span class="ident">rust_2018_idioms</span>, <span class="ident">unused_lifetimes</span>, <span class="ident">missing_docs</span>)]</span>
<span class="attribute">#![<span class="ident">cfg_attr</span>(<span class="ident">docsrs</span>, <span class="ident">feature</span>(<span class="ident">doc_cfg</span>))]</span>
<span class="attribute">#[<span class="ident">macro_use</span>]</span>
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">cfg_if</span>;
<span class="kw">mod</span> <span class="ident">error</span>;
<span class="kw">mod</span> <span class="ident">util</span>;
<span class="comment">// To prevent a breaking change when targets are added, we always export the</span>
<span class="comment">// register_custom_getrandom macro, so old Custom RNG crates continue to build.</span>
<span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"custom"</span>)]</span>
<span class="kw">mod</span> <span class="ident">custom</span>;
<span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"std"</span>)]</span>
<span class="kw">mod</span> <span class="ident">error_impls</span>;
<span class="kw">pub</span> <span class="kw">use</span> <span class="ident"><span class="kw">crate</span>::error::Error</span>;
<span class="comment">// System-specific implementations.</span>
<span class="comment">//</span>
<span class="comment">// These should all provide getrandom_inner with the same signature as getrandom.</span>
<span class="macro">cfg_if!</span> {
<span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">any</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"emscripten"</span>, <span class="ident">target_os</span> <span class="op">=</span> <span class="string">"haiku"</span>,
<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"redox"</span>))]</span> {
<span class="kw">mod</span> <span class="ident">util_libc</span>;
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"use_file.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">any</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"android"</span>, <span class="ident">target_os</span> <span class="op">=</span> <span class="string">"linux"</span>))]</span> {
<span class="kw">mod</span> <span class="ident">util_libc</span>;
<span class="kw">mod</span> <span class="ident">use_file</span>;
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"linux_android.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">any</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"illumos"</span>, <span class="ident">target_os</span> <span class="op">=</span> <span class="string">"solaris"</span>))]</span> {
<span class="kw">mod</span> <span class="ident">util_libc</span>;
<span class="kw">mod</span> <span class="ident">use_file</span>;
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"solaris_illumos.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">any</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"freebsd"</span>, <span class="ident">target_os</span> <span class="op">=</span> <span class="string">"netbsd"</span>))]</span> {
<span class="kw">mod</span> <span class="ident">util_libc</span>;
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"bsd_arandom.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"dragonfly"</span>)]</span> {
<span class="kw">mod</span> <span class="ident">util_libc</span>;
<span class="kw">mod</span> <span class="ident">use_file</span>;
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"dragonfly.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"fuchsia"</span>)]</span> {
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"fuchsia.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"ios"</span>)]</span> {
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"ios.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"macos"</span>)]</span> {
<span class="kw">mod</span> <span class="ident">util_libc</span>;
<span class="kw">mod</span> <span class="ident">use_file</span>;
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"macos.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"openbsd"</span>)]</span> {
<span class="kw">mod</span> <span class="ident">util_libc</span>;
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"openbsd.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"wasi"</span>)]</span> {
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"wasi.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">all</span>(<span class="ident">target_arch</span> <span class="op">=</span> <span class="string">"x86_64"</span>, <span class="ident">target_os</span> <span class="op">=</span> <span class="string">"hermit"</span>))]</span> {
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"rdrand.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"vxworks"</span>)]</span> {
<span class="kw">mod</span> <span class="ident">util_libc</span>;
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"vxworks.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"solid_asp3"</span>)]</span> {
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"solid.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"espidf"</span>)]</span> {
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"espidf.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">windows</span>)]</span> {
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"windows.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">all</span>(<span class="ident">target_arch</span> <span class="op">=</span> <span class="string">"x86_64"</span>, <span class="ident">target_env</span> <span class="op">=</span> <span class="string">"sgx"</span>))]</span> {
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"rdrand.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">all</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"rdrand"</span>,
<span class="ident">any</span>(<span class="ident">target_arch</span> <span class="op">=</span> <span class="string">"x86_64"</span>, <span class="ident">target_arch</span> <span class="op">=</span> <span class="string">"x86"</span>)))]</span> {
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"rdrand.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">all</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"js"</span>,
<span class="ident">target_arch</span> <span class="op">=</span> <span class="string">"wasm32"</span>, <span class="ident">target_os</span> <span class="op">=</span> <span class="string">"unknown"</span>))]</span> {
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"js.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">all</span>(<span class="ident">target_os</span> <span class="op">=</span> <span class="string">"horizon"</span>, <span class="ident">target_arch</span> <span class="op">=</span> <span class="string">"arm"</span>))]</span> {
<span class="comment">// We check for target_arch = "arm" because the Nintendo Switch also</span>
<span class="comment">// uses Horizon OS (it is aarch64).</span>
<span class="kw">mod</span> <span class="ident">util_libc</span>;
<span class="attribute">#[<span class="ident">path</span> <span class="op">=</span> <span class="string">"3ds.rs"</span>]</span> <span class="kw">mod</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">"custom"</span>)]</span> {
<span class="kw">use</span> <span class="ident">custom</span> <span class="kw">as</span> <span class="ident">imp</span>;
} <span class="kw">else</span> <span class="kw">if</span> <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">all</span>(<span class="ident">target_arch</span> <span class="op">=</span> <span class="string">"wasm32"</span>, <span class="ident">target_os</span> <span class="op">=</span> <span class="string">"unknown"</span>))]</span> {
<span class="macro">compile_error!</span>(<span class="string">"the wasm32-unknown-unknown target is not supported by \
default, you may need to enable the \"js\" feature. \
For more information see: \
https://docs.rs/getrandom/#webassembly-support"</span>);
} <span class="kw">else</span> {
<span class="macro">compile_error!</span>(<span class="string">"target is not supported, for more information see: \
https://docs.rs/getrandom/#unsupported-targets"</span>);
}
}
<span class="doccomment">/// Fill `dest` with random bytes from the system's preferred random number</span>
<span class="doccomment">/// source.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// This function returns an error on any failure, including partial reads. We</span>
<span class="doccomment">/// make no guarantees regarding the contents of `dest` on error. If `dest` is</span>
<span class="doccomment">/// empty, `getrandom` immediately returns success, making no calls to the</span>
<span class="doccomment">/// underlying operating system.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// Blocking is possible, at least during early boot; see module documentation.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// In general, `getrandom` will be fast enough for interactive usage, though</span>
<span class="doccomment">/// significantly slower than a user-space CSPRNG; for the latter consider</span>
<span class="doccomment">/// [`rand::thread_rng`](https://docs.rs/rand/*/rand/fn.thread_rng.html).</span>
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">getrandom</span>(<span class="ident">dest</span>: <span class="kw-2">&mut</span> [<span class="ident">u8</span>]) -> <span class="prelude-ty">Result</span><span class="op"><</span>(), <span class="ident">Error</span><span class="op">></span> {
<span class="kw">if</span> <span class="ident">dest</span>.<span class="ident">is_empty</span>() {
<span class="kw">return</span> <span class="prelude-val">Ok</span>(());
}
<span class="ident">imp::getrandom_inner</span>(<span class="ident">dest</span>)
}
</code></pre></div>
</section></div></main><div id="rustdoc-vars" data-root-path="../../" data-current-crate="getrandom" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.64.0-nightly (495b21669 2022-07-03)" ></div>
</body></html>