/usr/include/avis/errors.h is in libavis-dev 1.2.4-9.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 | /*
* Avis Elvin client library for C.
*
* Copyright (C) 2008 Matthew Phillips <avis@mattp.name>
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of version 3 of the GNU Lesser General
* Public License as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/** \file
* Error handling.
*/
#ifndef AVIS_ERRORS_H_
#define AVIS_ERRORS_H_
#include <stdlib.h>
#include <avis/stdtypes.h>
#include <avis/defs.h>
/**
* Error reporting information for the Avis client library. Functions
* in the library that may fail will use a pointer to an
* ElvinError instance to indicate, via an error code and message, if the
* function or any sub function fails. As a convenience, functions which
* would otherwise return void will often return true/false to indicate
* error status.
*
* Note that the Elvin struct used for client connections contains an
* embedded error context that takes the place of an explicit error
* context parameter.
*
* Example:
* <pre>
* ElvinError error = ELVIN_EMPTY_ERROR;
*
* function_that_may_fail (arg1, arg2, ..., &error);
*
* if (elvin_error_occurred (&error))
* elvin_perror ("error", &error);
*
* elvin_error_free (&error);
* </pre>
*
* @see elvin_error_set()
* @see elvin_error_ok()
* @see on_error_return_false()
* @see on_error_return()
*/
typedef struct
{
int code;
char * message;
} ElvinError;
#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)
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);
#define avis_emalloc(size) do_avis_emalloc ((size), __FILE__, __LINE__)
#define avis_estrdup(str) do_avis_estrdup ((str), __FILE__, __LINE__)
/**
* 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_EMPTY_ERROR {ELVIN_ERROR_NONE, NULL}
/**
* Free any resources allocated to an error instance and reset the
* error code. The error instance may be reused after this call.
*
* @see elvin_error_reset()
*/
AVIS_PUBLIC
void elvin_error_free (ElvinError *error);
/**
* Initialise an uninitialised error instance.
*
* @see ELVIN_EMPTY_ERROR
* @see elvin_error_reset()
*/
AVIS_PUBLIC
void elvin_error_init (ElvinError *error);
/**
* Free any resources and reset the error info back to OK state.
*/
#define elvin_error_reset(error) (elvin_error_free (error))
/**
* Macro statement to return false if an error is set in the "error"
* variable inside the current scope.
*
* @param stat The statement to execute before the test.
*
* See also on_error_return().
*/
#define on_error_return_false(stat) on_error_return (stat, false)
/**
* Macro statement to return a given value if an error is set in the
* "error" variable inside the current scope.
*
* @param stat The statement to execute before the test.
* @param retval The value to return on error.
*
* See also on_error_return().
*/
#define on_error_return(stat, retval) \
{stat; if (elvin_error_occurred (error)) return (retval);}
/**
* Convert the h_errno error code generated by gethostbyname () etc to
* an error code that can be used with elvin_error_set().
*/
#define host_to_elvin_error(code) (ELVIN_HOST_ERROR_BASE + (code))
/**
* Translate a system errno error code into a code that can be used with
* elvin_error_set().
*/
#define errno_to_elvin_error(code) (ELVIN_ERRNO_BASE + (code))
/**
* Like perror () but taking error info from an ElvinError instance.
*/
AVIS_PUBLIC
void elvin_perror (const char *tag, ElvinError *error);
/**
* Load an error status from the system's "errno" error variable and
* strerror () function.
*
* @param error The error to affect.
*
* @see elvin_error_set()
*/
AVIS_PUBLIC
bool elvin_error_from_errno (ElvinError *error);
/**
* 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).
*
* @param error The error to target.
* @param code The error code. One of the ELVIN_ERROR_* defines or
* host_to_elvin_error().
* @param message The message, possibly including printf-style format
* placeholders.
* @param ... The rest of the arguments if message contains format
* placeholders.
*
* @return Returns false as a convenience so that this can be used in
* return statements indicating an error.
*
* @see elvin_error_from_errno()
* @see elvin_error_free()
*/
AVIS_PUBLIC
bool elvin_error_set (ElvinError *error, int code, const char *message, ...);
/**
* True if no error has occurred.
*/
#define elvin_error_ok(error) ((error)->code == ELVIN_ERROR_NONE)
/**
* True if an error has occurred.
*/
#define elvin_error_occurred(error) (!elvin_error_ok (error))
#endif /*AVIS_ERRORS_H_*/
|