errors +linux +x86_64

The error module provides a number of error types which describe error conditions common to many types of code, as well as convenience functions for turning these errors into strings, and an error type which may be used to wrap some implementation-defined error data. If your program's error cases can be modelled by the errors offered in this module, you may use them to make your error types compatible with a wider range of support modules.



type opaque_data;


type again;
type busy;
type cancelled;
type error;
type exists;
type interrupted;
type invalid;
type noaccess;
type noentry;
type nomem;
type opaque;
type overflow;
type refused;
type timeout;
type unsupported;


fn errno(rt::errno) error;
fn strerror(error) const str;


type opaque_data[link]

type opaque_data = [24]u8;

Up to 24 bytes of arbitrary data that the opaque error type may use for domain-specific storage.


type again[link]

type again = !void;

The user should attempt an operation again.

type busy[link]

type busy = !void;

The requested resource is not available.

type cancelled[link]

type cancelled = !void;

The requested operation was cancelled.

type error[link]

type error = !(busy | exists | invalid | noaccess | noentry | overflow | unsupported |
timeout | cancelled | refused | nomem | interrupted | again | opaque);

A tagged union of all error types.

type exists[link]

type exists = !void;

An attempt was made to create a resource which already exists.

type interrupted[link]

type interrupted = !void;

An operation was interrupted.

type invalid[link]

type invalid = !void;

A function was called with an invalid combination of arguments.

type noaccess[link]

type noaccess = !void;

The user does not have permission to use this resource.

type noentry[link]

type noentry = !void;

An entry was requested which does not exist.

type nomem[link]

type nomem = !void;

Unable to allocate sufficient memory for the requested operation.

type opaque[link]

type opaque = !struct {
	strerror: *fn(op: *opaque_data) const str,
	data: opaque_data,

An "opaque" error is used as a portable error type for an underlying error which is implementation-specific. It provides a function which can be used to produce a string describing the error, and a small storage area for arbitrary implementation-specific storage.

The following example shows the usage of this type for custom errors:

fn wraperror(err: myerror) error::opaque = {
	static assert(size(myerror) <= size(errors::opaque_data));
	let wrapped = errors::opaque { strerror = &opaque_strerror, ... };
	let myptr = & *myerror;
	*myptr = err;
	return wrapped;

fn opaque_strerror(err: *errors::opaque_data) const str = {
	let ptr = &err: *myerr;
	return strerror(*ptr);

type overflow[link]

type overflow = !void;

The requested operation caused a numeric overflow condition.

type refused[link]

type refused = !void;

A connection attempt was refused.

type timeout[link]

type timeout = !void;

The requested operation timed out.

type unsupported[link]

type unsupported = !void;

The requested operation is not supported.


fn errno[link]

fn errno(errno: rt::errno) error;

Wraps an rt::errno to produce an errors::opaque. This is a non-portable interface which is mainly provided to support internal stdlib requirements.

fn strerror[link]

fn strerror(err: error) const str;

Converts an error into a human-friendly string representation.

Note that this strerror implementation lacks any context-specific information about the error types supported. For example, exists is stringified as "An attempt was made to create a resource which already exists", but if source of the error is, say, creating a file, it would likely be more appropriate to use the term "file" rather than "resource". For this reason, it is preferred that modules which return an error type from this module provide their own strerror function which provides more context-appropriate error messages for each of those types.