VirtualBox

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

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