Error handling for libical. More...

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

Enumerations
enum	icalerrorenum { ICAL_NO_ERROR = 0, ICAL_BADARG_ERROR, ICAL_NEWFAILED_ERROR, ICAL_ALLOCATION_ERROR, ICAL_THREADING_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. More...

void	icalerror_clear_errno (void)
	Resets icalerrno to ICAL_NO_ERROR. 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...

bool	icalerror_get_errors_are_fatal (void)
	Determine if errors are fatal. More...

icalerrorenum *	icalerror_icalerrno (void)
	Returns the current icalerrno value. More...

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. 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 (bool fatal)
	Change if errors are fatal. 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.

Definition in file icalerror.h.

Macro Definition Documentation

#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

```c if(icalerrno == ICAL_PARSE_ERROR) { // ... }

// resets error icalerrno = ICAL_NO_ERROR;
```

Definition at line 133 of file icalerror.h.

Enumeration Type Documentation

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_THREADING_ERROR	An error occurred with threading.
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.

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 88 of file icalerror.h.

Function Documentation

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.

void icalerror_clear_errno ( void )

Resets icalerrno to ICAL_NO_ERROR.

Usage

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

Definition at line 85 of file icalerror.c.

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

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

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

bool icalerror_get_errors_are_fatal ( void )

Determine if errors are fatal.

Returns: True if libical errors are fatal

Usage

```c 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.

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

```c assert(*icalerror_icalerrno() == icalerrno);
```

Definition at line 58 of file icalerror.c.

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

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

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

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

```c // suppress internal errors icalerror_supress("INTERNAL");

// ...

// restore internal errors icalerror_restore("INTERNAL", ICAL_ERROR_DEFAULT);
```

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

```c icalerror_set_errno(ICAL_PARSE_ERROR);
```

Definition at line 90 of file icalerror.c.

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

```c icalerror_set_error_state(ICAL_PARSE_ERROR, ICAL_ERROR_NONFATAL);
```

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

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

Definition at line 31 of file icalerror.c.

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

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

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

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

Libical API Documentation 4.0 STABLE VERSION Visit the v3.0 documentation

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation