Error handling

Error handling mechanism. More...

Collaboration diagram for Error handling:

Modules
	Csnip error codes

Macros
#define	csnip_err_Unhandled(errnumber)
	Handler for uncaught errors. More...
#define	csnip_err_Raise(value, err_expr)
	Raises an error in a macro. More...

Functions
void	csnip_err_str (int errnum, char *buf, size_t buf_len)
	Return a descriptive error string. More...

Detailed Description

Csnip provides an error handling mechanism for its macro designed to be flexible and simple to use, but not get in the way. Macros that have failure conditions have an error return containing either:

1. The name of an "int" variable that is set to one of the error codes if an error occurs.
2. The special name "_" that results in the csnip_err_Unhandled macro being invoked if an error occurs. By default that macro prints an error message to stderr and terminates the program, but the user can define or redefine that macro to do something else.
3. The special name "error_ignore" that results in potential error being ignored. This is occasionally useful when it's known that the possible errors are not critical, or that they can be detected through other means than csnip's error handling.

Csnip error handling is typically not used for user errors or direct validation of user input.

Macro Definition Documentation

csnip_err_Raise

#define csnip_err_Raise	(		value,
			err_expr
	)

err_expr is the error variable passed by the macro user. err_expr can be one of the following:

• An lvalue (lvalue expression not containing symbols _ or error_ignore). In this case the error code is stored in the err_expr value.
• The special symbol _. In this case the csnip_err_Unhandled macro is invoked. The default implementation of this macro prints out an error message an terminates the application, but the user can redefine it to do anything she wants.
• An lvalue dereferencing the NULL pointer (e.g. *(int*)0); this is equivalent to _.
• The special symbol error_ignore. The error is ignored, i.e., no error value is stored. This is useful, for example, when errors can be detected by means other than inspecting the error variable.

csnip_err_Unhandled

#define csnip_err_Unhandled

(

errnumber

)

This macro is "invoked" when an error occurs while _ is used as the error return value. You can redefine this to whatever you want rather than this default implementation.

Function Documentation

csnip_err_str()

void csnip_err_str	(	int	errnum,
		char *	buf,
		size_t	buf_len
	)

Given a csnip error code, write a descriptive string into a caller supplied buffer.

Parameters

[in]	errnum	the csnip error code (one of the csnip_err_* constants).
	buf	the buffer to write the error to.
	buf_len	the length of the supplied buffer.