Home › sys/errors

Module sys/errors

sys/errors
Stability: close to stable, and the most-depended-on type in `std/sys` — every `Result` in `std/fs`, `std/net` and `std/process` carries an `IoError`. The variants are the errno classes Rust's `std::io::ErrorKind` names, the mapping from errno is exhaustive for the codes `std` can produce, and `from_result` is the documented way to turn a raw syscall answer into a `Result`. What is open is only the tail: the enum is NOT documented as non-exhaustive, so adding a variant — which a new syscall surface can force — is a breaking change for any caller that matches exhaustively. Deciding that, and saying so here, is what freezing this module means. — stable modules only change additively; this one may still change.

IoError type — comprehensive I/O error type with errno-to-error mapping.

Stability

close to stable, and the most-depended-on type in std/sys — every Result in std/fs, std/net and std/process carries an IoError. The variants are the errno classes Rust's std::io::ErrorKind names, the mapping from errno is exhaustive for the codes std can produce, and from_result is the documented way to turn a raw syscall answer into a Result.

What is open is only the tail: the enum is NOT documented as non-exhaustive, so adding a variant — which a new syscall surface can force — is a breaking change for any caller that matches exhaustively. Deciding that, and saying so here, is what freezing this module means.

Types

IoError enum
IoError

Generic I/O error (EIO).

Variants

VariantFieldsDescription
NotFound

File or directory not found (ENOENT).

PermissionDenied

Permission denied (EACCES, EPERM).

AlreadyExists

File or directory already exists (EEXIST).

NotADirectory

Not a directory (ENOTDIR).

IsADirectory

Is a directory (EISDIR).

DirectoryNotEmpty

Directory not empty (ENOTEMPTY).

BrokenPipe

Broken pipe (EPIPE).

WouldBlock

Operation would block (EAGAIN, EWOULDBLOCK).

InvalidInput

Invalid argument (EINVAL).

Interrupted

Interrupted system call (EINTR).

TooManyOpenFiles

Too many open files (EMFILE, ENFILE).

FileTooLarge

File too large (EFBIG).

NoSpace

No space left on device (ENOSPC).

ReadOnlyFilesystem

Read-only filesystem (EROFS).

CrossDeviceLink

Cross-device link (EXDEV).

TooManyLinks

Too many links (EMLINK).

NameTooLong

File name too long (ENAMETOOLONG).

NotSupported

Operation not supported (ENOTSUP, EOPNOTSUPP).

TimedOut

Operation timed out (ETIMEDOUT).

Busy

Resource busy (EBUSY).

BadFileDescriptor

Bad file descriptor (EBADF).

IoError

Generic I/O error (EIO).

ConnectionRefused

Connection refused (ECONNREFUSED).

ConnectionReset

Connection reset by peer (ECONNRESET).

ConnectionAborted

Connection aborted (ECONNABORTED).

NotConnected

Not connected (ENOTCONN).

AddressInUse

Address already in use (EADDRINUSE).

AddressNotAvailable

Address not available (EADDRNOTAVAIL).

NetworkUnreachable

Network unreachable (ENETUNREACH).

HostUnreachable

Host unreachable (EHOSTUNREACH).

NetworkDown

Network is down (ENETDOWN).

AlreadyConnected

Already connected (EISCONN).

InvalidData

The stream contained malformed data for the operation — e.g. Reader.read_to_string over bytes that are not valid UTF-8. Not an errno; the Rust ErrorKind::InvalidData counterpart.

WriteZero

A write accepted 0 bytes, so the remaining data can never be delivered (Writer.write_all). Not an errno; the Rust ErrorKind::WriteZero counterpart.

Othercode: i32

Other error carrying the raw OS error code — errno on POSIX, GetLastError() on Windows (Rust's io::Error::raw_os_error).

Trait Implementations

Error Format
impl(generic(T : Type), where(T <: ToString), T : (ToString))
impl(generic(T : Type), where(T <: ToString), T : (ToString), Format)
format : fn(self : Self, spec : str) -> String

Render self under spec. An unrecognised spec degrades to the plain to_string() rendering rather than failing.

Parameters

NameTypeNotes
selfSelf
specstr

Returns: String

impl(IoError, ...)
from_errno : (IoError) fn(errno : i32) -> IoError

Parameters

NameTypeNotes
errnoi32

Returns: IoError

from_win32 : (IoError) fn(code : i32) -> IoError

Classify a Win32 GetLastError() code.

Win32 APIs do not set errno, and their codes share no numbering with it — 3 is ERROR_PATH_NOT_FOUND on Windows and ESRCH on POSIX. A structured error is only worth having if it classifies the SAME failure the same way on every platform, so the codes that have an IoError meaning are mapped here and the rest fall through to Other, which keeps the raw code. (Rust does the same for io::ErrorKind.)

The literals are the stable Win32 values from <winerror.h>; they are written numerically so this file stays platform-independent.

Parameters

NameTypeNotes
codei32

Returns: IoError

from_result : (IoError) fn(result : i32) -> Result(i32, IoError)

Parameters

NameTypeNotes
resulti32

Returns: Result(i32, IoError)

impl(IoError, ...)
check : (IoError) fn(result : i32, exn : Exception) -> i32

Parameters

NameTypeNotes
resulti32
exnException

Returns: i32

Methods
to_string : (IoError) fn(self : IoError) -> String

Parameters

NameTypeNotes
selfIoError

Returns: String

source : (IoError) fn(self : IoError) -> Option(dyn( + ToString))

The error that caused this one, or .None at the root of the chain.

Rust's Error::source. Defaulted to .None, so an error with nothing underneath it implements the trait by saying only what it is; a wrapper overrides it to hand back what it wrapped. Walking the chain to the root cause is not expressible yet — the returned Dyn loses the Error trait on an erased receiver, so a caller can print one link but cannot follow it (#521, issues/self-trait-in-a-return-type-loses-the-trait-on-an-erased-receiver.md).

Parameters

NameTypeNotes
selfIoError

Returns: Option(dyn( + ToString))