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