1 /* EINA - EFL data type library 2 * Copyright (C) 2007-2008 Jorge Luis Zapata Muga, Cedric Bail 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2.1 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this library; 16 * if not, see <http://www.gnu.org/licenses/>. 17 */ 18 19 #ifndef EINA_ERROR_H_ 20 #define EINA_ERROR_H_ 21 22 #include <stdarg.h> 23 24 #include "eina_types.h" 25 26 27 /** 28 * @page tutorial_error_page Error Tutorial 29 * 30 * @section tutorial_error_registering_msg Registering messages 31 * 32 * The error module can provide a system that extends the errno system 33 * of the C standard library. It consists in 2 parts: 34 * 35 * @li A way of registering new messages with 36 * eina_error_msg_register() and eina_error_msg_get(), 37 * @li A way of setting / getting the last error message with 38 * eina_error_set() / eina_error_get(). 39 * 40 * So one has to first register all the error messages that a program 41 * or a library should manage. Then, when an error occurs, use 42 * eina_error_set(), and when errors are managed, use 43 * eina_error_get(). If eina_error_set() is used to set an error, do 44 * not forget to remove previous set errors before calling eina_error_set(). 45 * 46 * Here is an example for use: 47 * 48 * @include eina_error_01.c 49 * @example eina_error_01.c 50 * 51 * Of course, instead of printf(), eina_log_print() can be used to 52 * have beautiful error messages. 53 */ 54 55 /** 56 * @defgroup Eina_Error_Group Error 57 * @ingroup Eina_Tools_Group 58 * 59 * @brief This group discusses the functions that provide error management for projects. 60 * 61 * The Eina error module provides a way to manage errors in a simple 62 * but powerful way in libraries and modules. It is also used in Eina 63 * itself. An extension to libC's @c errno and strerror() facilities, 64 * this is extensible and recommended for other libraries and 65 * applications as well. 66 * 67 * While libC's @c errno is fixed, Eina_Error can be extended by 68 * libraries and applications with domain-specific codes and 69 * associated error messages. All @c errno.h codes are usable 70 * seamlessly with Eina_Error. The constants defined in errno.h will 71 * have messages as reported by strerror() in eina_error_msg_get() 72 * 73 * Success (no-error) condition is reported with Eina_Error 0 74 * (#EINA_ERROR_NO_ERROR). 75 * 76 * A simple example of how to use this can be seen @ref tutorial_error_page 77 * "here". 78 * 79 * @{ 80 */ 81 82 /** 83 * @typedef Eina_Error 84 * @brief The integer type containing the error type. 85 * 86 * Errors are registered with eina_error_msg_register(), 87 * eina_error_msg_static_register() or those inherited from the 88 * system's @c errno.h such as @c ENOMEM. 89 */ 90 typedef int Eina_Error; 91 92 /** 93 * @typedef Eina_Success_Flag 94 * @brief A flag indicating a function completed succesfully. 95 * 96 * Errors are reported with a EINA_FALSE value for Eina_Success_Flag 97 * return and success with a EINA_TRUE. 98 */ 99 typedef Eina_Bool Eina_Success_Flag; 100 101 /** 102 * @def EINA_ERROR_NO_ERROR 103 * @brief No error reported. 104 * 105 * This is a convenience macro for people that are extra verbose, same 106 * as "0". 107 */ 108 #define EINA_ERROR_NO_ERROR ((Eina_Error)0) 109 110 /** 111 * @var Eina_Error EINA_ERROR_OUT_OF_MEMORY 112 * @brief The error identifier corresponding to lack of memory. 113 * 114 * @deprecated since 1.19, same as @c ENOMEM from @c errno.h 115 */ 116 EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY EINA_DEPRECATED; /* use ENOMEM */ 117 118 /** 119 * @brief Registers a new error type. 120 * @details This function stores the error message described by 121 * @p msg in a list. The returned value is a unique identifier greater than or equal 122 * to @c 1. The description can be retrieved later by passing 123 * the returned value to eina_error_msg_get(). 124 * 125 * @param[in] msg The description of the error \n 126 * It is duplicated using eina_stringshare_add(). 127 * @return The unique number identifier for this error 128 * 129 * @note There is no need to register messages that exist in libC's @c 130 * errno.h, such as @c ENOMEM or @c EBADF. 131 * 132 * @see eina_error_msg_static_register() 133 */ 134 EAPI Eina_Error eina_error_msg_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 135 136 /** 137 * @brief Registers a new error type, statically allocated message. 138 * @details This function stores the error message described by 139 * @p msg in a list. The returned value is a unique identifier greater than or equal 140 * to @c 1. The description can be retrieved later by passing 141 * the returned value to eina_error_msg_get(). 142 * 143 * @param[in] msg The description of the error \n 144 * This string is not duplicated and thus 145 * the given pointer should live during the usage of eina_error. 146 * @return The unique number identifier for this error 147 * 148 * @note There is no need to register messages that exist in libC's @c 149 * errno.h, such as @c ENOMEM or @c EBADF. 150 * 151 * @see eina_error_msg_register() 152 */ 153 EAPI Eina_Error eina_error_msg_static_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 154 155 /** 156 * @brief Changes the message of an already registered message. 157 * @details This function modifies the message associated with @p error and changes 158 * it to @p msg. If the error is previously registered by @ref eina_error_msg_static_register 159 * then the string is not duplicated, otherwise the previous message 160 * is unref'ed and @p msg is copied. 161 * 162 * @param[in] error The Eina_Error to change the message of 163 * @param[in] msg The description of the error \n 164 * This string is duplicated only if the error is registered with @ref eina_error_msg_register, 165 * otherwise it must remain intact for the duration. 166 * @return #EINA_TRUE if successful, otherwise #EINA_FALSE on error 167 * 168 * @note It is not possible to modify messages that exist in libC's @c 169 * errno.h, such as @c ENOMEM or @c EBADF. 170 * 171 * 172 * @see eina_error_msg_register() 173 */ 174 EAPI Eina_Bool eina_error_msg_modify(Eina_Error error, 175 const char *msg) EINA_ARG_NONNULL(2); 176 177 /** 178 * @brief Returns the last set error. 179 * @details This function returns the last error set by eina_error_set(). The 180 * description of the message is returned by eina_error_msg_get(). 181 * 182 * @return The last error or 0 (#EINA_ERROR_NO_ERROR). 183 * 184 * @note This function is thread safe @since 1.10, but slower to use. 185 */ 186 EAPI Eina_Error eina_error_get(void); 187 188 /** 189 * @brief Sets the last error. 190 * @details This function sets the last error identifier. The last error can be 191 * retrieved by eina_error_get(). 192 * 193 * @param[in] err The error identifier 194 * 195 * @note This is also used to clear previous errors, in which case @p err should 196 * be @c 0 (#EINA_ERROR_NO_ERROR). 197 * 198 * @note This function is thread safe @since 1.10, but slower to use. 199 */ 200 EAPI void eina_error_set(Eina_Error err); 201 202 /** 203 * @brief Returns the description of the given error number. 204 * @details This function returns the description of an error that has been 205 * registered by eina_error_msg_register(). If an incorrect error is 206 * given, then @c NULL is returned. 207 * @param[in] error The error number 208 * @return The description of the error 209 * 210 */ 211 EAPI const char *eina_error_msg_get(Eina_Error error) EINA_PURE; 212 213 /** 214 * @brief Finds the #Eina_Error corresponding to a message string. 215 * @details This function attempts to match @p msg with its corresponding #Eina_Error value. 216 * If no such value is found, @c 0 is returned. 217 * 218 * @param[in] msg The error message string to match (NOT @c NULL) 219 * @return The #Eina_Error matching @p msg, otherwise @c 0 on failure 220 * 221 * @note this function only works for explicitly registered errors 222 * such as the messages given to eina_error_msg_register(), 223 * eina_error_msg_static_register() or modified with 224 * eina_error_msg_modify(). 225 */ 226 EAPI Eina_Error eina_error_find(const char *msg) EINA_ARG_NONNULL(1) EINA_PURE; 227 228 /** 229 * @} 230 */ 231 232 #endif /* EINA_ERROR_H_ */ 233