VirtualBox

source: vbox/trunk/include/iprt/rand.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.3 KB
Line 
1/** @file
2 * IPRT - Random Numbers and Byte Streams.
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_rand_h
37#define IPRT_INCLUDED_rand_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44
45RT_C_DECLS_BEGIN
46
47/** @defgroup grp_rt_rand RTRand - Random Numbers and Byte Streams
48 * @ingroup grp_rt
49 * @{
50 */
51
52/**
53 * Fills a buffer with random bytes.
54 *
55 * @param pv Where to store the random bytes.
56 * @param cb Number of bytes to generate.
57 */
58RTDECL(void) RTRandBytes(void *pv, size_t cb) RT_NO_THROW_PROTO;
59
60/**
61 * Generate a 32-bit signed random number in the set [i32First..i32Last].
62 *
63 * @returns The random number.
64 * @param i32First First number in the set.
65 * @param i32Last Last number in the set.
66 */
67RTDECL(int32_t) RTRandS32Ex(int32_t i32First, int32_t i32Last) RT_NO_THROW_PROTO;
68
69/**
70 * Generate a 32-bit signed random number.
71 *
72 * @returns The random number.
73 */
74RTDECL(int32_t) RTRandS32(void) RT_NO_THROW_PROTO;
75
76/**
77 * Generate a 32-bit unsigned random number in the set [u32First..u32Last].
78 *
79 * @returns The random number.
80 * @param u32First First number in the set.
81 * @param u32Last Last number in the set.
82 */
83RTDECL(uint32_t) RTRandU32Ex(uint32_t u32First, uint32_t u32Last) RT_NO_THROW_PROTO;
84
85/**
86 * Generate a 32-bit unsigned random number.
87 *
88 * @returns The random number.
89 */
90RTDECL(uint32_t) RTRandU32(void) RT_NO_THROW_PROTO;
91
92/**
93 * Generate a 64-bit signed random number in the set [i64First..i64Last].
94 *
95 * @returns The random number.
96 * @param i64First First number in the set.
97 * @param i64Last Last number in the set.
98 */
99RTDECL(int64_t) RTRandS64Ex(int64_t i64First, int64_t i64Last) RT_NO_THROW_PROTO;
100
101/**
102 * Generate a 64-bit signed random number.
103 *
104 * @returns The random number.
105 */
106RTDECL(int64_t) RTRandS64(void) RT_NO_THROW_PROTO;
107
108/**
109 * Generate a 64-bit unsigned random number in the set [u64First..u64Last].
110 *
111 * @returns The random number.
112 * @param u64First First number in the set.
113 * @param u64Last Last number in the set.
114 */
115RTDECL(uint64_t) RTRandU64Ex(uint64_t u64First, uint64_t u64Last) RT_NO_THROW_PROTO;
116
117/**
118 * Generate a 64-bit unsigned random number.
119 *
120 * @returns The random number.
121 */
122RTDECL(uint64_t) RTRandU64(void) RT_NO_THROW_PROTO;
123
124
125/**
126 * Create an instance of the default random number generator.
127 *
128 * @returns IPRT status code.
129 * @param phRand Where to return the handle to the new random number
130 * generator.
131 */
132RTDECL(int) RTRandAdvCreate(PRTRAND phRand) RT_NO_THROW_PROTO;
133
134/**
135 * Create an instance of the default pseudo random number generator.
136 *
137 * @returns IPRT status code.
138 * @param phRand Where to store the handle to the generator.
139 */
140RTDECL(int) RTRandAdvCreatePseudo(PRTRAND phRand) RT_NO_THROW_PROTO;
141
142/**
143 * Create an instance of the Park-Miller pseudo random number generator.
144 *
145 * @returns IPRT status code.
146 * @param phRand Where to store the handle to the generator.
147 */
148RTDECL(int) RTRandAdvCreateParkMiller(PRTRAND phRand) RT_NO_THROW_PROTO;
149
150/**
151 * Create an instance of the faster random number generator for the OS.
152 *
153 * @returns IPRT status code.
154 * @retval VERR_NOT_SUPPORTED on platforms which doesn't have this feature.
155 * @retval VERR_FILE_NOT_FOUND on system where the random generator hasn't
156 * been installed or configured correctly.
157 * @retval VERR_PATH_NOT_FOUND for the same reasons as VERR_FILE_NOT_FOUND.
158 *
159 * @param phRand Where to store the handle to the generator.
160 *
161 * @remarks Think /dev/urandom.
162 */
163RTDECL(int) RTRandAdvCreateSystemFaster(PRTRAND phRand) RT_NO_THROW_PROTO;
164
165/**
166 * Create an instance of the truer random number generator for the OS.
167 *
168 * Don't use this unless you seriously need good random numbers because most
169 * systems will have will have problems producing sufficient entropy for this
170 * and you'll end up blocking while it accumulates.
171 *
172 * @returns IPRT status code.
173 * @retval VERR_NOT_SUPPORTED on platforms which doesn't have this feature.
174 * @retval VERR_FILE_NOT_FOUND on system where the random generator hasn't
175 * been installed or configured correctly.
176 * @retval VERR_PATH_NOT_FOUND for the same reasons as VERR_FILE_NOT_FOUND.
177 *
178 * @param phRand Where to store the handle to the generator.
179 *
180 * @remarks Think /dev/random.
181 */
182RTDECL(int) RTRandAdvCreateSystemTruer(PRTRAND phRand) RT_NO_THROW_PROTO;
183
184/**
185 * Destroys a random number generator.
186 *
187 * @returns IPRT status code.
188 * @param hRand Handle to the random number generator.
189 */
190RTDECL(int) RTRandAdvDestroy(RTRAND hRand) RT_NO_THROW_PROTO;
191
192/**
193 * Generic method for seeding of a random number generator.
194 *
195 * The different generators may have specialized methods for
196 * seeding, use one of those if you desire better control
197 * over the result.
198 *
199 * @returns IPRT status code.
200 * @retval VERR_NOT_SUPPORTED if it isn't a pseudo generator.
201 *
202 * @param hRand Handle to the random number generator.
203 * @param u64Seed Seed.
204 */
205RTDECL(int) RTRandAdvSeed(RTRAND hRand, uint64_t u64Seed) RT_NO_THROW_PROTO;
206
207/**
208 * Save the current state of a pseudo generator.
209 *
210 * This can be use to save the state so it can later be resumed at the same
211 * position.
212 *
213 * @returns IPRT status code.
214 * @retval VINF_SUCCESS on success. *pcbState contains the length of the
215 * returned string and pszState contains the state string.
216 * @retval VERR_BUFFER_OVERFLOW if the supplied buffer is too small. *pcbState
217 * will contain the necessary buffer size.
218 * @retval VERR_NOT_SUPPORTED by non-psuedo generators.
219 *
220 * @param hRand Handle to the random number generator.
221 * @param pszState Where to store the state. The returned string will be
222 * null terminated and printable.
223 * @param pcbState The size of the buffer pszState points to on input, the
224 * size required / used on return (including the
225 * terminator, thus the 'cb' instead of 'cch').
226 */
227RTDECL(int) RTRandAdvSaveState(RTRAND hRand, char *pszState, size_t *pcbState) RT_NO_THROW_PROTO;
228
229/**
230 * Restores the state of a pseudo generator.
231 *
232 * The state must have been obtained using RTRandAdvGetState.
233 *
234 * @returns IPRT status code.
235 * @retval VERR_PARSE_ERROR if the state string is malformed.
236 * @retval VERR_NOT_SUPPORTED by non-psuedo generators.
237 *
238 * @param hRand Handle to the random number generator.
239 * @param pszState The state to load.
240 */
241RTDECL(int) RTRandAdvRestoreState(RTRAND hRand, char const *pszState) RT_NO_THROW_PROTO;
242
243/**
244 * Fills a buffer with random bytes.
245 *
246 * @param hRand Handle to the random number generator.
247 * @param pv Where to store the random bytes.
248 * @param cb Number of bytes to generate.
249 */
250RTDECL(void) RTRandAdvBytes(RTRAND hRand, void *pv, size_t cb) RT_NO_THROW_PROTO;
251
252/**
253 * Generate a 32-bit signed random number in the set [i32First..i32Last].
254 *
255 * @returns The random number.
256 * @param hRand Handle to the random number generator.
257 * @param i32First First number in the set.
258 * @param i32Last Last number in the set.
259 */
260RTDECL(int32_t) RTRandAdvS32Ex(RTRAND hRand, int32_t i32First, int32_t i32Last) RT_NO_THROW_PROTO;
261
262/**
263 * Generate a 32-bit signed random number.
264 *
265 * @returns The random number.
266 * @param hRand Handle to the random number generator.
267 */
268RTDECL(int32_t) RTRandAdvS32(RTRAND hRand) RT_NO_THROW_PROTO;
269
270/**
271 * Generate a 32-bit unsigned random number in the set [u32First..u32Last].
272 *
273 * @returns The random number.
274 * @param hRand Handle to the random number generator.
275 * @param u32First First number in the set.
276 * @param u32Last Last number in the set.
277 */
278RTDECL(uint32_t) RTRandAdvU32Ex(RTRAND hRand, uint32_t u32First, uint32_t u32Last) RT_NO_THROW_PROTO;
279
280/**
281 * Generate a 32-bit unsigned random number.
282 *
283 * @returns The random number.
284 * @param hRand Handle to the random number generator.
285 */
286RTDECL(uint32_t) RTRandAdvU32(RTRAND hRand) RT_NO_THROW_PROTO;
287
288/**
289 * Generate a 64-bit signed random number in the set [i64First..i64Last].
290 *
291 * @returns The random number.
292 * @param hRand Handle to the random number generator.
293 * @param i64First First number in the set.
294 * @param i64Last Last number in the set.
295 */
296RTDECL(int64_t) RTRandAdvS64Ex(RTRAND hRand, int64_t i64First, int64_t i64Last) RT_NO_THROW_PROTO;
297
298/**
299 * Generate a 64-bit signed random number.
300 *
301 * @returns The random number.
302 */
303RTDECL(int64_t) RTRandAdvS64(RTRAND hRand) RT_NO_THROW_PROTO;
304
305/**
306 * Generate a 64-bit unsigned random number in the set [u64First..u64Last].
307 *
308 * @returns The random number.
309 * @param hRand Handle to the random number generator.
310 * @param u64First First number in the set.
311 * @param u64Last Last number in the set.
312 */
313RTDECL(uint64_t) RTRandAdvU64Ex(RTRAND hRand, uint64_t u64First, uint64_t u64Last) RT_NO_THROW_PROTO;
314
315/**
316 * Generate a 64-bit unsigned random number.
317 *
318 * @returns The random number.
319 * @param hRand Handle to the random number generator.
320 */
321RTDECL(uint64_t) RTRandAdvU64(RTRAND hRand) RT_NO_THROW_PROTO;
322
323
324/** @} */
325
326RT_C_DECLS_END
327
328
329#endif /* !IPRT_INCLUDED_rand_h */
330
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette