aboutsummaryrefslogtreecommitdiff
path: root/include/lldb/Core/Error.h
blob: 39c67f621c9279312903cbcb9e87509234ba4801 (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
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
//===-- Error.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 "llvm/Support/DataTypes.h"

#include <cstdarg>
#include <cstdio>
#include <string>

#include "lldb/lldb-private.h"

namespace lldb_private {

class Log;

//----------------------------------------------------------------------
/// @class Error Error.h "lldb/Core/Error.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 Error::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 Error
{
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.
    //------------------------------------------------------------------
    Error ();
    
    explicit
    Error (ValueType err, lldb::ErrorType type = lldb::eErrorTypeGeneric);

    explicit
    Error (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
    
    Error (const Error &rhs);
    //------------------------------------------------------------------
    /// Assignment operator.
    ///
    /// @param[in] err
    ///     An error code.
    ///
    /// @return
    ///     A const reference to this object.
    //------------------------------------------------------------------
    const Error&
    operator = (const Error& 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 Error&
    operator = (uint32_t err);

    ~Error();

    //------------------------------------------------------------------
    /// 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;

    //------------------------------------------------------------------
    /// Log an error to Log().
    ///
    /// Log the error given a formatted string \a format. If the this
    /// object contains an error code, update the error string to
    /// contain the prefix "error: ", followed by the formatted string,
    /// followed by the error value and any string that describes the
    /// error value. This allows more context to be given to an error
    /// string that remains cached in this object. Logging always occurs
    /// even when the error code contains a non-error value.
    ///
    /// @param[in] format
    ///     A printf style format string.
    ///
    /// @param[in] ...
    ///     Variable arguments that are needed for the printf style
    ///     format string \a format.
    //------------------------------------------------------------------
    void
    PutToLog (Log *log, const char *format, ...)  __attribute__ ((format (printf, 3, 4)));

    //------------------------------------------------------------------
    /// Log an error to Log() if the error value is an error.
    ///
    /// Log the error given a formatted string \a format only if the
    /// error value in this object describes an error condition. If the
    /// this object contains an error, update the error string to
    /// contain the prefix "error: " followed by the formatted string,
    /// followed by the error value and any string that describes the
    /// error value. This allows more context to be given to an error
    /// string that remains cached in this object.
    ///
    /// @param[in] format
    ///     A printf style format string.
    ///
    /// @param[in] ...
    ///     Variable arguments that are needed for the printf style
    ///     format string \a format.
    //------------------------------------------------------------------
    void
    LogIfError (Log *log, const char *format, ...)  __attribute__ ((format (printf, 3, 4)));

    //------------------------------------------------------------------
    /// 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);

    //------------------------------------------------------------------
    /// 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 Error::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 Error::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 (const char *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);

    //------------------------------------------------------------------
    /// 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;               ///< Error 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

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