include/libu8/u8exceptions.h File Reference

These functions provide ways of managing exception state for libu8 and programs built on it. More...

Data Structures
struct	U8_EXCEPTION
	struct U8_EXCEPTION represents an error condition. More...
Typedefs
typedef struct U8_EXCEPTION	U8_EXCEPTION
	struct U8_EXCEPTION represents an error condition.
Functions
U8_EXPORT u8_condition	u8_strerror (int num)
	Returns a u8_condition object corresponding to a given errno, using the POSIX strerror function.
U8_EXPORT U8_NOINLINE u8_exception	u8_new_exception (u8_condition c, u8_context cxt, u8_string details, void *xdata, void(*freefn)(void *))
	Creates a new exception Returns the current exception, pushing it onto the dynamic exception stack.
U8_EXPORT U8_NOINLINE u8_exception	u8_push_exception (u8_condition condition, u8_context context, u8_string details, void *xdata, void(*freefn)(void *))
	Pushes an exception Sets the current exception, pushing it onto the dynamic exception stack.
U8_EXPORT U8_NOINLINE u8_exception	u8_extend_exception (u8_context cxt, u8_string details, void *xdata, void(*freefn)(void *))
	Pushes an additional exception with additional data Sets the current exception, pushing it onto the dynamic exception stack.
U8_EXPORT U8_NOINLINE u8_exception	u8_pop_exception (void)
	Pops the exception stack Clears the current exception, popping it from the dynamic exception stack, which subsequently points to the exception which was current when the current exception was pushed.
U8_EXPORT u8_exception	u8_exception_root (u8_exception ex)
	Returns the root of the current error state This climbs the u8x_prev hierachy and returns the exception at the top which (presumably) started it all.
U8_EXPORT int	u8_exception_stacklen (u8_exception ex)
	Returns the number of exceptions in the stack starting at ex This climbs the u8x_prev hierachy and counts the number of exceptions When passed NULL, this returns 0.
U8_EXPORT u8_exception	u8_erreify (void)
	Returns and clears the current error state.
U8_EXPORT u8_exception	u8_restore_exception (u8_exception ex)
	Restores the exception stack Takes an exception structure, typically returned by u8_erreify(), and makes it current.
U8_EXPORT U8_NOINLINE u8_exception	u8_make_exception (u8_condition condition, u8_context context, u8_string details, void *xdata, void(*freefn)(void *))
	Creates an exception object Creates a new exception object but does not make it current.
U8_EXPORT u8_exception	u8_free_exception (u8_exception ex, int full)
	Frees an exception object or stack This is implicitly called by u8_pop_exception, so it is not normally needed without an intervening call to u8_erreify().
U8_EXPORT U8_NOINLINE int	u8_reterr (u8_condition c, u8_context cxt, u8_string details)
	Sets the current error state and returns an error value (-1) The condition and context are constant strings, but the details string should be mallocd.
U8_EXPORT U8_NOINLINE u8_exception	u8_errpush (u8_exception ex, u8_context cxt, u8_string details, void *xdata, void(*freefn)(void *))
	Creates a new exception based on an existing one This creates a new exception whose previous pointer is an existing exception but provides new field.
U8_EXPORT void	u8_clear_errors (int report)
	Clears all current errors.
U8_EXPORT u8_string	u8_errstring (struct U8_EXCEPTION *errdata)
	Returns a UTF-8 string describing an error state.
U8_EXPORT void	u8_graberr (int num, u8_string cxt, u8_string details)
	Takes an errno error and creates a libu8 error, given a particular context and details string.
U8_EXPORT U8_NOINLINE void	u8_seterr (u8_condition condition, u8_context context, u8_string details)
	Sets the current error state.
U8_EXPORT int	u8_geterr (u8_condition *conditionp, u8_context *contextp, u8_string *detailsp)
	Gets the current error state.
U8_EXPORT int	u8_poperr (u8_condition *conditionp, u8_context *contextp, u8_string *detailsp)
	Gets and clears the current error state.

---

Detailed Description

These functions provide ways of managing exception state for libu8 and programs built on it.

---

Typedef Documentation

typedef struct U8_EXCEPTION U8_EXCEPTION

struct U8_EXCEPTION represents an error condition.

The u8x_cond field contains the error condition, the u8x_context field contains the a string describing context in which the error occurred, the u8x_details field (if not null) provides more detailed information about the error. The u8x_xdata field, if not NULL, is a pointer to application-specific data which will be freed by the u8x_free_xdata function. Finally, the u8x_next field points to the error condition (or NULL) which was active when this error was indicated.

---

Function Documentation

U8_EXPORT void u8_clear_errors

(

int

report

)

Clears all current errors.

If report is non-zero, the errors are reported as messages

Parameters:

report

an integer

Returns:

void

U8_EXPORT u8_exception u8_erreify

(

void

)

Returns and clears the current error state.

This retrieves and clears the current error state and the chain of errors beyond it.

Returns:

an exception object

U8_EXPORT U8_NOINLINE u8_exception u8_errpush	(	u8_exception	ex,
		u8_context	cxt,
		u8_string	details,
		void *	xdata,
		void(*)(void *)	freefn
	)

Creates a new exception based on an existing one This creates a new exception whose previous pointer is an existing exception but provides new field.

Returns:

an exception object

U8_EXPORT u8_string u8_errstring

(

struct U8_EXCEPTION *

errdata

)

Returns a UTF-8 string describing an error state.

Parameters:

errdata

a pointer to a U8_ERRDATA structure

Returns:

void

U8_EXPORT u8_exception u8_exception_root

(

u8_exception

ex

)

Returns the root of the current error state This climbs the u8x_prev hierachy and returns the exception at the top which (presumably) started it all.

When passed NULL, this returns NULL

Parameters:

ex	an exception object

Returns:

an exception object

U8_EXPORT int u8_exception_stacklen

(

u8_exception

ex

)

Returns the number of exceptions in the stack starting at ex This climbs the u8x_prev hierachy and counts the number of exceptions When passed NULL, this returns 0.

Parameters:

ex	an exception object

Returns:

a non-negative integer

U8_EXPORT U8_NOINLINE u8_exception u8_extend_exception	(	u8_context	cxt,
		u8_string	details,
		void *	xdata,
		void(*)(void *)	freefn
	)

Pushes an additional exception with additional data Sets the current exception, pushing it onto the dynamic exception stack.

The context are constant strings, the details should be a mallocd string. xdata and freefn can be NULL. if freefn is provided, it is called on xdata when the exception is popped. The condition is copied from the current exception or is EmptyExceptionStack otherwise.

Parameters:

cxt	a utf-8 context string (a const string)
details	a utf-8 string detailing the error, or NULL
xdata	a void pointer to additional data describing the error or its context
freefn	a function to call on the xdata when freeing it

Returns:

an exception structure

U8_EXPORT u8_exception u8_free_exception	(	u8_exception	ex,
		int	full
	)

Frees an exception object or stack This is implicitly called by u8_pop_exception, so it is not normally needed without an intervening call to u8_erreify().

Frees its argument, an exception; with a second argument of 1, this recursively frees the whole exception stack. This returns the previous exception or NULL if the whole stack was freed.

Parameters:

ex	a pointer to an exception structure
full	1/0 indicating whether to free the whole stack

Returns:

an exception structure, or NULL

U8_EXPORT int u8_geterr	(	u8_condition *	conditionp,
		u8_context *	contextp,
		u8_string *	detailsp
	)

Gets the current error state.

This retrieves the current error state and stores it in designated locations. A null pointer indicates that no value is to be stored.

Parameters:

conditionp	a pointer to a location to store the error condition
contextp	a pointer to a location to store the error context
detailsp	a pointer to a location to store a (copy of) the error details

Returns:

1 if there is a current error, 0 otherwise

U8_EXPORT void u8_graberr	(	int	num,
		u8_string	cxt,
		u8_string	details
	)

Takes an errno error and creates a libu8 error, given a particular context and details string.

Parameters:

num	an errno number
cxt	a context string (a const utf-8 string)
details	a details string (a malloc'd utf-8 string)

U8_EXPORT U8_NOINLINE u8_exception u8_make_exception	(	u8_condition	condition,
		u8_context	context,
		u8_string	details,
		void *	xdata,
		void(*)(void *)	freefn
	)

Creates an exception object Creates a new exception object but does not make it current.

The condition and context are constant strings, the details should be a mallocd string. xdata and freefn can be NULL. if freefn is provided, it is called on xdata when the exception is popped.

Parameters:

condition	a utf-8 condition string (u8_condition)
context	a utf-8 context string (a const string)
details	a utf-8 string detailing the error, or NULL
xdata	a void pointer to additional data describing the error or its context
freefn	a function to call on the xdata when freeing it

Returns:

an exception structure

U8_EXPORT U8_NOINLINE u8_exception u8_new_exception	(	u8_condition	c,
		u8_context	cxt,
		u8_string	details,
		void *	xdata,
		void(*)(void *)	freefn
	)

Creates a new exception Returns the current exception, pushing it onto the dynamic exception stack.

The condition and context are constant strings, the details should be a mallocd string. xdata and freefn can be NULL. if freefn is provided, it is called on xdata when the exception is popped.

Parameters:

condition	a utf-8 condition string (u8_condition)
context	a utf-8 context string (a const string)
details	a utf-8 string detailing the error, or NULL
xdata	a void pointer to additional data describing the error or its context
freefn	a function to call on the xdata when freeing it

Returns:

an exception structure

U8_EXPORT U8_NOINLINE u8_exception u8_pop_exception

(

void

)

Pops the exception stack Clears the current exception, popping it from the dynamic exception stack, which subsequently points to the exception which was current when the current exception was pushed.

Returns:

an exception structure, the new current exception (possibly NULL)

U8_EXPORT int u8_poperr	(	u8_condition *	conditionp,
		u8_context *	contextp,
		u8_string *	detailsp
	)

Gets and clears the current error state.

This retrieves the current error state and stores it in designated locations. A null pointer indicates that no value is to be stored. After retrieving it, the current error state is cleared. Note that any error state existing before the error was signalled is then restored.

Parameters:

conditionp	a pointer to a location to store the error condition
contextp	a pointer to a location to store the error context
detailsp	a pointer to a location to store a (copy of) the error details

Returns:

1 if there is a current error, 0 otherwise

U8_EXPORT U8_NOINLINE u8_exception u8_push_exception	(	u8_condition	condition,
		u8_context	context,
		u8_string	details,
		void *	xdata,
		void(*)(void *)	freefn
	)

Pushes an exception Sets the current exception, pushing it onto the dynamic exception stack.

The condition and context are constant strings, the details should be a mallocd string. xdata and freefn can be NULL. if freefn is provided, it is called on xdata when the exception is popped.

Parameters:

condition	a utf-8 condition string (u8_condition)
context	a utf-8 context string (a const string)
details	a utf-8 string detailing the error, or NULL
xdata	a void pointer to additional data describing the error or its context
freefn	a function to call on the xdata when freeing it

Returns:

an exception structure

U8_EXPORT u8_exception u8_restore_exception

(

u8_exception

ex

)

Restores the exception stack Takes an exception structure, typically returned by u8_erreify(), and makes it current.

If there is no current exception, the structure simply becomes the current exception; if there is a current exception, the argument is added as the previous exception to the root of the current exception.

Parameters:

ex	a pointer to an exception structure not currently on the stack

Returns:

an exception structure, the new current exception (possibly NULL)

U8_EXPORT U8_NOINLINE int u8_reterr	(	u8_condition	c,
		u8_context	cxt,
		u8_string	details
	)

Sets the current error state and returns an error value (-1) The condition and context are constant strings, but the details string should be mallocd.

Parameters:

c	a utf-8 condition string (u8_condition)
cxt	a utf-8 context string (a const string)
details	a utf-8 string detailing the error, or NULL

Returns:

-1

U8_EXPORT U8_NOINLINE void u8_seterr	(	u8_condition	condition,
		u8_context	context,
		u8_string	details
	)

Sets the current error state.

The condition and context are constant strings, but the details string should be mallocd.

Parameters:

condition	a utf-8 condition string (u8_condition)
context	a utf-8 context string (a const string)
details	a utf-8 string detailing the error, or NULL

Returns:

void

U8_EXPORT u8_condition u8_strerror

(

int

num

)

Returns a u8_condition object corresponding to a given errno, using the POSIX strerror function.

Parameters:

num	an errno value

Returns:

a utf-8 condition object (a const string)