src/rand.h

   1 /** @file
   2  * innotek Portable Runtime - Random Numbers and Byte Streams.
   3  */
   4
   5 /*
   6  * Copyright (C) 2006-2007 innotek GmbH
   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 as published by the Free Software Foundation,
  12  * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
  13  * distribution. VirtualBox OSE is distributed in the hope that it will
  14  * be useful, but WITHOUT ANY WARRANTY of any kind.
  15  */
  16
  17 #ifndef ___iprt_rand_h
  18 #define ___iprt_rand_h
  19
  20 #include "cdefs.h"
  21 #include "types.h"
  22 #include <stddef.h>
  23
  24 __BEGIN_DECLS
  25
  26 /**
  27  * Initialize OS facilities for generating random bytes.
  28  */
  29 void rtRandLazyInitNative(void);
  30
  31 /**
  32  * Generate random bytes using OS facilities.
  33  *
  34  * @returns VINF_SUCCESS on success, some error status code on failure.
  35  * @param   pv      Where to store the random bytes.
  36  * @param   cb      How many random bytes to store.
  37  */
  38 int rtRandGenBytesNative(void *pv, size_t cb);
  39
  40 void rtRandGenBytesFallback(void *pv, size_t cb);
  41
  42 /** @defgroup grp_rt_rand       RTRand - Random Numbers and Byte Streams
  43  * @ingroup grp_rt
  44  * @{
  45  */
  46
  47 /**
  48  * Fills a buffer with random bytes.
  49  *
  50  * @param   pv  Where to store the random bytes.
  51  * @param   cb  Number of bytes to generate.
  52  */
  53 void RTRandBytes(void *pv, size_t cb);
  54
  55 /**
  56  * Generate a 32-bit signed random number in the set [i32First..i32Last].
  57  *
  58  * @returns The random number.
  59  * @param   i32First    First number in the set.
  60  * @param   i32Last     Last number in the set.
  61  */
  62 int32_t RTRandS32Ex(int32_t i32First, int32_t i32Last);
  63
  64 /**
  65  * Generate a 32-bit signed random number.
  66  *
  67  * @returns The random number.
  68  */
  69 int32_t RTRandS32(void);
  70
  71 /**
  72  * Generate a 32-bit unsigned random number in the set [u32First..u32Last].
  73  *
  74  * @returns The random number.
  75  * @param   u32First    First number in the set.
  76  * @param   u32Last     Last number in the set.
  77  */
  78 uint32_t RTRandU32Ex(uint32_t u32First, uint32_t u32Last);
  79
  80 /**
  81  * Generate a 32-bit unsigned random number.
  82  *
  83  * @returns The random number.
  84  */
  85 uint32_t RTRandU32(void);
  86
  87 /**
  88  * Generate a 32-bit signed random number in the set [i32First..i32Last].
  89  *
  90  * @returns The random number.
  91  * @param   i32First    First number in the set.
  92  * @param   i32Last     Last number in the set.
  93  */
  94 int64_t RTRandS64Ex(int64_t i64First, int64_t i64Last);
  95
  96 /**
  97  * Generate a 64-bit signed random number.
  98  *
  99  * @returns The random number.
 100  */
 101 int64_t RTRandS64(void);
 102
 103 /**
 104  * Generate a 64-bit unsigned random number in the set [u64First..u64Last].
 105  *
 106  * @returns The random number.
 107  * @param   u64First    First number in the set.
 108  * @param   u64Last     Last number in the set.
 109  */
 110 uint64_t RTRandU64Ex(uint64_t u64First, uint64_t u64Last);
 111
 112 /**
 113  * Generate a 64-bit unsigned random number.
 114  *
 115  * @returns The random number.
 116  */
 117 uint64_t RTRandU64(void);
 118
 119 /** @} */
 120
 121 __END_DECLS
 122
 123
 124 #endif
 125