gdb/python/python-internal.h

   1 /* Gdb/Python header for private use by Python module.
   2
   3    Copyright (C) 2008-2022 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 PYTHON_PYTHON_INTERNAL_H
  21 #define PYTHON_PYTHON_INTERNAL_H
  22
  23 #include "extension.h"
  24 #include "extension-priv.h"
  25
  26 /* These WITH_* macros are defined by the CPython API checker that
  27    comes with the Python plugin for GCC.  See:
  28    https://gcc-python-plugin.readthedocs.org/en/latest/cpychecker.html
  29    The checker defines a WITH_ macro for each attribute it
  30    exposes.  Note that we intentionally do not use
  31    'cpychecker_returns_borrowed_ref' -- that idiom is forbidden in
  32    gdb.  */
  33
  34 #ifdef WITH_CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF_ATTRIBUTE
  35 #define CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF(ARG)         \
  36   __attribute__ ((cpychecker_type_object_for_typedef (ARG)))
  37 #else
  38 #define CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF(ARG)
  39 #endif
  40
  41 #ifdef WITH_CPYCHECKER_SETS_EXCEPTION_ATTRIBUTE
  42 #define CPYCHECKER_SETS_EXCEPTION __attribute__ ((cpychecker_sets_exception))
  43 #else
  44 #define CPYCHECKER_SETS_EXCEPTION
  45 #endif
  46
  47 #ifdef WITH_CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION_ATTRIBUTE
  48 #define CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION               \
  49   __attribute__ ((cpychecker_negative_result_sets_exception))
  50 #else
  51 #define CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION
  52 #endif
  53
  54 /* /usr/include/features.h on linux systems will define _POSIX_C_SOURCE
  55    if it sees _GNU_SOURCE (which config.h will define).
  56    pyconfig.h defines _POSIX_C_SOURCE to a different value than
  57    /usr/include/features.h does causing compilation to fail.
  58    To work around this, undef _POSIX_C_SOURCE before we include Python.h.
  59
  60    Same problem with _XOPEN_SOURCE.  */
  61 #undef _POSIX_C_SOURCE
  62 #undef _XOPEN_SOURCE
  63
  64 /* On sparc-solaris, /usr/include/sys/feature_tests.h defines
  65    _FILE_OFFSET_BITS, which pyconfig.h also defines.  Same work
  66    around technique as above.  */
  67 #undef _FILE_OFFSET_BITS
  68
  69 /* A kludge to avoid redefinition of snprintf on Windows by pyerrors.h.  */
  70 #if defined(_WIN32) && defined(HAVE_DECL_SNPRINTF)
  71 #define HAVE_SNPRINTF 1
  72 #endif
  73
  74 /* Another kludge to avoid compilation errors because MinGW defines
  75    'hypot' to '_hypot', but the C++ headers says "using ::hypot".  */
  76 #ifdef __MINGW32__
  77 # define _hypot hypot
  78 #endif
  79
  80 /* Request clean size types from Python.  */
  81 #define PY_SSIZE_T_CLEAN
  82
  83 /* Include the Python header files using angle brackets rather than
  84    double quotes.  On case-insensitive filesystems, this prevents us
  85    from including our python/python.h header file.  */
  86 #include <Python.h>
  87 #include <frameobject.h>
  88 #include "py-ref.h"
  89
  90 #define Py_TPFLAGS_CHECKTYPES 0
  91
  92 #define PyInt_Check PyLong_Check
  93 #define PyInt_AsLong PyLong_AsLong
  94 #define PyInt_AsSsize_t PyLong_AsSsize_t
  95
  96 #define PyString_FromString PyUnicode_FromString
  97 #define PyString_Decode PyUnicode_Decode
  98 #define PyString_FromFormat PyUnicode_FromFormat
  99 #define PyString_Check PyUnicode_Check
 100
 101 /* If Python.h does not define WITH_THREAD, then the various
 102    GIL-related functions will not be defined.  However,
 103    PyGILState_STATE will be.  */
 104 #ifndef WITH_THREAD
 105 #define PyGILState_Ensure() ((PyGILState_STATE) 0)
 106 #define PyGILState_Release(ARG) ((void)(ARG))
 107 #define PyEval_InitThreads()
 108 #define PyThreadState_Swap(ARG) ((void)(ARG))
 109 #define PyEval_ReleaseLock()
 110 #endif
 111
 112 /* Python supplies HAVE_LONG_LONG and some `long long' support when it
 113    is available.  These defines let us handle the differences more
 114    cleanly.  */
 115 #ifdef HAVE_LONG_LONG
 116
 117 #define GDB_PY_LL_ARG "L"
 118 #define GDB_PY_LLU_ARG "K"
 119 typedef PY_LONG_LONG gdb_py_longest;
 120 typedef unsigned PY_LONG_LONG gdb_py_ulongest;
 121 #define gdb_py_long_as_ulongest PyLong_AsUnsignedLongLong
 122
 123 #else /* HAVE_LONG_LONG */
 124
 125 #define GDB_PY_LL_ARG "L"
 126 #define GDB_PY_LLU_ARG "K"
 127 typedef long gdb_py_longest;
 128 typedef unsigned long gdb_py_ulongest;
 129 #define gdb_py_long_as_ulongest PyLong_AsUnsignedLong
 130
 131 #endif /* HAVE_LONG_LONG */
 132
 133 #if PY_VERSION_HEX < 0x03020000
 134 typedef long Py_hash_t;
 135 #endif
 136
 137 /* PyMem_RawMalloc appeared in Python 3.4.  For earlier versions, we can just
 138    fall back to PyMem_Malloc.  */
 139
 140 #if PY_VERSION_HEX < 0x03040000
 141 #define PyMem_RawMalloc PyMem_Malloc
 142 #endif
 143
 144 /* Python 2.6 did not wrap Py_DECREF in 'do {...} while (0)', leading
 145    to 'suggest explicit braces to avoid ambiguous ‘else’' gcc errors.
 146    Wrap it ourselves, so that callers don't need to care.  */
 147
 148 static inline void
 149 gdb_Py_DECREF (void *op) /* ARI: editCase function */
 150 {
 151   Py_DECREF (op);
 152 }
 153
 154 #undef Py_DECREF
 155 #define Py_DECREF(op) gdb_Py_DECREF (op)
 156
 157 /* PyObject_CallMethod's 'method' and 'format' parameters were missing
 158    the 'const' qualifier before Python 3.4.  Hence, we wrap the
 159    function in our own version to avoid errors with string literals.
 160    Note, this is a variadic template because PyObject_CallMethod is a
 161    varargs function and Python doesn't have a "PyObject_VaCallMethod"
 162    variant taking a va_list that we could defer to instead.  */
 163
 164 template<typename... Args>
 165 static inline PyObject *
 166 gdb_PyObject_CallMethod (PyObject *o, const char *method, const char *format,
 167                          Args... args) /* ARI: editCase function */
 168 {
 169   return PyObject_CallMethod (o,
 170                               const_cast<char *> (method),
 171                               const_cast<char *> (format),
 172                               args...);
 173 }
 174
 175 #undef PyObject_CallMethod
 176 #define PyObject_CallMethod gdb_PyObject_CallMethod
 177
 178 /* The 'name' parameter of PyErr_NewException was missing the 'const'
 179    qualifier in Python <= 3.4.  Hence, we wrap it in a function to
 180    avoid errors when compiled with -Werror.  */
 181
 182 static inline PyObject*
 183 gdb_PyErr_NewException (const char *name, PyObject *base, PyObject *dict)
 184 {
 185   return PyErr_NewException (const_cast<char *> (name), base, dict);
 186 }
 187
 188 #define PyErr_NewException gdb_PyErr_NewException
 189
 190 /* PySys_GetObject's 'name' parameter was missing the 'const'
 191    qualifier before Python 3.4.  Hence, we wrap it in a function to
 192    avoid errors when compiled with -Werror.  */
 193
 194 static inline PyObject *
 195 gdb_PySys_GetObject (const char *name)
 196 {
 197   return PySys_GetObject (const_cast<char *> (name));
 198 }
 199
 200 #define PySys_GetObject gdb_PySys_GetObject
 201
 202 /* PySys_SetPath's 'path' parameter was missing the 'const' qualifier
 203    before Python 3.6.  Hence, we wrap it in a function to avoid errors
 204    when compiled with -Werror.  */
 205
 206 # define GDB_PYSYS_SETPATH_CHAR wchar_t
 207
 208 static inline void
 209 gdb_PySys_SetPath (const GDB_PYSYS_SETPATH_CHAR *path)
 210 {
 211   PySys_SetPath (const_cast<GDB_PYSYS_SETPATH_CHAR *> (path));
 212 }
 213
 214 #define PySys_SetPath gdb_PySys_SetPath
 215
 216 /* Wrap PyGetSetDef to allow convenient construction with string
 217    literals.  Unfortunately, PyGetSetDef's 'name' and 'doc' members
 218    are 'char *' instead of 'const char *', meaning that in order to
 219    list-initialize PyGetSetDef arrays with string literals (and
 220    without the wrapping below) would require writing explicit 'char *'
 221    casts.  Instead, we extend PyGetSetDef and add constexpr
 222    constructors that accept const 'name' and 'doc', hiding the ugly
 223    casts here in a single place.  */
 224
 225 struct gdb_PyGetSetDef : PyGetSetDef
 226 {
 227   constexpr gdb_PyGetSetDef (const char *name_, getter get_, setter set_,
 228                              const char *doc_, void *closure_)
 229     : PyGetSetDef {const_cast<char *> (name_), get_, set_,
 230                    const_cast<char *> (doc_), closure_}
 231   {}
 232
 233   /* Alternative constructor that allows omitting the closure in list
 234      initialization.  */
 235   constexpr gdb_PyGetSetDef (const char *name_, getter get_, setter set_,
 236                              const char *doc_)
 237     : gdb_PyGetSetDef {name_, get_, set_, doc_, NULL}
 238   {}
 239
 240   /* Constructor for the sentinel entries.  */
 241   constexpr gdb_PyGetSetDef (std::nullptr_t)
 242     : gdb_PyGetSetDef {NULL, NULL, NULL, NULL, NULL}
 243   {}
 244 };
 245
 246 /* The 'keywords' parameter of PyArg_ParseTupleAndKeywords has type
 247    'char **'.  However, string literals are const in C++, and so to
 248    avoid casting at every keyword array definition, we'll need to make
 249    the keywords array an array of 'const char *'.  To avoid having all
 250    callers add a 'const_cast<char **>' themselves when passing such an
 251    array through 'char **', we define our own version of
 252    PyArg_ParseTupleAndKeywords here with a corresponding 'keywords'
 253    parameter type that does the cast in a single place.  (This is not
 254    an overload of PyArg_ParseTupleAndKeywords in order to make it
 255    clearer that we're calling our own function instead of a function
 256    that exists in some newer Python version.)  */
 257
 258 static inline int
 259 gdb_PyArg_ParseTupleAndKeywords (PyObject *args, PyObject *kw,
 260                                  const char *format, const char **keywords, ...)
 261 {
 262   va_list ap;
 263   int res;
 264
 265   va_start (ap, keywords);
 266   res = PyArg_VaParseTupleAndKeywords (args, kw, format,
 267                                        const_cast<char **> (keywords),
 268                                        ap);
 269   va_end (ap);
 270
 271   return res;
 272 }
 273
 274 /* In order to be able to parse symtab_and_line_to_sal_object function
 275    a real symtab_and_line structure is needed.  */
 276 #include "symtab.h"
 277
 278 /* Also needed to parse enum var_types. */
 279 #include "command.h"
 280 #include "breakpoint.h"
 281
 282 enum gdbpy_iter_kind { iter_keys, iter_values, iter_items };
 283
 284 struct block;
 285 struct value;
 286 struct language_defn;
 287 struct program_space;
 288 struct bpstat;
 289 struct inferior;
 290
 291 extern int gdb_python_initialized;
 292
 293 extern PyObject *gdb_module;
 294 extern PyObject *gdb_python_module;
 295 extern PyTypeObject value_object_type
 296     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("value_object");
 297 extern PyTypeObject block_object_type
 298     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF("block_object");
 299 extern PyTypeObject symbol_object_type
 300     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("symbol_object");
 301 extern PyTypeObject event_object_type
 302     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("event_object");
 303 extern PyTypeObject breakpoint_object_type
 304     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("breakpoint_object");
 305 extern PyTypeObject frame_object_type
 306     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("frame_object");
 307 extern PyTypeObject thread_object_type
 308     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("thread_object");
 309
 310 struct gdbpy_breakpoint_object
 311 {
 312   PyObject_HEAD
 313
 314   /* The breakpoint number according to gdb.  */
 315   int number;
 316
 317   /* The gdb breakpoint object, or NULL if the breakpoint has been
 318      deleted.  */
 319   struct breakpoint *bp;
 320
 321   /* 1 is this is a FinishBreakpoint object, 0 otherwise.  */
 322   int is_finish_bp;
 323 };
 324
 325 /* Require that BREAKPOINT be a valid breakpoint ID; throw a Python
 326    exception if it is invalid.  */
 327 #define BPPY_REQUIRE_VALID(Breakpoint)                                  \
 328     do {                                                                \
 329       if ((Breakpoint)->bp == NULL)                                     \
 330         return PyErr_Format (PyExc_RuntimeError,                        \
 331                              _("Breakpoint %d is invalid."),            \
 332                              (Breakpoint)->number);                     \
 333     } while (0)
 334
 335 /* Require that BREAKPOINT be a valid breakpoint ID; throw a Python
 336    exception if it is invalid.  This macro is for use in setter functions.  */
 337 #define BPPY_SET_REQUIRE_VALID(Breakpoint)                              \
 338     do {                                                                \
 339       if ((Breakpoint)->bp == NULL)                                     \
 340         {                                                               \
 341           PyErr_Format (PyExc_RuntimeError, _("Breakpoint %d is invalid."), \
 342                         (Breakpoint)->number);                          \
 343           return -1;                                                    \
 344         }                                                               \
 345     } while (0)
 346
 347
 348 /* Variables used to pass information between the Breakpoint
 349    constructor and the breakpoint-created hook function.  */
 350 extern gdbpy_breakpoint_object *bppy_pending_object;
 351
 352
 353 struct thread_object
 354 {
 355   PyObject_HEAD
 356
 357   /* The thread we represent.  */
 358   struct thread_info *thread;
 359
 360   /* The Inferior object to which this thread belongs.  */
 361   PyObject *inf_obj;
 362 };
 363
 364 struct inferior_object;
 365
 366 extern struct cmd_list_element *set_python_list;
 367 extern struct cmd_list_element *show_python_list;
 368 \f
 369 /* extension_language_script_ops "methods".  */
 370
 371 /* Return true if auto-loading Python scripts is enabled.
 372    This is the extension_language_script_ops.auto_load_enabled "method".  */
 373
 374 extern bool gdbpy_auto_load_enabled (const struct extension_language_defn *);
 375
 376 /* extension_language_ops "methods".  */
 377
 378 extern enum ext_lang_rc gdbpy_apply_val_pretty_printer
 379   (const struct extension_language_defn *,
 380    struct value *value,
 381    struct ui_file *stream, int recurse,
 382    const struct value_print_options *options,
 383    const struct language_defn *language);
 384 extern enum ext_lang_bt_status gdbpy_apply_frame_filter
 385   (const struct extension_language_defn *,
 386    struct frame_info *frame, frame_filter_flags flags,
 387    enum ext_lang_frame_args args_type,
 388    struct ui_out *out, int frame_low, int frame_high);
 389 extern void gdbpy_preserve_values (const struct extension_language_defn *,
 390                                    struct objfile *objfile,
 391                                    htab_t copied_types);
 392 extern enum ext_lang_bp_stop gdbpy_breakpoint_cond_says_stop
 393   (const struct extension_language_defn *, struct breakpoint *);
 394 extern int gdbpy_breakpoint_has_cond (const struct extension_language_defn *,
 395                                       struct breakpoint *b);
 396
 397 extern enum ext_lang_rc gdbpy_get_matching_xmethod_workers
 398   (const struct extension_language_defn *extlang,
 399    struct type *obj_type, const char *method_name,
 400    std::vector<xmethod_worker_up> *dm_vec);
 401
 402 \f
 403 PyObject *gdbpy_history (PyObject *self, PyObject *args);
 404 PyObject *gdbpy_add_history (PyObject *self, PyObject *args);
 405 extern PyObject *gdbpy_history_count (PyObject *self, PyObject *args);
 406 PyObject *gdbpy_convenience_variable (PyObject *self, PyObject *args);
 407 PyObject *gdbpy_set_convenience_variable (PyObject *self, PyObject *args);
 408 PyObject *gdbpy_breakpoints (PyObject *, PyObject *);
 409 PyObject *gdbpy_frame_stop_reason_string (PyObject *, PyObject *);
 410 PyObject *gdbpy_lookup_symbol (PyObject *self, PyObject *args, PyObject *kw);
 411 PyObject *gdbpy_lookup_global_symbol (PyObject *self, PyObject *args,
 412                                       PyObject *kw);
 413 PyObject *gdbpy_lookup_static_symbol (PyObject *self, PyObject *args,
 414                                       PyObject *kw);
 415 PyObject *gdbpy_lookup_static_symbols (PyObject *self, PyObject *args,
 416                                            PyObject *kw);
 417 PyObject *gdbpy_start_recording (PyObject *self, PyObject *args);
 418 PyObject *gdbpy_current_recording (PyObject *self, PyObject *args);
 419 PyObject *gdbpy_stop_recording (PyObject *self, PyObject *args);
 420 PyObject *gdbpy_newest_frame (PyObject *self, PyObject *args);
 421 PyObject *gdbpy_selected_frame (PyObject *self, PyObject *args);
 422 PyObject *gdbpy_lookup_type (PyObject *self, PyObject *args, PyObject *kw);
 423 int gdbpy_is_field (PyObject *obj);
 424 PyObject *gdbpy_create_lazy_string_object (CORE_ADDR address, long length,
 425                                            const char *encoding,
 426                                            struct type *type);
 427 PyObject *gdbpy_inferiors (PyObject *unused, PyObject *unused2);
 428 PyObject *gdbpy_create_ptid_object (ptid_t ptid);
 429 PyObject *gdbpy_selected_thread (PyObject *self, PyObject *args);
 430 PyObject *gdbpy_selected_inferior (PyObject *self, PyObject *args);
 431 PyObject *gdbpy_string_to_argv (PyObject *self, PyObject *args);
 432 PyObject *gdbpy_parameter_value (const setting &var);
 433 gdb::unique_xmalloc_ptr<char> gdbpy_parse_command_name
 434   (const char *name, struct cmd_list_element ***base_list,
 435    struct cmd_list_element **start_list);
 436 PyObject *gdbpy_register_tui_window (PyObject *self, PyObject *args,
 437                                      PyObject *kw);
 438
 439 PyObject *symtab_and_line_to_sal_object (struct symtab_and_line sal);
 440 PyObject *symtab_to_symtab_object (struct symtab *symtab);
 441 PyObject *symbol_to_symbol_object (struct symbol *sym);
 442 PyObject *block_to_block_object (const struct block *block,
 443                                  struct objfile *objfile);
 444 PyObject *value_to_value_object (struct value *v);
 445 PyObject *value_to_value_object_no_release (struct value *v);
 446 PyObject *type_to_type_object (struct type *);
 447 PyObject *frame_info_to_frame_object (struct frame_info *frame);
 448 PyObject *symtab_to_linetable_object (PyObject *symtab);
 449 gdbpy_ref<> pspace_to_pspace_object (struct program_space *);
 450 PyObject *pspy_get_printers (PyObject *, void *);
 451 PyObject *pspy_get_frame_filters (PyObject *, void *);
 452 PyObject *pspy_get_frame_unwinders (PyObject *, void *);
 453 PyObject *pspy_get_xmethods (PyObject *, void *);
 454
 455 gdbpy_ref<> objfile_to_objfile_object (struct objfile *);
 456 PyObject *objfpy_get_printers (PyObject *, void *);
 457 PyObject *objfpy_get_frame_filters (PyObject *, void *);
 458 PyObject *objfpy_get_frame_unwinders (PyObject *, void *);
 459 PyObject *objfpy_get_xmethods (PyObject *, void *);
 460 PyObject *gdbpy_lookup_objfile (PyObject *self, PyObject *args, PyObject *kw);
 461
 462 PyObject *gdbarch_to_arch_object (struct gdbarch *gdbarch);
 463 PyObject *gdbpy_all_architecture_names (PyObject *self, PyObject *args);
 464
 465 PyObject *gdbpy_new_register_descriptor_iterator (struct gdbarch *gdbarch,
 466                                                   const char *group_name);
 467 PyObject *gdbpy_new_reggroup_iterator (struct gdbarch *gdbarch);
 468
 469 gdbpy_ref<thread_object> create_thread_object (struct thread_info *tp);
 470 gdbpy_ref<> thread_to_thread_object (thread_info *thr);;
 471 gdbpy_ref<inferior_object> inferior_to_inferior_object (inferior *inf);
 472
 473 PyObject *gdbpy_buffer_to_membuf (gdb::unique_xmalloc_ptr<gdb_byte> buffer,
 474                                   CORE_ADDR address, ULONGEST length);
 475
 476 struct process_stratum_target;
 477 gdbpy_ref<> target_to_connection_object (process_stratum_target *target);
 478 PyObject *gdbpy_connections (PyObject *self, PyObject *args);
 479
 480 const struct block *block_object_to_block (PyObject *obj);
 481 struct symbol *symbol_object_to_symbol (PyObject *obj);
 482 struct value *value_object_to_value (PyObject *self);
 483 struct value *convert_value_from_python (PyObject *obj);
 484 struct type *type_object_to_type (PyObject *obj);
 485 struct symtab *symtab_object_to_symtab (PyObject *obj);
 486 struct symtab_and_line *sal_object_to_symtab_and_line (PyObject *obj);
 487 struct frame_info *frame_object_to_frame_info (PyObject *frame_obj);
 488 struct gdbarch *arch_object_to_gdbarch (PyObject *obj);
 489
 490 /* Convert Python object OBJ to a program_space pointer.  OBJ must be a
 491    gdb.Progspace reference.  Return nullptr if the gdb.Progspace is not
 492    valid (see gdb.Progspace.is_valid), otherwise return the program_space
 493    pointer.  */
 494
 495 extern struct program_space *progspace_object_to_program_space (PyObject *obj);
 496
 497 void gdbpy_initialize_gdb_readline (void);
 498 int gdbpy_initialize_auto_load (void)
 499   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 500 int gdbpy_initialize_values (void)
 501   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 502 int gdbpy_initialize_frames (void)
 503   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 504 int gdbpy_initialize_instruction (void)
 505   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 506 int gdbpy_initialize_btrace (void)
 507   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 508 int gdbpy_initialize_record (void)
 509   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 510 int gdbpy_initialize_symtabs (void)
 511   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 512 int gdbpy_initialize_commands (void)
 513   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 514 int gdbpy_initialize_symbols (void)
 515   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 516 int gdbpy_initialize_symtabs (void)
 517   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 518 int gdbpy_initialize_blocks (void)
 519   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 520 int gdbpy_initialize_types (void)
 521   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 522 int gdbpy_initialize_functions (void)
 523   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 524 int gdbpy_initialize_pspace (void)
 525   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 526 int gdbpy_initialize_objfile (void)
 527   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 528 int gdbpy_initialize_breakpoints (void)
 529   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 530 int gdbpy_initialize_finishbreakpoints (void)
 531   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 532 int gdbpy_initialize_lazy_string (void)
 533   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 534 int gdbpy_initialize_linetable (void)
 535   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 536 int gdbpy_initialize_parameters (void)
 537   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 538 int gdbpy_initialize_thread (void)
 539   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 540 int gdbpy_initialize_inferior (void)
 541   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 542 int gdbpy_initialize_eventregistry (void)
 543   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 544 int gdbpy_initialize_event (void)
 545   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 546 int gdbpy_initialize_py_events (void)
 547   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 548 int gdbpy_initialize_arch (void)
 549   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 550 int gdbpy_initialize_registers ()
 551   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 552 int gdbpy_initialize_xmethods (void)
 553   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 554 int gdbpy_initialize_unwind (void)
 555   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 556 int gdbpy_initialize_tui ()
 557   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 558 int gdbpy_initialize_membuf ()
 559   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 560 int gdbpy_initialize_connection ()
 561   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 562 int gdbpy_initialize_micommands (void)
 563   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 564 void gdbpy_finalize_micommands ();
 565
 566 /* A wrapper for PyErr_Fetch that handles reference counting for the
 567    caller.  */
 568 class gdbpy_err_fetch
 569 {
 570 public:
 571
 572   gdbpy_err_fetch ()
 573   {
 574     PyErr_Fetch (&m_error_type, &m_error_value, &m_error_traceback);
 575   }
 576
 577   ~gdbpy_err_fetch ()
 578   {
 579     Py_XDECREF (m_error_type);
 580     Py_XDECREF (m_error_value);
 581     Py_XDECREF (m_error_traceback);
 582   }
 583
 584   /* Call PyErr_Restore using the values stashed in this object.
 585      After this call, this object is invalid and neither the to_string
 586      nor restore methods may be used again.  */
 587
 588   void restore ()
 589   {
 590     PyErr_Restore (m_error_type, m_error_value, m_error_traceback);
 591     m_error_type = nullptr;
 592     m_error_value = nullptr;
 593     m_error_traceback = nullptr;
 594   }
 595
 596   /* Return the string representation of the exception represented by
 597      this object.  If the result is NULL a python error occurred, the
 598      caller must clear it.  */
 599
 600   gdb::unique_xmalloc_ptr<char> to_string () const;
 601
 602   /* Return the string representation of the type of the exception
 603      represented by this object.  If the result is NULL a python error
 604      occurred, the caller must clear it.  */
 605
 606   gdb::unique_xmalloc_ptr<char> type_to_string () const;
 607
 608   /* Return true if the stored type matches TYPE, false otherwise.  */
 609
 610   bool type_matches (PyObject *type) const
 611   {
 612     return PyErr_GivenExceptionMatches (m_error_type, type);
 613   }
 614
 615 private:
 616
 617   PyObject *m_error_type, *m_error_value, *m_error_traceback;
 618 };
 619
 620 /* Called before entering the Python interpreter to install the
 621    current language and architecture to be used for Python values.
 622    Also set the active extension language for GDB so that SIGINT's
 623    are directed our way, and if necessary install the right SIGINT
 624    handler.  */
 625 class gdbpy_enter
 626 {
 627  public:
 628
 629   /* Set the ambient Python architecture to GDBARCH and the language
 630      to LANGUAGE.  If GDBARCH is nullptr, then the architecture will
 631      be computed, when needed, using get_current_arch; see the
 632      get_gdbarch method.  If LANGUAGE is not nullptr, then the current
 633      language at time of construction will be saved (to be restored on
 634      destruction), and the current language will be set to
 635      LANGUAGE.  */
 636   explicit gdbpy_enter (struct gdbarch *gdbarch = nullptr,
 637                         const struct language_defn *language = nullptr);
 638
 639   ~gdbpy_enter ();
 640
 641   DISABLE_COPY_AND_ASSIGN (gdbpy_enter);
 642
 643   /* Return the current gdbarch, as known to the Python layer.  This
 644      is either python_gdbarch (which comes from the most recent call
 645      to the gdbpy_enter constructor), or, if that is nullptr, the
 646      result of get_current_arch.  */
 647   static struct gdbarch *get_gdbarch ();
 648
 649   /* Called only during gdb shutdown.  This sets python_gdbarch to an
 650      acceptable value.  */
 651   static void finalize ();
 652
 653  private:
 654
 655   /* The current gdbarch, according to Python.  This can be
 656      nullptr.  */
 657   static struct gdbarch *python_gdbarch;
 658
 659   struct active_ext_lang_state *m_previous_active;
 660   PyGILState_STATE m_state;
 661   struct gdbarch *m_gdbarch;
 662   const struct language_defn *m_language;
 663
 664   /* An optional is used here because we don't want to call
 665      PyErr_Fetch too early.  */
 666   gdb::optional<gdbpy_err_fetch> m_error;
 667 };
 668
 669 /* Like gdbpy_enter, but takes a varobj.  This is a subclass just to
 670    make constructor delegation a little nicer.  */
 671 class gdbpy_enter_varobj : public gdbpy_enter
 672 {
 673  public:
 674
 675   /* This is defined in varobj.c, where it can access varobj
 676      internals.  */
 677   gdbpy_enter_varobj (const struct varobj *var);
 678
 679 };
 680
 681 /* The opposite of gdb_enter: this releases the GIL around a region,
 682    allowing other Python threads to run.  No Python APIs may be used
 683    while this is active.  */
 684 class gdbpy_allow_threads
 685 {
 686 public:
 687
 688   gdbpy_allow_threads ()
 689     : m_save (PyEval_SaveThread ())
 690   {
 691     gdb_assert (m_save != nullptr);
 692   }
 693
 694   ~gdbpy_allow_threads ()
 695   {
 696     PyEval_RestoreThread (m_save);
 697   }
 698
 699   DISABLE_COPY_AND_ASSIGN (gdbpy_allow_threads);
 700
 701 private:
 702
 703   PyThreadState *m_save;
 704 };
 705
 706 /* Use this after a TRY_EXCEPT to throw the appropriate Python
 707    exception.  */
 708 #define GDB_PY_HANDLE_EXCEPTION(Exception)      \
 709   do {                                          \
 710     if (Exception.reason < 0)                   \
 711       {                                         \
 712         gdbpy_convert_exception (Exception);    \
 713         return NULL;                            \
 714       }                                         \
 715   } while (0)
 716
 717 /* Use this after a TRY_EXCEPT to throw the appropriate Python
 718    exception.  This macro is for use inside setter functions.  */
 719 #define GDB_PY_SET_HANDLE_EXCEPTION(Exception)                          \
 720     do {                                                                \
 721       if (Exception.reason < 0)                                         \
 722         {                                                               \
 723           gdbpy_convert_exception (Exception);                          \
 724           return -1;                                                    \
 725         }                                                               \
 726     } while (0)
 727
 728 int gdbpy_print_python_errors_p (void);
 729 void gdbpy_print_stack (void);
 730 void gdbpy_print_stack_or_quit ();
 731 void gdbpy_handle_exception () ATTRIBUTE_NORETURN;
 732
 733 /* A wrapper around calling 'error'.  Prefixes the error message with an
 734    'Error occurred in Python' string.  Use this in C++ code if we spot
 735    something wrong with an object returned from Python code.  The prefix
 736    string gives the user a hint that the mistake is within Python code,
 737    rather than some other part of GDB.
 738
 739    This always calls error, and never returns.  */
 740
 741 void gdbpy_error (const char *fmt, ...)
 742   ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 2);
 743
 744 gdbpy_ref<> python_string_to_unicode (PyObject *obj);
 745 gdb::unique_xmalloc_ptr<char> unicode_to_target_string (PyObject *unicode_str);
 746 gdb::unique_xmalloc_ptr<char> python_string_to_target_string (PyObject *obj);
 747 gdbpy_ref<> python_string_to_target_python_string (PyObject *obj);
 748 gdb::unique_xmalloc_ptr<char> python_string_to_host_string (PyObject *obj);
 749 gdbpy_ref<> host_string_to_python_string (const char *str);
 750 int gdbpy_is_string (PyObject *obj);
 751 gdb::unique_xmalloc_ptr<char> gdbpy_obj_to_string (PyObject *obj);
 752
 753 int gdbpy_is_lazy_string (PyObject *result);
 754 void gdbpy_extract_lazy_string (PyObject *string, CORE_ADDR *addr,
 755                                 struct type **str_type,
 756                                 long *length,
 757                                 gdb::unique_xmalloc_ptr<char> *encoding);
 758
 759 int gdbpy_is_value_object (PyObject *obj);
 760
 761 /* Note that these are declared here, and not in python.h with the
 762    other pretty-printer functions, because they refer to PyObject.  */
 763 gdbpy_ref<> apply_varobj_pretty_printer (PyObject *print_obj,
 764                                          struct value **replacement,
 765                                          struct ui_file *stream);
 766 gdbpy_ref<> gdbpy_get_varobj_pretty_printer (struct value *value);
 767 gdb::unique_xmalloc_ptr<char> gdbpy_get_display_hint (PyObject *printer);
 768 PyObject *gdbpy_default_visualizer (PyObject *self, PyObject *args);
 769
 770 void bpfinishpy_pre_stop_hook (struct gdbpy_breakpoint_object *bp_obj);
 771 void bpfinishpy_post_stop_hook (struct gdbpy_breakpoint_object *bp_obj);
 772
 773 extern PyObject *gdbpy_doc_cst;
 774 extern PyObject *gdbpy_children_cst;
 775 extern PyObject *gdbpy_to_string_cst;
 776 extern PyObject *gdbpy_display_hint_cst;
 777 extern PyObject *gdbpy_enabled_cst;
 778 extern PyObject *gdbpy_value_cst;
 779
 780 /* Exception types.  */
 781 extern PyObject *gdbpy_gdb_error;
 782 extern PyObject *gdbpy_gdb_memory_error;
 783 extern PyObject *gdbpy_gdberror_exc;
 784
 785 extern void gdbpy_convert_exception (const struct gdb_exception &)
 786     CPYCHECKER_SETS_EXCEPTION;
 787
 788 int get_addr_from_python (PyObject *obj, CORE_ADDR *addr)
 789     CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 790
 791 gdbpy_ref<> gdb_py_object_from_longest (LONGEST l);
 792 gdbpy_ref<> gdb_py_object_from_ulongest (ULONGEST l);
 793 int gdb_py_int_as_long (PyObject *, long *);
 794
 795 PyObject *gdb_py_generic_dict (PyObject *self, void *closure);
 796
 797 int gdb_pymodule_addobject (PyObject *module, const char *name,
 798                             PyObject *object)
 799   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
 800
 801 struct varobj_iter;
 802 struct varobj;
 803 std::unique_ptr<varobj_iter> py_varobj_get_iterator (struct varobj *var,
 804                                                      PyObject *printer);
 805
 806 /* Deleter for Py_buffer unique_ptr specialization.  */
 807
 808 struct Py_buffer_deleter
 809 {
 810   void operator() (Py_buffer *b) const
 811   {
 812     PyBuffer_Release (b);
 813   }
 814 };
 815
 816 /* A unique_ptr specialization for Py_buffer.  */
 817 typedef std::unique_ptr<Py_buffer, Py_buffer_deleter> Py_buffer_up;
 818
 819 /* Parse a register number from PYO_REG_ID and place the register number
 820    into *REG_NUM.  The register is a register for GDBARCH.
 821
 822    If a register is parsed successfully then *REG_NUM will have been
 823    updated, and true is returned.  Otherwise the contents of *REG_NUM are
 824    undefined, and false is returned.
 825
 826    The PYO_REG_ID object can be a string, the name of the register.  This
 827    is the slowest approach as GDB has to map the name to a number for each
 828    call.  Alternatively PYO_REG_ID can be an internal GDB register
 829    number.  This is quick but should not be encouraged as this means
 830    Python scripts are now dependent on GDB's internal register numbering.
 831    Final PYO_REG_ID can be a gdb.RegisterDescriptor object, these objects
 832    can be looked up by name once, and then cache the register number so
 833    should be as quick as using a register number.  */
 834
 835 extern bool gdbpy_parse_register_id (struct gdbarch *gdbarch,
 836                                      PyObject *pyo_reg_id, int *reg_num);
 837
 838 /* Return true if OBJ is a gdb.Architecture object, otherwise, return
 839    false.  */
 840
 841 extern bool gdbpy_is_architecture (PyObject *obj);
 842
 843 /* Return true if OBJ is a gdb.Progspace object, otherwise, return false.  */
 844
 845 extern bool gdbpy_is_progspace (PyObject *obj);
 846
 847 #endif /* PYTHON_PYTHON_INTERNAL_H */