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 
23 namespace llvm {
24 class raw_ostream;
25 }
26 
27 namespace 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.
44 class Status {
45 public:
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   ~Status();
68 
69   // llvm::Error support
70   explicit Status(llvm::Error error) { *this = std::move(error); }
71   const Status &operator=(llvm::Error error);
72   llvm::Error ToError() const;
73 
74   /// Get the error string associated with the current error.
75   //
76   /// Gets the error value as a NULL terminated C string. The error string
77   /// will be fetched and cached on demand. The error string will be retrieved
78   /// from a callback that is appropriate for the type of the error and will
79   /// be cached until the error value is changed or cleared.
80   ///
81   /// \return
82   ///     The error as a NULL terminated C string value if the error
83   ///     is valid and is able to be converted to a string value,
84   ///     NULL otherwise.
85   const char *AsCString(const char *default_error_str = "unknown error") const;
86 
87   /// Clear the object state.
88   ///
89   /// Reverts the state of this object to contain a generic success value and
90   /// frees any cached error string value.
91   void Clear();
92 
93   /// Test for error condition.
94   ///
95   /// \return
96   ///     \b true if this object contains an error, \b false
97   ///     otherwise.
98   bool Fail() const;
99 
100   /// Access the error value.
101   ///
102   /// \return
103   ///     The error value.
104   ValueType GetError() const;
105 
106   /// Access the error type.
107   ///
108   /// \return
109   ///     The error type enumeration value.
110   lldb::ErrorType GetType() const;
111 
112   /// Set accessor from a kern_return_t.
113   ///
114   /// Set accessor for the error value to \a err and the error type to \c
115   /// MachKernel.
116   ///
117   /// \param[in] err
118   ///     A mach error code.
119   void SetMachError(uint32_t err);
120 
121   void SetExpressionError(lldb::ExpressionResults, const char *mssg);
122 
123   int SetExpressionErrorWithFormat(lldb::ExpressionResults, const char *format,
124                                    ...) __attribute__((format(printf, 3, 4)));
125 
126   /// Set accessor with an error value and type.
127   ///
128   /// Set accessor for the error value to \a err and the error type to \a
129   /// type.
130   ///
131   /// \param[in] err
132   ///     A mach error code.
133   ///
134   /// \param[in] type
135   ///     The type for \a err.
136   void SetError(ValueType err, lldb::ErrorType type);
137 
138   /// Set the current error to errno.
139   ///
140   /// Update the error value to be \c errno and update the type to be \c
141   /// Status::POSIX.
142   void SetErrorToErrno();
143 
144   /// Set the current error to a generic error.
145   ///
146   /// Update the error value to be \c LLDB_GENERIC_ERROR and update the type
147   /// to be \c Status::Generic.
148   void SetErrorToGenericError();
149 
150   /// Set the current error string to \a err_str.
151   ///
152   /// Set accessor for the error string value for a generic errors, or to
153   /// supply additional details above and beyond the standard error strings
154   /// that the standard type callbacks typically provide. This allows custom
155   /// strings to be supplied as an error explanation. The error string value
156   /// will remain until the error value is cleared or a new error value/type
157   /// is assigned.
158   ///
159   /// \param err_str
160   ///     The new custom error string to copy and cache.
161   void SetErrorString(llvm::StringRef err_str);
162 
163   /// Set the current error string to a formatted error string.
164   ///
165   /// \param format
166   ///     A printf style format string
167   int SetErrorStringWithFormat(const char *format, ...)
168       __attribute__((format(printf, 2, 3)));
169 
170   int SetErrorStringWithVarArg(const char *format, va_list args);
171 
172   template <typename... Args>
173   void SetErrorStringWithFormatv(const char *format, Args &&... args) {
174     SetErrorString(llvm::formatv(format, std::forward<Args>(args)...).str());
175   }
176 
177   /// Test for success condition.
178   ///
179   /// Returns true if the error code in this object is considered a successful
180   /// return value.
181   ///
182   /// \return
183   ///     \b true if this object contains an value that describes
184   ///     success (non-erro), \b false otherwise.
185   bool Success() const;
186 
187 protected:
188   /// Member variables
189   ValueType m_code = 0; ///< Status code as an integer value.
190   lldb::ErrorType m_type =
191       lldb::eErrorTypeInvalid;  ///< The type of the above error code.
192   mutable std::string m_string; ///< A string representation of the error code.
193 };
194 
195 } // namespace lldb_private
196 
197 namespace llvm {
198 template <> struct format_provider<lldb_private::Status> {
199   static void format(const lldb_private::Status &error, llvm::raw_ostream &OS,
200                      llvm::StringRef Options);
201 };
202 }
203 
204 #define LLDB_ERRORF(status, fmt, ...)                                          \
205   do {                                                                         \
206     if (status) {                                                              \
207       (status)->SetErrorStringWithFormat((fmt), __VA_ARGS__);                  \
208     }                                                                          \
209   } while (0);
210 
211 #endif // LLDB_UTILITY_STATUS_H
212