Error.h revision 0d62dfd4974eb23f550f992e594894b96c5696d1
1//===-- Error.h -------------------------------------------------*- C++ -*-===// 2// 3// The LLVM Compiler Infrastructure 4// 5// This file is distributed under the University of Illinois Open Source 6// License. See LICENSE.TXT for details. 7// 8//===----------------------------------------------------------------------===// 9 10#ifndef __DCError_h__ 11#define __DCError_h__ 12#if defined(__cplusplus) 13 14#ifdef __APPLE__ 15#include <mach/mach.h> 16#endif 17#include <stdint.h> 18#include <stdio.h> 19#include <string> 20 21#include "lldb/lldb-private.h" 22 23namespace lldb_private { 24 25class Log; 26 27//---------------------------------------------------------------------- 28/// @class Error Error.h "lldb/Core/Error.h" 29/// @brief An error handling class. 30/// 31/// This class is designed to be able to hold any error code that can be 32/// encountered on a given platform. The errors are stored as a value 33/// of type Error::ValueType. This value should be large enough to hold 34/// any and all errors that the class supports. Each error has an 35/// associated type that is of type lldb::ErrorType. New types 36/// can be added to support new error types, and architecture specific 37/// types can be enabled. In the future we may wish to switch to a 38/// registration mechanism where new error types can be registered at 39/// runtime instead of a hard coded scheme. 40/// 41/// All errors in this class also know how to generate a string 42/// representation of themselves for printing results and error codes. 43/// The string value will be fetched on demand and its string value will 44/// be cached until the error is cleared of the value of the error 45/// changes. 46//---------------------------------------------------------------------- 47class Error 48{ 49public: 50 //------------------------------------------------------------------ 51 /// Every error value that this object can contain needs to be able 52 /// to fit into ValueType. 53 //------------------------------------------------------------------ 54 typedef uint32_t ValueType; 55 56 //------------------------------------------------------------------ 57 /// Default constructor. 58 /// 59 /// Initialize the error object with a generic success value. 60 /// 61 /// @param[in] err 62 /// An error code. 63 /// 64 /// @param[in] type 65 /// The type for \a err. 66 //------------------------------------------------------------------ 67 Error (); 68 69 explicit 70 Error (ValueType err, lldb::ErrorType type = lldb::eErrorTypeGeneric); 71 72 Error (const Error &rhs); 73 //------------------------------------------------------------------ 74 /// Assignment operator. 75 /// 76 /// @param[in] err 77 /// An error code. 78 /// 79 /// @return 80 /// A const reference to this object. 81 //------------------------------------------------------------------ 82 const Error& 83 operator = (const Error& rhs); 84 85 86 //------------------------------------------------------------------ 87 /// Assignment operator from a kern_return_t. 88 /// 89 /// Sets the type to \c MachKernel and the error code to \a err. 90 /// 91 /// @param[in] err 92 /// A mach error code. 93 /// 94 /// @return 95 /// A const reference to this object. 96 //------------------------------------------------------------------ 97 const Error& 98 operator = (uint32_t err); 99 100 ~Error(); 101 102 //------------------------------------------------------------------ 103 /// Get the error string associated with the current error. 104 // 105 /// Gets the error value as a NULL terminated C string. The error 106 /// string will be fetched and cached on demand. The error string 107 /// will be retrieved from a callback that is appropriate for the 108 /// type of the error and will be cached until the error value is 109 /// changed or cleared. 110 /// 111 /// @return 112 /// The error as a NULL terminated C string value if the error 113 /// is valid and is able to be converted to a string value, 114 /// NULL otherwise. 115 //------------------------------------------------------------------ 116 const char * 117 AsCString (const char *default_error_str = "unknown error") const; 118 119 //------------------------------------------------------------------ 120 /// Clear the object state. 121 /// 122 /// Reverts the state of this object to contain a generic success 123 /// value and frees any cached error string value. 124 //------------------------------------------------------------------ 125 void 126 Clear (); 127 128 //------------------------------------------------------------------ 129 /// Test for error condition. 130 /// 131 /// @return 132 /// \b true if this object contains an error, \b false 133 /// otherwise. 134 //------------------------------------------------------------------ 135 bool 136 Fail () const; 137 138 //------------------------------------------------------------------ 139 /// Access the error value. 140 /// 141 /// @return 142 /// The error value. 143 //------------------------------------------------------------------ 144 ValueType 145 GetError () const; 146 147 //------------------------------------------------------------------ 148 /// Access the error type. 149 /// 150 /// @return 151 /// The error type enumeration value. 152 //------------------------------------------------------------------ 153 lldb::ErrorType 154 GetType () const; 155 156 //------------------------------------------------------------------ 157 /// Log an error to Log(). 158 /// 159 /// Log the error given a formatted string \a format. If the this 160 /// object contains an error code, update the error string to 161 /// contain the prefix "error: ", followed by the formatted string, 162 /// followed by the error value and any string that describes the 163 /// error value. This allows more context to be given to an error 164 /// string that remains cached in this object. Logging always occurs 165 /// even when the error code contains a non-error value. 166 /// 167 /// @param[in] format 168 /// A printf style format string. 169 /// 170 /// @param[in] ... 171 /// Variable arguments that are needed for the printf style 172 /// format string \a format. 173 //------------------------------------------------------------------ 174 void 175 PutToLog (Log *log, const char *format, ...); 176 177 //------------------------------------------------------------------ 178 /// Log an error to Log() if the error value is an error. 179 /// 180 /// Log the error given a formatted string \a format only if the 181 /// error value in this object describes an error condition. If the 182 /// this object contains an error, update the error string to 183 /// contain the prefix "error: " followed by the formatted string, 184 /// followed by the error value and any string that describes the 185 /// error value. This allows more context to be given to an error 186 /// string that remains cached in this object. 187 /// 188 /// @param[in] format 189 /// A printf style format string. 190 /// 191 /// @param[in] ... 192 /// Variable arguments that are needed for the printf style 193 /// format string \a format. 194 //------------------------------------------------------------------ 195 void 196 LogIfError (Log *log, const char *format, ...); 197 198 //------------------------------------------------------------------ 199 /// Set accessor from a kern_return_t. 200 /// 201 /// Set accesssor for the error value to \a err and the error type 202 /// to \c MachKernel. 203 /// 204 /// @param[in] err 205 /// A mach error code. 206 //------------------------------------------------------------------ 207 void 208 SetError (uint32_t err); 209 210 //------------------------------------------------------------------ 211 /// Set accesssor with an error value and type. 212 /// 213 /// Set accesssor for the error value to \a err and the error type 214 /// to \a type. 215 /// 216 /// @param[in] err 217 /// A mach error code. 218 /// 219 /// @param[in] type 220 /// The type for \a err. 221 //------------------------------------------------------------------ 222 void 223 SetError (ValueType err, lldb::ErrorType type); 224 225 //------------------------------------------------------------------ 226 /// Set the current error to errno. 227 /// 228 /// Update the error value to be \c errno and update the type to 229 /// be \c Error::POSIX. 230 //------------------------------------------------------------------ 231 void 232 SetErrorToErrno (); 233 234 //------------------------------------------------------------------ 235 /// Set the current error to a generic error. 236 /// 237 /// Update the error value to be \c LLDB_GENERIC_ERROR and update the 238 /// type to be \c Error::Generic. 239 //------------------------------------------------------------------ 240 void 241 SetErrorToGenericError (); 242 243 //------------------------------------------------------------------ 244 /// Set the current error string to \a err_str. 245 /// 246 /// Set accessor for the error string value for a generic errors, 247 /// or to supply additional details above and beyond the standard 248 /// error strings that the standard type callbacks typically 249 /// provide. This allows custom strings to be supplied as an 250 /// error explanation. The error string value will remain until the 251 /// error value is cleared or a new error value/type is assigned. 252 /// 253 /// @param err_str 254 /// The new custom error string to copy and cache. 255 //------------------------------------------------------------------ 256 void 257 SetErrorString (const char *err_str); 258 259 //------------------------------------------------------------------ 260 /// Set the current error string to a formatted error string. 261 /// 262 /// @param format 263 /// A printf style format string 264 //------------------------------------------------------------------ 265 int 266 SetErrorStringWithFormat (const char *format, ...); 267 268 int 269 SetErrorStringWithVarArg (const char *format, va_list args); 270 271 //------------------------------------------------------------------ 272 /// Test for success condition. 273 /// 274 /// Returns true if the error code in this object is considered a 275 /// successful return value. 276 /// 277 /// @return 278 /// \b true if this object contains an value that describes 279 /// success (non-erro), \b false otherwise. 280 //------------------------------------------------------------------ 281 bool 282 Success () const; 283 284protected: 285 //------------------------------------------------------------------ 286 /// Member variables 287 //------------------------------------------------------------------ 288 ValueType m_code; ///< Error code as an integer value. 289 lldb::ErrorType m_type; ///< The type of the above error code. 290 mutable std::string m_string; ///< A string representation of the error code. 291}; 292 293} // namespace lldb_private 294 295#endif // #if defined(__cplusplus) 296#endif // #ifndef __DCError_h__ 297