icalerror.h File Reference

Error handling for libical. More...

Go to the source code of this file.

Macros
#define	ICAL_ERRORS_ARE_FATAL   0
	Determines if all libical errors are fatal and lead to the process aborting. More...
#define	ICAL_SETERROR_ISFUNC
#define	icalerrno   (*(icalerrno_return()))
	Access the current icalerrno value. More...
#define	icalerror_assert(test, message)
	Assert with a message. More...
#define	icalerror_check_arg(test, arg)
	Checks the assertion test and raises error on failure. More...
#define	icalerror_check_arg_re(test, arg, error)
	Checks the assertion test and raises error on failure, returns error. More...
#define	icalerror_check_arg_rv(test, arg)
	Checks the assertion test and raises error on failure, returns void. More...
#define	icalerror_check_arg_rx(test, arg, x)
	Checks the assertion test and raises error on failure, returns x. More...
#define	icalerror_check_arg_rz(test, arg)
	Checks the assertion test and raises error on failure, returns 0. More...
#define	icalerror_check_component_type(value, type)   ;
#define	icalerror_check_parameter_type(value, type)   ;
#define	icalerror_check_property_type(value, type)   ;
#define	icalerror_check_value_type(value, type)   ;
#define	icalerror_warn(message)   {fprintf(stderr, "%s:%d: %s\n", __FILE__, __LINE__, message);}
	Prints a formatted warning message to stderr. More...

Typedefs
typedef enum icalerrorenum	icalerrorenum
typedef enum icalerrorstate	icalerrorstate

Enumerations
enum	icalerrorenum {   ICAL_NO_ERROR = 0, ICAL_BADARG_ERROR, ICAL_NEWFAILED_ERROR, ICAL_ALLOCATION_ERROR,   ICAL_MALFORMEDDATA_ERROR, ICAL_PARSE_ERROR, ICAL_INTERNAL_ERROR, ICAL_FILE_ERROR,   ICAL_USAGE_ERROR, ICAL_UNIMPLEMENTED_ERROR, ICAL_UNKNOWN_ERROR }
	Represents the different types of errors that can be triggered in libical. More...
enum	icalerrorstate { ICAL_ERROR_FATAL, ICAL_ERROR_NONFATAL, ICAL_ERROR_DEFAULT, ICAL_ERROR_UNKNOWN }
	Determine if an error is fatal or non-fatal. More...

Functions
void	ical_bt (void)
	Prints backtrace. More...
icalerrorenum *	icalerrno_return (void)
	Returns the current icalerrno value. More...
void	icalerror_clear_errno (void)
	Resets icalerrno to ICAL_NO_ERROR. More...
void	icalerror_crash_here (void)
	Triggered to abort the process. More...
icalerrorenum	icalerror_error_from_string (const char *str)
	Reads an error from a string. More...
icalerrorstate	icalerror_get_error_state (icalerrorenum error)
	Gets the error state (severity) for a given error. More...
int	icalerror_get_errors_are_fatal (void)
	Determine if errors are fatal. More...
const char *	icalerror_perror (void)
	Returns the description string for the current error in icalerrno. More...
void	icalerror_restore (const char *error, icalerrorstate es)
void	icalerror_set_errno (icalerrorenum x)
	Sets the icalerrno to a given error. More...
void	icalerror_set_error_state (icalerrorenum error, icalerrorstate state)
	Sets the icalerrorstate for a given icalerrorenum error. More...
void	icalerror_set_errors_are_fatal (int fatal)
	Change if errors are fatal. More...
void	icalerror_stop_here (void)
	Triggered before any error is called. More...
const char *	icalerror_strerror (icalerrorenum e)
	Finds the description string for error. More...
icalerrorstate	icalerror_supress (const char *error)
	Suppresses a given error. More...

Detailed Description

Error handling for libical.

Most routines will set the global error value icalerrno on errors. This variable is an enumeration; permissible values can be found in icalerror.h. If the routine returns an enum icalerrorenum, then the return value will be the same as icalerrno. You can use icalerror_strerror() to get a string that describes the error, or icalerror_perror() to get a string describing the current error set in icalerrno.

Macro Definition Documentation

ICAL_ERRORS_ARE_FATAL

#define ICAL_ERRORS_ARE_FATAL   0

Determines if all libical errors are fatal and lead to the process aborting.

If set to 1, all libical errors are fatal and lead to the process aborting upon encountering on. Otherwise, errors are nonfatal.

Can be checked with libical_get_errors_are_fatal().

icalerrno

#define icalerrno   (*(icalerrno_return()))

Access the current icalerrno value.

Returns

The current icalerrno value

Note

Pseudo-variable that can be used to access the current icalerrno.

Usage

if(icalerrno == ICAL_PARSE_ERROR) {
    // ...
}
 
// resets error
icalerrno = ICAL_NO_ERROR;

icalerror_assert

#define icalerror_assert	(		test,
			message
	)

Assert with a message.

Parameters

test	The assertion to test
message	The message to print on failure of assertion

Tests the given assertion test, and if it fails, prints the message given on stderr as a warning and aborts the process. This only works if ICAL_ERRORS_ARE_FATAL is true, otherwise does nothing.

icalerror_check_arg

#define icalerror_check_arg	(		test,
			arg
	)

Value:

if (!(test)) { \
    icalerror_set_errno(ICAL_BADARG_ERROR); \
}

Checks the assertion test and raises error on failure.

Parameters

test	The assertion to check
arg	The argument involved (as a string)

This function checks the assertion test, which is used to test if the parameter arg is correct. If the assertion fails, it sets icalerrno to ICAL_BADARG_ERROR.

Example

void test_function(icalcomponent *component) {
   icalerror_check_arg(component != 0, "component");
 
   // use component
}

icalerror_check_arg_re

#define icalerror_check_arg_re	(		test,
			arg,
			error
	)

Value:

if (!(test)) { \
    icalerror_stop_here(); \
    assert(0); \
    return error; \
}

Checks the assertion test and raises error on failure, returns error.

Parameters

test	The assertion to check
arg	The argument involved (as a string)
error	What to return on error

This function checks the assertion test, which is used to test if the parameter arg is correct. If the assertion fails, it aborts the process with assert(0) and causes the enclosing function to return error.

Example

icalcomponent *test_function(icalcomponent *component) {
   icalerror_check_arg_re(component != 0, "component", NULL);
 
   // use component
   return icalcomponent_get_first_real_component(component);
}

icalerror_check_arg_rv

#define icalerror_check_arg_rv	(		test,
			arg
	)

Value:

if (!(test)) { \
    icalerror_set_errno(ICAL_BADARG_ERROR); \
    return; \
}

Checks the assertion test and raises error on failure, returns void.

Parameters

test	The assertion to check
arg	The argument involved (as a string)

This function checks the assertion test, which is used to test if the parameter arg is correct. If the assertion fails, it sets icalerrno to ICAL_BADARG_ERROR and causes the enclosing function to return void.

Example

void test_function(icalcomponent *component) {
   icalerror_check_arg_rv(component != 0, "component");
 
   // use component
}

icalerror_check_arg_rx

#define icalerror_check_arg_rx	(		test,
			arg,
			x
	)

Value:

if (!(test)) { \
    icalerror_set_errno(ICAL_BADARG_ERROR); \
    return x; \
}

Checks the assertion test and raises error on failure, returns x.

Parameters

test	The assertion to check
arg	The argument involved (as a string)
x	What to return on error

This function checks the assertion test, which is used to test if the parameter arg is correct. If the assertion fails, it sets icalerrno to ICAL_BADARG_ERROR and causes the enclosing function to return x.

Example

icalcomponent *test_function(icalcomponent *component) {
   icalerror_check_arg_rx(component != 0, "component", NULL);
 
   // use component
   return icalcomponent_get_first_real_component(component);
}

icalerror_check_arg_rz

#define icalerror_check_arg_rz	(		test,
			arg
	)

Value:

if (!(test)) { \
    icalerror_set_errno(ICAL_BADARG_ERROR); \
    return 0; \
}

Checks the assertion test and raises error on failure, returns 0.

Parameters

test	The assertion to check
arg	The argument involved (as a string)

This function checks the assertion test, which is used to test if the parameter arg is correct. If the assertion fails, it sets icalerrno to ICAL_BADARG_ERROR and causes the enclosing function to return 0.

Example

int test_function(icalcomponent *component) {
   icalerror_check_arg_rz(component != 0, "component");
 
   // use component
   return icalcomponent_count_kinds(component, ICAL_ANY_COMPONENT);
}

icalerror_warn

#define icalerror_warn

(

message

)

{fprintf(stderr, "%s:%d: %s\n", __FILE__, __LINE__, message);}

Prints a formatted warning message to stderr.

Parameters

message

Warning message to print

Usage

icalerror_warn("Non-standard tag encountered");

Enumeration Type Documentation

icalerrorenum

enum icalerrorenum

Represents the different types of errors that can be triggered in libical.

Each of these values represent a different type of error, which is stored in icalerrno on exit of the library function (or can be returned, but if it is, icalerrno is also set).

Enumerator
ICAL_NO_ERROR	No error happened.
ICAL_BADARG_ERROR	A bad argument was passed to a function.
ICAL_NEWFAILED_ERROR	An error occurred while creating a new object with a *_new() routine.
ICAL_ALLOCATION_ERROR	An error occurred while allocating some memory.
ICAL_MALFORMEDDATA_ERROR	Malformed data was passed to a function.
ICAL_PARSE_ERROR	An error occurred while parsing part of an iCal component.
ICAL_INTERNAL_ERROR	An internal error happened in library code.
ICAL_FILE_ERROR	An error happened while working with a file.
ICAL_USAGE_ERROR	Failure to properly sequence calls to a set of interfaces.
ICAL_UNIMPLEMENTED_ERROR	An unimplemented function was called.
ICAL_UNKNOWN_ERROR	An unknown error occurred.

icalerrorstate

enum icalerrorstate

Determine if an error is fatal or non-fatal.

Enumerator
ICAL_ERROR_FATAL	Fatal.
ICAL_ERROR_NONFATAL	Non-fatal.
ICAL_ERROR_DEFAULT	Fatal if icalerror_errors_are_fatal(), non-fatal otherwise.
ICAL_ERROR_UNKNOWN	Asked state for an unknown error type.

Function Documentation

ical_bt()

void ical_bt

(

void

)

Prints backtrace.

Note

Only works on systems that support it (HAVE_BACKTRACE enabled).

Usage

if(icalerrno != ICAL_NO_ERROR) {
    ical_bt();
}

icalerrno_return()

icalerrorenum* icalerrno_return

(

void

)

Returns the current icalerrno value.

Returns

A pointer to the current icalerrno value

Yields a pointer to the current icalerrno value. This can be used to access (read from and write to) it.

Examples

assert(*icalerrno_return() == icalerrno);

icalerror_clear_errno()

void icalerror_clear_errno

(

void

)

Resets icalerrno to ICAL_NO_ERROR.

Usage

if(icalerrno == ICAL_PARSE_ERROR) {
    // ignore parsing errors
    icalerror_clear_errno();
}

icalerror_crash_here()

void icalerror_crash_here

(

void

)

Triggered to abort the process.

This routine is called to abort the process in the case of an error.

icalerror_error_from_string()

icalerrorenum icalerror_error_from_string

(

const char *

str

)

Reads an error from a string.

Parameters

str	The error name string

Returns

An icalerrorenum representing the error

Error handling

If the error specified in str can't be found, instead ICAL_UNKNOWN_ERROR is returned.

Usage

assert(icalerror_error_from_string("PARSE") == ICAL_PARSE_ERROR);
assert(icalerror_error_from_string("NONSENSE") == ICAL_UNKNOWN_ERROR);

icalerror_get_error_state()

icalerrorstate icalerror_get_error_state

(

icalerrorenum

error

)

Gets the error state (severity) for a given error.

Parameters

error

The error to examine

Returns

Returns the severity of the error

icalerror_get_errors_are_fatal()

int icalerror_get_errors_are_fatal

(

void

)

Determine if errors are fatal.

Returns

True if libical errors are fatal

Usage

if(icalerror_get_errors_are_fatal()) {
    // since errors are fatal, this will abort the
    // program.
    icalerror_set_errno(ICAL_PARSE_ERROR);
}

icalerror_perror()

const char* icalerror_perror

(

void

)

Returns the description string for the current error in icalerrno.

Error handling

If the type of error e wasn't found, it returns the description for ICAL_UNKNOWN_ERROR.

Ownership

The string that is returned is owned by the library and must not be free'd() by the user.

Usage

if(icalerrno != ICAL_NO_ERROR) {
    printf("%s\n", icalerror_perror());
}

icalerror_restore()

void icalerror_restore	(	const char *	error,
		icalerrorstate	es
	)

Assigns the given error the given icalerrorstate (severity).

Parameters

error	The error in question
es	The icalerrorstate (severity) to set it to

Calling the function changes the icalerrorstate of the given error.

Usage

// suppress internal errors
icalerror_supress("INTERNAL");
 
// ...
 
// restore internal errors
icalerror_restore("INTERNAL", ICAL_ERROR_DEFAULT);

icalerror_set_errno()

void icalerror_set_errno

(

icalerrorenum

x

)

Sets the icalerrno to a given error.

Parameters

x	The error to set icalerrno to

Sets icalerrno to the error given in x. Additionally, if the error is an ICAL_ERROR_FATAL or if it's an ICAL_ERROR_DEFAULT and ICAL_ERRORS_ARE_FATAL is true, it prints a warning to stderr and aborts the process.

Usage

icalerror_set_errno(ICAL_PARSE_ERROR);

icalerror_set_error_state()

void icalerror_set_error_state	(	icalerrorenum	error,
		icalerrorstate	state
	)

Sets the icalerrorstate for a given icalerrorenum error.

Parameters

error	The error to change
state	The new error state of the error

Sets the severity of a given error. For example, it can be used to set the severity of an ICAL_PARSE_ERROR to be an ICAL_ERROR_NONFATAL.

Usage

icalerror_set_error_state(ICAL_PARSE_ERROR, ICAL_ERROR_NONFATAL);

icalerror_set_errors_are_fatal()

void icalerror_set_errors_are_fatal

(

int

fatal

)

Change if errors are fatal.

Parameters

fatal

If true, libical aborts after a call to icalerror_set_error()

Warning

NOT THREAD SAFE: it is recommended that you do not change this in a multithreaded program.

Usage

icalerror_set_errors_are_fatal(true); // default
icalerror_set_errors_are_fatal(false);

icalerror_stop_here()

void icalerror_stop_here

(

void

)

Triggered before any error is called.

This routine is called before any error is triggered. It is called by icalerror_set_errno(), so it does not appear in all of the macros below.

This routine can be used while debugging by setting a breakpoint here.

icalerror_strerror()

const char* icalerror_strerror

(

icalerrorenum

e

)

Finds the description string for error.

Parameters

e	The type of error that occurred

Returns

A string describing the error that occurred

Error handling

If the type of error e wasn't found, it returns the description for ICAL_UNKNOWN_ERROR.

Ownership

The string that is returned is owned by the library and must not be free'd() by the user.

Usage

if(icalerrno != ICAL_NO_ERROR) {
    printf("%s\n", icalerror_strerror(icalerrno));
}

icalerror_supress()

icalerrorstate icalerror_supress

(

const char *

error

)

Suppresses a given error.

Parameters

error

The name of the error to suppress

Returns

The previous icalerrorstate (severity)

Calling this function causes the given error to be listed as ICAL_ERROR_NONFATAL, and thus suppressed. Error states can be restored with icalerror_restore().

Usage

// suppresses internal errors
icalerror_supress("INTERNAL");