1 // SPDX-License-Identifier: GPL-2.0 2 3 //! Kernel errors. 4 //! 5 //! C header: [`include/uapi/asm-generic/errno-base.h`](../../../include/uapi/asm-generic/errno-base.h) 6 7 use alloc::{ 8 alloc::{AllocError, LayoutError}, 9 collections::TryReserveError, 10 }; 11 12 use core::convert::From; 13 use core::num::TryFromIntError; 14 use core::str::Utf8Error; 15 16 /// Contains the C-compatible error codes. 17 pub mod code { 18 macro_rules! declare_err { 19 ($err:tt $(,)? $($doc:expr),+) => { 20 $( 21 #[doc = $doc] 22 )* 23 pub const $err: super::Error = super::Error(-(crate::bindings::$err as i32)); 24 }; 25 } 26 27 declare_err!(EPERM, "Operation not permitted."); 28 declare_err!(ENOENT, "No such file or directory."); 29 declare_err!(ESRCH, "No such process."); 30 declare_err!(EINTR, "Interrupted system call."); 31 declare_err!(EIO, "I/O error."); 32 declare_err!(ENXIO, "No such device or address."); 33 declare_err!(E2BIG, "Argument list too long."); 34 declare_err!(ENOEXEC, "Exec format error."); 35 declare_err!(EBADF, "Bad file number."); 36 declare_err!(ECHILD, "Exec format error."); 37 declare_err!(EAGAIN, "Try again."); 38 declare_err!(ENOMEM, "Out of memory."); 39 declare_err!(EACCES, "Permission denied."); 40 declare_err!(EFAULT, "Bad address."); 41 declare_err!(ENOTBLK, "Block device required."); 42 declare_err!(EBUSY, "Device or resource busy."); 43 declare_err!(EEXIST, "File exists."); 44 declare_err!(EXDEV, "Cross-device link."); 45 declare_err!(ENODEV, "No such device."); 46 declare_err!(ENOTDIR, "Not a directory."); 47 declare_err!(EISDIR, "Is a directory."); 48 declare_err!(EINVAL, "Invalid argument."); 49 declare_err!(ENFILE, "File table overflow."); 50 declare_err!(EMFILE, "Too many open files."); 51 declare_err!(ENOTTY, "Not a typewriter."); 52 declare_err!(ETXTBSY, "Text file busy."); 53 declare_err!(EFBIG, "File too large."); 54 declare_err!(ENOSPC, "No space left on device."); 55 declare_err!(ESPIPE, "Illegal seek."); 56 declare_err!(EROFS, "Read-only file system."); 57 declare_err!(EMLINK, "Too many links."); 58 declare_err!(EPIPE, "Broken pipe."); 59 declare_err!(EDOM, "Math argument out of domain of func."); 60 declare_err!(ERANGE, "Math result not representable."); 61 } 62 63 /// Generic integer kernel error. 64 /// 65 /// The kernel defines a set of integer generic error codes based on C and 66 /// POSIX ones. These codes may have a more specific meaning in some contexts. 67 /// 68 /// # Invariants 69 /// 70 /// The value is a valid `errno` (i.e. `>= -MAX_ERRNO && < 0`). 71 #[derive(Clone, Copy, PartialEq, Eq)] 72 pub struct Error(core::ffi::c_int); 73 74 impl Error { 75 /// Creates an [`Error`] from a kernel error code. 76 /// 77 /// It is a bug to pass an out-of-range `errno`. `EINVAL` would 78 /// be returned in such a case. 79 #[allow(dead_code)] 80 pub(crate) fn from_errno(errno: core::ffi::c_int) -> Error { 81 if errno < -(bindings::MAX_ERRNO as i32) || errno >= 0 { 82 // TODO: Make it a `WARN_ONCE` once available. 83 crate::pr_warn!( 84 "attempted to create `Error` with out of range `errno`: {}", 85 errno 86 ); 87 return code::EINVAL; 88 } 89 90 // INVARIANT: The check above ensures the type invariant 91 // will hold. 92 Error(errno) 93 } 94 95 /// Creates an [`Error`] from a kernel error code. 96 /// 97 /// # Safety 98 /// 99 /// `errno` must be within error code range (i.e. `>= -MAX_ERRNO && < 0`). 100 #[allow(dead_code)] 101 unsafe fn from_errno_unchecked(errno: core::ffi::c_int) -> Error { 102 // INVARIANT: The contract ensures the type invariant 103 // will hold. 104 Error(errno) 105 } 106 107 /// Returns the kernel error code. 108 pub fn to_errno(self) -> core::ffi::c_int { 109 self.0 110 } 111 112 /// Returns the error encoded as a pointer. 113 #[allow(dead_code)] 114 pub(crate) fn to_ptr<T>(self) -> *mut T { 115 // SAFETY: self.0 is a valid error due to its invariant. 116 unsafe { bindings::ERR_PTR(self.0.into()) as *mut _ } 117 } 118 } 119 120 impl From<AllocError> for Error { 121 fn from(_: AllocError) -> Error { 122 code::ENOMEM 123 } 124 } 125 126 impl From<TryFromIntError> for Error { 127 fn from(_: TryFromIntError) -> Error { 128 code::EINVAL 129 } 130 } 131 132 impl From<Utf8Error> for Error { 133 fn from(_: Utf8Error) -> Error { 134 code::EINVAL 135 } 136 } 137 138 impl From<TryReserveError> for Error { 139 fn from(_: TryReserveError) -> Error { 140 code::ENOMEM 141 } 142 } 143 144 impl From<LayoutError> for Error { 145 fn from(_: LayoutError) -> Error { 146 code::ENOMEM 147 } 148 } 149 150 impl From<core::fmt::Error> for Error { 151 fn from(_: core::fmt::Error) -> Error { 152 code::EINVAL 153 } 154 } 155 156 impl From<core::convert::Infallible> for Error { 157 fn from(e: core::convert::Infallible) -> Error { 158 match e {} 159 } 160 } 161 162 /// A [`Result`] with an [`Error`] error type. 163 /// 164 /// To be used as the return type for functions that may fail. 165 /// 166 /// # Error codes in C and Rust 167 /// 168 /// In C, it is common that functions indicate success or failure through 169 /// their return value; modifying or returning extra data through non-`const` 170 /// pointer parameters. In particular, in the kernel, functions that may fail 171 /// typically return an `int` that represents a generic error code. We model 172 /// those as [`Error`]. 173 /// 174 /// In Rust, it is idiomatic to model functions that may fail as returning 175 /// a [`Result`]. Since in the kernel many functions return an error code, 176 /// [`Result`] is a type alias for a [`core::result::Result`] that uses 177 /// [`Error`] as its error type. 178 /// 179 /// Note that even if a function does not return anything when it succeeds, 180 /// it should still be modeled as returning a `Result` rather than 181 /// just an [`Error`]. 182 pub type Result<T = ()> = core::result::Result<T, Error>; 183