Something went wrong. Try again.
(I'm so sorry!) Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349// SPDX-License-Identifier: (BSD-2-Clause OR Apache-2.0) OR MIT//// Copyright 2024 The Fuchsia Authors//// Licensed under the 2-Clause BSD License <LICENSE-BSD or// https://opensource.org/license/bsd-2-clause>, Apache License, Version 2.0// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.// This file may not be copied, modified, or distributed except according to// those terms.
//! Types related to error reporting.//!//! ## Single failure mode errors//!//! Generally speaking, zerocopy's conversions may fail for one of up to three//! reasons://! - [`AlignmentError`]: the conversion source was improperly aligned//! - [`SizeError`]: the conversion source was of incorrect size//! - [`ValidityError`]: the conversion source contained invalid data//!//! Methods that only have one failure mode, like//! [`FromBytes::read_from_bytes`], return that mode's corresponding error type//! directly.//!//! ## Compound errors//!//! Conversion methods that have either two or three possible failure modes//! return one of these error types://! - [`CastError`]: the error type of reference conversions//! - [`TryCastError`]: the error type of fallible reference conversions//! - [`TryReadError`]: the error type of fallible read conversions//!//! ## [`Unaligned`] destination types//!//! For [`Unaligned`] destination types, alignment errors are impossible. All//! compound error types support infallibly discarding the alignment error via//! [`From`] so long as `Dst: Unaligned`. For example, see [`<SizeError as//! From<ConvertError>>::from`][size-error-from].//!//! [size-error-from]: struct.SizeError.html#method.from-1//!//! ## Accessing the conversion source//!//! All error types provide an `into_src` method that converts the error into//! the source value underlying the failed conversion.//!//! ## Display formatting//!//! All error types provide a `Display` implementation that produces a//! human-readable error message. When `debug_assertions` are enabled, these//! error messages are verbose and may include potentially sensitive//! information, including://!//! - the names of the involved types//! - the sizes of the involved types//! - the addresses of the involved types//! - the contents of the involved types//!//! When `debug_assertions` are disabled (as is default for `release` builds),//! such potentially sensitive information is excluded.//!//! In the future, we may support manually configuring this behavior. If you are//! interested in this feature, [let us know on GitHub][issue-1457] so we know//! to prioritize it.//!//! [issue-1457]: https://github.com/google/zerocopy/issues/1457//!//! ## Validation order//!//! Our conversion methods typically check alignment, then size, then bit//! validity. However, we do not guarantee that this is always the case, and//! this behavior may change between releases.//!//! ## `Send`, `Sync`, and `'static`//!//! Our error types are `Send`, `Sync`, and `'static` when their `Src` parameter//! is `Send`, `Sync`, or `'static`, respectively. This can cause issues when an//! error is sent or synchronized across threads; e.g.://!//! ```compile_fail,E0515//! use zerocopy::*;//!//! let result: SizeError<&[u8], u32> = std::thread::spawn(|| {//! let source = &mut [0u8, 1, 2][..];//! // Try (and fail) to read a `u32` from `source`.//! u32::read_from_bytes(source).unwrap_err()//! }).join().unwrap();//! ```//!//! To work around this, use [`map_src`][CastError::map_src] to convert the//! source parameter to an unproblematic type; e.g.://!//! ```//! use zerocopy::*;//!//! let result: SizeError<(), u32> = std::thread::spawn(|| {//! let source = &mut [0u8, 1, 2][..];//! // Try (and fail) to read a `u32` from `source`.//! u32::read_from_bytes(source).unwrap_err()//! // Erase the error source.//! .map_src(drop)//! }).join().unwrap();//! ```//!//! Alternatively, use `.to_string()` to eagerly convert the error into a//! human-readable message; e.g.://!//! ```//! use zerocopy::*;//!//! let result: Result<u32, String> = std::thread::spawn(|| {//! let source = &mut [0u8, 1, 2][..];//! // Try (and fail) to read a `u32` from `source`.//! u32::read_from_bytes(source)//! // Eagerly render the error message.//! .map_err(|err| err.to_string())//! }).join().unwrap();//! ```#[cfg(not(no_zerocopy_core_error_1_81_0))]use core::error::Error;use core::{ convert::Infallible, fmt::{self, Debug, Write}, ops::Deref,};#[cfg(all(no_zerocopy_core_error_1_81_0, any(feature = "std", test)))]use std::error::Error;
use crate::{util::SendSyncPhantomData, KnownLayout, TryFromBytes, Unaligned};#[cfg(doc)]use crate::{FromBytes, Ref};
/// Zerocopy's generic error type.////// Generally speaking, zerocopy's conversions may fail for one of up to three/// reasons:/// - [`AlignmentError`]: the conversion source was improperly aligned/// - [`SizeError`]: the conversion source was of incorrect size/// - [`ValidityError`]: the conversion source contained invalid data////// However, not all conversions produce all errors. For instance,/// [`FromBytes::ref_from_bytes`] may fail due to alignment or size issues, but/// not validity issues. This generic error type captures these/// (im)possibilities via parameterization: `A` is parameterized with/// [`AlignmentError`], `S` is parameterized with [`SizeError`], and `V` is/// parameterized with [`Infallible`].////// Zerocopy never uses this type directly in its API. Rather, we provide three/// pre-parameterized aliases:/// - [`CastError`]: the error type of reference conversions/// - [`TryCastError`]: the error type of fallible reference conversions/// - [`TryReadError`]: the error type of fallible read conversions#[derive(PartialEq, Eq, Clone)]pub enum ConvertError<A, S, V> { /// The conversion source was improperly aligned. Alignment(A), /// The conversion source was of incorrect size. Size(S), /// The conversion source contained invalid data. Validity(V),}
impl<Src, Dst: ?Sized + Unaligned, S, V> From<ConvertError<AlignmentError<Src, Dst>, S, V>> for ConvertError<Infallible, S, V>{ /// Infallibly discards the alignment error from this `ConvertError` since /// `Dst` is unaligned. /// /// Since [`Dst: Unaligned`], it is impossible to encounter an alignment /// error. This method permits discarding that alignment error infallibly /// and replacing it with [`Infallible`]. /// /// [`Dst: Unaligned`]: crate::Unaligned /// /// # Examples /// /// ``` /// use core::convert::Infallible; /// use zerocopy::*; /// # use zerocopy_derive::*; /// /// #[derive(TryFromBytes, KnownLayout, Unaligned, Immutable)] /// #[repr(C, packed)] /// struct Bools { /// one: bool, /// two: bool, /// many: [bool], /// } /// /// impl Bools { /// fn parse(bytes: &[u8]) -> Result<&Bools, AlignedTryCastError<&[u8], Bools>> { /// // Since `Bools: Unaligned`, we can infallibly discard /// // the alignment error. /// Bools::try_ref_from_bytes(bytes).map_err(Into::into) /// } /// } /// ``` #[inline] fn from(err: ConvertError<AlignmentError<Src, Dst>, S, V>) -> ConvertError<Infallible, S, V> { match err { #[allow(unreachable_code)] ConvertError::Alignment(e) => match Infallible::from(e) {}, ConvertError::Size(e) => ConvertError::Size(e), ConvertError::Validity(e) => ConvertError::Validity(e), } }}
impl<A: fmt::Debug, S: fmt::Debug, V: fmt::Debug> fmt::Debug for ConvertError<A, S, V> { #[inline] fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { Self::Alignment(e) => f.debug_tuple("Alignment").field(e).finish(), Self::Size(e) => f.debug_tuple("Size").field(e).finish(), Self::Validity(e) => f.debug_tuple("Validity").field(e).finish(), } }}
/// Produces a human-readable error message.////// The message differs between debug and release builds. When/// `debug_assertions` are enabled, this message is verbose and includes/// potentially sensitive information.impl<A: fmt::Display, S: fmt::Display, V: fmt::Display> fmt::Display for ConvertError<A, S, V> { #[inline] fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { Self::Alignment(e) => e.fmt(f), Self::Size(e) => e.fmt(f), Self::Validity(e) => e.fmt(f), } }}
#[cfg(any(not(no_zerocopy_core_error_1_81_0), feature = "std", test))]#[cfg_attr(doc_cfg, doc(cfg(any(rust = "1.81.0", feature = "std"))))]impl<A, S, V> Error for ConvertError<A, S, V>where A: fmt::Display + fmt::Debug, S: fmt::Display + fmt::Debug, V: fmt::Display + fmt::Debug,{}
/// The error emitted if the conversion source is improperly aligned.pub struct AlignmentError<Src, Dst: ?Sized> { /// The source value involved in the conversion. src: Src, /// The inner destination type involved in the conversion. /// /// INVARIANT: An `AlignmentError` may only be constructed if `Dst`'s /// alignment requirement is greater than one. _dst: SendSyncPhantomData<Dst>,}
impl<Src, Dst: ?Sized> AlignmentError<Src, Dst> { /// # Safety /// /// The caller must ensure that `Dst`'s alignment requirement is greater /// than one. pub(crate) unsafe fn new_unchecked(src: Src) -> Self { // INVARIANT: The caller guarantees that `Dst`'s alignment requirement // is greater than one. Self { src, _dst: SendSyncPhantomData::default() } }
/// Produces the source underlying the failed conversion. #[inline] pub fn into_src(self) -> Src { self.src }
pub(crate) fn with_src<NewSrc>(self, new_src: NewSrc) -> AlignmentError<NewSrc, Dst> { // INVARIANT: `with_src` doesn't change the type of `Dst`, so the // invariant that `Dst`'s alignment requirement is greater than one is // preserved. AlignmentError { src: new_src, _dst: SendSyncPhantomData::default() } }
/// Maps the source value associated with the conversion error. /// /// This can help mitigate [issues with `Send`, `Sync` and `'static` /// bounds][self#send-sync-and-static]. /// /// # Examples /// /// ``` /// use zerocopy::*; /// /// let unaligned = Unalign::new(0u16); /// /// // Attempt to deref `unaligned`. This might fail with an alignment error. /// let maybe_n: Result<&u16, AlignmentError<&Unalign<u16>, u16>> = unaligned.try_deref(); /// /// // Map the error's source to its address as a usize. /// let maybe_n: Result<&u16, AlignmentError<usize, u16>> = maybe_n.map_err(|err| { /// err.map_src(|src| src as *const _ as usize) /// }); /// ``` #[inline] pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> AlignmentError<NewSrc, Dst> { AlignmentError { src: f(self.src), _dst: SendSyncPhantomData::default() } }
pub(crate) fn into<S, V>(self) -> ConvertError<Self, S, V> { ConvertError::Alignment(self) }
/// Format extra details for a verbose, human-readable error message. /// /// This formatting may include potentially sensitive information. fn display_verbose_extras(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result where Src: Deref, Dst: KnownLayout, { #[allow(clippy::as_conversions)] let addr = self.src.deref() as *const _ as *const (); let addr_align = 2usize.pow((crate::util::AsAddress::addr(addr)).trailing_zeros());
f.write_str("\n\nSource type: ")?; f.write_str(core::any::type_name::<Src>())?;
f.write_str("\nSource address: ")?; addr.fmt(f)?; f.write_str(" (a multiple of ")?; addr_align.fmt(f)?; f.write_str(")")?;
f.write_str("\nDestination type: ")?; f.write_str(core::any::type_name::<Dst>())?;
f.write_str("\nDestination alignment: ")?; <Dst as KnownLayout>::LAYOUT.align.get().fmt(f)?;
Ok(()) }}
impl<Src: Clone, Dst: ?Sized> Clone for AlignmentError<Src, Dst> { #[inline] fn clone(&self) -> Self { Self { src: self.src.clone(), _dst: SendSyncPhantomData::default() } }}
impl<Src: PartialEq, Dst: ?Sized> PartialEq for AlignmentError<Src, Dst> { #[inline] fn eq(&self, other: &Self) -> bool { self.src == other.src }}
impl<Src: Eq, Dst: ?Sized> Eq for AlignmentError<Src, Dst> {}
impl<Src, Dst: ?Sized + Unaligned> From<AlignmentError<Src, Dst>> for Infallible { #[inline(always)] fn from(_: AlignmentError<Src, Dst>) -> Infallible { // SAFETY: `AlignmentError`s can only be constructed when `Dst`'s // alignment requirement is greater than one. In this block, `Dst: // Unaligned`, which means that its alignment requirement is equal to // one. Thus, it's not possible to reach here at runtime. unsafe { core::hint::unreachable_unchecked() } }}
#[cfg(test)]impl<Src, Dst> AlignmentError<Src, Dst> { // A convenience constructor so that test code doesn't need to write // `unsafe`. fn new_checked(src: Src) -> AlignmentError<Src, Dst> { assert_ne!(core::mem::align_of::<Dst>(), 1); // SAFETY: The preceding assertion guarantees that `Dst`'s alignment // requirement is greater than one. unsafe { AlignmentError::new_unchecked(src) } }}
impl<Src, Dst: ?Sized> fmt::Debug for AlignmentError<Src, Dst> { #[inline] fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("AlignmentError").finish() }}
/// Produces a human-readable error message.////// The message differs between debug and release builds. When/// `debug_assertions` are enabled, this message is verbose and includes/// potentially sensitive information.impl<Src, Dst: ?Sized> fmt::Display for AlignmentError<Src, Dst>where Src: Deref, Dst: KnownLayout,{ #[inline] fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str("The conversion failed because the address of the source is not a multiple of the alignment of the destination type.")?;
if cfg!(debug_assertions) { self.display_verbose_extras(f) } else { Ok(()) } }}
#[cfg(any(not(no_zerocopy_core_error_1_81_0), feature = "std", test))]#[cfg_attr(doc_cfg, doc(cfg(any(rust = "1.81.0", feature = "std"))))]impl<Src, Dst: ?Sized> Error for AlignmentError<Src, Dst>where Src: Deref, Dst: KnownLayout,{}
impl<Src, Dst: ?Sized, S, V> From<AlignmentError<Src, Dst>> for ConvertError<AlignmentError<Src, Dst>, S, V>{ #[inline(always)] fn from(err: AlignmentError<Src, Dst>) -> Self { Self::Alignment(err) }}
/// The error emitted if the conversion source is of incorrect size.pub struct SizeError<Src, Dst: ?Sized> { /// The source value involved in the conversion. src: Src, /// The inner destination type involved in the conversion. _dst: SendSyncPhantomData<Dst>,}
impl<Src, Dst: ?Sized> SizeError<Src, Dst> { pub(crate) fn new(src: Src) -> Self { Self { src, _dst: SendSyncPhantomData::default() } }
/// Produces the source underlying the failed conversion. #[inline] pub fn into_src(self) -> Src { self.src }
/// Sets the source value associated with the conversion error. pub(crate) fn with_src<NewSrc>(self, new_src: NewSrc) -> SizeError<NewSrc, Dst> { SizeError { src: new_src, _dst: SendSyncPhantomData::default() } }
/// Maps the source value associated with the conversion error. /// /// This can help mitigate [issues with `Send`, `Sync` and `'static` /// bounds][self#send-sync-and-static]. /// /// # Examples /// /// ``` /// use zerocopy::*; /// /// let source: [u8; 3] = [0, 1, 2]; /// /// // Try to read a `u32` from `source`. This will fail because there are insufficient /// // bytes in `source`. /// let maybe_u32: Result<u32, SizeError<&[u8], u32>> = u32::read_from_bytes(&source[..]); /// /// // Map the error's source to its size. /// let maybe_u32: Result<u32, SizeError<usize, u32>> = maybe_u32.map_err(|err| { /// err.map_src(|src| src.len()) /// }); /// ``` #[inline] pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> SizeError<NewSrc, Dst> { SizeError { src: f(self.src), _dst: SendSyncPhantomData::default() } }
/// Sets the destination type associated with the conversion error. pub(crate) fn with_dst<NewDst: ?Sized>(self) -> SizeError<Src, NewDst> { SizeError { src: self.src, _dst: SendSyncPhantomData::default() } }
/// Converts the error into a general [`ConvertError`]. pub(crate) fn into<A, V>(self) -> ConvertError<A, Self, V> { ConvertError::Size(self) }
/// Format extra details for a verbose, human-readable error message. /// /// This formatting may include potentially sensitive information. fn display_verbose_extras(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result where Src: Deref, Dst: KnownLayout, { // include the source type f.write_str("\nSource type: ")?; f.write_str(core::any::type_name::<Src>())?;
// include the source.deref() size let src_size = core::mem::size_of_val(&*self.src); f.write_str("\nSource size: ")?; src_size.fmt(f)?; f.write_str(" byte")?; if src_size != 1 { f.write_char('s')?; }
// if `Dst` is `Sized`, include the `Dst` size if let crate::SizeInfo::Sized { size } = Dst::LAYOUT.size_info { f.write_str("\nDestination size: ")?; size.fmt(f)?; f.write_str(" byte")?; if size != 1 { f.write_char('s')?; } }
// include the destination type f.write_str("\nDestination type: ")?; f.write_str(core::any::type_name::<Dst>())?;
Ok(()) }}
impl<Src: Clone, Dst: ?Sized> Clone for SizeError<Src, Dst> { #[inline] fn clone(&self) -> Self { Self { src: self.src.clone(), _dst: SendSyncPhantomData::default() } }}
impl<Src: PartialEq, Dst: ?Sized> PartialEq for SizeError<Src, Dst> { #[inline] fn eq(&self, other: &Self) -> bool { self.src == other.src }}
impl<Src: Eq, Dst: ?Sized> Eq for SizeError<Src, Dst> {}
impl<Src, Dst: ?Sized> fmt::Debug for SizeError<Src, Dst> { #[inline] fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("SizeError").finish() }}
/// Produces a human-readable error message.////// The message differs between debug and release builds. When/// `debug_assertions` are enabled, this message is verbose and includes/// potentially sensitive information.impl<Src, Dst: ?Sized> fmt::Display for SizeError<Src, Dst>where Src: Deref, Dst: KnownLayout,{ #[inline] fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str("The conversion failed because the source was incorrectly sized to complete the conversion into the destination type.")?; if cfg!(debug_assertions) { f.write_str("\n")?; self.display_verbose_extras(f)?; } Ok(()) }}
#[cfg(any(not(no_zerocopy_core_error_1_81_0), feature = "std", test))]#[cfg_attr(doc_cfg, doc(cfg(any(rust = "1.81.0", feature = "std"))))]impl<Src, Dst: ?Sized> Error for SizeError<Src, Dst>where Src: Deref, Dst: KnownLayout,{}
impl<Src, Dst: ?Sized, A, V> From<SizeError<Src, Dst>> for ConvertError<A, SizeError<Src, Dst>, V> { #[inline(always)] fn from(err: SizeError<Src, Dst>) -> Self { Self::Size(err) }}
/// The error emitted if the conversion source contains invalid data.pub struct ValidityError<Src, Dst: ?Sized + TryFromBytes> { /// The source value involved in the conversion. pub(crate) src: Src, /// The inner destination type involved in the conversion. _dst: SendSyncPhantomData<Dst>,}
impl<Src, Dst: ?Sized + TryFromBytes> ValidityError<Src, Dst> { pub(crate) fn new(src: Src) -> Self { Self { src, _dst: SendSyncPhantomData::default() } }
/// Produces the source underlying the failed conversion. #[inline] pub fn into_src(self) -> Src { self.src }
/// Maps the source value associated with the conversion error. /// /// This can help mitigate [issues with `Send`, `Sync` and `'static` /// bounds][self#send-sync-and-static]. /// /// # Examples /// /// ``` /// use zerocopy::*; /// /// let source: u8 = 42; /// /// // Try to transmute the `source` to a `bool`. This will fail. /// let maybe_bool: Result<bool, ValidityError<u8, bool>> = try_transmute!(source); /// /// // Drop the error's source. /// let maybe_bool: Result<bool, ValidityError<(), bool>> = maybe_bool.map_err(|err| { /// err.map_src(drop) /// }); /// ``` #[inline] pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> ValidityError<NewSrc, Dst> { ValidityError { src: f(self.src), _dst: SendSyncPhantomData::default() } }
/// Converts the error into a general [`ConvertError`]. pub(crate) fn into<A, S>(self) -> ConvertError<A, S, Self> { ConvertError::Validity(self) }
/// Format extra details for a verbose, human-readable error message. /// /// This formatting may include potentially sensitive information. fn display_verbose_extras(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result where Dst: KnownLayout, { f.write_str("Destination type: ")?; f.write_str(core::any::type_name::<Dst>())?; Ok(()) }}
impl<Src: Clone, Dst: ?Sized + TryFromBytes> Clone for ValidityError<Src, Dst> { #[inline] fn clone(&self) -> Self { Self { src: self.src.clone(), _dst: SendSyncPhantomData::default() } }}
// SAFETY: `ValidityError` contains a single `Self::Inner = Src`, and no other// non-ZST fields. `map` passes ownership of `self`'s sole `Self::Inner` to `f`.unsafe impl<Src, NewSrc, Dst> crate::pointer::TryWithError<NewSrc> for crate::ValidityError<Src, Dst>where Dst: TryFromBytes + ?Sized,{ type Inner = Src; type Mapped = crate::ValidityError<NewSrc, Dst>; #[inline] fn map<F: FnOnce(Src) -> NewSrc>(self, f: F) -> Self::Mapped { self.map_src(f) }}
impl<Src: PartialEq, Dst: ?Sized + TryFromBytes> PartialEq for ValidityError<Src, Dst> { #[inline] fn eq(&self, other: &Self) -> bool { self.src == other.src }}
impl<Src: Eq, Dst: ?Sized + TryFromBytes> Eq for ValidityError<Src, Dst> {}
impl<Src, Dst: ?Sized + TryFromBytes> fmt::Debug for ValidityError<Src, Dst> { #[inline] fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("ValidityError").finish() }}
/// Produces a human-readable error message.////// The message differs between debug and release builds. When/// `debug_assertions` are enabled, this message is verbose and includes/// potentially sensitive information.impl<Src, Dst: ?Sized> fmt::Display for ValidityError<Src, Dst>where Dst: KnownLayout + TryFromBytes,{ #[inline] fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str("The conversion failed because the source bytes are not a valid value of the destination type.")?; if cfg!(debug_assertions) { f.write_str("\n\n")?; self.display_verbose_extras(f)?; } Ok(()) }}
#[cfg(any(not(no_zerocopy_core_error_1_81_0), feature = "std", test))]#[cfg_attr(doc_cfg, doc(cfg(any(rust = "1.81.0", feature = "std"))))]impl<Src, Dst: ?Sized> Error for ValidityError<Src, Dst> where Dst: KnownLayout + TryFromBytes {}
impl<Src, Dst: ?Sized + TryFromBytes, A, S> From<ValidityError<Src, Dst>> for ConvertError<A, S, ValidityError<Src, Dst>>{ #[inline(always)] fn from(err: ValidityError<Src, Dst>) -> Self { Self::Validity(err) }}
/// The error type of reference conversions.////// Reference conversions, like [`FromBytes::ref_from_bytes`] may emit/// [alignment](AlignmentError) and [size](SizeError) errors.// Bounds on generic parameters are not enforced in type aliases, but they do// appear in rustdoc.#[allow(type_alias_bounds)]pub type CastError<Src, Dst: ?Sized> = ConvertError<AlignmentError<Src, Dst>, SizeError<Src, Dst>, Infallible>;
impl<Src, Dst: ?Sized> CastError<Src, Dst> { /// Produces the source underlying the failed conversion. #[inline] pub fn into_src(self) -> Src { match self { Self::Alignment(e) => e.src, Self::Size(e) => e.src, Self::Validity(i) => match i {}, } }
/// Sets the source value associated with the conversion error. pub(crate) fn with_src<NewSrc>(self, new_src: NewSrc) -> CastError<NewSrc, Dst> { match self { Self::Alignment(e) => CastError::Alignment(e.with_src(new_src)), Self::Size(e) => CastError::Size(e.with_src(new_src)), Self::Validity(i) => match i {}, } }
/// Maps the source value associated with the conversion error. /// /// This can help mitigate [issues with `Send`, `Sync` and `'static` /// bounds][self#send-sync-and-static]. /// /// # Examples /// /// ``` /// use zerocopy::*; /// /// let source: [u8; 3] = [0, 1, 2]; /// /// // Try to read a `u32` from `source`. This will fail because there are insufficient /// // bytes in `source`. /// let maybe_u32: Result<&u32, CastError<&[u8], u32>> = u32::ref_from_bytes(&source[..]); /// /// // Map the error's source to its size and address. /// let maybe_u32: Result<&u32, CastError<(usize, usize), u32>> = maybe_u32.map_err(|err| { /// err.map_src(|src| (src.len(), src.as_ptr() as usize)) /// }); /// ``` #[inline] pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> CastError<NewSrc, Dst> { match self { Self::Alignment(e) => CastError::Alignment(e.map_src(f)), Self::Size(e) => CastError::Size(e.map_src(f)), Self::Validity(i) => match i {}, } }
/// Converts the error into a general [`ConvertError`]. pub(crate) fn into(self) -> TryCastError<Src, Dst> where Dst: TryFromBytes, { match self { Self::Alignment(e) => TryCastError::Alignment(e), Self::Size(e) => TryCastError::Size(e), Self::Validity(i) => match i {}, } }}
// SAFETY: `CastError` is either a single `AlignmentError` or a single// `SizeError`. In either case, it contains a single `Self::Inner = Src`, and no// other non-ZST fields. `map` passes ownership of `self`'s sole `Self::Inner`// to `f`.unsafe impl<Src, NewSrc, Dst> crate::pointer::TryWithError<NewSrc> for crate::CastError<Src, Dst>where Dst: ?Sized,{ type Inner = Src; type Mapped = crate::CastError<NewSrc, Dst>;
#[inline] fn map<F: FnOnce(Src) -> NewSrc>(self, f: F) -> Self::Mapped { self.map_src(f) }}
impl<Src, Dst: ?Sized + Unaligned> From<CastError<Src, Dst>> for SizeError<Src, Dst> { /// Infallibly extracts the [`SizeError`] from this `CastError` since `Dst` /// is unaligned. /// /// Since [`Dst: Unaligned`], it is impossible to encounter an alignment /// error, and so the only error that can be encountered at runtime is a /// [`SizeError`]. This method permits extracting that `SizeError` /// infallibly. /// /// [`Dst: Unaligned`]: crate::Unaligned /// /// # Examples /// /// ```rust /// use zerocopy::*; /// # use zerocopy_derive::*; /// /// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)] /// #[repr(C)] /// struct UdpHeader { /// src_port: [u8; 2], /// dst_port: [u8; 2], /// length: [u8; 2], /// checksum: [u8; 2], /// } /// /// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)] /// #[repr(C, packed)] /// struct UdpPacket { /// header: UdpHeader, /// body: [u8], /// } /// /// impl UdpPacket { /// pub fn parse(bytes: &[u8]) -> Result<&UdpPacket, SizeError<&[u8], UdpPacket>> { /// // Since `UdpPacket: Unaligned`, we can map the `CastError` to a `SizeError`. /// UdpPacket::ref_from_bytes(bytes).map_err(Into::into) /// } /// } /// ``` #[inline(always)] fn from(err: CastError<Src, Dst>) -> SizeError<Src, Dst> { match err { #[allow(unreachable_code)] CastError::Alignment(e) => match Infallible::from(e) {}, CastError::Size(e) => e, CastError::Validity(i) => match i {}, } }}
/// The error type of fallible reference conversions.////// Fallible reference conversions, like [`TryFromBytes::try_ref_from_bytes`]/// may emit [alignment](AlignmentError), [size](SizeError), and/// [validity](ValidityError) errors.// Bounds on generic parameters are not enforced in type aliases, but they do// appear in rustdoc.#[allow(type_alias_bounds)]pub type TryCastError<Src, Dst: ?Sized + TryFromBytes> = ConvertError<AlignmentError<Src, Dst>, SizeError<Src, Dst>, ValidityError<Src, Dst>>;
// FIXME(#1139): Remove the `TryFromBytes` here and in other downstream// locations (all the way to `ValidityError`) if we determine it's not necessary// for rich validity errors.impl<Src, Dst: ?Sized + TryFromBytes> TryCastError<Src, Dst> { /// Produces the source underlying the failed conversion. #[inline] pub fn into_src(self) -> Src { match self { Self::Alignment(e) => e.src, Self::Size(e) => e.src, Self::Validity(e) => e.src, } }
/// Maps the source value associated with the conversion error. /// /// This can help mitigate [issues with `Send`, `Sync` and `'static` /// bounds][self#send-sync-and-static]. /// /// # Examples /// /// ``` /// use core::num::NonZeroU32; /// use zerocopy::*; /// /// let source: [u8; 3] = [0, 0, 0]; /// /// // Try to read a `NonZeroU32` from `source`. /// let maybe_u32: Result<&NonZeroU32, TryCastError<&[u8], NonZeroU32>> /// = NonZeroU32::try_ref_from_bytes(&source[..]); /// /// // Map the error's source to its size and address. /// let maybe_u32: Result<&NonZeroU32, TryCastError<(usize, usize), NonZeroU32>> = /// maybe_u32.map_err(|err| { /// err.map_src(|src| (src.len(), src.as_ptr() as usize)) /// }); /// ``` #[inline] pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> TryCastError<NewSrc, Dst> { match self { Self::Alignment(e) => TryCastError::Alignment(e.map_src(f)), Self::Size(e) => TryCastError::Size(e.map_src(f)), Self::Validity(e) => TryCastError::Validity(e.map_src(f)), } }}
impl<Src, Dst: ?Sized + TryFromBytes> From<CastError<Src, Dst>> for TryCastError<Src, Dst> { #[inline] fn from(value: CastError<Src, Dst>) -> Self { match value { CastError::Alignment(e) => Self::Alignment(e), CastError::Size(e) => Self::Size(e), CastError::Validity(i) => match i {}, } }}
/// The error type of fallible read-conversions.////// Fallible read-conversions, like [`TryFromBytes::try_read_from_bytes`] may/// emit [size](SizeError) and [validity](ValidityError) errors, but not/// alignment errors.// Bounds on generic parameters are not enforced in type aliases, but they do// appear in rustdoc.#[allow(type_alias_bounds)]pub type TryReadError<Src, Dst: ?Sized + TryFromBytes> = ConvertError<Infallible, SizeError<Src, Dst>, ValidityError<Src, Dst>>;
impl<Src, Dst: ?Sized + TryFromBytes> TryReadError<Src, Dst> { /// Produces the source underlying the failed conversion. #[inline] pub fn into_src(self) -> Src { match self { Self::Alignment(i) => match i {}, Self::Size(e) => e.src, Self::Validity(e) => e.src, } }
/// Maps the source value associated with the conversion error. /// /// This can help mitigate [issues with `Send`, `Sync` and `'static` /// bounds][self#send-sync-and-static]. /// /// # Examples /// /// ``` /// use core::num::NonZeroU32; /// use zerocopy::*; /// /// let source: [u8; 3] = [0, 0, 0]; /// /// // Try to read a `NonZeroU32` from `source`. /// let maybe_u32: Result<NonZeroU32, TryReadError<&[u8], NonZeroU32>> /// = NonZeroU32::try_read_from_bytes(&source[..]); /// /// // Map the error's source to its size. /// let maybe_u32: Result<NonZeroU32, TryReadError<usize, NonZeroU32>> = /// maybe_u32.map_err(|err| { /// err.map_src(|src| src.len()) /// }); /// ``` #[inline] pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> TryReadError<NewSrc, Dst> { match self { Self::Alignment(i) => match i {}, Self::Size(e) => TryReadError::Size(e.map_src(f)), Self::Validity(e) => TryReadError::Validity(e.map_src(f)), } }}
/// The error type of well-aligned, fallible casts.////// This is like [`TryCastError`], but for casts that are always well-aligned./// It is identical to `TryCastError`, except that its alignment error is/// [`Infallible`].////// As of this writing, none of zerocopy's API produces this error directly./// However, it is useful since it permits users to infallibly discard alignment/// errors when they can prove statically that alignment errors are impossible.////// # Examples////// ```/// use core::convert::Infallible;/// use zerocopy::*;/// # use zerocopy_derive::*;////// #[derive(TryFromBytes, KnownLayout, Unaligned, Immutable)]/// #[repr(C, packed)]/// struct Bools {/// one: bool,/// two: bool,/// many: [bool],/// }////// impl Bools {/// fn parse(bytes: &[u8]) -> Result<&Bools, AlignedTryCastError<&[u8], Bools>> {/// // Since `Bools: Unaligned`, we can infallibly discard/// // the alignment error./// Bools::try_ref_from_bytes(bytes).map_err(Into::into)/// }/// }/// ```#[allow(type_alias_bounds)]pub type AlignedTryCastError<Src, Dst: ?Sized + TryFromBytes> = ConvertError<Infallible, SizeError<Src, Dst>, ValidityError<Src, Dst>>;
/// The error type of a failed allocation.////// This type is intended to be deprecated in favor of the standard library's/// [`AllocError`] type once it is stabilized. When that happens, this type will/// be replaced by a type alias to the standard library type. We do not intend/// to treat this as a breaking change; users who wish to avoid breakage should/// avoid writing code which assumes that this is *not* such an alias. For/// example, implementing the same trait for both types will result in an impl/// conflict once this type is an alias.////// [`AllocError`]: https://doc.rust-lang.org/alloc/alloc/struct.AllocError.html#[derive(Copy, Clone, PartialEq, Eq, Debug)]pub struct AllocError;
#[cfg(test)]mod tests { use core::convert::Infallible;
use super::*;
#[test] fn test_send_sync() { // Test that all error types are `Send + Sync` even if `Dst: !Send + // !Sync`.
#[allow(dead_code)] fn is_send_sync<T: Send + Sync>(_t: T) {}
#[allow(dead_code)] fn alignment_err_is_send_sync<Src: Send + Sync, Dst>(err: AlignmentError<Src, Dst>) { is_send_sync(err) }
#[allow(dead_code)] fn size_err_is_send_sync<Src: Send + Sync, Dst>(err: SizeError<Src, Dst>) { is_send_sync(err) }
#[allow(dead_code)] fn validity_err_is_send_sync<Src: Send + Sync, Dst: TryFromBytes>( err: ValidityError<Src, Dst>, ) { is_send_sync(err) }
#[allow(dead_code)] fn convert_error_is_send_sync<Src: Send + Sync, Dst: TryFromBytes>( err: ConvertError< AlignmentError<Src, Dst>, SizeError<Src, Dst>, ValidityError<Src, Dst>, >, ) { is_send_sync(err) } }
#[test] fn test_eq_partial_eq_clone() { // Test that all error types implement `Eq`, `PartialEq` // and `Clone` if src does // even if `Dst: !Eq`, `!PartialEq`, `!Clone`.
#[allow(dead_code)] fn is_eq_partial_eq_clone<T: Eq + PartialEq + Clone>(_t: T) {}
#[allow(dead_code)] fn alignment_err_is_eq_partial_eq_clone<Src: Eq + PartialEq + Clone, Dst>( err: AlignmentError<Src, Dst>, ) { is_eq_partial_eq_clone(err) }
#[allow(dead_code)] fn size_err_is_eq_partial_eq_clone<Src: Eq + PartialEq + Clone, Dst>( err: SizeError<Src, Dst>, ) { is_eq_partial_eq_clone(err) }
#[allow(dead_code)] fn validity_err_is_eq_partial_eq_clone<Src: Eq + PartialEq + Clone, Dst: TryFromBytes>( err: ValidityError<Src, Dst>, ) { is_eq_partial_eq_clone(err) }
#[allow(dead_code)] fn convert_error_is_eq_partial_eq_clone<Src: Eq + PartialEq + Clone, Dst: TryFromBytes>( err: ConvertError< AlignmentError<Src, Dst>, SizeError<Src, Dst>, ValidityError<Src, Dst>, >, ) { is_eq_partial_eq_clone(err) } }
#[test] fn alignment_display() { #[repr(C, align(128))] struct Aligned { bytes: [u8; 128], }
impl_known_layout!(elain::Align::<8>);
let aligned = Aligned { bytes: [0; 128] };
let bytes = &aligned.bytes[1..]; let addr = crate::util::AsAddress::addr(bytes); assert_eq!( AlignmentError::<_, elain::Align::<8>>::new_checked(bytes).to_string(), format!("The conversion failed because the address of the source is not a multiple of the alignment of the destination type.\n\ \nSource type: &[u8]\ \nSource address: 0x{:x} (a multiple of 1)\ \nDestination type: elain::Align<8>\ \nDestination alignment: 8", addr) );
let bytes = &aligned.bytes[2..]; let addr = crate::util::AsAddress::addr(bytes); assert_eq!( AlignmentError::<_, elain::Align::<8>>::new_checked(bytes).to_string(), format!("The conversion failed because the address of the source is not a multiple of the alignment of the destination type.\n\ \nSource type: &[u8]\ \nSource address: 0x{:x} (a multiple of 2)\ \nDestination type: elain::Align<8>\ \nDestination alignment: 8", addr) );
let bytes = &aligned.bytes[3..]; let addr = crate::util::AsAddress::addr(bytes); assert_eq!( AlignmentError::<_, elain::Align::<8>>::new_checked(bytes).to_string(), format!("The conversion failed because the address of the source is not a multiple of the alignment of the destination type.\n\ \nSource type: &[u8]\ \nSource address: 0x{:x} (a multiple of 1)\ \nDestination type: elain::Align<8>\ \nDestination alignment: 8", addr) );
let bytes = &aligned.bytes[4..]; let addr = crate::util::AsAddress::addr(bytes); assert_eq!( AlignmentError::<_, elain::Align::<8>>::new_checked(bytes).to_string(), format!("The conversion failed because the address of the source is not a multiple of the alignment of the destination type.\n\ \nSource type: &[u8]\ \nSource address: 0x{:x} (a multiple of 4)\ \nDestination type: elain::Align<8>\ \nDestination alignment: 8", addr) ); }
#[test] fn size_display() { assert_eq!( SizeError::<_, [u8]>::new(&[0u8; 2][..]).to_string(), "The conversion failed because the source was incorrectly sized to complete the conversion into the destination type.\n\ \nSource type: &[u8]\ \nSource size: 2 bytes\ \nDestination type: [u8]" );
assert_eq!( SizeError::<_, [u8; 2]>::new(&[0u8; 1][..]).to_string(), "The conversion failed because the source was incorrectly sized to complete the conversion into the destination type.\n\ \nSource type: &[u8]\ \nSource size: 1 byte\ \nDestination size: 2 bytes\ \nDestination type: [u8; 2]" ); }
#[test] fn validity_display() { assert_eq!( ValidityError::<_, bool>::new(&[2u8; 1][..]).to_string(), "The conversion failed because the source bytes are not a valid value of the destination type.\n\ \n\ Destination type: bool" ); }
#[test] fn test_convert_error_debug() { let err: ConvertError< AlignmentError<&[u8], u16>, SizeError<&[u8], u16>, ValidityError<&[u8], bool>, > = ConvertError::Alignment(AlignmentError::new_checked(&[0u8])); assert_eq!(format!("{:?}", err), "Alignment(AlignmentError)");
let err: ConvertError< AlignmentError<&[u8], u16>, SizeError<&[u8], u16>, ValidityError<&[u8], bool>, > = ConvertError::Size(SizeError::new(&[0u8])); assert_eq!(format!("{:?}", err), "Size(SizeError)");
let err: ConvertError< AlignmentError<&[u8], u16>, SizeError<&[u8], u16>, ValidityError<&[u8], bool>, > = ConvertError::Validity(ValidityError::new(&[0u8])); assert_eq!(format!("{:?}", err), "Validity(ValidityError)"); }
#[test] fn test_convert_error_from_unaligned() { // u8 is Unaligned let err: ConvertError< AlignmentError<&[u8], u8>, SizeError<&[u8], u8>, ValidityError<&[u8], bool>, > = ConvertError::Size(SizeError::new(&[0u8])); let converted: ConvertError<Infallible, SizeError<&[u8], u8>, ValidityError<&[u8], bool>> = ConvertError::from(err); match converted { ConvertError::Size(_) => {} _ => panic!("Expected Size error"), } }
#[test] fn test_alignment_error_display_debug() { let err: AlignmentError<&[u8], u16> = AlignmentError::new_checked(&[0u8]); assert!(format!("{:?}", err).contains("AlignmentError")); assert!(format!("{}", err).contains("address of the source is not a multiple")); }
#[test] fn test_size_error_display_debug() { let err: SizeError<&[u8], u16> = SizeError::new(&[0u8]); assert!(format!("{:?}", err).contains("SizeError")); assert!(format!("{}", err).contains("source was incorrectly sized")); }
#[test] fn test_validity_error_display_debug() { let err: ValidityError<&[u8], bool> = ValidityError::new(&[0u8]); assert!(format!("{:?}", err).contains("ValidityError")); assert!(format!("{}", err).contains("source bytes are not a valid value")); }
#[test] fn test_convert_error_display_debug_more() { let err: ConvertError< AlignmentError<&[u8], u16>, SizeError<&[u8], u16>, ValidityError<&[u8], bool>, > = ConvertError::Alignment(AlignmentError::new_checked(&[0u8])); assert!(format!("{}", err).contains("address of the source is not a multiple"));
let err: ConvertError< AlignmentError<&[u8], u16>, SizeError<&[u8], u16>, ValidityError<&[u8], bool>, > = ConvertError::Size(SizeError::new(&[0u8])); assert!(format!("{}", err).contains("source was incorrectly sized"));
let err: ConvertError< AlignmentError<&[u8], u16>, SizeError<&[u8], u16>, ValidityError<&[u8], bool>, > = ConvertError::Validity(ValidityError::new(&[0u8])); assert!(format!("{}", err).contains("source bytes are not a valid value")); }
#[test] fn test_alignment_error_methods() { let err: AlignmentError<&[u8], u16> = AlignmentError::new_checked(&[0u8]);
// into_src let src = err.clone().into_src(); assert_eq!(src, &[0u8]);
// into let converted: ConvertError< AlignmentError<&[u8], u16>, SizeError<&[u8], u16>, ValidityError<&[u8], bool>, > = err.clone().into(); match converted { ConvertError::Alignment(_) => {} _ => panic!("Expected Alignment error"), }
// clone let cloned = err.clone(); assert_eq!(err, cloned);
// eq assert_eq!(err, cloned); let err2: AlignmentError<&[u8], u16> = AlignmentError::new_checked(&[1u8]); assert_ne!(err, err2); }
#[test] fn test_convert_error_from_unaligned_variants() { // u8 is Unaligned let err: ConvertError< AlignmentError<&[u8], u8>, SizeError<&[u8], u8>, ValidityError<&[u8], bool>, > = ConvertError::Validity(ValidityError::new(&[0u8])); let converted: ConvertError<Infallible, SizeError<&[u8], u8>, ValidityError<&[u8], bool>> = ConvertError::from(err); match converted { ConvertError::Validity(_) => {} _ => panic!("Expected Validity error"), }
let err: ConvertError< AlignmentError<&[u8], u8>, SizeError<&[u8], u8>, ValidityError<&[u8], bool>, > = ConvertError::Size(SizeError::new(&[0u8])); let converted: ConvertError<Infallible, SizeError<&[u8], u8>, ValidityError<&[u8], bool>> = ConvertError::from(err); match converted { ConvertError::Size(_) => {} _ => panic!("Expected Size error"), } }}