Libical API Documentation 3.0

Macros | Typedefs | Enumerations | Functions
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;
ICAL_NO_ERROR
@ ICAL_NO_ERROR
Definition: icalerror.h:78
ICAL_PARSE_ERROR
@ ICAL_PARSE_ERROR
Definition: icalerror.h:93
icalerrno
#define icalerrno
Access the current icalerrno value.
Definition: icalerror.h:144

## ◆ 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); \
}
ICAL_BADARG_ERROR
@ ICAL_BADARG_ERROR
Definition: icalerror.h:81

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
#define icalerror_check_arg(test, arg)
Checks the assertion test and raises error on failure.
Definition: icalerror.h:441
icalcomponent_impl
Definition: icalcomponent.c:36

## ◆ 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);
}
icalcomponent_get_first_real_component
icalcomponent * icalcomponent_get_first_real_component(icalcomponent *c)
Returns a reference to the first VEVENT, VTODO or VJOURNAL in the component.
Definition: icalcomponent.c:582
icalerror_check_arg_re
#define icalerror_check_arg_re(test, arg, error)
Checks the assertion test and raises error on failure, returns error.
Definition: icalerror.h:518

## ◆ 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_rv
#define icalerror_check_arg_rv(test, arg)
Checks the assertion test and raises error on failure, returns void.
Definition: icalerror.h:465

## ◆ 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_rx
#define icalerror_check_arg_rx(test, arg, x)
Checks the assertion test and raises error on failure, returns x.
Definition: icalerror.h:546

## ◆ 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_check_arg_rz
#define icalerror_check_arg_rz(test, arg)
Checks the assertion test and raises error on failure, returns 0.
Definition: icalerror.h:491

## ◆ 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");
icalerror_warn
#define icalerror_warn(message)
Prints a formatted warning message to stderr.
Definition: icalerror.h:192

## 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();
}
ical_bt
void ical_bt(void)
Prints backtrace.
Definition: icalerror.c:260

## ◆ 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);
icalerrno_return
icalerrorenum * icalerrno_return(void)
Returns the current icalerrno value.
Definition: icalerror.c:70

## ◆ 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_clear_errno
void icalerror_clear_errno(void)
Resets icalerrno to ICAL_NO_ERROR.
Definition: icalerror.c:95

## ◆ 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);
ICAL_UNKNOWN_ERROR
@ ICAL_UNKNOWN_ERROR
Definition: icalerror.h:108
icalerror_error_from_string
icalerrorenum icalerror_error_from_string(const char *str)
Reads an error from a string.
Definition: icalerror.c:181

## ◆ 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_get_errors_are_fatal
int icalerror_get_errors_are_fatal(void)
Determine if errors are fatal.
Definition: icalerror.c:111
icalerror_set_errno
void icalerror_set_errno(icalerrorenum x)
Sets the icalerrno to a given error.
Definition: icalerror.c:117

## ◆ 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_perror
const char * icalerror_perror(void)
Returns the description string for the current error in icalerrno.
Definition: icalerror.c:209

## ◆ 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);
ICAL_ERROR_DEFAULT
@ ICAL_ERROR_DEFAULT
Definition: icalerror.h:223
icalerror_restore
void icalerror_restore(const char *error, icalerrorstate es)
Definition: icalerror.c:214
icalerror_supress
icalerrorstate icalerror_supress(const char *error)
Suppresses a given error.
Definition: icalerror.c:194

## ◆ 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);
ICAL_ERROR_NONFATAL
@ ICAL_ERROR_NONFATAL
Definition: icalerror.h:220
icalerror_set_error_state
void icalerror_set_error_state(icalerrorenum error, icalerrorstate state)
Sets the icalerrorstate for a given icalerrorenum error.
Definition: icalerror.c:223

## ◆ 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_set_errors_are_fatal
void icalerror_set_errors_are_fatal(int fatal)
Change if errors are fatal.
Definition: icalerror.c:106

## ◆ 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_strerror
const char * icalerror_strerror(icalerrorenum e)
Finds the description string for error.
Definition: icalerror.c:247

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