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     /// 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
 299 protected:
 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__