1 | #[cfg (feature = "std" )] |
2 | extern crate std; |
3 | |
4 | use core::{fmt, num::NonZeroU32}; |
5 | |
6 | // This private alias mirrors `std::io::RawOsError`: |
7 | // https://doc.rust-lang.org/std/io/type.RawOsError.html) |
8 | cfg_if::cfg_if!( |
9 | if #[cfg(target_os = "uefi" )] { |
10 | type RawOsError = usize; |
11 | } else { |
12 | type RawOsError = i32; |
13 | } |
14 | ); |
15 | |
16 | /// A small and `no_std` compatible error type |
17 | /// |
18 | /// The [`Error::raw_os_error()`] will indicate if the error is from the OS, and |
19 | /// if so, which error code the OS gave the application. If such an error is |
20 | /// encountered, please consult with your system documentation. |
21 | /// |
22 | /// Internally this type is a NonZeroU32, with certain values reserved for |
23 | /// certain purposes, see [`Error::INTERNAL_START`] and [`Error::CUSTOM_START`]. |
24 | /// |
25 | /// *If this crate's `"std"` Cargo feature is enabled*, then: |
26 | /// - [`getrandom::Error`][Error] implements |
27 | /// [`std::error::Error`](https://doc.rust-lang.org/std/error/trait.Error.html) |
28 | /// - [`std::io::Error`](https://doc.rust-lang.org/std/io/struct.Error.html) implements |
29 | /// [`From<getrandom::Error>`](https://doc.rust-lang.org/std/convert/trait.From.html). |
30 | #[derive (Copy, Clone, Eq, PartialEq)] |
31 | pub struct Error(NonZeroU32); |
32 | |
33 | impl Error { |
34 | /// This target/platform is not supported by `getrandom`. |
35 | pub const UNSUPPORTED: Error = Self::new_internal(0); |
36 | /// The platform-specific `errno` returned a non-positive value. |
37 | pub const ERRNO_NOT_POSITIVE: Error = Self::new_internal(1); |
38 | /// Encountered an unexpected situation which should not happen in practice. |
39 | pub const UNEXPECTED: Error = Self::new_internal(2); |
40 | |
41 | /// Codes below this point represent OS Errors (i.e. positive i32 values). |
42 | /// Codes at or above this point, but below [`Error::CUSTOM_START`] are |
43 | /// reserved for use by the `rand` and `getrandom` crates. |
44 | pub const INTERNAL_START: u32 = 1 << 31; |
45 | |
46 | /// Codes at or above this point can be used by users to define their own |
47 | /// custom errors. |
48 | pub const CUSTOM_START: u32 = (1 << 31) + (1 << 30); |
49 | |
50 | /// Creates a new instance of an `Error` from a particular OS error code. |
51 | /// |
52 | /// This method is analogous to [`std::io::Error::from_raw_os_error()`][1], |
53 | /// except that it works in `no_std` contexts and `code` will be |
54 | /// replaced with `Error::UNEXPECTED` if it isn't in the range |
55 | /// `1..Error::INTERNAL_START`. Thus, for the result `r`, |
56 | /// `r == Self::UNEXPECTED || r.raw_os_error().unsigned_abs() == code`. |
57 | /// |
58 | /// [1]: https://doc.rust-lang.org/std/io/struct.Error.html#method.from_raw_os_error |
59 | #[allow (dead_code)] |
60 | pub(super) fn from_os_error(code: u32) -> Self { |
61 | match NonZeroU32::new(code) { |
62 | Some(code) if code.get() < Self::INTERNAL_START => Self(code), |
63 | _ => Self::UNEXPECTED, |
64 | } |
65 | } |
66 | |
67 | /// Extract the raw OS error code (if this error came from the OS) |
68 | /// |
69 | /// This method is identical to [`std::io::Error::raw_os_error()`][1], except |
70 | /// that it works in `no_std` contexts. On most targets this method returns |
71 | /// `Option<i32>`, but some platforms (e.g. UEFI) may use a different primitive |
72 | /// type like `usize`. Consult with the [`RawOsError`] docs for more information. |
73 | /// |
74 | /// If this method returns `None`, the error value can still be formatted via |
75 | /// the `Display` implementation. |
76 | /// |
77 | /// [1]: https://doc.rust-lang.org/std/io/struct.Error.html#method.raw_os_error |
78 | /// [`RawOsError`]: https://doc.rust-lang.org/std/io/type.RawOsError.html |
79 | #[inline ] |
80 | pub fn raw_os_error(self) -> Option<RawOsError> { |
81 | let code = self.0.get(); |
82 | if code >= Self::INTERNAL_START { |
83 | return None; |
84 | } |
85 | let errno = RawOsError::try_from(code).ok()?; |
86 | #[cfg (target_os = "solid_asp3" )] |
87 | let errno = -errno; |
88 | Some(errno) |
89 | } |
90 | |
91 | /// Creates a new instance of an `Error` from a particular custom error code. |
92 | pub const fn new_custom(n: u16) -> Error { |
93 | // SAFETY: code > 0 as CUSTOM_START > 0 and adding n won't overflow a u32. |
94 | let code = Error::CUSTOM_START + (n as u32); |
95 | Error(unsafe { NonZeroU32::new_unchecked(code) }) |
96 | } |
97 | |
98 | /// Creates a new instance of an `Error` from a particular internal error code. |
99 | pub(crate) const fn new_internal(n: u16) -> Error { |
100 | // SAFETY: code > 0 as INTERNAL_START > 0 and adding n won't overflow a u32. |
101 | let code = Error::INTERNAL_START + (n as u32); |
102 | Error(unsafe { NonZeroU32::new_unchecked(code) }) |
103 | } |
104 | |
105 | fn internal_desc(&self) -> Option<&'static str> { |
106 | let desc = match *self { |
107 | Error::UNSUPPORTED => "getrandom: this target is not supported" , |
108 | Error::ERRNO_NOT_POSITIVE => "errno: did not return a positive value" , |
109 | Error::UNEXPECTED => "unexpected situation" , |
110 | #[cfg (any( |
111 | target_os = "ios" , |
112 | target_os = "visionos" , |
113 | target_os = "watchos" , |
114 | target_os = "tvos" , |
115 | ))] |
116 | Error::IOS_RANDOM_GEN => "SecRandomCopyBytes: iOS Security framework failure" , |
117 | #[cfg (all(windows, target_vendor = "win7" ))] |
118 | Error::WINDOWS_RTL_GEN_RANDOM => "RtlGenRandom: Windows system function failure" , |
119 | #[cfg (all(feature = "wasm_js" , getrandom_backend = "wasm_js" ))] |
120 | Error::WEB_CRYPTO => "Web Crypto API is unavailable" , |
121 | #[cfg (target_os = "vxworks" )] |
122 | Error::VXWORKS_RAND_SECURE => "randSecure: VxWorks RNG module is not initialized" , |
123 | |
124 | #[cfg (any( |
125 | getrandom_backend = "rdrand" , |
126 | all(target_arch = "x86_64" , target_env = "sgx" ) |
127 | ))] |
128 | Error::FAILED_RDRAND => "RDRAND: failed multiple times: CPU issue likely" , |
129 | #[cfg (any( |
130 | getrandom_backend = "rdrand" , |
131 | all(target_arch = "x86_64" , target_env = "sgx" ) |
132 | ))] |
133 | Error::NO_RDRAND => "RDRAND: instruction not supported" , |
134 | |
135 | #[cfg (getrandom_backend = "rndr" )] |
136 | Error::RNDR_FAILURE => "RNDR: Could not generate a random number" , |
137 | #[cfg (getrandom_backend = "rndr" )] |
138 | Error::RNDR_NOT_AVAILABLE => "RNDR: Register not supported" , |
139 | _ => return None, |
140 | }; |
141 | Some(desc) |
142 | } |
143 | } |
144 | |
145 | impl fmt::Debug for Error { |
146 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
147 | let mut dbg: DebugStruct<'_, '_> = f.debug_struct(name:"Error" ); |
148 | if let Some(errno: i32) = self.raw_os_error() { |
149 | dbg.field(name:"os_error" , &errno); |
150 | #[cfg (feature = "std" )] |
151 | dbg.field(name:"description" , &std::io::Error::from_raw_os_error(code:errno)); |
152 | } else if let Some(desc: &'static str) = self.internal_desc() { |
153 | dbg.field(name:"internal_code" , &self.0.get()); |
154 | dbg.field(name:"description" , &desc); |
155 | } else { |
156 | dbg.field(name:"unknown_code" , &self.0.get()); |
157 | } |
158 | dbg.finish() |
159 | } |
160 | } |
161 | |
162 | impl fmt::Display for Error { |
163 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
164 | if let Some(errno: i32) = self.raw_os_error() { |
165 | cfg_if! { |
166 | if #[cfg(feature = "std" )] { |
167 | std::io::Error::from_raw_os_error(errno).fmt(f) |
168 | } else { |
169 | write!(f, "OS Error: {}" , errno) |
170 | } |
171 | } |
172 | } else if let Some(desc: &'static str) = self.internal_desc() { |
173 | f.write_str(data:desc) |
174 | } else { |
175 | write!(f, "Unknown Error: {}" , self.0.get()) |
176 | } |
177 | } |
178 | } |
179 | |
180 | #[cfg (test)] |
181 | mod tests { |
182 | use super::Error; |
183 | use core::mem::size_of; |
184 | |
185 | #[test ] |
186 | fn test_size() { |
187 | assert_eq!(size_of::<Error>(), 4); |
188 | assert_eq!(size_of::<Result<(), Error>>(), 4); |
189 | } |
190 | } |
191 | |