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