Debian Codegraph @

libdrgn/error.h

raw
1 // Copyright (c) Meta Platforms, Inc. and affiliates.
2 // SPDX-License-Identifier: LGPL-2.1-or-later
3
4 /**
5 * @file
6 *
7 * Error helpers.
8 *
9 * See @ref Errors.
10 */
11
12 #ifndef DRGN_ERROR_H
13 #define DRGN_ERROR_H
14
15 #include "drgn_internal.h"
16 #include "pp.h"
17
18 /**
19 * @ingroup Internals
20 *
21 * @defgroup Errors Errors
22 *
23 * Common errors.
24 *
25 * @{
26 */
27
28 struct drgn_operand_type;
29
30 /** Global stop iteration error. */
31 extern struct drgn_error drgn_stop;
32
33 /** Global @ref DRGN_ERROR_OBJECT_ABSENT error. */
34 extern struct drgn_error drgn_error_object_absent;
35
36 /**
37 * Return whether an error is fatal, meaning that it should usually be returned
38 * to the caller instead of being handled or logged.
39 */
40 static inline bool drgn_error_is_fatal(struct drgn_error *err)
41 {
42 return err == &drgn_enomem;
43 }
44
45 struct string_builder;
46
47 /**
48 * Append a formatted @ref drgn_error to a @ref string_builder.
49 *
50 * @return @c true on success, @c false on error (if we couldn't allocate
51 * memory).
52 */
53 bool string_builder_append_error(struct string_builder *sb,
54 struct drgn_error *err);
55
56 /** Create a @ref drgn_error from the libelf error indicator. */
57 struct drgn_error *drgn_error_libelf(void)
58 __attribute__((__returns_nonnull__));
59
60 /** Create a @ref drgn_error from the libdw error indicator. */
61 struct drgn_error *drgn_error_libdw(void)
62 __attribute__((__returns_nonnull__));
63
64 /**
65 * Create a @ref drgn_error with a type name.
66 *
67 * The error code will be @ref DRGN_ERROR_TYPE.
68 *
69 * @param[in] format Format string for the type error. Must contain %s, which
70 * will be replaced with the type name, and no other conversion specifications.
71 */
72 struct drgn_error *drgn_type_error(const char *format, struct drgn_type *type)
73 __attribute__((__returns_nonnull__));
74
75 /**
76 * Create a @ref drgn_error with a qualified type name.
77 *
78 * @sa drgn_type_error().
79 */
80 struct drgn_error *
81 drgn_qualified_type_error(const char *format,
82 struct drgn_qualified_type qualified_type)
83 __attribute__((__returns_nonnull__));
84
85 /**
86 * Create a @ref drgn_error with two qualified type names.
87 *
88 * @param[in] format Format string for the type error. Must contain two `%s`,
89 * which will be replaced with the two type names, and no other conversion
90 * specifications.
91 */
92 struct drgn_error *
93 drgn_2_qualified_types_error(const char *format,
94 struct drgn_qualified_type qualified_type1,
95 struct drgn_qualified_type qualified_type2)
96 __attribute__((__returns_nonnull__));
97
98 /**
99 * Create a @ref drgn_error for an incomplete type.
100 *
101 * @sa drgn_type_error().
102 */
103 struct drgn_error *drgn_error_incomplete_type(const char *format,
104 struct drgn_type *type);
105
106 /** Create a @ref drgn_error for invalid types to a binary operator. */
107 struct drgn_error *drgn_error_binary_op(const char *op_name,
108 struct drgn_operand_type *type1,
109 struct drgn_operand_type *type2)
110 __attribute__((__returns_nonnull__));
111
112 /** Create a @ref drgn_error for an invalid type to a unary operator. */
113 struct drgn_error *drgn_error_unary_op(const char *op_name,
114 struct drgn_operand_type *type)
115 __attribute__((__returns_nonnull__));
116
117 /** Create a @ref drgn_error for a failed symbol lookup. */
118 struct drgn_error *drgn_error_symbol_not_found(uint64_t address)
119 __attribute__((__returns_nonnull__));
120
121 /**
122 * Scope guard that counts recursive calls and returns with a @ref
123 * DRGN_ERROR_RECURSION error if the recursion depth exceeds a limit.
124 *
125 * ```
126 * struct drgn_error *my_recursive_function(int n)
127 * {
128 * drgn_recursion_guard(1000, "maximum recursion depth exceeded");
129 * if (n <= 0)
130 * return NULL;
131 * return my_recursive_function(n - 1);
132 * }
133 * ```
134 *
135 * @param[in] limit Maximum recursion depth. For example, 0 means that the
136 * function may be called but may not make any recursive calls.
137 * @param[in] message Error message if limit is exceeded.
138 */
139 #define drgn_recursion_guard(limit, message) \
140 drgn_recursion_guard_impl(limit, message, PP_UNIQUE(recursion_count))
141
142 static inline void drgn_recursion_guard_cleanup(int **guard)
143 {
144 (**guard)--;
145 }
146
147 #define drgn_recursion_guard_impl(limit, message, unique_recursion_count) \
148 static _Thread_local int unique_recursion_count = 0; \
149 if (unique_recursion_count > (limit)) \
150 return drgn_error_create(DRGN_ERROR_RECURSION, (message)); \
151 unique_recursion_count++; \
152 __attribute__((__cleanup__(drgn_recursion_guard_cleanup), __unused__)) \
153 int *PP_UNIQUE(recursion_count_ptr) = &unique_recursion_count
154
155 /**
156 * Catch a certain kind of @ref drgn_error and free it
157 *
158 * If @a errp points to a non-@c NULL error whose code matches @a code, then the
159 * free the error (if necessary), replace the pointer value with @c NULL, and
160 * return @c true. Otherwise, return @c false, and @a err is not modified.
161 */
162 static inline bool drgn_error_catch(struct drgn_error **errp,
163 enum drgn_error_code code)
164 {
165 if (*errp && (*errp)->code == code) {
166 drgn_error_destroy(*errp);
167 *errp = NULL;
168 return true;
169 }
170 return false;
171 }
172
173 /** @} */
174
175 #endif /* DRGN_ERROR_H */