icalerror.h File Reference

Error handling for libical. More...

Go to the source code of this file.

Macros
#define	icalerrno   (*(icalerror_icalerrno()))
	Access the current icalerrno value.

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	icalerror_backtrace (void)
	Prints backtrace.
void	icalerror_clear_errno (void)
	Resets icalerrno to ICAL_NO_ERROR.
icalerrorenum	icalerror_error_from_string (const char *str)
	Reads an error from a string.
icalerrorstate	icalerror_get_error_state (icalerrorenum error)
	Gets the error state (severity) for a given error.
bool	icalerror_get_errors_are_fatal (void)
	Determine if errors are fatal.
icalerrorenum *	icalerror_icalerrno (void)
	Returns the current icalerrno value.
const char *	icalerror_perror (void)
void	icalerror_restore (const char *error, icalerrorstate es)
void	icalerror_set_errno (icalerrorenum x)
	Sets the icalerrno to a given error.
void	icalerror_set_error_state (icalerrorenum error, icalerrorstate state)
	Sets the icalerrorstate for a given icalerrorenum error.
void	icalerror_set_errors_are_fatal (bool fatal)
	Change if errors are fatal.
const char *	icalerror_strerror (icalerrorenum e)
	Finds the description string for error.
icalerrorstate	icalerror_supress (const char *error)
	Suppresses a given error.

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.

Definition in file icalerror.h.

Macro Definition Documentation

icalerrno

#define icalerrno   (*(icalerror_icalerrno()))

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;

Definition at line 130 of file icalerror.h.

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.

Definition at line 41 of file icalerror.h.

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.

Definition at line 85 of file icalerror.h.

Function Documentation

icalerror_backtrace()

void icalerror_backtrace

(

void

)

Prints backtrace.

Note

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

Usage

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

Definition at line 101 of file icalerror.c.

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();
}

Definition at line 85 of file icalerror.c.

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()

bool 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);
}

Definition at line 36 of file icalerror.c.

icalerror_icalerrno()

icalerrorenum * icalerror_icalerrno

(

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(*icalerror_icalerrno() == icalerrno);

Definition at line 58 of file icalerror.c.

icalerror_perror()

const char * icalerror_perror

(

void

)

Gets the description string for the current error in icalerrno

Error handling

If the type of error 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 freed by the user.

Usage

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

Returns

a pointer to a char string containing the description of the current icalerror.

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 icalerror_get_errors_are_fatal() is true, it prints a warning to stderr and aborts the process.

Usage

icalerror_set_errno(ICAL_PARSE_ERROR);

Definition at line 90 of file icalerror.c.

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

(

bool

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);

Definition at line 31 of file icalerror.c.

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");