aboutsummaryrefslogtreecommitdiff
path: root/include/lldb/Utility/Status.h
blob: 4ac191b1f613765112615883bbb57e4a51fc57ec (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
//===-- Status.h -------------------------------------------------*- C++
//-*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef __DCError_h__
#define __DCError_h__
#if defined(__cplusplus)

#include "lldb/lldb-defines.h"
#include "lldb/lldb-enumerations.h" // for ErrorType, ErrorType...
#include "llvm/ADT/StringRef.h"     // for StringRef
#include "llvm/Support/FormatVariadic.h"

#include <cstdarg>
#include <string>
#include <system_error> // for error_code
#include <type_traits>  // for forward

#include <stdint.h> // for uint32_t

namespace llvm {
class raw_ostream;
}

namespace lldb_private {

//----------------------------------------------------------------------
/// @class Status Status.h "lldb/Utility/Status.h"
/// @brief An error handling class.
///
/// This class is designed to be able to hold any error code that can be
/// encountered on a given platform. The errors are stored as a value
/// of type Status::ValueType. This value should be large enough to hold
/// any and all errors that the class supports. Each error has an
/// associated type that is of type lldb::ErrorType. New types
/// can be added to support new error types, and architecture specific
/// types can be enabled. In the future we may wish to switch to a
/// registration mechanism where new error types can be registered at
/// runtime instead of a hard coded scheme.
///
/// All errors in this class also know how to generate a string
/// representation of themselves for printing results and error codes.
/// The string value will be fetched on demand and its string value will
/// be cached until the error is cleared of the value of the error
/// changes.
//----------------------------------------------------------------------
class Status {
public:
  //------------------------------------------------------------------
  /// Every error value that this object can contain needs to be able
  /// to fit into ValueType.
  //------------------------------------------------------------------
  typedef uint32_t ValueType;

  //------------------------------------------------------------------
  /// Default constructor.
  ///
  /// Initialize the error object with a generic success value.
  ///
  /// @param[in] err
  ///     An error code.
  ///
  /// @param[in] type
  ///     The type for \a err.
  //------------------------------------------------------------------
  Status();

  explicit Status(ValueType err,
                  lldb::ErrorType type = lldb::eErrorTypeGeneric);

  /* implicit */ Status(std::error_code EC);

  explicit Status(const char *format, ...)
      __attribute__((format(printf, 2, 3)));

  Status(const Status &rhs);
  //------------------------------------------------------------------
  /// Assignment operator.
  ///
  /// @param[in] err
  ///     An error code.
  ///
  /// @return
  ///     A const reference to this object.
  //------------------------------------------------------------------
  const Status &operator=(const Status &rhs);

  //------------------------------------------------------------------
  /// Assignment operator from a kern_return_t.
  ///
  /// Sets the type to \c MachKernel and the error code to \a err.
  ///
  /// @param[in] err
  ///     A mach error code.
  ///
  /// @return
  ///     A const reference to this object.
  //------------------------------------------------------------------
  const Status &operator=(uint32_t err);

  ~Status();

  //------------------------------------------------------------------
  /// Get the error string associated with the current error.
  //
  /// Gets the error value as a NULL terminated C string. The error
  /// string will be fetched and cached on demand. The error string
  /// will be retrieved from a callback that is appropriate for the
  /// type of the error and will be cached until the error value is
  /// changed or cleared.
  ///
  /// @return
  ///     The error as a NULL terminated C string value if the error
  ///     is valid and is able to be converted to a string value,
  ///     NULL otherwise.
  //------------------------------------------------------------------
  const char *AsCString(const char *default_error_str = "unknown error") const;

  //------------------------------------------------------------------
  /// Clear the object state.
  ///
  /// Reverts the state of this object to contain a generic success
  /// value and frees any cached error string value.
  //------------------------------------------------------------------
  void Clear();

  //------------------------------------------------------------------
  /// Test for error condition.
  ///
  /// @return
  ///     \b true if this object contains an error, \b false
  ///     otherwise.
  //------------------------------------------------------------------
  bool Fail() const;

  //------------------------------------------------------------------
  /// Access the error value.
  ///
  /// @return
  ///     The error value.
  //------------------------------------------------------------------
  ValueType GetError() const;

  //------------------------------------------------------------------
  /// Access the error type.
  ///
  /// @return
  ///     The error type enumeration value.
  //------------------------------------------------------------------
  lldb::ErrorType GetType() const;

  //------------------------------------------------------------------
  /// Set accessor from a kern_return_t.
  ///
  /// Set accesssor for the error value to \a err and the error type
  /// to \c MachKernel.
  ///
  /// @param[in] err
  ///     A mach error code.
  //------------------------------------------------------------------
  void SetMachError(uint32_t err);

  void SetExpressionError(lldb::ExpressionResults, const char *mssg);

  int SetExpressionErrorWithFormat(lldb::ExpressionResults, const char *format,
                                   ...) __attribute__((format(printf, 3, 4)));

  //------------------------------------------------------------------
  /// Set accesssor with an error value and type.
  ///
  /// Set accesssor for the error value to \a err and the error type
  /// to \a type.
  ///
  /// @param[in] err
  ///     A mach error code.
  ///
  /// @param[in] type
  ///     The type for \a err.
  //------------------------------------------------------------------
  void SetError(ValueType err, lldb::ErrorType type);

  //------------------------------------------------------------------
  /// Set the current error to errno.
  ///
  /// Update the error value to be \c errno and update the type to
  /// be \c Status::POSIX.
  //------------------------------------------------------------------
  void SetErrorToErrno();

  //------------------------------------------------------------------
  /// Set the current error to a generic error.
  ///
  /// Update the error value to be \c LLDB_GENERIC_ERROR and update the
  /// type to be \c Status::Generic.
  //------------------------------------------------------------------
  void SetErrorToGenericError();

  //------------------------------------------------------------------
  /// Set the current error string to \a err_str.
  ///
  /// Set accessor for the error string value for a generic errors,
  /// or to supply additional details above and beyond the standard
  /// error strings that the standard type callbacks typically
  /// provide. This allows custom strings to be supplied as an
  /// error explanation. The error string value will remain until the
  /// error value is cleared or a new error value/type is assigned.
  ///
  /// @param err_str
  ///     The new custom error string to copy and cache.
  //------------------------------------------------------------------
  void SetErrorString(llvm::StringRef err_str);

  //------------------------------------------------------------------
  /// Set the current error string to a formatted error string.
  ///
  /// @param format
  ///     A printf style format string
  //------------------------------------------------------------------
  int SetErrorStringWithFormat(const char *format, ...)
      __attribute__((format(printf, 2, 3)));

  int SetErrorStringWithVarArg(const char *format, va_list args);

  template <typename... Args>
  void SetErrorStringWithFormatv(const char *format, Args &&... args) {
    SetErrorString(llvm::formatv(format, std::forward<Args>(args)...).str());
  }

  //------------------------------------------------------------------
  /// Test for success condition.
  ///
  /// Returns true if the error code in this object is considered a
  /// successful return value.
  ///
  /// @return
  ///     \b true if this object contains an value that describes
  ///     success (non-erro), \b false otherwise.
  //------------------------------------------------------------------
  bool Success() const;

  //------------------------------------------------------------------
  /// Test for a failure due to a generic interrupt.
  ///
  /// Returns true if the error code in this object was caused by an interrupt.
  /// At present only supports Posix EINTR.
  ///
  /// @return
  ///     \b true if this object contains an value that describes
  ///     failure due to interrupt, \b false otherwise.
  //------------------------------------------------------------------
  bool WasInterrupted() const;

protected:
  //------------------------------------------------------------------
  /// Member variables
  //------------------------------------------------------------------
  ValueType m_code;             ///< Status code as an integer value.
  lldb::ErrorType m_type;       ///< The type of the above error code.
  mutable std::string m_string; ///< A string representation of the error code.
};

} // namespace lldb_private

namespace llvm {
template <> struct format_provider<lldb_private::Status> {
  static void format(const lldb_private::Status &error, llvm::raw_ostream &OS,
                     llvm::StringRef Options);
};
}

#endif // #if defined(__cplusplus)
#endif // #ifndef __DCError_h__