1#[cfg(feature = "std")]
2extern crate std;
3
4use core::{fmt, num::NonZeroU32};
5
6// This private alias mirrors `std::io::RawOsError`:
7// https://doc.rust-lang.org/std/io/type.RawOsError.html)
8cfg_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)]
31pub struct Error(NonZeroU32);
32
33impl 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
145impl 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
162impl 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)]
181mod 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