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