Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

os_utils.h
Go to the documentation of this file.
1 /*
2 * OS specific utility functions
3 * (C) 2015,2016,2017 Jack Lloyd
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 */
7
8 #ifndef BOTAN_OS_UTILS_H__
9 #define BOTAN_OS_UTILS_H__
10
11 #include <botan/types.h>
12 #include <functional>
13
14 namespace Botan {
15
16 namespace OS {
17
18 /*
19 * This header is internal (not installed) and these functions are not
20 * intended to be called by applications. However they are given public
21 * visibility (using BOTAN_DLL macro) for the tests. This also probably
22 * allows them to be overridden by the application on ELF systems, but
23 * this hasn't been tested.
24 */
25
26 /**
27 * @return process ID assigned by the operating system.
28 * On Unix and Windows systems, this always returns a result
29 * On IncludeOS it returns 0 since there is no process ID to speak of
30 * in a unikernel.
31 */
32 uint32_t BOTAN_DLL get_process_id();
33
34 /**
35 * @return CPU processor clock, if available
36 *
37 * On Windows, calls QueryPerformanceCounter.
38 *
39 * Under GCC or Clang on supported platforms the hardware cycle counter is queried.
40 * Currently supported processors are x86, PPC, Alpha, SPARC, IA-64, S/390x, and HP-PA.
41 * If no CPU cycle counter is available on this system, returns zero.
42 */
43 uint64_t BOTAN_DLL get_processor_timestamp();
44
45 /*
46 * @return best resolution timestamp available
47 *
48 * The epoch and update rate of this clock is arbitrary and depending
49 * on the hardware it may not tick at a constant rate.
50 *
51 * Uses hardware cycle counter, if available.
52 * On POSIX platforms clock_gettime is used with a monotonic timer
53 * As a final fallback std::chrono::high_resolution_clock is used.
54 */
55 uint64_t BOTAN_DLL get_high_resolution_clock();
56
57 /**
58 * @return system clock (reflecting wall clock) with best resolution
59 * available, normalized to nanoseconds resolution.
60 */
61 uint64_t BOTAN_DLL get_system_timestamp_ns();
62
63 /**
64 * @return maximum amount of memory (in bytes) Botan could/should
65 * hyptothetically allocate for the memory poool. Reads environment
66 * variable "BOTAN_MLOCK_POOL_SIZE", set to "0" to disable pool.
67 */
68 size_t get_memory_locking_limit();
69
70 /**
71 * Request so many bytes of page-aligned RAM locked into memory using
72 * mlock, VirtualLock, or similar. Returns null on failure. The memory
73 * returned is zeroed. Free it with free_locked_pages.
74 * @param length requested allocation in bytes
75 */
76 void* allocate_locked_pages(size_t length);
77
78 /**
79 * Free memory allocated by allocate_locked_pages
80 * @param ptr a pointer returned by allocate_locked_pages
81 * @param length length passed to allocate_locked_pages
82 */
83 void free_locked_pages(void* ptr, size_t length);
84
85 /**
86 * Run a probe instruction to test for support for a CPU instruction.
87 * Runs in system-specific env that catches illegal instructions; this
88 * function always fails if the OS doesn't provide this.
89 * Returns value of probe_fn, if it could run.
90 * If error occurs, returns negative number.
91 * This allows probe_fn to indicate errors of its own, if it wants.
92 * For example the instruction might not only be only available on some
93 * CPUs, but also buggy on some subset of these - the probe function
94 * can test to make sure the instruction works properly before
95 * indicating that the instruction is available.
96 *
97 * @warning on Unix systems uses signal handling in a way that is not
98 * thread safe. It should only be called in a single-threaded context
99 * (ie, at static init time).
100 *
101 * If probe_fn throws an exception the result is undefined.
102 *
103 * Return codes:
104 * -1 illegal instruction detected
105 */
106 int BOTAN_DLL run_cpu_instruction_probe(std::function<int ()> probe_fn);
107
108 }
109
110 }
111
112 #endif
Botan::OS::run_cpu_instruction_probe
int BOTAN_DLL run_cpu_instruction_probe(std::function< int()> probe_fn)
Definition: os_utils.cpp:346
Botan::OS::get_process_id
uint32_t BOTAN_DLL get_process_id()
Definition: os_utils.cpp:31
Botan::OS::allocate_locked_pages
void * allocate_locked_pages(size_t length)
Definition: os_utils.cpp:257
Botan::OS::get_memory_locking_limit
size_t get_memory_locking_limit()
Definition: os_utils.cpp:171
Botan::OS::get_processor_timestamp
uint64_t BOTAN_DLL get_processor_timestamp()
Definition: os_utils.cpp:44
Botan::OS::get_system_timestamp_ns
uint64_t BOTAN_DLL get_system_timestamp_ns()
Definition: os_utils.cpp:157
Botan
Definition: alg_id.cpp:13
Botan::OS::free_locked_pages
void free_locked_pages(void *ptr, size_t length)
Definition: os_utils.cpp:314
Botan::OS::get_high_resolution_clock
uint64_t BOTAN_DLL get_high_resolution_clock()
Definition: os_utils.cpp:109