1 /* Exception (throw catch) mechanism, for GDB, the GNU debugger. 2 3 Copyright (C) 1986-2023 Free Software Foundation, Inc. 4 5 This file is part of GDB. 6 7 This program is free software; you can redistribute it and/or modify 8 it under the terms of the GNU General Public License as published by 9 the Free Software Foundation; either version 3 of the License, or 10 (at your option) any later version. 11 12 This program is distributed in the hope that it will be useful, 13 but WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 GNU General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with this program. If not, see <http://www.gnu.org/licenses/>. */ 19 20 #ifndef COMMON_COMMON_EXCEPTIONS_H 21 #define COMMON_COMMON_EXCEPTIONS_H 22 23 #include <setjmp.h> 24 #include <new> 25 #include <memory> 26 #include <string> 27 #include <functional> 28 29 /* Reasons for calling throw_exceptions(). NOTE: all reason values 30 must be different from zero. enum value 0 is reserved for internal 31 use as the return value from an initial setjmp(). */ 32 33 enum return_reason 34 { 35 /* User interrupt. */ 36 RETURN_QUIT = -2, 37 /* Any other error. */ 38 RETURN_ERROR 39 }; 40 41 #define RETURN_MASK(reason) (1 << (int)(-reason)) 42 43 typedef enum 44 { 45 RETURN_MASK_QUIT = RETURN_MASK (RETURN_QUIT), 46 RETURN_MASK_ERROR = RETURN_MASK (RETURN_ERROR), 47 RETURN_MASK_ALL = (RETURN_MASK_QUIT | RETURN_MASK_ERROR) 48 } return_mask; 49 50 /* Describe all exceptions. */ 51 52 enum errors { 53 GDB_NO_ERROR, 54 55 /* Any generic error, the corresponding text is in 56 exception.message. */ 57 GENERIC_ERROR, 58 59 /* Something requested was not found. */ 60 NOT_FOUND_ERROR, 61 62 /* Thread library lacks support necessary for finding thread local 63 storage. */ 64 TLS_NO_LIBRARY_SUPPORT_ERROR, 65 66 /* Load module not found while attempting to find thread local storage. */ 67 TLS_LOAD_MODULE_NOT_FOUND_ERROR, 68 69 /* Thread local storage has not been allocated yet. */ 70 TLS_NOT_ALLOCATED_YET_ERROR, 71 72 /* Something else went wrong while attempting to find thread local 73 storage. The ``struct gdb_exception'' message field provides 74 more detail. */ 75 TLS_GENERIC_ERROR, 76 77 /* Problem parsing an XML document. */ 78 XML_PARSE_ERROR, 79 80 /* Error accessing memory. */ 81 MEMORY_ERROR, 82 83 /* Value not available. E.g., a register was not collected in a 84 traceframe. */ 85 NOT_AVAILABLE_ERROR, 86 87 /* Value was optimized out. Note: if the value was a register, this 88 means the register was not saved in the frame. */ 89 OPTIMIZED_OUT_ERROR, 90 91 /* DW_OP_entry_value resolving failed. */ 92 NO_ENTRY_VALUE_ERROR, 93 94 /* Target throwing an error has been closed. Current command should be 95 aborted as the inferior state is no longer valid. */ 96 TARGET_CLOSE_ERROR, 97 98 /* An undefined command was executed. */ 99 UNDEFINED_COMMAND_ERROR, 100 101 /* Requested feature, method, mechanism, etc. is not supported. */ 102 NOT_SUPPORTED_ERROR, 103 104 /* The number of candidates generated during line completion has 105 reached the user's specified limit. This isn't an error, this exception 106 is used to halt searching for more completions, but for consistency 107 "_ERROR" is appended to the name. */ 108 MAX_COMPLETIONS_REACHED_ERROR, 109 110 /* Add more errors here. */ 111 NR_ERRORS 112 }; 113 114 struct gdb_exception 115 { 116 gdb_exception () 117 : reason ((enum return_reason) 0), 118 error (GDB_NO_ERROR) 119 { 120 } 121 122 gdb_exception (enum return_reason r, enum errors e) 123 : reason (r), 124 error (e) 125 { 126 } 127 128 gdb_exception (enum return_reason r, enum errors e, 129 const char *fmt, va_list ap) 130 ATTRIBUTE_PRINTF (4, 0) 131 : reason (r), 132 error (e), 133 message (std::make_shared<std::string> (string_vprintf (fmt, ap))) 134 { 135 } 136 137 /* The move constructor exists so that we can mark it "noexcept", 138 which is a good practice for any sort of exception object. */ 139 explicit gdb_exception (gdb_exception &&other) noexcept = default; 140 141 /* The copy constructor exists so that we can mark it "noexcept", 142 which is a good practice for any sort of exception object. */ 143 gdb_exception (const gdb_exception &other) noexcept 144 : reason (other.reason), 145 error (other.error), 146 message (other.message) 147 { 148 } 149 150 /* The assignment operator exists so that we can mark it "noexcept", 151 which is a good practice for any sort of exception object. */ 152 gdb_exception &operator= (const gdb_exception &other) noexcept 153 { 154 reason = other.reason; 155 error = other.error; 156 message = other.message; 157 return *this; 158 } 159 160 gdb_exception &operator= (gdb_exception &&other) noexcept = default; 161 162 /* Return the contents of the exception message, as a C string. The 163 string remains owned by the exception object. */ 164 const char *what () const noexcept 165 { 166 return message->c_str (); 167 } 168 169 /* Compare two exceptions. */ 170 bool operator== (const gdb_exception &other) const 171 { 172 const char *msg1 = message == nullptr ? "" : what (); 173 const char *msg2 = other.message == nullptr ? "" : other.what (); 174 175 return (reason == other.reason 176 && error == other.error 177 && strcmp (msg1, msg2) == 0); 178 } 179 180 /* Compare two exceptions. */ 181 bool operator!= (const gdb_exception &other) const 182 { 183 return !(*this == other); 184 } 185 186 enum return_reason reason; 187 enum errors error; 188 std::shared_ptr<std::string> message; 189 }; 190 191 namespace std 192 { 193 194 /* Specialization of std::hash for gdb_exception. */ 195 template<> 196 struct hash<gdb_exception> 197 { 198 size_t operator() (const gdb_exception &exc) const 199 { 200 size_t result = exc.reason + exc.error; 201 if (exc.message != nullptr) 202 result += std::hash<std::string> {} (*exc.message); 203 return result; 204 } 205 }; 206 207 } 208 209 /* Functions to drive the sjlj-based exceptions state machine. Though 210 declared here by necessity, these functions should be considered 211 internal to the exceptions subsystem and not used other than via 212 the TRY/CATCH (or TRY_SJLJ/CATCH_SJLJ) macros defined below. */ 213 214 extern jmp_buf *exceptions_state_mc_init (void); 215 extern int exceptions_state_mc_action_iter (void); 216 extern int exceptions_state_mc_action_iter_1 (void); 217 extern int exceptions_state_mc_catch (struct gdb_exception *, int); 218 219 /* Macro to wrap up standard try/catch behavior. 220 221 The double loop lets us correctly handle code "break"ing out of the 222 try catch block. (It works as the "break" only exits the inner 223 "while" loop, the outer for loop detects this handling it 224 correctly.) Of course "return" and "goto" are not so lucky. 225 226 For instance: 227 228 *INDENT-OFF* 229 230 TRY_SJLJ 231 { 232 } 233 CATCH_SJLJ (e, RETURN_MASK_ERROR) 234 { 235 switch (e.reason) 236 { 237 case RETURN_ERROR: ... 238 } 239 } 240 END_CATCH_SJLJ 241 242 The SJLJ variants are needed in some cases where gdb exceptions 243 need to cross third-party library code compiled without exceptions 244 support (e.g., readline). */ 245 246 #define TRY_SJLJ \ 247 { \ 248 jmp_buf *buf = \ 249 exceptions_state_mc_init (); \ 250 setjmp (*buf); \ 251 } \ 252 while (exceptions_state_mc_action_iter ()) \ 253 while (exceptions_state_mc_action_iter_1 ()) 254 255 #define CATCH_SJLJ(EXCEPTION, MASK) \ 256 { \ 257 struct gdb_exception EXCEPTION; \ 258 if (exceptions_state_mc_catch (&(EXCEPTION), MASK)) 259 260 #define END_CATCH_SJLJ \ 261 } 262 263 /* The exception types client code may catch. They're just shims 264 around gdb_exception that add nothing but type info. Which is used 265 is selected depending on the MASK argument passed to CATCH. */ 266 267 struct gdb_exception_error : public gdb_exception 268 { 269 gdb_exception_error (enum errors e, const char *fmt, va_list ap) 270 ATTRIBUTE_PRINTF (3, 0) 271 : gdb_exception (RETURN_ERROR, e, fmt, ap) 272 { 273 } 274 275 explicit gdb_exception_error (gdb_exception &&ex) noexcept 276 : gdb_exception (std::move (ex)) 277 { 278 gdb_assert (ex.reason == RETURN_ERROR); 279 } 280 }; 281 282 struct gdb_exception_quit : public gdb_exception 283 { 284 gdb_exception_quit (const char *fmt, va_list ap) 285 ATTRIBUTE_PRINTF (2, 0) 286 : gdb_exception (RETURN_QUIT, GDB_NO_ERROR, fmt, ap) 287 { 288 } 289 290 explicit gdb_exception_quit (gdb_exception &&ex) noexcept 291 : gdb_exception (std::move (ex)) 292 { 293 gdb_assert (ex.reason == RETURN_QUIT); 294 } 295 }; 296 297 /* An exception type that inherits from both std::bad_alloc and a gdb 298 exception. This is necessary because operator new can only throw 299 std::bad_alloc, and OTOH, we want exceptions thrown due to memory 300 allocation error to be caught by all the CATCH/RETURN_MASK_ALL 301 spread around the codebase. */ 302 303 struct gdb_quit_bad_alloc 304 : public gdb_exception_quit, 305 public std::bad_alloc 306 { 307 explicit gdb_quit_bad_alloc (gdb_exception &&ex) noexcept 308 : gdb_exception_quit (std::move (ex)), 309 std::bad_alloc () 310 { 311 } 312 }; 313 314 /* *INDENT-ON* */ 315 316 /* Throw an exception (as described by "struct gdb_exception"), 317 landing in the inner most containing exception handler established 318 using TRY/CATCH. */ 319 extern void throw_exception (gdb_exception &&exception) 320 ATTRIBUTE_NORETURN; 321 322 /* Throw an exception by executing a LONG JUMP to the inner most 323 containing exception handler established using TRY_SJLJ. Necessary 324 in some cases where we need to throw GDB exceptions across 325 third-party library code (e.g., readline). */ 326 extern void throw_exception_sjlj (const struct gdb_exception &exception) 327 ATTRIBUTE_NORETURN; 328 329 /* Convenience wrappers around throw_exception that throw GDB 330 errors. */ 331 extern void throw_verror (enum errors, const char *fmt, va_list ap) 332 ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 0); 333 extern void throw_vquit (const char *fmt, va_list ap) 334 ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 0); 335 extern void throw_error (enum errors error, const char *fmt, ...) 336 ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 3); 337 extern void throw_quit (const char *fmt, ...) 338 ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 2); 339 340 #endif /* COMMON_COMMON_EXCEPTIONS_H */ 341