1 //===-- Status.h ------------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef LLDB_UTILITY_STATUS_H
11 #define LLDB_UTILITY_STATUS_H
13 #include "lldb/lldb-defines.h"
14 #include "lldb/lldb-enumerations.h" // for ErrorType, ErrorType...
15 #include "llvm/ADT/StringRef.h" // for StringRef
16 #include "llvm/Support/Error.h"
17 #include "llvm/Support/FormatVariadic.h"
19 #include <stdint.h> // for uint32_t
21 #include <system_error> // for error_code
22 #include <type_traits> // for forward
28 namespace lldb_private {
30 //----------------------------------------------------------------------
31 /// @class Status Status.h "lldb/Utility/Status.h"
32 /// @brief An error handling class.
34 /// This class is designed to be able to hold any error code that can be
35 /// encountered on a given platform. The errors are stored as a value
36 /// of type Status::ValueType. This value should be large enough to hold
37 /// any and all errors that the class supports. Each error has an
38 /// associated type that is of type lldb::ErrorType. New types
39 /// can be added to support new error types, and architecture specific
40 /// types can be enabled. In the future we may wish to switch to a
41 /// registration mechanism where new error types can be registered at
42 /// runtime instead of a hard coded scheme.
44 /// All errors in this class also know how to generate a string
45 /// representation of themselves for printing results and error codes.
46 /// The string value will be fetched on demand and its string value will
47 /// be cached until the error is cleared of the value of the error
49 //----------------------------------------------------------------------
52 //------------------------------------------------------------------
53 /// Every error value that this object can contain needs to be able
54 /// to fit into ValueType.
55 //------------------------------------------------------------------
56 typedef uint32_t ValueType;
58 //------------------------------------------------------------------
59 /// Default constructor.
61 /// Initialize the error object with a generic success value.
67 /// The type for \a err.
68 //------------------------------------------------------------------
71 explicit Status(ValueType err,
72 lldb::ErrorType type = lldb::eErrorTypeGeneric);
74 /* implicit */ Status(std::error_code EC);
76 explicit Status(const char *format, ...)
77 __attribute__((format(printf, 2, 3)));
79 Status(const Status &rhs);
80 //------------------------------------------------------------------
81 /// Assignment operator.
87 /// A const reference to this object.
88 //------------------------------------------------------------------
89 const Status &operator=(const Status &rhs);
91 //------------------------------------------------------------------
92 /// Assignment operator from a kern_return_t.
94 /// Sets the type to \c MachKernel and the error code to \a err.
97 /// A mach error code.
100 /// A const reference to this object.
101 //------------------------------------------------------------------
102 const Status &operator=(uint32_t err);
106 // llvm::Error support
107 explicit Status(llvm::Error error) { *this = std::move(error); }
108 const Status &operator=(llvm::Error error);
109 llvm::Error ToError() const;
111 //------------------------------------------------------------------
112 /// Get the error string associated with the current error.
114 /// Gets the error value as a NULL terminated C string. The error
115 /// string will be fetched and cached on demand. The error string
116 /// will be retrieved from a callback that is appropriate for the
117 /// type of the error and will be cached until the error value is
118 /// changed or cleared.
121 /// The error as a NULL terminated C string value if the error
122 /// is valid and is able to be converted to a string value,
124 //------------------------------------------------------------------
125 const char *AsCString(const char *default_error_str = "unknown error") const;
127 //------------------------------------------------------------------
128 /// Clear the object state.
130 /// Reverts the state of this object to contain a generic success
131 /// value and frees any cached error string value.
132 //------------------------------------------------------------------
135 //------------------------------------------------------------------
136 /// Test for error condition.
139 /// \b true if this object contains an error, \b false
141 //------------------------------------------------------------------
144 //------------------------------------------------------------------
145 /// Access the error value.
149 //------------------------------------------------------------------
150 ValueType GetError() const;
152 //------------------------------------------------------------------
153 /// Access the error type.
156 /// The error type enumeration value.
157 //------------------------------------------------------------------
158 lldb::ErrorType GetType() const;
160 //------------------------------------------------------------------
161 /// Set accessor from a kern_return_t.
163 /// Set accesssor for the error value to \a err and the error type
164 /// to \c MachKernel.
167 /// A mach error code.
168 //------------------------------------------------------------------
169 void SetMachError(uint32_t err);
171 void SetExpressionError(lldb::ExpressionResults, const char *mssg);
173 int SetExpressionErrorWithFormat(lldb::ExpressionResults, const char *format,
174 ...) __attribute__((format(printf, 3, 4)));
176 //------------------------------------------------------------------
177 /// Set accesssor with an error value and type.
179 /// Set accesssor for the error value to \a err and the error type
183 /// A mach error code.
186 /// The type for \a err.
187 //------------------------------------------------------------------
188 void SetError(ValueType err, lldb::ErrorType type);
190 //------------------------------------------------------------------
191 /// Set the current error to errno.
193 /// Update the error value to be \c errno and update the type to
194 /// be \c Status::POSIX.
195 //------------------------------------------------------------------
196 void SetErrorToErrno();
198 //------------------------------------------------------------------
199 /// Set the current error to a generic error.
201 /// Update the error value to be \c LLDB_GENERIC_ERROR and update the
202 /// type to be \c Status::Generic.
203 //------------------------------------------------------------------
204 void SetErrorToGenericError();
206 //------------------------------------------------------------------
207 /// Set the current error string to \a err_str.
209 /// Set accessor for the error string value for a generic errors,
210 /// or to supply additional details above and beyond the standard
211 /// error strings that the standard type callbacks typically
212 /// provide. This allows custom strings to be supplied as an
213 /// error explanation. The error string value will remain until the
214 /// error value is cleared or a new error value/type is assigned.
217 /// The new custom error string to copy and cache.
218 //------------------------------------------------------------------
219 void SetErrorString(llvm::StringRef err_str);
221 //------------------------------------------------------------------
222 /// Set the current error string to a formatted error string.
225 /// A printf style format string
226 //------------------------------------------------------------------
227 int SetErrorStringWithFormat(const char *format, ...)
228 __attribute__((format(printf, 2, 3)));
230 int SetErrorStringWithVarArg(const char *format, va_list args);
232 template <typename... Args>
233 void SetErrorStringWithFormatv(const char *format, Args &&... args) {
234 SetErrorString(llvm::formatv(format, std::forward<Args>(args)...).str());
237 //------------------------------------------------------------------
238 /// Test for success condition.
240 /// Returns true if the error code in this object is considered a
241 /// successful return value.
244 /// \b true if this object contains an value that describes
245 /// success (non-erro), \b false otherwise.
246 //------------------------------------------------------------------
247 bool Success() const;
249 //------------------------------------------------------------------
250 /// Test for a failure due to a generic interrupt.
252 /// Returns true if the error code in this object was caused by an interrupt.
253 /// At present only supports Posix EINTR.
256 /// \b true if this object contains an value that describes
257 /// failure due to interrupt, \b false otherwise.
258 //------------------------------------------------------------------
259 bool WasInterrupted() const;
262 //------------------------------------------------------------------
264 //------------------------------------------------------------------
265 ValueType m_code; ///< Status code as an integer value.
266 lldb::ErrorType m_type; ///< The type of the above error code.
267 mutable std::string m_string; ///< A string representation of the error code.
270 } // namespace lldb_private
273 template <> struct format_provider<lldb_private::Status> {
274 static void format(const lldb_private::Status &error, llvm::raw_ostream &OS,
275 llvm::StringRef Options);
279 #endif // #ifndef LLDB_UTILITY_STATUS_H