Avis Client Library: avis/errors.h File Reference

# avis/errors.h File Reference

## Detailed Description

Error handling.

`#include <stdlib.h>`
`#include <avis/stdtypes.h>`
`#include <avis/defs.h>`

Go to the source code of this file.

## Data Structures
struct | ElvinError
| Error reporting information for the Avis client library. More...
## Defines
#define | ELVIN_ERROR_BASE 0
#define | ELVIN_ERRNO_BASE 10000
#define | ELVIN_HOST_ERROR_BASE 20000
#define | ELVIN_ERROR_NONE 0
#define | ELVIN_ERROR_INTERNAL (ELVIN_ERROR_BASE + 1)
#define | ELVIN_ERROR_PROTOCOL (ELVIN_ERROR_BASE + 2)
#define | ELVIN_ERROR_CONNECTION_CLOSED (ELVIN_ERROR_BASE + 3)
#define | ELVIN_ERROR_INVALID_URI (ELVIN_ERROR_BASE + 4)
#define | ELVIN_ERROR_SYNTAX (ELVIN_ERROR_BASE + 5)
#define | ELVIN_ERROR_TRIVIAL_EXPRESSION (ELVIN_ERROR_BASE + 6)
#define | ELVIN_ERROR_NACK (ELVIN_ERROR_BASE + 7)
#define | ELVIN_ERROR_USAGE (ELVIN_ERROR_BASE + 8)
#define | ELVIN_ERROR_TIMEOUT (ELVIN_ERROR_BASE + 9)
#define | ELVIN_ERROR_ROUTER_FAILURE (ELVIN_ERROR_BASE + 10)
#define | avis_emalloc(size) do_avis_emalloc ((size), __FILE__, __LINE__)
#define | avis_estrdup(str) do_avis_estrdup ((str), __FILE__, __LINE__)
#define | ELVIN_EMPTY_ERROR {ELVIN_ERROR_NONE, NULL}
| An empty error instance.
#define | elvin_error_reset(error) (elvin_error_free (error))
| Free any resources and reset the error info back to OK state.
#define | on_error_return_false(stat) on_error_return (stat, false)
| Macro statement to return false if an error is set in the "error" variable inside the current scope.
#define | on_error_return(stat, retval) {stat; if (elvin_error_occurred (error)) return (retval);}
| Macro statement to return a given value if an error is set in the "error" variable inside the current scope.
#define | host_to_elvin_error(code) (ELVIN_HOST_ERROR_BASE + (code))
| Convert the h_errno error code generated by gethostbyname () etc to an error code that can be used with elvin_error_set().
#define | errno_to_elvin_error(code) (ELVIN_ERRNO_BASE + (code))
| Translate a system errno error code into a code that can be used with elvin_error_set().
#define | elvin_error_ok(error) ((error)->code == ELVIN_ERROR_NONE)
| True if no error has occurred.
#define | elvin_error_occurred(error) (!elvin_error_ok (error))
| True if an error has occurred.
## Functions
AVIS_PUBLIC void * | do_avis_emalloc (size_t size, const char *file, int line)
AVIS_PUBLIC char * | do_avis_estrdup (const char *str, const char *file, int line)
AVIS_PUBLIC void | elvin_error_free (ElvinError *error)
| Free any resources allocated to an error instance and reset the error code.
AVIS_PUBLIC void | elvin_error_init (ElvinError *error)
| Initialise an uninitialised error instance.
AVIS_PUBLIC void | elvin_perror (const char *tag, ElvinError *error)
| Like perror () but taking error info from an ElvinError instance.
AVIS_PUBLIC bool | elvin_error_from_errno (ElvinError *error)
| Load an error status from the system's "errno" error variable and strerror () function.
AVIS_PUBLIC bool | elvin_error_set (ElvinError *error, int code, const char *message,...)
| Signal an error has occurred.

## Define Documentation

#define avis_emalloc | ( | size |  | ) | do_avis_emalloc ((size), __FILE__, __LINE__)

#define avis_estrdup | ( | str |  | ) | do_avis_estrdup ((str), __FILE__, __LINE__)

#define ELVIN_EMPTY_ERROR {ELVIN_ERROR_NONE, NULL}

An empty error instance.

This can be assigned to an error instance to initialise it on declaration rather than using elvin_error_init() (which is the other method). Regardless of initialisation method, elvin_error_free() should be used to release any resources allocated before disposing.

#define ELVIN_ERRNO_BASE 10000

#define ELVIN_ERROR_BASE 0

#define ELVIN_ERROR_CONNECTION_CLOSED (ELVIN_ERROR_BASE + 3)

#define ELVIN_ERROR_INTERNAL (ELVIN_ERROR_BASE + 1)

#define ELVIN_ERROR_INVALID_URI (ELVIN_ERROR_BASE + 4)

#define ELVIN_ERROR_NACK (ELVIN_ERROR_BASE + 7)

#define ELVIN_ERROR_NONE 0

#define elvin_error_occurred | ( | error |  | ) | (!elvin_error_ok (error))

True if an error has occurred.

#define elvin_error_ok | ( | error |  | ) | ((error)->code == ELVIN_ERROR_NONE)

True if no error has occurred.

#define ELVIN_ERROR_PROTOCOL (ELVIN_ERROR_BASE + 2)

#define elvin_error_reset | ( | error |  | ) | (elvin_error_free (error))

Free any resources and reset the error info back to OK state.

#define ELVIN_ERROR_ROUTER_FAILURE (ELVIN_ERROR_BASE + 10)

#define ELVIN_ERROR_SYNTAX (ELVIN_ERROR_BASE + 5)

#define ELVIN_ERROR_TIMEOUT (ELVIN_ERROR_BASE + 9)

#define ELVIN_ERROR_TRIVIAL_EXPRESSION (ELVIN_ERROR_BASE + 6)

#define ELVIN_ERROR_USAGE (ELVIN_ERROR_BASE + 8)

#define ELVIN_HOST_ERROR_BASE 20000

#define errno_to_elvin_error | ( | code |  | ) | (ELVIN_ERRNO_BASE + (code))

Translate a system errno error code into a code that can be used with elvin_error_set().

#define host_to_elvin_error | ( | code |  | ) | (ELVIN_HOST_ERROR_BASE + (code))

Convert the h_errno error code generated by gethostbyname () etc to an error code that can be used with elvin_error_set().

#define on_error_return | ( | stat,
|  | retval |  | ) | {stat; if (elvin_error_occurred (error)) return (retval);}

Macro statement to return a given value if an error is set in the "error" variable inside the current scope.

Parameters:

  | stat | The statement to execute before the test.
  | retval | The value to return on error.

See also on_error_return().

#define on_error_return_false | ( | stat |  | ) | on_error_return (stat, false)

Macro statement to return false if an error is set in the "error" variable inside the current scope.

Parameters:

  | stat | The statement to execute before the test.

See also on_error_return().

## Function Documentation

AVIS_PUBLIC void* do_avis_emalloc | ( | size_t | size,
|  | const char * | file,
|  | int | line |
| ) |  |  |

AVIS_PUBLIC char* do_avis_estrdup | ( | const char * | str,
|  | const char * | file,
|  | int | line |
| ) |  |  |

AVIS_PUBLIC void elvin_error_free | ( | ElvinError * | error | ) |

Free any resources allocated to an error instance and reset the error code.

The error instance may be reused after this call.

See also:
  elvin_error_reset()

AVIS_PUBLIC bool elvin_error_from_errno | ( | ElvinError * | error | ) |

Load an error status from the system's "errno" error variable and strerror () function.

Parameters:

  | error | The error to affect.

See also:
  elvin_error_set()

AVIS_PUBLIC void elvin_error_init | ( | ElvinError * | error | ) |

Initialise an uninitialised error instance.

See also:
  ELVIN_EMPTY_ERROR

  elvin_error_reset()

AVIS_PUBLIC bool elvin_error_set | ( | ElvinError * | error,
|  | int | code,
|  | const char * | message,
|  |  | ... |
| ) |  |  |

Signal an error has occurred.

If an error is already set, this has no effect (see elvin_error_reset() if you want to override any existing error status).

Parameters:

  | error | The error to target.
  | code | The error code. One of the ELVIN_ERROR_* defines or host_to_elvin_error().
  | message | The message, possibly including printf-style format placeholders.
  | ... | The rest of the arguments if message contains format placeholders.

Returns:
  Returns false as a convenience so that this can be used in return statements indicating an error.

See also:
  elvin_error_from_errno()

  elvin_error_free()

AVIS_PUBLIC void elvin_perror | ( | const char * | tag,
|  | ElvinError * | error |
| ) |  |  |

Like perror () but taking error info from an ElvinError instance.