rust/util/src/error.rs - qemu - Git at Google

 // SPDX-License-Identifier: GPL-2.0-or-later

 //! Error propagation for QEMU Rust code
 //!
 //! This module contains [`Error`], the bridge between Rust errors and
 //! [`Result`](std::result::Result)s and QEMU's C [`Error`](bindings::Error)
 //! struct.
 //!
 //! For FFI code, [`Error`] provides functions to simplify conversion between
 //! the Rust ([`Result<>`](std::result::Result)) and C (`Error**`) conventions:
 //!
 //! * [`ok_or_propagate`](crate::Error::ok_or_propagate),
 //!   [`bool_or_propagate`](crate::Error::bool_or_propagate),
 //!   [`ptr_or_propagate`](crate::Error::ptr_or_propagate) can be used to build
 //!   a C return value while also propagating an error condition
 //!
 //! * [`with_errp`](crate::Error::with_errp) can be used to build a `Result`
 //!
 //! This module is most commonly used at the boundary between C and Rust code;
 //! other code will usually access it through the
 //! [`utils::Result`](crate::Result) type alias, and will use the
 //! [`std::error::Error`] interface to let C errors participate in Rust's error
 //! handling functionality.
 //!
 //! Rust code can also create use this module to create an error object that
 //! will be passed up to C code, though in most cases this will be done
 //! transparently through the `?` operator.  Errors can be constructed from a
 //! simple error string, from an [`anyhow::Error`] to pass any other Rust error
 //! type up to C code, or from a combination of the two.
 //!
 //! The third case, corresponding to [`Error::with_error`], is the only one that
 //! requires mentioning [`utils::Error`](crate::Error) explicitly.  Similar
 //! to how QEMU's C code handles errno values, the string and the
 //! `anyhow::Error` object will be concatenated with `:` as the separator.

 use std::{
     borrow::Cow,
     ffi::{c_char, c_int, c_void, CStr},
     fmt::{self, Display},
     ops::Deref,
     panic,
     ptr::{self, addr_of_mut},
 };

 use foreign::{prelude::*, OwnedPointer};

 use crate::bindings;

 pub type Result<T> = std::result::Result<T, Error>;

 #[derive(Debug)]
 pub struct Error {
     cause: anyhow::Error,
     file: &'static str,
     line: u32,
 }

 impl Deref for Error {
     type Target = anyhow::Error;

     fn deref(&self) -> &Self::Target {
         &self.cause
     }
 }

 impl Display for Error {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         Display::fmt(&format_args!("{:#}", self.cause), f)
     }
 }

 impl<E> From<E> for Error
 where
     anyhow::Error: From<E>,
 {
     #[track_caller]
     fn from(src: E) -> Self {
         Self::new(anyhow::Error::from(src))
     }
 }

 impl Error {
     /// Create a new error from an [`anyhow::Error`].
     ///
     /// This wraps the error with QEMU's location tracking information.
     /// Most code should use the `?` operator instead of calling this directly.
     #[track_caller]
     pub fn new(cause: anyhow::Error) -> Self {
         let location = panic::Location::caller();
         Self {
             cause,
             file: location.file(),
             line: location.line(),
         }
     }

     /// Create a new error from a string message.
     ///
     /// This is a convenience wrapper around [`Error::new`] for simple string
     /// errors. Most code should use the [`ensure!`](crate::ensure) macro
     /// instead of calling this directly.
     #[track_caller]
     pub fn msg(src: impl Into<Cow<'static, str>>) -> Self {
         Self::new(anyhow::Error::msg(src.into()))
     }

     #[track_caller]
     #[doc(hidden)]
     #[inline(always)]
     pub fn format(args: fmt::Arguments) -> Self {
         // anyhow::Error::msg will allocate anyway, might as well let fmt::format doit.
         let msg = fmt::format(args);
         Self::new(anyhow::Error::msg(msg))
     }

     /// Create a new error, prepending `msg` to the
     /// description of `cause`
     #[track_caller]
     pub fn with_error(msg: impl Into<Cow<'static, str>>, cause: impl Into<anyhow::Error>) -> Self {
         fn do_with_error(
             msg: Cow<'static, str>,
             cause: anyhow::Error,
             location: &'static panic::Location<'static>,
         ) -> Error {
             Error {
                 cause: cause.context(msg),
                 file: location.file(),
                 line: location.line(),
             }
         }
         do_with_error(msg.into(), cause.into(), panic::Location::caller())
     }

     /// Consume a result, returning `false` if it is an error and
     /// `true` if it is successful.  The error is propagated into
     /// `errp` like the C API `error_propagate` would do.
     ///
     /// # Safety
     ///
     /// `errp` must be a valid argument to `error_propagate`;
     /// typically it is received from C code and need not be
     /// checked further at the Rust↔C boundary.
     pub unsafe fn bool_or_propagate(result: Result<()>, errp: *mut *mut bindings::Error) -> bool {
         // SAFETY: caller guarantees errp is valid
         unsafe { Self::ok_or_propagate(result, errp) }.is_some()
     }

     /// Consume a result, returning a `NULL` pointer if it is an error and
     /// a C representation of the contents if it is successful.  This is
     /// similar to the C API `error_propagate`, but it panics if `*errp`
     /// is not `NULL`.
     ///
     /// # Safety
     ///
     /// `errp` must be a valid argument to `error_propagate`;
     /// typically it is received from C code and need not be
     /// checked further at the Rust↔C boundary.
     ///
     /// See [`propagate`](Error::propagate) for more information.
     #[must_use]
     pub unsafe fn ptr_or_propagate<T: CloneToForeign>(
         result: Result<T>,
         errp: *mut *mut bindings::Error,
     ) -> *mut T::Foreign {
         // SAFETY: caller guarantees errp is valid
         unsafe { Self::ok_or_propagate(result, errp) }.clone_to_foreign_ptr()
     }

     /// Consume a result in the same way as `self.ok()`, but also propagate
     /// a possible error into `errp`.  This is similar to the C API
     /// `error_propagate`, but it panics if `*errp` is not `NULL`.
     ///
     /// # Safety
     ///
     /// `errp` must be a valid argument to `error_propagate`;
     /// typically it is received from C code and need not be
     /// checked further at the Rust↔C boundary.
     ///
     /// See [`propagate`](Error::propagate) for more information.
     pub unsafe fn ok_or_propagate<T>(
         result: Result<T>,
         errp: *mut *mut bindings::Error,
     ) -> Option<T> {
         result.map_err(|err| unsafe { err.propagate(errp) }).ok()
     }

     /// Equivalent of the C function `error_propagate`.  Fill `*errp`
     /// with the information container in `self` if `errp` is not NULL;
     /// then consume it.
     ///
     /// This is similar to the C API `error_propagate`, but it panics if
     /// `*errp` is not `NULL`.
     ///
     /// # Safety
     ///
     /// `errp` must be a valid argument to `error_propagate`; it can be
     /// `NULL` or it can point to any of:
     /// * `error_abort`
     /// * `error_fatal`
     /// * a local variable of (C) type `Error *`
     ///
     /// Typically `errp` is received from C code and need not be
     /// checked further at the Rust↔C boundary.
     pub unsafe fn propagate(self, errp: *mut *mut bindings::Error) {
         if errp.is_null() {
             return;
         }

         // SAFETY: caller guarantees that errp and *errp are valid
         unsafe {
             assert_eq!(*errp, ptr::null_mut());
             bindings::error_propagate(errp, self.clone_to_foreign_ptr());
         }
     }

     /// Pass a C `Error*` to the closure, and convert the result
     /// (either the return value of the closure, or the error)
     /// into a Rust `Result`.
     ///
     /// # Safety
     ///
     /// One exit from `f`, `c_error` must be unchanged or point to a
     /// valid C [`struct Error`](bindings::Error).
     pub unsafe fn with_errp<T, F: FnOnce(&mut *mut bindings::Error) -> T>(f: F) -> Result<T> {
         let mut c_error: *mut bindings::Error = ptr::null_mut();

         // SAFETY: guaranteed by the postcondition of `f`
         match (f(&mut c_error), unsafe { c_error.into_native() }) {
             (result, None) => Ok(result),
             (_, Some(err)) => Err(err),
         }
     }
 }

 /// Extension trait for `std::result::Result`, providing extra
 /// methods when the error type can be converted into a QEMU
 /// Error.
 pub trait ResultExt {
     /// The success type `T` in `Result<T, E>`.
     type OkType;

     /// Report a fatal error and exit QEMU, or return the success value.
     /// Note that, unlike [`unwrap()`](std::result::Result::unwrap), this
     /// is not an abort and can be used for user errors.
     fn unwrap_fatal(self) -> Self::OkType;
 }

 impl<T, E> ResultExt for std::result::Result<T, E>
 where
     Error: From<E>,
 {
     type OkType = T;

     fn unwrap_fatal(self) -> T {
         // SAFETY: errp is valid
         self.map_err(|err| unsafe {
             Error::from(err).propagate(addr_of_mut!(bindings::error_fatal))
         })
         .unwrap()
     }
 }

 impl FreeForeign for Error {
     type Foreign = bindings::Error;

     unsafe fn free_foreign(p: *mut bindings::Error) {
         // SAFETY: caller guarantees p is valid
         unsafe {
             bindings::error_free(p);
         }
     }
 }

 impl CloneToForeign for Error {
     fn clone_to_foreign(&self) -> OwnedPointer<Self> {
         // SAFETY: all arguments are controlled by this function
         unsafe {
             let err: *mut c_void = libc::malloc(std::mem::size_of::<bindings::Error>());
             let err: &mut bindings::Error = &mut *err.cast();
             *err = bindings::Error {
                 msg: format!("{self}").clone_to_foreign_ptr(),
                 err_class: bindings::ERROR_CLASS_GENERIC_ERROR,
                 src_len: self.file.len() as c_int,
                 src: self.file.as_ptr().cast::<c_char>(),
                 line: self.line as c_int,
                 func: ptr::null_mut(),
                 hint: ptr::null_mut(),
             };
             OwnedPointer::new(err)
         }
     }
 }

 impl FromForeign for Error {
     unsafe fn cloned_from_foreign(c_error: *const bindings::Error) -> Self {
         // SAFETY: caller guarantees c_error is valid
         unsafe {
             let error = &*c_error;
             let file = if error.src_len < 0 {
                 // NUL-terminated
                 CStr::from_ptr(error.src).to_str()
             } else {
                 // Can become str::from_utf8 with Rust 1.87.0
                 std::str::from_utf8(std::slice::from_raw_parts(
                     &*error.src.cast::<u8>(),
                     error.src_len as usize,
                 ))
             };

             Error {
                 cause: anyhow::Error::msg(String::cloned_from_foreign(error.msg)),
                 file: file.unwrap(),
                 line: error.line as u32,
             }
         }
     }
 }

 /// Ensure that a condition is true, returning an error if it is false.
 ///
 /// This macro is similar to [`anyhow::ensure`] but returns a QEMU [`Result`].
 /// If the condition evaluates to `false`, the macro returns early with an error
 /// constructed from the provided message.
 ///
 /// # Examples
 ///
 /// ```
 /// # use util::{ensure, Result};
 /// # fn check_positive(x: i32) -> Result<()> {
 /// ensure!(x > 0, "value must be positive");
 /// #   Ok(())
 /// # }
 /// ```
 ///
 /// ```
 /// # use util::{ensure, Result};
 /// # const MIN: i32 = 123;
 /// # const MAX: i32 = 456;
 /// # fn check_range(x: i32) -> Result<()> {
 /// ensure!(
 ///     x >= MIN && x <= MAX,
 ///     "{} not between {} and {}",
 ///     x,
 ///     MIN,
 ///     MAX
 /// );
 /// #   Ok(())
 /// # }
 /// ```
 #[macro_export]
 macro_rules! ensure {
     ($cond:expr, $fmt:literal, $($arg:tt)*) => {
         if !$cond {
             let e = $crate::Error::format(format_args!($fmt, $($arg)*));
             return $crate::Result::Err(e);
         }
     };
     ($cond:expr, $err:expr $(,)?) => {
         if !$cond {
             let e = $crate::Error::msg($err);
             return $crate::Result::Err(e);
         }
     };
 }

 #[cfg(test)]
 mod tests {
     use std::ffi::CStr;

     use anyhow::anyhow;
     use common::assert_match;
     use foreign::OwnedPointer;

     use super::*;

     #[track_caller]
     fn error_for_test(msg: &CStr) -> OwnedPointer<Error> {
         // SAFETY: all arguments are controlled by this function
         let location = panic::Location::caller();
         unsafe {
             let err: *mut c_void = libc::malloc(std::mem::size_of::<bindings::Error>());
             let err: &mut bindings::Error = &mut *err.cast();
             *err = bindings::Error {
                 msg: msg.clone_to_foreign_ptr(),
                 err_class: bindings::ERROR_CLASS_GENERIC_ERROR,
                 src_len: location.file().len() as c_int,
                 src: location.file().as_ptr().cast::<c_char>(),
                 line: location.line() as c_int,
                 func: ptr::null_mut(),
                 hint: ptr::null_mut(),
             };
             OwnedPointer::new(err)
         }
     }

     unsafe fn error_get_pretty<'a>(local_err: *mut bindings::Error) -> &'a CStr {
         unsafe { CStr::from_ptr(bindings::error_get_pretty(local_err)) }
     }

     #[test]
     fn test_display() {
         assert_eq!(&*format!("{}", Error::msg("msg")), "msg");
         assert_eq!(&*format!("{}", Error::msg("msg".to_owned())), "msg");
         assert_eq!(&*format!("{}", Error::from(anyhow!("msg"))), "msg");

         assert_eq!(
             &*format!("{}", Error::with_error("msg", anyhow!("cause"))),
             "msg: cause"
         );
     }

     #[test]
     fn test_bool_or_propagate() {
         unsafe {
             let mut local_err: *mut bindings::Error = ptr::null_mut();

             assert!(Error::bool_or_propagate(Ok(()), &mut local_err));
             assert_eq!(local_err, ptr::null_mut());

             let my_err = Error::msg("msg");
             assert!(!Error::bool_or_propagate(Err(my_err), &mut local_err));
             assert_ne!(local_err, ptr::null_mut());
             assert_eq!(error_get_pretty(local_err), c"msg");
             bindings::error_free(local_err);
         }
     }

     #[test]
     fn test_ptr_or_propagate() {
         unsafe {
             let mut local_err: *mut bindings::Error = ptr::null_mut();

             let ret = Error::ptr_or_propagate(Ok("abc".to_owned()), &mut local_err);
             assert_eq!(String::from_foreign(ret), "abc");
             assert_eq!(local_err, ptr::null_mut());

             let my_err = Error::msg("msg");
             assert_eq!(
                 Error::ptr_or_propagate(Err::<String, _>(my_err), &mut local_err),
                 ptr::null_mut()
             );
             assert_ne!(local_err, ptr::null_mut());
             assert_eq!(error_get_pretty(local_err), c"msg");
             bindings::error_free(local_err);
         }
     }

     #[test]
     fn test_with_errp() {
         unsafe {
             let result = Error::with_errp(|_errp| true);
             assert_match!(result, Ok(true));

             let err = Error::with_errp(|errp| {
                 *errp = error_for_test(c"msg").into_inner();
                 false
             })
             .unwrap_err();
             assert_eq!(&*format!("{err}"), "msg");
         }
     }
 }
	// SPDX-License-Identifier: GPL-2.0-or-later

	//! Error propagation for QEMU Rust code
	//!
	//! This module contains [`Error`], the bridge between Rust errors and
	//! [`Result`](std::result::Result)s and QEMU's C [`Error`](bindings::Error)
	//! struct.
	//!
	//! For FFI code, [`Error`] provides functions to simplify conversion between
	//! the Rust ([`Result<>`](std::result::Result)) and C (`Error**`) conventions:
	//!
	//! * [`ok_or_propagate`](crate::Error::ok_or_propagate),
	//! [`bool_or_propagate`](crate::Error::bool_or_propagate),
	//! [`ptr_or_propagate`](crate::Error::ptr_or_propagate) can be used to build
	//! a C return value while also propagating an error condition
	//!
	//! * [`with_errp`](crate::Error::with_errp) can be used to build a `Result`
	//!
	//! This module is most commonly used at the boundary between C and Rust code;
	//! other code will usually access it through the
	//! [`utils::Result`](crate::Result) type alias, and will use the
	//! [`std::error::Error`] interface to let C errors participate in Rust's error
	//! handling functionality.
	//!
	//! Rust code can also create use this module to create an error object that
	//! will be passed up to C code, though in most cases this will be done
	//! transparently through the `?` operator. Errors can be constructed from a
	//! simple error string, from an [`anyhow::Error`] to pass any other Rust error
	//! type up to C code, or from a combination of the two.
	//!
	//! The third case, corresponding to [`Error::with_error`], is the only one that
	//! requires mentioning [`utils::Error`](crate::Error) explicitly. Similar
	//! to how QEMU's C code handles errno values, the string and the
	//! `anyhow::Error` object will be concatenated with `:` as the separator.

	use std::{
	borrow::Cow,
	ffi::{c_char, c_int, c_void, CStr},
	fmt::{self, Display},
	ops::Deref,
	panic,
	ptr::{self, addr_of_mut},
	};

	use foreign::{prelude::*, OwnedPointer};

	use crate::bindings;

	pub type Result<T> = std::result::Result<T, Error>;

	#[derive(Debug)]
	pub struct Error {
	cause: anyhow::Error,
	file: &'static str,
	line: u32,
	}

	impl Deref for Error {
	type Target = anyhow::Error;

	fn deref(&self) -> &Self::Target {
	&self.cause
	}
	}

	impl Display for Error {
	fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
	Display::fmt(&format_args!("{:#}", self.cause), f)
	}
	}

	impl<E> From<E> for Error
	where
	anyhow::Error: From<E>,
	{
	#[track_caller]
	fn from(src: E) -> Self {
	Self::new(anyhow::Error::from(src))
	}
	}

	impl Error {
	/// Create a new error from an [`anyhow::Error`].
	///
	/// This wraps the error with QEMU's location tracking information.
	/// Most code should use the `?` operator instead of calling this directly.
	#[track_caller]
	pub fn new(cause: anyhow::Error) -> Self {
	let location = panic::Location::caller();
	Self {
	cause,
	file: location.file(),
	line: location.line(),
	}
	}

	/// Create a new error from a string message.
	///
	/// This is a convenience wrapper around [`Error::new`] for simple string
	/// errors. Most code should use the [`ensure!`](crate::ensure) macro
	/// instead of calling this directly.
	#[track_caller]
	pub fn msg(src: impl Into<Cow<'static, str>>) -> Self {
	Self::new(anyhow::Error::msg(src.into()))
	}

	#[track_caller]
	#[doc(hidden)]
	#[inline(always)]
	pub fn format(args: fmt::Arguments) -> Self {
	// anyhow::Error::msg will allocate anyway, might as well let fmt::format doit.
	let msg = fmt::format(args);
	Self::new(anyhow::Error::msg(msg))
	}

	/// Create a new error, prepending `msg` to the
	/// description of `cause`
	#[track_caller]
	pub fn with_error(msg: impl Into<Cow<'static, str>>, cause: impl Into<anyhow::Error>) -> Self {
	fn do_with_error(
	msg: Cow<'static, str>,
	cause: anyhow::Error,
	location: &'static panic::Location<'static>,
	) -> Error {
	Error {
	cause: cause.context(msg),
	file: location.file(),
	line: location.line(),
	}
	}
	do_with_error(msg.into(), cause.into(), panic::Location::caller())
	}

	/// Consume a result, returning `false` if it is an error and
	/// `true` if it is successful. The error is propagated into
	/// `errp` like the C API `error_propagate` would do.
	///
	/// # Safety
	///
	/// `errp` must be a valid argument to `error_propagate`;
	/// typically it is received from C code and need not be
	/// checked further at the Rust↔C boundary.
	pub unsafe fn bool_or_propagate(result: Result<()>, errp: mut mut bindings::Error) -> bool {
	// SAFETY: caller guarantees errp is valid
	unsafe { Self::ok_or_propagate(result, errp) }.is_some()
	}

	/// Consume a result, returning a `NULL` pointer if it is an error and
	/// a C representation of the contents if it is successful. This is
	/// similar to the C API `error_propagate`, but it panics if `*errp`
	/// is not `NULL`.
	///
	/// # Safety
	///
	/// `errp` must be a valid argument to `error_propagate`;
	/// typically it is received from C code and need not be
	/// checked further at the Rust↔C boundary.
	///
	/// See [`propagate`](Error::propagate) for more information.
	#[must_use]
	pub unsafe fn ptr_or_propagate<T: CloneToForeign>(
	result: Result<T>,
	errp: mut mut bindings::Error,
	) -> *mut T::Foreign {
	// SAFETY: caller guarantees errp is valid
	unsafe { Self::ok_or_propagate(result, errp) }.clone_to_foreign_ptr()
	}

	/// Consume a result in the same way as `self.ok()`, but also propagate
	/// a possible error into `errp`. This is similar to the C API
	/// `error_propagate`, but it panics if `*errp` is not `NULL`.
	///
	/// # Safety
	///
	/// `errp` must be a valid argument to `error_propagate`;
	/// typically it is received from C code and need not be
	/// checked further at the Rust↔C boundary.
	///
	/// See [`propagate`](Error::propagate) for more information.
	pub unsafe fn ok_or_propagate<T>(
	result: Result<T>,
	errp: mut mut bindings::Error,
	) -> Option<T> {
	result.map_err(\|err\| unsafe { err.propagate(errp) }).ok()
	}

	/// Equivalent of the C function `error_propagate`. Fill `*errp`
	/// with the information container in `self` if `errp` is not NULL;
	/// then consume it.
	///
	/// This is similar to the C API `error_propagate`, but it panics if
	/// `*errp` is not `NULL`.
	///
	/// # Safety
	///
	/// `errp` must be a valid argument to `error_propagate`; it can be
	/// `NULL` or it can point to any of:
	/// * `error_abort`
	/// * `error_fatal`
	/// * a local variable of (C) type `Error *`
	///
	/// Typically `errp` is received from C code and need not be
	/// checked further at the Rust↔C boundary.
	pub unsafe fn propagate(self, errp: mut mut bindings::Error) {
	if errp.is_null() {
	return;
	}

	// SAFETY: caller guarantees that errp and *errp are valid
	unsafe {
	assert_eq!(*errp, ptr::null_mut());
	bindings::error_propagate(errp, self.clone_to_foreign_ptr());
	}
	}

	/// Pass a C `Error*` to the closure, and convert the result
	/// (either the return value of the closure, or the error)
	/// into a Rust `Result`.
	///
	/// # Safety
	///
	/// One exit from `f`, `c_error` must be unchanged or point to a
	/// valid C [`struct Error`](bindings::Error).
	pub unsafe fn with_errp<T, F: FnOnce(&mut *mut bindings::Error) -> T>(f: F) -> Result<T> {
	let mut c_error: *mut bindings::Error = ptr::null_mut();

	// SAFETY: guaranteed by the postcondition of `f`
	match (f(&mut c_error), unsafe { c_error.into_native() }) {
	(result, None) => Ok(result),
	(_, Some(err)) => Err(err),
	}
	}
	}

	/// Extension trait for `std::result::Result`, providing extra
	/// methods when the error type can be converted into a QEMU
	/// Error.
	pub trait ResultExt {
	/// The success type `T` in `Result<T, E>`.
	type OkType;

	/// Report a fatal error and exit QEMU, or return the success value.
	/// Note that, unlike [`unwrap()`](std::result::Result::unwrap), this
	/// is not an abort and can be used for user errors.
	fn unwrap_fatal(self) -> Self::OkType;
	}

	impl<T, E> ResultExt for std::result::Result<T, E>
	where
	Error: From<E>,
	{
	type OkType = T;

	fn unwrap_fatal(self) -> T {
	// SAFETY: errp is valid
	self.map_err(\|err\| unsafe {
	Error::from(err).propagate(addr_of_mut!(bindings::error_fatal))
	})
	.unwrap()
	}
	}

	impl FreeForeign for Error {
	type Foreign = bindings::Error;

	unsafe fn free_foreign(p: *mut bindings::Error) {
	// SAFETY: caller guarantees p is valid
	unsafe {
	bindings::error_free(p);
	}
	}
	}

	impl CloneToForeign for Error {
	fn clone_to_foreign(&self) -> OwnedPointer<Self> {
	// SAFETY: all arguments are controlled by this function
	unsafe {
	let err: *mut c_void = libc::malloc(std::mem::size_of::<bindings::Error>());
	let err: &mut bindings::Error = &mut *err.cast();
	*err = bindings::Error {
	msg: format!("{self}").clone_to_foreign_ptr(),
	err_class: bindings::ERROR_CLASS_GENERIC_ERROR,
	src_len: self.file.len() as c_int,
	src: self.file.as_ptr().cast::<c_char>(),
	line: self.line as c_int,
	func: ptr::null_mut(),
	hint: ptr::null_mut(),
	};
	OwnedPointer::new(err)
	}
	}
	}

	impl FromForeign for Error {
	unsafe fn cloned_from_foreign(c_error: *const bindings::Error) -> Self {
	// SAFETY: caller guarantees c_error is valid
	unsafe {
	let error = &*c_error;
	let file = if error.src_len < 0 {
	// NUL-terminated
	CStr::from_ptr(error.src).to_str()
	} else {
	// Can become str::from_utf8 with Rust 1.87.0
	std::str::from_utf8(std::slice::from_raw_parts(
	&*error.src.cast::<u8>(),
	error.src_len as usize,
	))
	};

	Error {
	cause: anyhow::Error::msg(String::cloned_from_foreign(error.msg)),
	file: file.unwrap(),
	line: error.line as u32,
	}
	}
	}
	}

	/// Ensure that a condition is true, returning an error if it is false.
	///
	/// This macro is similar to [`anyhow::ensure`] but returns a QEMU [`Result`].
	/// If the condition evaluates to `false`, the macro returns early with an error
	/// constructed from the provided message.
	///
	/// # Examples
	///
	/// ```
	/// # use util::{ensure, Result};
	/// # fn check_positive(x: i32) -> Result<()> {
	/// ensure!(x > 0, "value must be positive");
	/// # Ok(())
	/// # }
	/// ```
	///
	/// ```
	/// # use util::{ensure, Result};
	/// # const MIN: i32 = 123;
	/// # const MAX: i32 = 456;
	/// # fn check_range(x: i32) -> Result<()> {
	/// ensure!(
	/// x >= MIN && x <= MAX,
	/// "{} not between {} and {}",
	/// x,
	/// MIN,
	/// MAX
	/// );
	/// # Ok(())
	/// # }
	/// ```
	#[macro_export]
	macro_rules! ensure {
	($cond:expr, $fmt:literal, $($arg:tt)*) => {
	if !$cond {
	let e = $crate::Error::format(format_args!($fmt, $($arg)*));
	return $crate::Result::Err(e);
	}
	};
	($cond:expr, $err:expr $(,)?) => {
	if !$cond {
	let e = $crate::Error::msg($err);
	return $crate::Result::Err(e);
	}
	};
	}

	#[cfg(test)]
	mod tests {
	use std::ffi::CStr;

	use anyhow::anyhow;
	use common::assert_match;
	use foreign::OwnedPointer;

	use super::*;

	#[track_caller]
	fn error_for_test(msg: &CStr) -> OwnedPointer<Error> {
	// SAFETY: all arguments are controlled by this function
	let location = panic::Location::caller();
	unsafe {
	let err: *mut c_void = libc::malloc(std::mem::size_of::<bindings::Error>());
	let err: &mut bindings::Error = &mut *err.cast();
	*err = bindings::Error {
	msg: msg.clone_to_foreign_ptr(),
	err_class: bindings::ERROR_CLASS_GENERIC_ERROR,
	src_len: location.file().len() as c_int,
	src: location.file().as_ptr().cast::<c_char>(),
	line: location.line() as c_int,
	func: ptr::null_mut(),
	hint: ptr::null_mut(),
	};
	OwnedPointer::new(err)
	}
	}

	unsafe fn error_get_pretty<'a>(local_err: *mut bindings::Error) -> &'a CStr {
	unsafe { CStr::from_ptr(bindings::error_get_pretty(local_err)) }
	}

	#[test]
	fn test_display() {
	assert_eq!(&*format!("{}", Error::msg("msg")), "msg");
	assert_eq!(&*format!("{}", Error::msg("msg".to_owned())), "msg");
	assert_eq!(&*format!("{}", Error::from(anyhow!("msg"))), "msg");

	assert_eq!(
	&*format!("{}", Error::with_error("msg", anyhow!("cause"))),
	"msg: cause"
	);
	}

	#[test]
	fn test_bool_or_propagate() {
	unsafe {
	let mut local_err: *mut bindings::Error = ptr::null_mut();

	assert!(Error::bool_or_propagate(Ok(()), &mut local_err));
	assert_eq!(local_err, ptr::null_mut());

	let my_err = Error::msg("msg");
	assert!(!Error::bool_or_propagate(Err(my_err), &mut local_err));
	assert_ne!(local_err, ptr::null_mut());
	assert_eq!(error_get_pretty(local_err), c"msg");
	bindings::error_free(local_err);
	}
	}

	#[test]
	fn test_ptr_or_propagate() {
	unsafe {
	let mut local_err: *mut bindings::Error = ptr::null_mut();

	let ret = Error::ptr_or_propagate(Ok("abc".to_owned()), &mut local_err);
	assert_eq!(String::from_foreign(ret), "abc");
	assert_eq!(local_err, ptr::null_mut());

	let my_err = Error::msg("msg");
	assert_eq!(
	Error::ptr_or_propagate(Err::<String, _>(my_err), &mut local_err),
	ptr::null_mut()
	);
	assert_ne!(local_err, ptr::null_mut());
	assert_eq!(error_get_pretty(local_err), c"msg");
	bindings::error_free(local_err);
	}
	}

	#[test]
	fn test_with_errp() {
	unsafe {
	let result = Error::with_errp(\|_errp\| true);
	assert_match!(result, Ok(true));

	let err = Error::with_errp(\|errp\| {
	*errp = error_for_test(c"msg").into_inner();
	false
	})
	.unwrap_err();
	assert_eq!(&*format!("{err}"), "msg");
	}
	}
	}