contrib/llvm/tools/lldb/include/lldb/Core/Error.h

   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
  22 namespace lldb_private {
  23
  24 class 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 //----------------------------------------------------------------------
  46 class Error
  47 {
  48 public:
  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     void
 214     SetExpressionError (lldb::ExpressionResults, const char *mssg);
 215
 216     int
 217     SetExpressionErrorWithFormat (lldb::ExpressionResults, const char *format, ...) __attribute__ ((format (printf, 3,4)));
 218
 219     //------------------------------------------------------------------
 220     /// Set accesssor with an error value and type.
 221     ///
 222     /// Set accesssor for the error value to \a err and the error type
 223     /// to \a type.
 224     ///
 225     /// @param[in] err
 226     ///     A mach error code.
 227     ///
 228     /// @param[in] type
 229     ///     The type for \a err.
 230     //------------------------------------------------------------------
 231     void
 232     SetError (ValueType err, lldb::ErrorType type);
 233
 234     //------------------------------------------------------------------
 235     /// Set the current error to errno.
 236     ///
 237     /// Update the error value to be \c errno and update the type to
 238     /// be \c Error::POSIX.
 239     //------------------------------------------------------------------
 240     void
 241     SetErrorToErrno ();
 242
 243     //------------------------------------------------------------------
 244     /// Set the current error to a generic error.
 245     ///
 246     /// Update the error value to be \c LLDB_GENERIC_ERROR and update the
 247     /// type to be \c Error::Generic.
 248     //------------------------------------------------------------------
 249     void
 250     SetErrorToGenericError ();
 251
 252     //------------------------------------------------------------------
 253     /// Set the current error string to \a err_str.
 254     ///
 255     /// Set accessor for the error string value for a generic errors,
 256     /// or to supply additional details above and beyond the standard
 257     /// error strings that the standard type callbacks typically
 258     /// provide. This allows custom strings to be supplied as an
 259     /// error explanation. The error string value will remain until the
 260     /// error value is cleared or a new error value/type is assigned.
 261     ///
 262     /// @param err_str
 263     ///     The new custom error string to copy and cache.
 264     //------------------------------------------------------------------
 265     void
 266     SetErrorString (const char *err_str);
 267
 268     //------------------------------------------------------------------
 269     /// Set the current error string to a formatted error string.
 270     ///
 271     /// @param format
 272     ///     A printf style format string
 273     //------------------------------------------------------------------
 274     int
 275     SetErrorStringWithFormat (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
 276
 277     int
 278     SetErrorStringWithVarArg (const char *format, va_list args);
 279
 280     //------------------------------------------------------------------
 281     /// Test for success condition.
 282     ///
 283     /// Returns true if the error code in this object is considered a
 284     /// successful return value.
 285     ///
 286     /// @return
 287     ///     \b true if this object contains an value that describes
 288     ///     success (non-erro), \b false otherwise.
 289     //------------------------------------------------------------------
 290     bool
 291     Success () const;
 292
 293     //------------------------------------------------------------------
 294     /// Test for a failure due to a generic interrupt.
 295     ///
 296     /// Returns true if the error code in this object was caused by an interrupt.
 297     /// At present only supports Posix EINTR.
 298     ///
 299     /// @return
 300     ///     \b true if this object contains an value that describes
 301     ///     failure due to interrupt, \b false otherwise.
 302     //------------------------------------------------------------------
 303     bool
 304     WasInterrupted() const;
 305
 306 protected:
 307     //------------------------------------------------------------------
 308     /// Member variables
 309     //------------------------------------------------------------------
 310     ValueType m_code;               ///< Error code as an integer value.
 311     lldb::ErrorType m_type;         ///< The type of the above error code.
 312     mutable std::string m_string;   ///< A string representation of the error code.
 313 };
 314
 315 } // namespace lldb_private
 316
 317 #endif  // #if defined(__cplusplus)
 318 #endif    // #ifndef __DCError_h__