Error.h revision 6206317b8d8b0e8b51a9ab7d75803340216a57e6
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 explicit 68 Error (ValueType err = 0, lldb::ErrorType type = lldb::eErrorTypeGeneric); 69 70 //------------------------------------------------------------------ 71 /// Assignment operator. 72 /// 73 /// @param[in] err 74 /// An error code. 75 /// 76 /// @return 77 /// A const reference to this object. 78 //------------------------------------------------------------------ 79 const Error& 80 operator = (const Error& rhs); 81 82 83 //------------------------------------------------------------------ 84 /// Assignment operator from a kern_return_t. 85 /// 86 /// Sets the type to \c MachKernel and the error code to \a err. 87 /// 88 /// @param[in] err 89 /// A mach error code. 90 /// 91 /// @return 92 /// A const reference to this object. 93 //------------------------------------------------------------------ 94 const Error& 95 operator = (uint32_t err); 96 97 ~Error(); 98 99 //------------------------------------------------------------------ 100 /// Get the error string associated with the current error. 101 // 102 /// Gets the error value as a NULL terminated C string. The error 103 /// string will be fetched and cached on demand. The error string 104 /// will be retrieved from a callback that is appropriate for the 105 /// type of the error and will be cached until the error value is 106 /// changed or cleared. 107 /// 108 /// @return 109 /// The error as a NULL terminated C string value if the error 110 /// is valid and is able to be converted to a string value, 111 /// NULL otherwise. 112 //------------------------------------------------------------------ 113 const char * 114 AsCString (const char *default_error_str = "unknown error") const; 115 116 //------------------------------------------------------------------ 117 /// Clear the object state. 118 /// 119 /// Reverts the state of this object to contain a generic success 120 /// value and frees any cached error string value. 121 //------------------------------------------------------------------ 122 void 123 Clear (); 124 125 //------------------------------------------------------------------ 126 /// Test for error condition. 127 /// 128 /// @return 129 /// \b true if this object contains an error, \b false 130 /// otherwise. 131 //------------------------------------------------------------------ 132 bool 133 Fail () const; 134 135 //------------------------------------------------------------------ 136 /// Access the error value. 137 /// 138 /// @return 139 /// The error value. 140 //------------------------------------------------------------------ 141 ValueType 142 GetError () const; 143 144 //------------------------------------------------------------------ 145 /// Access the error type. 146 /// 147 /// @return 148 /// The error type enumeration value. 149 //------------------------------------------------------------------ 150 lldb::ErrorType 151 GetType () const; 152 153 //------------------------------------------------------------------ 154 /// Log an error to Log(). 155 /// 156 /// Log the error given a formatted string \a format. If the this 157 /// object contains an error code, update the error string to 158 /// contain the prefix "error: ", followed by the formatted string, 159 /// followed by the error value and any string that describes the 160 /// error value. This allows more context to be given to an error 161 /// string that remains cached in this object. Logging always occurs 162 /// even when the error code contains a non-error value. 163 /// 164 /// @param[in] format 165 /// A printf style format string. 166 /// 167 /// @param[in] ... 168 /// Variable arguments that are needed for the printf style 169 /// format string \a format. 170 //------------------------------------------------------------------ 171 void 172 PutToLog (Log *log, const char *format, ...); 173 174 //------------------------------------------------------------------ 175 /// Log an error to Log() if the error value is an error. 176 /// 177 /// Log the error given a formatted string \a format only if the 178 /// error value in this object describes an error condition. If the 179 /// this object contains an error, update the error string to 180 /// contain the prefix "error: " followed by the formatted string, 181 /// followed by the error value and any string that describes the 182 /// error value. This allows more context to be given to an error 183 /// string that remains cached in this object. 184 /// 185 /// @param[in] format 186 /// A printf style format string. 187 /// 188 /// @param[in] ... 189 /// Variable arguments that are needed for the printf style 190 /// format string \a format. 191 //------------------------------------------------------------------ 192 void 193 LogIfError (Log *log, const char *format, ...); 194 195 //------------------------------------------------------------------ 196 /// Set accessor from a kern_return_t. 197 /// 198 /// Set accesssor for the error value to \a err and the error type 199 /// to \c MachKernel. 200 /// 201 /// @param[in] err 202 /// A mach error code. 203 //------------------------------------------------------------------ 204 void 205 SetError (uint32_t err); 206 207 //------------------------------------------------------------------ 208 /// Set accesssor with an error value and type. 209 /// 210 /// Set accesssor for the error value to \a err and the error type 211 /// to \a type. 212 /// 213 /// @param[in] err 214 /// A mach error code. 215 /// 216 /// @param[in] type 217 /// The type for \a err. 218 //------------------------------------------------------------------ 219 void 220 SetError (ValueType err, lldb::ErrorType type); 221 222 //------------------------------------------------------------------ 223 /// Set the current error to errno. 224 /// 225 /// Update the error value to be \c errno and update the type to 226 /// be \c Error::POSIX. 227 //------------------------------------------------------------------ 228 void 229 SetErrorToErrno (); 230 231 //------------------------------------------------------------------ 232 /// Set the current error to a generic error. 233 /// 234 /// Update the error value to be \c LLDB_GENERIC_ERROR and update the 235 /// type to be \c Error::Generic. 236 //------------------------------------------------------------------ 237 void 238 SetErrorToGenericError (); 239 240 //------------------------------------------------------------------ 241 /// Set the current error string to \a err_str. 242 /// 243 /// Set accessor for the error string value for a generic errors, 244 /// or to supply additional details above and beyond the standard 245 /// error strings that the standard type callbacks typically 246 /// provide. This allows custom strings to be supplied as an 247 /// error explanation. The error string value will remain until the 248 /// error value is cleared or a new error value/type is assigned. 249 /// 250 /// @param err_str 251 /// The new custom error string to copy and cache. 252 //------------------------------------------------------------------ 253 void 254 SetErrorString (const char *err_str); 255 256 //------------------------------------------------------------------ 257 /// Set the current error string to a formatted error string. 258 /// 259 /// @param format 260 /// A printf style format string 261 //------------------------------------------------------------------ 262 int 263 SetErrorStringWithFormat (const char *format, ...); 264 265 int 266 SetErrorStringWithVarArg (const char *format, va_list args); 267 268 //------------------------------------------------------------------ 269 /// Test for success condition. 270 /// 271 /// Returns true if the error code in this object is considered a 272 /// successful return value. 273 /// 274 /// @return 275 /// \b true if this object contains an value that describes 276 /// success (non-erro), \b false otherwise. 277 //------------------------------------------------------------------ 278 bool 279 Success () const; 280 281protected: 282 //------------------------------------------------------------------ 283 /// Member variables 284 //------------------------------------------------------------------ 285 ValueType m_code; ///< Error code as an integer value. 286 lldb::ErrorType m_type; ///< The type of the above error code. 287 mutable std::string m_string; ///< A string representation of the error code. 288}; 289 290} // namespace lldb_private 291 292#endif // #if defined(__cplusplus) 293#endif // #ifndef __DCError_h__ 294