Enum Error 

pub enum Error {
    Io(Error),
    ShortRead {
        offset: u64,
        want: usize,
        got: usize,
    },
    ReadOnly,
    OutOfBounds {
        offset: u64,
        len: u64,
        size: u64,
    },
    Custom(String),
}

Variants

Io(Error)

Underlying I/O failure (open, seek, read, write).

ShortRead

A read that could not be satisfied in full: the source ran out of data before want bytes had been transferred.

got counts the bytes actually placed in the caller’s buffer, not the bytes that were available. FileDevice copies what it can and reports that count, so a read straddling EOF comes back with the readable prefix in buf and got equal to its length. The slice adapters in crate::slice refuse an out-of-range read before touching the parent, so they leave buf untouched and always report got: 0 — including for a read that begins inside the slice and runs off its end, where a FileDevice of the same size would have reported a non-zero prefix. So got: 0 always means nothing was transferred, and does not on its own tell you whether anything was available: from a FileDevice at EOF it happens to mean both, from a slice it means only the former.

It is not the only error an over-read can produce, because most of this crate’s devices do not own the bytes they serve:

• crate::CachingDevice, crate::ReadOnlyDevice and the slice adapters forward an in-range read to their parent and return the parent’s error unchanged. Over a parent that reports over-reads as Error::OutOfBounds — the img-* container readers do — that is what the wrapper reports too.
• crate::CallbackDevice surfaces a failing host callback as Error::Io. The callback ABI is an errno-space code carrying no byte count, so there is nothing to put in got.

Fields

offset: u64

want: usize

got: usize

ReadOnly

write_at invoked on a device opened read-only.

OutOfBounds

A request refused before any transfer because its range is not wholly inside the device’s declared size. Nothing was read or written; size is the device size, so the caller can clamp.

This crate constructs it in exactly one place: crate::OwnedRwSlice’s write_at, for a write outside the slice. No read path here builds it, so matching it to catch an over-read of a FileDevice, or a read past a slice’s own end, is an arm that will never be taken — those report Error::ShortRead with got: 0.

It still reaches reads, from elsewhere. A container that knows its virtual size before touching the backing store rejects an over-read up front rather than discovering EOF, and the img-qcow2, img-vhd, img-vhdx and img-vmdk readers all return OutOfBounds from BlockRead::read_at on that path. This crate’s wrappers — crate::CachingDevice, crate::ReadOnlyDevice, the slice adapters — forward it unchanged from such a parent.

So code reading through a dyn BlockRead of unknown provenance has to handle this as well as Error::ShortRead — and cannot treat the pair as exhaustive, because a crate::CallbackDevice reports its host’s refusal as Error::Io however the host arrived at it. Only code that knows its device bottoms out in a FileDevice can rely on ShortRead alone.

Fields

offset: u64

len: u64

size: u64

Custom(String)

Driver-specific error lifted to the trait boundary. Each driver’s internal error type implements Into<Error> via this variant.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(e: Error) -> Self

Converts to this type from the input type.