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. More...
 

Functions

U8_EXPORT u8_condition u8_strerror (int num)
 Returns a u8_condition object corresponding to a given errno, using the POSIX strerror function. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
U8_EXPORT u8_exception u8_erreify (void)
 Returns and clears the current error state. More...
 
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. More...
 
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. More...
 
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(). More...
 
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. More...
 
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. More...
 
U8_EXPORT void u8_clear_errors (int report)
 Clears all current errors. More...
 
U8_EXPORT u8_string u8_errstring (struct U8_EXCEPTION *errdata)
 Returns a UTF-8 string describing an error state. More...
 
U8_EXPORT void u8_graberr (int num, u8_context cxt, u8_string details)
 Takes an errno error and creates a libu8 error, given a particular context and details string. More...
 
U8_EXPORT void u8_graberrno (u8_context cxt, u8_string details)
 Takes the current errno value (if non zero) and creates a libu8 error, given a particular context and details string. More...
 
U8_EXPORT U8_NOINLINE void u8_seterr (u8_condition condition, u8_context context, u8_string details)
 Sets the current error state. More...
 
U8_EXPORT int u8_geterr (u8_condition *conditionp, u8_context *contextp, u8_string *detailsp)
 Gets the current error state. More...
 
U8_EXPORT int u8_poperr (u8_condition *conditionp, u8_context *contextp, u8_string *detailsp)
 Gets and clears the current error state. More...
 

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

References u8_logger(), u8_pop_exception(), and U8_STREAM_OWNS_BUF.

Referenced by u8_add_server(), and u8_rmdir().

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

References u8_printf().

Referenced by u8_reterr().

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

References U8_INIT_STATIC_OUTPUT.

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

References u8_make_exception().

Referenced by u8_push_exception().

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

Referenced by u8_poperr().

U8_EXPORT void u8_graberr ( int  num,
u8_context  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)

References u8_seterr(), and u8_strerror().

Referenced by u8_chmod(), u8_connect_x(), u8_file_atime(), u8_file_ctime(), u8_file_mode(), u8_file_mtime(), u8_file_owner(), u8_file_size(), u8_getcwd(), u8_gethostbyname(), u8_gethostname(), u8_graberrno(), u8_init_connpool(), u8_init_xtime(), u8_local_xtime(), u8_lookup_host(), u8_movefile(), u8_now(), u8_open_fd(), u8_readlink(), u8_removefile(), u8_renew(), u8_rmdir(), u8_sessionid(), u8_set_nodelay(), u8_setcwd(), u8_shutdown_server(), u8_subscribe(), and u8_use_syslog().

U8_EXPORT void u8_graberrno ( u8_context  cxt,
u8_string  details 
)

Takes the current errno value (if non zero) and creates a libu8 error, given a particular context and details string.

Parameters
cxta context string (a const utf-8 string)
detailsa details string (a malloc'd utf-8 string)

References u8_graberr().

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

References u8_new_exception().

Referenced by u8_extend_exception(), and u8_push_exception().

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
ca utf-8 condition string (u8_condition)
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

References u8_push_exception().

Referenced by u8_make_exception(), and u8_push_exception().

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)

References u8_log().

Referenced by u8_clear_errors(), and u8_poperr().

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

References u8_geterr(), and u8_pop_exception().

Referenced by u8_renew_all().

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

References u8_extend_exception(), u8_make_exception(), and u8_new_exception().

Referenced by u8_new_exception(), u8_reterr(), and u8_seterr().

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

References u8_errpush(), and u8_push_exception().

Referenced by u8_do_printf(), u8_file_atime(), u8_linkfile(), u8_random_vector(), u8_set_mtime(), and u8_shutdown_server().

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

References u8_push_exception().

Referenced by u8_connect_x(), u8_dynamic_load(), u8_extalloc(), u8_get_connection(), u8_getenv(), u8_gethostbyname(), u8_getrusage(), u8_graberr(), u8_lookup_host(), u8_mallocz(), u8_parse_entity_err(), u8_random_vector(), u8_read_base16(), u8_readlink(), u8_reallocz(), u8_reconnect(), u8_rmdir(), u8_sessionid(), u8_set_default_encoding(), u8_sha1(), u8_sha256(), u8_shutdown_server(), and u8_ungetc().

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)

References u8_fromlibc().

Referenced by u8_graberr(), u8_renew_all(), and u8_signal_raise().