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 #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
  23 namespace lldb_private {
  24
  25 class 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 //----------------------------------------------------------------------
  47 class Error
  48 {
  49 public:
  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
 300 protected:
 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__