libu8
Data Structures | Typedefs | Functions
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:
reportan 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:
errdataa 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:
exan 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:
exan 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:
cxta utf-8 context string (a const string)
detailsa utf-8 string detailing the error, or NULL
xdataa void pointer to additional data describing the error or its context
freefna 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:
exa pointer to an exception structure
full1/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:
conditionpa pointer to a location to store the error condition
contextpa pointer to a location to store the error context
detailspa 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:
numan errno number
cxta context string (a const utf-8 string)
detailsa 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:
conditiona utf-8 condition string (u8_condition)
contexta utf-8 context string (a const string)
detailsa utf-8 string detailing the error, or NULL
xdataa void pointer to additional data describing the error or its context
freefna 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:
conditiona utf-8 condition string (u8_condition)
contexta utf-8 context string (a const string)
detailsa utf-8 string detailing the error, or NULL
xdataa void pointer to additional data describing the error or its context
freefna 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:
conditionpa pointer to a location to store the error condition
contextpa pointer to a location to store the error context
detailspa 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:
conditiona utf-8 condition string (u8_condition)
contexta utf-8 context string (a const string)
detailsa utf-8 string detailing the error, or NULL
xdataa void pointer to additional data describing the error or its context
freefna 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:
exa 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:
ca utf-8 condition string (u8_condition)
cxta utf-8 context string (a const string)
detailsa 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:
conditiona utf-8 condition string (u8_condition)
contexta utf-8 context string (a const string)
detailsa 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:
numan errno value
Returns:
a utf-8 condition object (a const string)