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