aboutsummaryrefslogtreecommitdiffstats
path: root/include/lldb/Utility/Status.h
blob: ae730b90dffe5b466e94f7b4f741d0cf15ac52c7 (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
//===-- Status.h ------------------------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//

#ifndef LLDB_UTILITY_STATUS_H
#define LLDB_UTILITY_STATUS_H

#include "lldb/lldb-defines.h"
#include "lldb/lldb-enumerations.h"
#include "llvm/ADT/StringRef.h"
#include "llvm/Support/Error.h"
#include "llvm/Support/FormatVariadic.h"
#include <cstdarg>
#include <stdint.h>
#include <string>
#include <system_error>
#include <type_traits>

namespace llvm {
class raw_ostream;
}

namespace lldb_private {

/// \class Status Status.h "lldb/Utility/Status.h" 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)));

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

  ~Status();

  // llvm::Error support
  explicit Status(llvm::Error error) { *this = std::move(error); }
  const Status &operator=(llvm::Error error);
  llvm::Error ToError() const;

  /// 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 // #ifndef LLDB_UTILITY_STATUS_H