ose_errno.h File Reference

Status codes for context bundles. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	ose_errno_set(b, e)   ose_context_set_status((b), (e))
	Set the errno value of b to e.
#define	ose_errno_get(b)   (enum ose_errno)ose_context_get_status((b))
	Get the errno for bundle b.
#define	ose_errno_module_set(b, e)    ose_context_set_status((b), ((e) | ose_err_source_module))
	Set the errno value of b to e indicating that the error originates in a module.
#define	ose_errno_source_get(e)    ((e) & ose_err_source_mask)
	Get the source of the error e (libose or module).
#define	ose_errno_cause_get(e)    ((e) & ose_err_cause_mask)
	Get the cause of the error e.

Enumerations
enum	ose_errno {   OSE_ERR_NONE = 0 , ose_err_source_libose = 0x10000 , OSE_ERR_TYPE , OSE_ERR_ELEM_TYPE ,   OSE_ERR_ITEM_TYPE , OSE_ERR_ELEM_COUNT , OSE_ERR_ITEM_COUNT , OSE_ERR_RANGE ,   OSE_ERR_UNKNOWN_TYPETAG , OSE_ERR_UNKNOWN_CONTEXT_BUNDLE , OSE_ERR_BLOB_CONTENTS , OSE_ERR_MALFORMED ,   OSE_ERR_UNTRUSTED_TYPE , OSE_ERR_MODULE_LOAD , OSE_ERR_MODULE_ABI , OSE_ERR_UNBOUND ,   OSE_ERR_FOREIGNFUNC_RAISED , OSE_ERR_WILDPTR_CALLED , OSE_ERR_REGISTER_EXISTS , OSE_ERR_REGISTER_FULL ,   ose_err_source_module = 0x20000 , ose_err_cause_mask = 0xFFFF , ose_err_source_mask = 0xFF0000 }

Functions
const char *	ose_errno_string (enum ose_errno e)
	What an errno means, in words.

Detailed Description

Status codes for context bundles.

Enumeration Type Documentation

ose_errno

enum ose_errno

Enumerator
OSE_ERR_NONE	No error
OSE_ERR_TYPE	Generic type-related error
OSE_ERR_ELEM_TYPE	Wrong type of element encountered
OSE_ERR_ITEM_TYPE	Wrong type of item encountered
OSE_ERR_ELEM_COUNT	Bundle has the wrong number of elements
OSE_ERR_ITEM_COUNT	An element has the wrong number of items
OSE_ERR_RANGE	Range error
OSE_ERR_UNKNOWN_TYPETAG	Unknown typetag
OSE_ERR_UNKNOWN_CONTEXT_BUNDLE	Unknown context bundle referred to
OSE_ERR_BLOB_CONTENTS	Unexpected blob contents
OSE_ERR_MALFORMED	Bytes are not a well formed OSC bundle
OSE_ERR_UNTRUSTED_TYPE	A type that may not arrive from outside
OSE_ERR_MODULE_LOAD	A module could not be opened
OSE_ERR_MODULE_ABI	A module was built against a different libose
OSE_ERR_UNBOUND	A name resolved to nothing
OSE_ERR_FOREIGNFUNC_RAISED	A function outside libose, called through a binding, failed. The FFI sense of "foreign": code implemented in another runtime and reached across a boundary – a callable in another language behind a trampoline, a host object's method, a callback in an embedding runtime. It is a distinct condition from anything libose decides for itself, and it is the caller's failure to report, not ours to interpret. Contract: whoever sets this leaves an /error message on the stack carrying the detail – the exception text, the reason, whatever the far side knows. The code says which kind of failure it is; the message says what happened. Without the message this code is no more use than the one it replaced. Distinct from OSE_ERR_MODULE_LOAD and OSE_ERR_MODULE_ABI, which are about loading foreign code rather than calling it, and distinct from OSE_ERR_ITEM_TYPE, which is libose refusing an argument. The three used to be indistinguishable in a language binding: a function in the other language correctly raising a type error read exactly like a broken binding.
OSE_ERR_WILDPTR_CALLED	A wild bound function was applied. A 'P' is a bound function belonging to another PROCESS – see OSETT_WILDPTR in ose.h. Its address means nothing here, so applying one raises rather than quietly doing nothing. Distinct from OSE_ERR_UNTRUSTED_TYPE, which is the DOOR refusing a live 'p' from outside. That one is about arrival; this is about being called. Reusing it made a caller see "a type that may not arrive from outside" for a function it had just tried to run, which is a true sentence about the wrong event. "Wild" and not "foreign": OSE_ERR_FOREIGNFUNC_RAISED above already spends that word on the FFI sense – code in another runtime – and two meanings of it in one header is an hour someone else pays for.
OSE_ERR_REGISTER_EXISTS	A register name that is already live was claimed again. Appended here rather than filed beside OSE_ERR_RANGE deliberately: these are numbered by position, they reach a user as bare integers (errno 65542), and they appear in notes and bug reports. Inserting one in the middle renumbers every code below it and quietly falsifies every record of them. See also ose_pushContextMessage()
OSE_ERR_REGISTER_FULL	A register could not grow, so a write did not happen. Distinct from OSE_ERR_RANGE, and that distinction is the whole reason this exists. OSE_ERR_RANGE carries two unrelated things: a precondition that was violated and handled – ose_drop() on an empty stack, an offset past the end – and a register that ran out of room. The first is ordinary and the caller deals with it; the second means the machine lost data and nobody is going to notice. Told apart, the second can be carried up to the machine that owns the register, which is what osevm_collectRefusals() does. Conflated, it cannot, and a handled decline is promoted into a fault – which an empty /_i and /_s with a megabyte free between them will do. It also reads better where it surfaces: "a register is full" is something a person can act on, where "out of range" is the same words for several different sizing walls. Appended, for the reason OSE_ERR_REGISTER_EXISTS gives above. See also ose_addToSize(), ose_incSize(), osevm_collectRefusals()

Function Documentation

ose_errno_string()

const char * ose_errno_string

(

enum ose_errno

e

)

What an errno means, in words.

Returns

A short description, always non-NULL and always a static string. An unrecognised value gives "unknown error", not NULL, so a caller may print the result without checking.

The descriptions existed only as doxygen comments on the enum above, which meant nothing at runtime had them. A raised error therefore reached the user as a bare number: Caught exception 65540 is what a host said when a program asked for an element that was not there, and 65540 is not something anyone can act on without this header open beside them.

The high bits carry the source (libose or a module) and are masked off here – a module's error numbering is its own, so the most this can say about one is that it came from a module.