1//===-- Status.h ------------------------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLDB_UTILITY_STATUS_H
10#define LLDB_UTILITY_STATUS_H
11
12#include "lldb/lldb-defines.h"
13#include "lldb/lldb-enumerations.h"
14#include "llvm/ADT/StringRef.h"
15#include "llvm/Support/Error.h"
16#include "llvm/Support/FormatVariadic.h"
17#include <cstdarg>
18#include <cstdint>
19#include <string>
20#include <system_error>
21#include <type_traits>
22
23namespace llvm {
24class raw_ostream;
25}
26
27namespace lldb_private {
28
29/// \class Status Status.h "lldb/Utility/Status.h" 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 of type
33/// Status::ValueType. This value should be large enough to hold any and all
34/// errors that the class supports. Each error has an associated type that is
35/// of type lldb::ErrorType. New types can be added to support new error
36/// types, and architecture specific types can be enabled. In the future we
37/// may wish to switch to a registration mechanism where new error types can
38/// be registered at runtime instead of a hard coded scheme.
39///
40/// All errors in this class also know how to generate a string representation
41/// of themselves for printing results and error codes. The string value will
42/// be fetched on demand and its string value will be cached until the error
43/// is cleared of the value of the error changes.
44class Status {
45public:
46 /// Every error value that this object can contain needs to be able to fit
47 /// into ValueType.
48 typedef uint32_t ValueType;
49
50 Status();
51
52 /// Initialize the error object with a generic success value.
53 ///
54 /// \param[in] err
55 /// An error code.
56 ///
57 /// \param[in] type
58 /// The type for \a err.
59 explicit Status(ValueType err,
60 lldb::ErrorType type = lldb::eErrorTypeGeneric);
61
62 Status(std::error_code EC);
63
64 explicit Status(const char *format, ...)
65 __attribute__((format(printf, 2, 3)));
66
67 template <typename... Args>
68 static Status createWithFormat(const char *format, Args &&...args) {
69 return Status(llvm::formatv(format, std::forward<Args>(args)...));
70 }
71
72 ~Status();
73
74 // llvm::Error support
75 explicit Status(llvm::Error error) { *this = std::move(error); }
76 const Status &operator=(llvm::Error error);
77 llvm::Error ToError() const;
78
79 /// Get the error string associated with the current error.
80 //
81 /// Gets the error value as a NULL terminated C string. The error string
82 /// will be fetched and cached on demand. The error string will be retrieved
83 /// from a callback that is appropriate for the type of the error and will
84 /// be cached until the error value is changed or cleared.
85 ///
86 /// \return
87 /// The error as a NULL terminated C string value if the error
88 /// is valid and is able to be converted to a string value,
89 /// NULL otherwise.
90 const char *AsCString(const char *default_error_str = "unknown error") const;
91
92 /// Clear the object state.
93 ///
94 /// Reverts the state of this object to contain a generic success value and
95 /// frees any cached error string value.
96 void Clear();
97
98 /// Test for error condition.
99 ///
100 /// \return
101 /// \b true if this object contains an error, \b false
102 /// otherwise.
103 bool Fail() const;
104
105 /// Access the error value.
106 ///
107 /// \return
108 /// The error value.
109 ValueType GetError() const;
110
111 /// Access the error type.
112 ///
113 /// \return
114 /// The error type enumeration value.
115 lldb::ErrorType GetType() const;
116
117 void SetExpressionError(lldb::ExpressionResults, const char *mssg);
118
119 int SetExpressionErrorWithFormat(lldb::ExpressionResults, const char *format,
120 ...) __attribute__((format(printf, 3, 4)));
121
122 /// Set accessor with an error value and type.
123 ///
124 /// Set accessor for the error value to \a err and the error type to \a
125 /// type.
126 ///
127 /// \param[in] err
128 /// A mach error code.
129 ///
130 /// \param[in] type
131 /// The type for \a err.
132 void SetError(ValueType err, lldb::ErrorType type);
133
134 /// Set the current error to errno.
135 ///
136 /// Update the error value to be \c errno and update the type to be \c
137 /// Status::POSIX.
138 void SetErrorToErrno();
139
140 /// Set the current error to a generic error.
141 ///
142 /// Update the error value to be \c LLDB_GENERIC_ERROR and update the type
143 /// to be \c Status::Generic.
144 void SetErrorToGenericError();
145
146 /// Set the current error string to \a err_str.
147 ///
148 /// Set accessor for the error string value for a generic errors, or to
149 /// supply additional details above and beyond the standard error strings
150 /// that the standard type callbacks typically provide. This allows custom
151 /// strings to be supplied as an error explanation. The error string value
152 /// will remain until the error value is cleared or a new error value/type
153 /// is assigned.
154 ///
155 /// \param err_str
156 /// The new custom error string to copy and cache.
157 void SetErrorString(llvm::StringRef err_str);
158
159 /// Set the current error string to a formatted error string.
160 ///
161 /// \param format
162 /// A printf style format string
163 int SetErrorStringWithFormat(const char *format, ...)
164 __attribute__((format(printf, 2, 3)));
165
166 int SetErrorStringWithVarArg(const char *format, va_list args);
167
168 template <typename... Args>
169 void SetErrorStringWithFormatv(const char *format, Args &&... args) {
170 SetErrorString(llvm::formatv(format, std::forward<Args>(args)...).str());
171 }
172
173 /// Test for success condition.
174 ///
175 /// Returns true if the error code in this object is considered a successful
176 /// return value.
177 ///
178 /// \return
179 /// \b true if this object contains an value that describes
180 /// success (non-erro), \b false otherwise.
181 bool Success() const;
182
183protected:
184 /// Member variables
185 ValueType m_code = 0; ///< Status code as an integer value.
186 lldb::ErrorType m_type =
187 lldb::eErrorTypeInvalid; ///< The type of the above error code.
188 mutable std::string m_string; ///< A string representation of the error code.
189private:
190 explicit Status(const llvm::formatv_object_base &payload) {
191 SetErrorToGenericError();
192 m_string = payload.str();
193 }
194};
195
196} // namespace lldb_private
197
198namespace llvm {
199template <> struct format_provider<lldb_private::Status> {
200 static void format(const lldb_private::Status &error, llvm::raw_ostream &OS,
201 llvm::StringRef Options);
202};
203}
204
205#define LLDB_ERRORF(status, fmt, ...) \
206 do { \
207 if (status) { \
208 (status)->SetErrorStringWithFormat((fmt), __VA_ARGS__); \
209 } \
210 } while (0);
211
212#endif // LLDB_UTILITY_STATUS_H
213

source code of lldb/include/lldb/Utility/Status.h