Enum ErrorKind

#[non_exhaustive]
pub enum ErrorKind {
    NotFound,
    PermissionDenied,
    ConnectionRefused,
    ConnectionReset,
    HostUnreachable,
    NetworkUnreachable,
    ConnectionAborted,
    NotConnected,
    AddrInUse,
    AddrNotAvailable,
    NetworkDown,
    BrokenPipe,
    AlreadyExists,
    WouldBlock,
    NotADirectory,
    IsADirectory,
    DirectoryNotEmpty,
    ReadOnlyFilesystem,
    FilesystemLoop,
    StaleNetworkFileHandle,
    InvalidInput,
    InvalidData,
    TimedOut,
    WriteZero,
    StorageFull,
    NotSeekable,
    FilesystemQuotaExceeded,
    FileTooLarge,
    ResourceBusy,
    ExecutableFileBusy,
    Deadlock,
    CrossesDevices,
    TooManyLinks,
    InvalidFilename,
    ArgumentListTooLong,
    Interrupted,
    Unsupported,
    UnexpectedEof,
    OutOfMemory,
    InProgress,
    Other,
}

A list specifying general categories of I/O error.

This list is intended to grow over time and it is not recommended to exhaustively match against it.

It is used with the io::Error type.

Handling errors and matching on ErrorKind

In application code, use match for the ErrorKind values you are expecting; use _ to match “all other errors”.

In comprehensive and thorough tests that want to verify that a test doesn’t return any known incorrect error kind, you may want to cut-and-paste the current full list of errors from here into your test code, and then match _ as the correct case. This seems counterintuitive, but it will make your tests more robust. In particular, if you want to verify that your code does produce an unrecognized error kind, the robust solution is to check for all the recognized error kinds and fail in those cases.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

NotFound

An entity was not found, often a file.

PermissionDenied

The operation lacked the necessary privileges to complete.

ConnectionRefused

The connection was refused by the remote server.

ConnectionReset

The connection was reset by the remote server.

HostUnreachable

The remote host is not reachable.

NetworkUnreachable

The network containing the remote host is not reachable.

ConnectionAborted

The connection was aborted (terminated) by the remote server.

NotConnected

The network operation failed because it was not connected yet.

AddrInUse

A socket address could not be bound because the address is already in use elsewhere.

AddrNotAvailable

A nonexistent interface was requested or the requested address was not local.

NetworkDown

The system’s networking is down.

BrokenPipe

The operation failed because a pipe was closed.

AlreadyExists

An entity already exists, often a file.

WouldBlock

The operation needs to block to complete, but the blocking operation was requested to not occur.

NotADirectory

A filesystem object is, unexpectedly, not a directory.

For example, a filesystem path was specified where one of the intermediate directory components was, in fact, a plain file.

IsADirectory

The filesystem object is, unexpectedly, a directory.

A directory was specified when a non-directory was expected.

DirectoryNotEmpty

A non-empty directory was specified where an empty directory was expected.

ReadOnlyFilesystem

The filesystem or storage medium is read-only, but a write operation was attempted.

FilesystemLoop

🔬This is a nightly-only experimental API. (io_error_more #86442)

Loop in the filesystem or IO subsystem; often, too many levels of symbolic links.

There was a loop (or excessively long chain) resolving a filesystem object or file IO object.

On Unix this is usually the result of a symbolic link loop; or, of exceeding the system-specific limit on the depth of symlink traversal.

StaleNetworkFileHandle

Stale network file handle.

With some network filesystems, notably NFS, an open file (or directory) can be invalidated by problems with the network or server.

InvalidInput

A parameter was incorrect.

InvalidData

Data not valid for the operation were encountered.

Unlike InvalidInput, this typically means that the operation parameters were valid, however the error was caused by malformed input data.

For example, a function that reads a file into a string will error with InvalidData if the file’s contents are not valid UTF-8.

TimedOut

The I/O operation’s timeout expired, causing it to be canceled.

WriteZero

An error returned when an operation could not be completed because a call to write returned Ok(0).

This typically means that an operation could only succeed if it wrote a particular number of bytes but only a smaller number of bytes could be written.

StorageFull

The underlying storage (typically, a filesystem) is full.

This does not include out of quota errors.

NotSeekable

Seek on unseekable file.

Seeking was attempted on an open file handle which is not suitable for seeking - for example, on Unix, a named pipe opened with File::open.

FilesystemQuotaExceeded

🔬This is a nightly-only experimental API. (io_error_more #86442)

Filesystem quota was exceeded.

FileTooLarge

File larger than allowed or supported.

This might arise from a hard limit of the underlying filesystem or file access API, or from an administratively imposed resource limitation. Simple disk full, and out of quota, have their own errors.

ResourceBusy

Resource is busy.

ExecutableFileBusy

Executable file is busy.

An attempt was made to write to a file which is also in use as a running program. (Not all operating systems detect this situation.)

Deadlock

Deadlock (avoided).

A file locking operation would result in deadlock. This situation is typically detected, if at all, on a best-effort basis.

CrossesDevices

🔬This is a nightly-only experimental API. (io_error_more #86442)

Cross-device or cross-filesystem (hard) link or rename.

TooManyLinks

Too many (hard) links to the same filesystem object.

The filesystem does not support making so many hardlinks to the same file.

InvalidFilename

🔬This is a nightly-only experimental API. (io_error_more #86442)

A filename was invalid.

This error can also cause if it exceeded the filename length limit.

ArgumentListTooLong

Program argument list too long.

When trying to run an external program, a system or process limit on the size of the arguments would have been exceeded.

Interrupted

This operation was interrupted.

Interrupted operations can typically be retried.

Unsupported

This operation is unsupported on this platform.

This means that the operation can never succeed.

UnexpectedEof

An error returned when an operation could not be completed because an “end of file” was reached prematurely.

This typically means that an operation could only succeed if it read a particular number of bytes but only a smaller number of bytes could be read.

OutOfMemory

An operation could not be completed, because it failed to allocate enough memory.

InProgress

🔬This is a nightly-only experimental API. (io_error_inprogress #130840)

The operation was partially successful and needs to be checked later on due to not blocking.

Other

A custom error that does not fall under any other I/O error kind.

This can be used to construct your own Errors that do not match any ErrorKind.

This ErrorKind is not used by the standard library.

Errors from the standard library that do not fall under any of the I/O error kinds cannot be matched on, and will only match a wildcard (_) pattern. New ErrorKinds might be added in the future for some of those.

Trait Implementations

impl Clone for ErrorKind

fn clone(&self) -> ErrorKind

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ErrorKind

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

Formats the value using the given formatter.

impl Display for ErrorKind

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

Shows a human-readable description of the ErrorKind.

This is similar to impl Display for Error, but doesn’t require first converting to Error.

Examples

use std::io::ErrorKind;
assert_eq!("entity not found", ErrorKind::NotFound.to_string());

impl From<ErrorKind> for Error

Intended for use for errors not exposed to the user, where allocating onto the heap (for normal construction via Error::new) is too costly.

fn from(kind: ErrorKind) -> Error

Converts an ErrorKind into an Error.

This conversion creates a new error with a simple representation of error kind.

Examples

use std::io::{Error, ErrorKind};

let not_found = ErrorKind::NotFound;
let error = Error::from(not_found);
assert_eq!("entity not found", format!("{error}"));

impl Hash for ErrorKind

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for ErrorKind

fn cmp(&self, other: &ErrorKind) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for ErrorKind

fn eq(&self, other: &ErrorKind) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for ErrorKind

fn partial_cmp(&self, other: &ErrorKind) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for ErrorKind

impl Eq for ErrorKind

impl StructuralPartialEq for ErrorKind