1 /* General python/gdb code
3 Copyright (C) 2008-2021 Free Software Foundation, Inc.
5 This file is part of GDB.
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.
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.
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/>. */
21 #include "arch-utils.h"
24 #include "cli/cli-script.h"
26 #include "progspace.h"
30 #include "gdbsupport/event-loop.h"
31 #include "readline/tilde.h"
33 #include "extension-priv.h"
34 #include "cli/cli-utils.h"
37 #include "run-on-main-thread.h"
38 #include "gdbsupport/selftest.h"
39 #include "observable.h"
41 /* Declared constants and enum for python stack printing. */
42 static const char python_excp_none[] = "none";
43 static const char python_excp_full[] = "full";
44 static const char python_excp_message[] = "message";
46 /* "set python print-stack" choices. */
47 static const char *const python_excp_enums[] =
55 /* The exception printing variable. 'full' if we want to print the
56 error message and stack, 'none' if we want to print nothing, and
57 'message' if we only want to print the error message. 'message' is
59 static const char *gdbpy_should_print_stack = python_excp_message;
62 /* Forward decls, these are defined later. */
63 extern const struct extension_language_script_ops python_extension_script_ops;
64 extern const struct extension_language_ops python_extension_ops;
67 /* The main struct describing GDB's interface to the Python
68 extension language. */
69 const struct extension_language_defn extension_language_python =
81 &python_extension_script_ops,
91 #include "cli/cli-decode.h"
94 #include "python-internal.h"
97 #include "gdbsupport/version.h"
99 #include "gdbthread.h"
101 #include "event-top.h"
102 #include "py-event.h"
104 /* True if Python has been successfully initialized, false
107 int gdb_python_initialized;
109 extern PyMethodDef python_GdbMethods[];
111 PyObject *gdb_module;
112 PyObject *gdb_python_module;
114 /* Some string constants we may wish to use. */
115 PyObject *gdbpy_to_string_cst;
116 PyObject *gdbpy_children_cst;
117 PyObject *gdbpy_display_hint_cst;
118 PyObject *gdbpy_doc_cst;
119 PyObject *gdbpy_enabled_cst;
120 PyObject *gdbpy_value_cst;
122 /* The GdbError exception. */
123 PyObject *gdbpy_gdberror_exc;
125 /* The `gdb.error' base class. */
126 PyObject *gdbpy_gdb_error;
128 /* The `gdb.MemoryError' exception. */
129 PyObject *gdbpy_gdb_memory_error;
131 static script_sourcer_func gdbpy_source_script;
132 static objfile_script_sourcer_func gdbpy_source_objfile_script;
133 static objfile_script_executor_func gdbpy_execute_objfile_script;
134 static void gdbpy_initialize (const struct extension_language_defn *);
135 static int gdbpy_initialized (const struct extension_language_defn *);
136 static void gdbpy_eval_from_control_command
137 (const struct extension_language_defn *, struct command_line *cmd);
138 static void gdbpy_start_type_printers (const struct extension_language_defn *,
139 struct ext_lang_type_printers *);
140 static enum ext_lang_rc gdbpy_apply_type_printers
141 (const struct extension_language_defn *,
142 const struct ext_lang_type_printers *, struct type *, char **);
143 static void gdbpy_free_type_printers (const struct extension_language_defn *,
144 struct ext_lang_type_printers *);
145 static void gdbpy_set_quit_flag (const struct extension_language_defn *);
146 static int gdbpy_check_quit_flag (const struct extension_language_defn *);
147 static enum ext_lang_rc gdbpy_before_prompt_hook
148 (const struct extension_language_defn *, const char *current_gdb_prompt);
149 static gdb::optional<std::string> gdbpy_colorize
150 (const std::string &filename, const std::string &contents);
152 /* The interface between gdb proper and loading of python scripts. */
154 const struct extension_language_script_ops python_extension_script_ops =
157 gdbpy_source_objfile_script,
158 gdbpy_execute_objfile_script,
159 gdbpy_auto_load_enabled
162 /* The interface between gdb proper and python extensions. */
164 const struct extension_language_ops python_extension_ops =
169 gdbpy_eval_from_control_command,
171 gdbpy_start_type_printers,
172 gdbpy_apply_type_printers,
173 gdbpy_free_type_printers,
175 gdbpy_apply_val_pretty_printer,
177 gdbpy_apply_frame_filter,
179 gdbpy_preserve_values,
181 gdbpy_breakpoint_has_cond,
182 gdbpy_breakpoint_cond_says_stop,
185 gdbpy_check_quit_flag,
187 gdbpy_before_prompt_hook,
189 gdbpy_get_matching_xmethod_workers,
194 /* Architecture and language to be used in callbacks from
195 the Python interpreter. */
196 struct gdbarch *python_gdbarch;
197 const struct language_defn *python_language;
199 gdbpy_enter::gdbpy_enter (struct gdbarch *gdbarch,
200 const struct language_defn *language)
201 : m_gdbarch (python_gdbarch),
202 m_language (python_language)
204 /* We should not ever enter Python unless initialized. */
205 if (!gdb_python_initialized)
206 error (_("Python not initialized"));
208 m_previous_active = set_active_ext_lang (&extension_language_python);
210 m_state = PyGILState_Ensure ();
212 python_gdbarch = gdbarch;
213 python_language = language;
215 /* Save it and ensure ! PyErr_Occurred () afterwards. */
219 gdbpy_enter::~gdbpy_enter ()
221 /* Leftover Python error is forbidden by Python Exception Handling. */
222 if (PyErr_Occurred ())
224 /* This order is similar to the one calling error afterwards. */
225 gdbpy_print_stack ();
226 warning (_("internal error: Unhandled Python exception"));
231 python_gdbarch = m_gdbarch;
232 python_language = m_language;
234 restore_active_ext_lang (m_previous_active);
235 PyGILState_Release (m_state);
238 /* A helper class to save and restore the GIL, but without touching
239 the other globals that are handled by gdbpy_enter. */
246 : m_state (PyGILState_Ensure ())
252 PyGILState_Release (m_state);
255 DISABLE_COPY_AND_ASSIGN (gdbpy_gil);
259 PyGILState_STATE m_state;
262 /* Set the quit flag. */
265 gdbpy_set_quit_flag (const struct extension_language_defn *extlang)
267 PyErr_SetInterrupt ();
270 /* Return true if the quit flag has been set, false otherwise. */
273 gdbpy_check_quit_flag (const struct extension_language_defn *extlang)
275 if (!gdb_python_initialized)
279 return PyOS_InterruptOccurred ();
282 /* Evaluate a Python command like PyRun_SimpleString, but uses
283 Py_single_input which prints the result of expressions, and does
284 not automatically print the stack on errors. */
287 eval_python_command (const char *command)
291 m = PyImport_AddModule ("__main__");
295 d = PyModule_GetDict (m);
298 gdbpy_ref<> v (PyRun_StringFlags (command, Py_single_input, d, d, NULL));
310 /* Implementation of the gdb "python-interactive" command. */
313 python_interactive_command (const char *arg, int from_tty)
315 struct ui *ui = current_ui;
318 scoped_restore save_async = make_scoped_restore (¤t_ui->async, 0);
320 arg = skip_spaces (arg);
322 gdbpy_enter enter_py (get_current_arch (), current_language);
326 std::string script = std::string (arg) + "\n";
327 err = eval_python_command (script.c_str ());
331 err = PyRun_InteractiveLoop (ui->instream, "<stdin>");
337 gdbpy_print_stack ();
338 error (_("Error while executing Python code."));
342 /* A wrapper around PyRun_SimpleFile. FILE is the Python script to run
345 On Windows hosts few users would build Python themselves (this is no
346 trivial task on this platform), and thus use binaries built by
347 someone else instead. There may happen situation where the Python
348 library and GDB are using two different versions of the C runtime
349 library. Python, being built with VC, would use one version of the
350 msvcr DLL (Eg. msvcr100.dll), while MinGW uses msvcrt.dll.
351 A FILE * from one runtime does not necessarily operate correctly in
354 To work around this potential issue, we run code in Python to load
358 python_run_simple_file (FILE *file, const char *filename)
362 PyRun_SimpleFile (file, filename);
366 /* Because we have a string for a filename, and are using Python to
367 open the file, we need to expand any tilde in the path first. */
368 gdb::unique_xmalloc_ptr<char> full_path (tilde_expand (filename));
370 if (gdb_python_module == nullptr
371 || ! PyObject_HasAttrString (gdb_python_module, "_execute_file"))
372 error (_("Installation error: gdb._execute_file function is missing"));
374 gdbpy_ref<> return_value
375 (PyObject_CallMethod (gdb_python_module, "_execute_file", "s",
377 if (return_value == nullptr)
379 /* Use PyErr_PrintEx instead of gdbpy_print_stack to better match the
380 behavior of the non-Windows codepath. */
387 /* Given a command_line, return a command string suitable for passing
388 to Python. Lines in the string are separated by newlines. */
391 compute_python_string (struct command_line *l)
393 struct command_line *iter;
396 for (iter = l; iter; iter = iter->next)
398 script += iter->line;
404 /* Take a command line structure representing a 'python' command, and
405 evaluate its body using the Python interpreter. */
408 gdbpy_eval_from_control_command (const struct extension_language_defn *extlang,
409 struct command_line *cmd)
413 if (cmd->body_list_1 != nullptr)
414 error (_("Invalid \"python\" block structure."));
416 gdbpy_enter enter_py (get_current_arch (), current_language);
418 std::string script = compute_python_string (cmd->body_list_0.get ());
419 ret = PyRun_SimpleString (script.c_str ());
421 error (_("Error while executing Python code."));
424 /* Implementation of the gdb "python" command. */
427 python_command (const char *arg, int from_tty)
429 gdbpy_enter enter_py (get_current_arch (), current_language);
431 scoped_restore save_async = make_scoped_restore (¤t_ui->async, 0);
433 arg = skip_spaces (arg);
436 if (PyRun_SimpleString (arg))
437 error (_("Error while executing Python code."));
441 counted_command_line l = get_command_line (python_control, "");
443 execute_control_command_untraced (l.get ());
449 /* Transform a gdb parameters's value into a Python value. May return
450 NULL (and set a Python exception) on error. Helper function for
453 gdbpy_parameter_value (const setting &var)
458 case var_string_noescape:
459 case var_optional_filename:
464 if (var.type () == var_enum)
465 str = var.get<const char *> ();
467 str = var.get<std::string> ().c_str ();
469 return host_string_to_python_string (str).release ();
474 if (var.get<bool> ())
480 case var_auto_boolean:
482 enum auto_boolean ab = var.get<enum auto_boolean> ();
484 if (ab == AUTO_BOOLEAN_TRUE)
486 else if (ab == AUTO_BOOLEAN_FALSE)
493 if (var.get<int> () == INT_MAX)
497 case var_zuinteger_unlimited:
498 return gdb_py_object_from_longest (var.get<int> ()).release ();
502 unsigned int val = var.get<unsigned int> ();
506 return gdb_py_object_from_ulongest (val).release ();
511 unsigned int val = var.get<unsigned int> ();
512 return gdb_py_object_from_ulongest (val).release ();
516 return PyErr_Format (PyExc_RuntimeError,
517 _("Programmer error: unhandled type."));
520 /* A Python function which returns a gdb parameter's value as a Python
524 gdbpy_parameter (PyObject *self, PyObject *args)
526 struct cmd_list_element *alias, *prefix, *cmd;
530 if (! PyArg_ParseTuple (args, "s", &arg))
533 std::string newarg = std::string ("show ") + arg;
537 found = lookup_cmd_composition (newarg.c_str (), &alias, &prefix, &cmd);
539 catch (const gdb_exception &ex)
541 GDB_PY_HANDLE_EXCEPTION (ex);
545 return PyErr_Format (PyExc_RuntimeError,
546 _("Could not find parameter `%s'."), arg);
548 if (!cmd->var.has_value ())
549 return PyErr_Format (PyExc_RuntimeError,
550 _("`%s' is not a parameter."), arg);
552 return gdbpy_parameter_value (*cmd->var);
555 /* Wrapper for target_charset. */
558 gdbpy_target_charset (PyObject *self, PyObject *args)
560 const char *cset = target_charset (python_gdbarch);
562 return PyUnicode_Decode (cset, strlen (cset), host_charset (), NULL);
565 /* Wrapper for target_wide_charset. */
568 gdbpy_target_wide_charset (PyObject *self, PyObject *args)
570 const char *cset = target_wide_charset (python_gdbarch);
572 return PyUnicode_Decode (cset, strlen (cset), host_charset (), NULL);
575 /* A Python function which evaluates a string using the gdb CLI. */
578 execute_gdb_command (PyObject *self, PyObject *args, PyObject *kw)
581 PyObject *from_tty_obj = NULL, *to_string_obj = NULL;
582 int from_tty, to_string;
583 static const char *keywords[] = { "command", "from_tty", "to_string", NULL };
585 if (!gdb_PyArg_ParseTupleAndKeywords (args, kw, "s|O!O!", keywords, &arg,
586 &PyBool_Type, &from_tty_obj,
587 &PyBool_Type, &to_string_obj))
593 int cmp = PyObject_IsTrue (from_tty_obj);
602 int cmp = PyObject_IsTrue (to_string_obj);
608 std::string to_string_res;
610 scoped_restore preventer = prevent_dont_repeat ();
614 gdbpy_allow_threads allow_threads;
616 struct interp *interp;
618 std::string arg_copy = arg;
620 char *save_ptr = nullptr;
624 const char *result = strtok_r (first ? &arg_copy[0] : nullptr,
630 counted_command_line lines = read_command_lines_1 (reader, 1, nullptr);
633 scoped_restore save_async = make_scoped_restore (¤t_ui->async,
636 scoped_restore save_uiout = make_scoped_restore (¤t_uiout);
638 /* Use the console interpreter uiout to have the same print format
639 for console or MI. */
640 interp = interp_lookup (current_ui, "console");
641 current_uiout = interp->interp_ui_out ();
644 to_string_res = execute_control_commands_to_string (lines.get (),
647 execute_control_commands (lines.get (), from_tty);
650 /* Do any commands attached to breakpoint we stopped at. */
651 bpstat_do_actions ();
653 catch (const gdb_exception &except)
655 /* If an exception occurred then we won't hit normal_stop (), or have
656 an exception reach the top level of the event loop, which are the
657 two usual places in which stdin would be re-enabled. So, before we
658 convert the exception and continue back in Python, we should
659 re-enable stdin here. */
660 async_enable_stdin ();
661 GDB_PY_HANDLE_EXCEPTION (except);
665 return PyString_FromString (to_string_res.c_str ());
669 /* Implementation of Python rbreak command. Take a REGEX and
670 optionally a MINSYMS, THROTTLE and SYMTABS keyword and return a
671 Python list that contains newly set breakpoints that match that
672 criteria. REGEX refers to a GDB format standard regex pattern of
673 symbols names to search; MINSYMS is an optional boolean (default
674 False) that indicates if the function should search GDB's minimal
675 symbols; THROTTLE is an optional integer (default unlimited) that
676 indicates the maximum amount of breakpoints allowable before the
677 function exits (note, if the throttle bound is passed, no
678 breakpoints will be set and a runtime error returned); SYMTABS is
679 an optional Python iterable that contains a set of gdb.Symtabs to
680 constrain the search within. */
683 gdbpy_rbreak (PyObject *self, PyObject *args, PyObject *kw)
686 std::vector<symbol_search> symbols;
687 unsigned long count = 0;
688 PyObject *symtab_list = NULL;
689 PyObject *minsyms_p_obj = NULL;
691 unsigned int throttle = 0;
692 static const char *keywords[] = {"regex","minsyms", "throttle",
695 if (!gdb_PyArg_ParseTupleAndKeywords (args, kw, "s|O!IO", keywords,
696 ®ex, &PyBool_Type,
697 &minsyms_p_obj, &throttle,
701 /* Parse minsyms keyword. */
702 if (minsyms_p_obj != NULL)
704 int cmp = PyObject_IsTrue (minsyms_p_obj);
710 global_symbol_searcher spec (FUNCTIONS_DOMAIN, regex);
712 for (const char *elem : spec.filenames)
713 xfree ((void *) elem);
716 /* The "symtabs" keyword is any Python iterable object that returns
717 a gdb.Symtab on each iteration. If specified, iterate through
718 the provided gdb.Symtabs and extract their full path. As
719 python_string_to_target_string returns a
720 gdb::unique_xmalloc_ptr<char> and a vector containing these types
721 cannot be coerced to a const char **p[] via the vector.data call,
722 release the value from the unique_xmalloc_ptr and place it in a
723 simple type symtab_list_type (which holds the vector and a
724 destructor that frees the contents of the allocated strings. */
725 if (symtab_list != NULL)
727 gdbpy_ref<> iter (PyObject_GetIter (symtab_list));
734 gdbpy_ref<> next (PyIter_Next (iter.get ()));
738 if (PyErr_Occurred ())
743 gdbpy_ref<> obj_name (PyObject_GetAttrString (next.get (),
746 if (obj_name == NULL)
749 /* Is the object file still valid? */
750 if (obj_name == Py_None)
753 gdb::unique_xmalloc_ptr<char> filename =
754 python_string_to_target_string (obj_name.get ());
756 if (filename == NULL)
759 /* Make sure there is a definite place to store the value of
760 filename before it is released. */
761 spec.filenames.push_back (nullptr);
762 spec.filenames.back () = filename.release ();
766 /* The search spec. */
767 symbols = spec.search ();
769 /* Count the number of symbols (both symbols and optionally minimal
770 symbols) so we can correctly check the throttle limit. */
771 for (const symbol_search &p : symbols)
773 /* Minimal symbols included? */
776 if (p.msymbol.minsym != NULL)
780 if (p.symbol != NULL)
784 /* Check throttle bounds and exit if in excess. */
785 if (throttle != 0 && count > throttle)
787 PyErr_SetString (PyExc_RuntimeError,
788 _("Number of breakpoints exceeds throttled maximum."));
792 gdbpy_ref<> return_list (PyList_New (0));
794 if (return_list == NULL)
797 /* Construct full path names for symbols and call the Python
798 breakpoint constructor on the resulting names. Be tolerant of
799 individual breakpoint failures. */
800 for (const symbol_search &p : symbols)
802 std::string symbol_name;
804 /* Skipping minimal symbols? */
806 if (p.msymbol.minsym != NULL)
809 if (p.msymbol.minsym == NULL)
811 struct symtab *symtab = symbol_symtab (p.symbol);
812 const char *fullname = symtab_to_fullname (symtab);
814 symbol_name = fullname;
816 symbol_name += p.symbol->linkage_name ();
819 symbol_name = p.msymbol.minsym->linkage_name ();
821 gdbpy_ref<> argList (Py_BuildValue("(s)", symbol_name.c_str ()));
822 gdbpy_ref<> obj (PyObject_CallObject ((PyObject *)
823 &breakpoint_object_type,
826 /* Tolerate individual breakpoint failures. */
828 gdbpy_print_stack ();
831 if (PyList_Append (return_list.get (), obj.get ()) == -1)
835 return return_list.release ();
838 /* A Python function which is a wrapper for decode_line_1. */
841 gdbpy_decode_line (PyObject *self, PyObject *args)
843 const char *arg = NULL;
845 gdbpy_ref<> unparsed;
846 event_location_up location;
848 if (! PyArg_ParseTuple (args, "|s", &arg))
851 /* Treat a string consisting of just whitespace the same as
855 arg = skip_spaces (arg);
861 location = string_to_event_location_basic (&arg, python_language,
862 symbol_name_match_type::WILD);
864 std::vector<symtab_and_line> decoded_sals;
865 symtab_and_line def_sal;
866 gdb::array_view<symtab_and_line> sals;
869 if (location != NULL)
871 decoded_sals = decode_line_1 (location.get (), 0, NULL, NULL, 0);
876 set_default_source_symtab_and_line ();
877 def_sal = get_current_source_symtab_and_line ();
881 catch (const gdb_exception &ex)
883 /* We know this will always throw. */
884 gdbpy_convert_exception (ex);
890 result.reset (PyTuple_New (sals.size ()));
893 for (size_t i = 0; i < sals.size (); ++i)
895 PyObject *obj = symtab_and_line_to_sal_object (sals[i]);
899 PyTuple_SetItem (result.get (), i, obj);
903 result = gdbpy_ref<>::new_reference (Py_None);
905 gdbpy_ref<> return_result (PyTuple_New (2));
906 if (return_result == NULL)
909 if (arg != NULL && strlen (arg) > 0)
911 unparsed.reset (PyString_FromString (arg));
912 if (unparsed == NULL)
916 unparsed = gdbpy_ref<>::new_reference (Py_None);
918 PyTuple_SetItem (return_result.get (), 0, unparsed.release ());
919 PyTuple_SetItem (return_result.get (), 1, result.release ());
921 return return_result.release ();
924 /* Parse a string and evaluate it as an expression. */
926 gdbpy_parse_and_eval (PyObject *self, PyObject *args)
928 const char *expr_str;
929 struct value *result = NULL;
931 if (!PyArg_ParseTuple (args, "s", &expr_str))
936 gdbpy_allow_threads allow_threads;
937 result = parse_and_eval (expr_str);
939 catch (const gdb_exception &except)
941 GDB_PY_HANDLE_EXCEPTION (except);
944 return value_to_value_object (result);
947 /* Implementation of gdb.invalidate_cached_frames. */
950 gdbpy_invalidate_cached_frames (PyObject *self, PyObject *args)
952 reinit_frame_cache ();
956 /* Read a file as Python code.
957 This is the extension_language_script_ops.script_sourcer "method".
958 FILE is the file to load. FILENAME is name of the file FILE.
959 This does not throw any errors. If an exception occurs python will print
960 the traceback and clear the error indicator. */
963 gdbpy_source_script (const struct extension_language_defn *extlang,
964 FILE *file, const char *filename)
966 gdbpy_enter enter_py (get_current_arch (), current_language);
967 python_run_simple_file (file, filename);
972 /* Posting and handling events. */
974 /* A single event. */
977 gdbpy_event (gdbpy_ref<> &&func)
978 : m_func (func.release ())
982 gdbpy_event (gdbpy_event &&other) noexcept
983 : m_func (other.m_func)
985 other.m_func = nullptr;
988 gdbpy_event (const gdbpy_event &other)
989 : m_func (other.m_func)
1001 gdbpy_event &operator= (const gdbpy_event &other) = delete;
1005 gdbpy_enter enter_py (get_current_arch (), current_language);
1007 gdbpy_ref<> call_result (PyObject_CallObject (m_func, NULL));
1008 if (call_result == NULL)
1009 gdbpy_print_stack ();
1014 /* The Python event. This is just a callable object. Note that
1015 this is not a gdbpy_ref<>, because we have to take particular
1016 care to only destroy the reference when holding the GIL. */
1020 /* Submit an event to the gdb thread. */
1022 gdbpy_post_event (PyObject *self, PyObject *args)
1026 if (!PyArg_ParseTuple (args, "O", &func))
1029 if (!PyCallable_Check (func))
1031 PyErr_SetString (PyExc_RuntimeError,
1032 _("Posted event is not callable"));
1036 gdbpy_ref<> func_ref = gdbpy_ref<>::new_reference (func);
1037 gdbpy_event event (std::move (func_ref));
1038 run_on_main_thread (event);
1045 /* This is the extension_language_ops.before_prompt "method". */
1047 static enum ext_lang_rc
1048 gdbpy_before_prompt_hook (const struct extension_language_defn *extlang,
1049 const char *current_gdb_prompt)
1051 if (!gdb_python_initialized)
1052 return EXT_LANG_RC_NOP;
1054 gdbpy_enter enter_py (get_current_arch (), current_language);
1056 if (!evregpy_no_listeners_p (gdb_py_events.before_prompt)
1057 && evpy_emit_event (NULL, gdb_py_events.before_prompt) < 0)
1058 return EXT_LANG_RC_ERROR;
1060 if (gdb_python_module
1061 && PyObject_HasAttrString (gdb_python_module, "prompt_hook"))
1063 gdbpy_ref<> hook (PyObject_GetAttrString (gdb_python_module,
1067 gdbpy_print_stack ();
1068 return EXT_LANG_RC_ERROR;
1071 if (PyCallable_Check (hook.get ()))
1073 gdbpy_ref<> current_prompt (PyString_FromString (current_gdb_prompt));
1074 if (current_prompt == NULL)
1076 gdbpy_print_stack ();
1077 return EXT_LANG_RC_ERROR;
1081 (PyObject_CallFunctionObjArgs (hook.get (), current_prompt.get (),
1085 gdbpy_print_stack ();
1086 return EXT_LANG_RC_ERROR;
1089 /* Return type should be None, or a String. If it is None,
1090 fall through, we will not set a prompt. If it is a
1091 string, set PROMPT. Anything else, set an exception. */
1092 if (result != Py_None && ! PyString_Check (result.get ()))
1094 PyErr_Format (PyExc_RuntimeError,
1095 _("Return from prompt_hook must " \
1096 "be either a Python string, or None"));
1097 gdbpy_print_stack ();
1098 return EXT_LANG_RC_ERROR;
1101 if (result != Py_None)
1103 gdb::unique_xmalloc_ptr<char>
1104 prompt (python_string_to_host_string (result.get ()));
1108 gdbpy_print_stack ();
1109 return EXT_LANG_RC_ERROR;
1112 set_prompt (prompt.get ());
1113 return EXT_LANG_RC_OK;
1118 return EXT_LANG_RC_NOP;
1121 /* This is the extension_language_ops.colorize "method". */
1123 static gdb::optional<std::string>
1124 gdbpy_colorize (const std::string &filename, const std::string &contents)
1126 if (!gdb_python_initialized)
1129 gdbpy_enter enter_py (get_current_arch (), current_language);
1131 if (gdb_python_module == nullptr
1132 || !PyObject_HasAttrString (gdb_python_module, "colorize"))
1135 gdbpy_ref<> hook (PyObject_GetAttrString (gdb_python_module, "colorize"));
1136 if (hook == nullptr)
1138 gdbpy_print_stack ();
1142 if (!PyCallable_Check (hook.get ()))
1145 gdbpy_ref<> fname_arg (PyString_FromString (filename.c_str ()));
1146 if (fname_arg == nullptr)
1148 gdbpy_print_stack ();
1151 gdbpy_ref<> contents_arg (PyString_FromString (contents.c_str ()));
1152 if (contents_arg == nullptr)
1154 gdbpy_print_stack ();
1158 gdbpy_ref<> result (PyObject_CallFunctionObjArgs (hook.get (),
1160 contents_arg.get (),
1162 if (result == nullptr)
1164 gdbpy_print_stack ();
1168 if (!gdbpy_is_string (result.get ()))
1171 gdbpy_ref<> unic = python_string_to_unicode (result.get ());
1172 if (unic == nullptr)
1174 gdbpy_print_stack ();
1177 gdbpy_ref<> host_str (PyUnicode_AsEncodedString (unic.get (),
1180 if (host_str == nullptr)
1182 gdbpy_print_stack ();
1186 return std::string (PyBytes_AsString (host_str.get ()));
1193 /* A python function to write a single string using gdb's filtered
1194 output stream . The optional keyword STREAM can be used to write
1195 to a particular stream. The default stream is to gdb_stdout. */
1198 gdbpy_write (PyObject *self, PyObject *args, PyObject *kw)
1201 static const char *keywords[] = { "text", "stream", NULL };
1202 int stream_type = 0;
1204 if (!gdb_PyArg_ParseTupleAndKeywords (args, kw, "s|i", keywords, &arg,
1210 switch (stream_type)
1214 fprintf_filtered (gdb_stderr, "%s", arg);
1219 fprintf_filtered (gdb_stdlog, "%s", arg);
1223 fprintf_filtered (gdb_stdout, "%s", arg);
1226 catch (const gdb_exception &except)
1228 GDB_PY_HANDLE_EXCEPTION (except);
1234 /* A python function to flush a gdb stream. The optional keyword
1235 STREAM can be used to flush a particular stream. The default stream
1239 gdbpy_flush (PyObject *self, PyObject *args, PyObject *kw)
1241 static const char *keywords[] = { "stream", NULL };
1242 int stream_type = 0;
1244 if (!gdb_PyArg_ParseTupleAndKeywords (args, kw, "|i", keywords,
1248 switch (stream_type)
1252 gdb_flush (gdb_stderr);
1257 gdb_flush (gdb_stdlog);
1261 gdb_flush (gdb_stdout);
1267 /* Return non-zero if print-stack is not "none". */
1270 gdbpy_print_python_errors_p (void)
1272 return gdbpy_should_print_stack != python_excp_none;
1275 /* Print a python exception trace, print just a message, or print
1276 nothing and clear the python exception, depending on
1277 gdbpy_should_print_stack. Only call this if a python exception is
1280 gdbpy_print_stack (void)
1283 /* Print "none", just clear exception. */
1284 if (gdbpy_should_print_stack == python_excp_none)
1288 /* Print "full" message and backtrace. */
1289 else if (gdbpy_should_print_stack == python_excp_full)
1292 /* PyErr_Print doesn't necessarily end output with a newline.
1293 This works because Python's stdout/stderr is fed through
1299 catch (const gdb_exception &except)
1303 /* Print "message", just error print message. */
1306 gdbpy_err_fetch fetched_error;
1308 gdb::unique_xmalloc_ptr<char> msg = fetched_error.to_string ();
1309 gdb::unique_xmalloc_ptr<char> type;
1310 /* Don't compute TYPE if MSG already indicates that there is an
1313 type = fetched_error.type_to_string ();
1317 if (msg == NULL || type == NULL)
1319 /* An error occurred computing the string representation of the
1321 fprintf_filtered (gdb_stderr,
1322 _("Error occurred computing Python error" \
1327 fprintf_filtered (gdb_stderr, "Python Exception %s: %s\n",
1328 type.get (), msg.get ());
1330 catch (const gdb_exception &except)
1336 /* Like gdbpy_print_stack, but if the exception is a
1337 KeyboardException, throw a gdb "quit" instead. */
1340 gdbpy_print_stack_or_quit ()
1342 if (PyErr_ExceptionMatches (PyExc_KeyboardInterrupt))
1345 throw_quit ("Quit");
1347 gdbpy_print_stack ();
1352 /* Return a sequence holding all the Progspaces. */
1355 gdbpy_progspaces (PyObject *unused1, PyObject *unused2)
1357 gdbpy_ref<> list (PyList_New (0));
1361 for (struct program_space *ps : program_spaces)
1363 gdbpy_ref<> item = pspace_to_pspace_object (ps);
1365 if (item == NULL || PyList_Append (list.get (), item.get ()) == -1)
1369 return list.release ();
1374 /* The "current" objfile. This is set when gdb detects that a new
1375 objfile has been loaded. It is only set for the duration of a call to
1376 gdbpy_source_objfile_script and gdbpy_execute_objfile_script; it is NULL
1378 static struct objfile *gdbpy_current_objfile;
1380 /* Set the current objfile to OBJFILE and then read FILE named FILENAME
1381 as Python code. This does not throw any errors. If an exception
1382 occurs python will print the traceback and clear the error indicator.
1383 This is the extension_language_script_ops.objfile_script_sourcer
1387 gdbpy_source_objfile_script (const struct extension_language_defn *extlang,
1388 struct objfile *objfile, FILE *file,
1389 const char *filename)
1391 if (!gdb_python_initialized)
1394 gdbpy_enter enter_py (objfile->arch (), current_language);
1395 scoped_restore restire_current_objfile
1396 = make_scoped_restore (&gdbpy_current_objfile, objfile);
1398 python_run_simple_file (file, filename);
1401 /* Set the current objfile to OBJFILE and then execute SCRIPT
1402 as Python code. This does not throw any errors. If an exception
1403 occurs python will print the traceback and clear the error indicator.
1404 This is the extension_language_script_ops.objfile_script_executor
1408 gdbpy_execute_objfile_script (const struct extension_language_defn *extlang,
1409 struct objfile *objfile, const char *name,
1412 if (!gdb_python_initialized)
1415 gdbpy_enter enter_py (objfile->arch (), current_language);
1416 scoped_restore restire_current_objfile
1417 = make_scoped_restore (&gdbpy_current_objfile, objfile);
1419 PyRun_SimpleString (script);
1422 /* Return the current Objfile, or None if there isn't one. */
1425 gdbpy_get_current_objfile (PyObject *unused1, PyObject *unused2)
1427 if (! gdbpy_current_objfile)
1430 return objfile_to_objfile_object (gdbpy_current_objfile).release ();
1433 /* Compute the list of active python type printers and store them in
1434 EXT_PRINTERS->py_type_printers. The product of this function is used by
1435 gdbpy_apply_type_printers, and freed by gdbpy_free_type_printers.
1436 This is the extension_language_ops.start_type_printers "method". */
1439 gdbpy_start_type_printers (const struct extension_language_defn *extlang,
1440 struct ext_lang_type_printers *ext_printers)
1442 PyObject *printers_obj = NULL;
1444 if (!gdb_python_initialized)
1447 gdbpy_enter enter_py (get_current_arch (), current_language);
1449 gdbpy_ref<> type_module (PyImport_ImportModule ("gdb.types"));
1450 if (type_module == NULL)
1452 gdbpy_print_stack ();
1456 gdbpy_ref<> func (PyObject_GetAttrString (type_module.get (),
1457 "get_type_recognizers"));
1460 gdbpy_print_stack ();
1464 printers_obj = PyObject_CallFunctionObjArgs (func.get (), (char *) NULL);
1465 if (printers_obj == NULL)
1466 gdbpy_print_stack ();
1468 ext_printers->py_type_printers = printers_obj;
1471 /* If TYPE is recognized by some type printer, store in *PRETTIED_TYPE
1472 a newly allocated string holding the type's replacement name, and return
1473 EXT_LANG_RC_OK. The caller is responsible for freeing the string.
1474 If there's a Python error return EXT_LANG_RC_ERROR.
1475 Otherwise, return EXT_LANG_RC_NOP.
1476 This is the extension_language_ops.apply_type_printers "method". */
1478 static enum ext_lang_rc
1479 gdbpy_apply_type_printers (const struct extension_language_defn *extlang,
1480 const struct ext_lang_type_printers *ext_printers,
1481 struct type *type, char **prettied_type)
1483 PyObject *printers_obj = (PyObject *) ext_printers->py_type_printers;
1484 gdb::unique_xmalloc_ptr<char> result;
1486 if (printers_obj == NULL)
1487 return EXT_LANG_RC_NOP;
1489 if (!gdb_python_initialized)
1490 return EXT_LANG_RC_NOP;
1492 gdbpy_enter enter_py (get_current_arch (), current_language);
1494 gdbpy_ref<> type_obj (type_to_type_object (type));
1495 if (type_obj == NULL)
1497 gdbpy_print_stack ();
1498 return EXT_LANG_RC_ERROR;
1501 gdbpy_ref<> type_module (PyImport_ImportModule ("gdb.types"));
1502 if (type_module == NULL)
1504 gdbpy_print_stack ();
1505 return EXT_LANG_RC_ERROR;
1508 gdbpy_ref<> func (PyObject_GetAttrString (type_module.get (),
1509 "apply_type_recognizers"));
1512 gdbpy_print_stack ();
1513 return EXT_LANG_RC_ERROR;
1516 gdbpy_ref<> result_obj (PyObject_CallFunctionObjArgs (func.get (),
1520 if (result_obj == NULL)
1522 gdbpy_print_stack ();
1523 return EXT_LANG_RC_ERROR;
1526 if (result_obj == Py_None)
1527 return EXT_LANG_RC_NOP;
1529 result = python_string_to_host_string (result_obj.get ());
1532 gdbpy_print_stack ();
1533 return EXT_LANG_RC_ERROR;
1536 *prettied_type = result.release ();
1537 return EXT_LANG_RC_OK;
1540 /* Free the result of start_type_printers.
1541 This is the extension_language_ops.free_type_printers "method". */
1544 gdbpy_free_type_printers (const struct extension_language_defn *extlang,
1545 struct ext_lang_type_printers *ext_printers)
1547 PyObject *printers = (PyObject *) ext_printers->py_type_printers;
1549 if (printers == NULL)
1552 if (!gdb_python_initialized)
1555 gdbpy_enter enter_py (get_current_arch (), current_language);
1556 Py_DECREF (printers);
1559 #else /* HAVE_PYTHON */
1561 /* Dummy implementation of the gdb "python-interactive" and "python"
1565 python_interactive_command (const char *arg, int from_tty)
1567 arg = skip_spaces (arg);
1569 error (_("Python scripting is not supported in this copy of GDB."));
1572 counted_command_line l = get_command_line (python_control, "");
1574 execute_control_command_untraced (l.get ());
1579 python_command (const char *arg, int from_tty)
1581 python_interactive_command (arg, from_tty);
1584 #endif /* HAVE_PYTHON */
1586 /* When this is turned on before Python is initialised then Python will
1587 ignore any environment variables related to Python. This is equivalent
1588 to passing `-E' to the python program. */
1589 static bool python_ignore_environment = false;
1591 /* Implement 'show python ignore-environment'. */
1594 show_python_ignore_environment (struct ui_file *file, int from_tty,
1595 struct cmd_list_element *c, const char *value)
1597 fprintf_filtered (file, _("Python's ignore-environment setting is %s.\n"),
1601 /* Implement 'set python ignore-environment'. This sets Python's internal
1602 flag no matter when the command is issued, however, if this is used
1603 after Py_Initialize has been called then most of the environment will
1604 already have been read. */
1607 set_python_ignore_environment (const char *args, int from_tty,
1608 struct cmd_list_element *c)
1611 Py_IgnoreEnvironmentFlag = python_ignore_environment ? 1 : 0;
1615 /* When this is turned on before Python is initialised then Python will
1616 not write `.pyc' files on import of a module. */
1617 static enum auto_boolean python_dont_write_bytecode = AUTO_BOOLEAN_AUTO;
1619 /* Implement 'show python dont-write-bytecode'. */
1622 show_python_dont_write_bytecode (struct ui_file *file, int from_tty,
1623 struct cmd_list_element *c, const char *value)
1625 if (python_dont_write_bytecode == AUTO_BOOLEAN_AUTO)
1627 const char *auto_string
1628 = (python_ignore_environment
1629 || getenv ("PYTHONDONTWRITEBYTECODE") == nullptr) ? "off" : "on";
1631 fprintf_filtered (file,
1632 _("Python's dont-write-bytecode setting is %s (currently %s).\n"),
1633 value, auto_string);
1636 fprintf_filtered (file, _("Python's dont-write-bytecode setting is %s.\n"),
1640 /* Implement 'set python dont-write-bytecode'. This sets Python's internal
1641 flag no matter when the command is issued, however, if this is used
1642 after Py_Initialize has been called then many modules could already
1643 have been imported and their byte code written out. */
1646 set_python_dont_write_bytecode (const char *args, int from_tty,
1647 struct cmd_list_element *c)
1650 if (python_dont_write_bytecode == AUTO_BOOLEAN_AUTO)
1651 Py_DontWriteBytecodeFlag
1652 = (!python_ignore_environment
1653 && getenv ("PYTHONDONTWRITEBYTECODE") != nullptr) ? 1 : 0;
1655 Py_DontWriteBytecodeFlag
1656 = python_dont_write_bytecode == AUTO_BOOLEAN_TRUE ? 1 : 0;
1657 #endif /* HAVE_PYTHON */
1662 /* Lists for 'set python' commands. */
1664 static struct cmd_list_element *user_set_python_list;
1665 static struct cmd_list_element *user_show_python_list;
1667 /* Initialize the Python code. */
1671 /* This is installed as a final cleanup and cleans up the
1672 interpreter. This lets Python's 'atexit' work. */
1675 finalize_python (void *ignore)
1677 struct active_ext_lang_state *previous_active;
1679 /* We don't use ensure_python_env here because if we ever ran the
1680 cleanup, gdb would crash -- because the cleanup calls into the
1681 Python interpreter, which we are about to destroy. It seems
1682 clearer to make the needed calls explicitly here than to create a
1683 cleanup and then mysteriously discard it. */
1685 /* This is only called as a final cleanup so we can assume the active
1686 SIGINT handler is gdb's. We still need to tell it to notify Python. */
1687 previous_active = set_active_ext_lang (&extension_language_python);
1689 (void) PyGILState_Ensure ();
1690 python_gdbarch = target_gdbarch ();
1691 python_language = current_language;
1695 gdb_python_initialized = false;
1696 restore_active_ext_lang (previous_active);
1700 static struct PyModuleDef python_GdbModuleDef =
1702 PyModuleDef_HEAD_INIT,
1713 /* This is called via the PyImport_AppendInittab mechanism called
1714 during initialization, to make the built-in _gdb module known to
1716 PyMODINIT_FUNC init__gdb_module (void);
1718 init__gdb_module (void)
1720 return PyModule_Create (&python_GdbModuleDef);
1724 /* Emit a gdb.GdbExitingEvent, return a negative value if there are any
1725 errors, otherwise, return 0. */
1728 emit_exiting_event (int exit_code)
1730 gdbpy_ref<> event_obj = create_event_object (&gdb_exiting_event_object_type);
1731 if (event_obj == nullptr)
1734 gdbpy_ref<> code = gdb_py_object_from_longest (exit_code);
1735 if (evpy_add_attribute (event_obj.get (), "exit_code", code.get ()) < 0)
1738 return evpy_emit_event (event_obj.get (), gdb_py_events.gdb_exiting);
1741 /* Callback for the gdb_exiting observable. EXIT_CODE is the value GDB
1745 gdbpy_gdb_exiting (int exit_code)
1747 if (!gdb_python_initialized)
1750 gdbpy_enter enter_py (python_gdbarch, python_language);
1752 if (emit_exiting_event (exit_code) < 0)
1753 gdbpy_print_stack ();
1757 do_start_initialization ()
1759 #ifdef WITH_PYTHON_PATH
1760 /* Work around problem where python gets confused about where it is,
1761 and then can't find its libraries, etc.
1762 NOTE: Python assumes the following layout:
1764 /foo/lib/pythonX.Y/...
1765 This must be done before calling Py_Initialize. */
1766 gdb::unique_xmalloc_ptr<char> progname
1767 (concat (ldirname (python_libdir.c_str ()).c_str (), SLASH_STRING, "bin",
1768 SLASH_STRING, "python", (char *) NULL));
1770 /* Python documentation indicates that the memory given
1771 to Py_SetProgramName cannot be freed. However, it seems that
1772 at least Python 3.7.4 Py_SetProgramName takes a copy of the
1773 given program_name. Making progname_copy static and not release
1774 the memory avoids a leak report for Python versions that duplicate
1775 program_name, and respect the requirement of Py_SetProgramName
1776 for Python versions that do not duplicate program_name. */
1777 static wchar_t *progname_copy;
1779 std::string oldloc = setlocale (LC_ALL, NULL);
1780 setlocale (LC_ALL, "");
1781 size_t progsize = strlen (progname.get ());
1782 progname_copy = XNEWVEC (wchar_t, progsize + 1);
1783 size_t count = mbstowcs (progname_copy, progname.get (), progsize + 1);
1784 if (count == (size_t) -1)
1786 fprintf (stderr, "Could not convert python path to string\n");
1789 setlocale (LC_ALL, oldloc.c_str ());
1791 /* Note that Py_SetProgramName expects the string it is passed to
1792 remain alive for the duration of the program's execution, so
1793 it is not freed after this call. */
1794 Py_SetProgramName (progname_copy);
1796 /* Define _gdb as a built-in module. */
1797 PyImport_AppendInittab ("_gdb", init__gdb_module);
1799 Py_SetProgramName (progname.release ());
1804 #if PY_VERSION_HEX < 0x03090000
1805 /* PyEval_InitThreads became deprecated in Python 3.9 and will
1806 be removed in Python 3.11. Prior to Python 3.7, this call was
1807 required to initialize the GIL. */
1808 PyEval_InitThreads ();
1812 gdb_module = PyImport_ImportModule ("_gdb");
1814 gdb_module = Py_InitModule ("_gdb", python_GdbMethods);
1816 if (gdb_module == NULL)
1819 if (PyModule_AddStringConstant (gdb_module, "VERSION", version) < 0
1820 || PyModule_AddStringConstant (gdb_module, "HOST_CONFIG", host_name) < 0
1821 || PyModule_AddStringConstant (gdb_module, "TARGET_CONFIG",
1825 /* Add stream constants. */
1826 if (PyModule_AddIntConstant (gdb_module, "STDOUT", 0) < 0
1827 || PyModule_AddIntConstant (gdb_module, "STDERR", 1) < 0
1828 || PyModule_AddIntConstant (gdb_module, "STDLOG", 2) < 0)
1831 gdbpy_gdb_error = PyErr_NewException ("gdb.error", PyExc_RuntimeError, NULL);
1832 if (gdbpy_gdb_error == NULL
1833 || gdb_pymodule_addobject (gdb_module, "error", gdbpy_gdb_error) < 0)
1836 gdbpy_gdb_memory_error = PyErr_NewException ("gdb.MemoryError",
1837 gdbpy_gdb_error, NULL);
1838 if (gdbpy_gdb_memory_error == NULL
1839 || gdb_pymodule_addobject (gdb_module, "MemoryError",
1840 gdbpy_gdb_memory_error) < 0)
1843 gdbpy_gdberror_exc = PyErr_NewException ("gdb.GdbError", NULL, NULL);
1844 if (gdbpy_gdberror_exc == NULL
1845 || gdb_pymodule_addobject (gdb_module, "GdbError",
1846 gdbpy_gdberror_exc) < 0)
1849 gdbpy_initialize_gdb_readline ();
1851 if (gdbpy_initialize_auto_load () < 0
1852 || gdbpy_initialize_values () < 0
1853 || gdbpy_initialize_frames () < 0
1854 || gdbpy_initialize_commands () < 0
1855 || gdbpy_initialize_instruction () < 0
1856 || gdbpy_initialize_record () < 0
1857 || gdbpy_initialize_btrace () < 0
1858 || gdbpy_initialize_symbols () < 0
1859 || gdbpy_initialize_symtabs () < 0
1860 || gdbpy_initialize_blocks () < 0
1861 || gdbpy_initialize_functions () < 0
1862 || gdbpy_initialize_parameters () < 0
1863 || gdbpy_initialize_types () < 0
1864 || gdbpy_initialize_pspace () < 0
1865 || gdbpy_initialize_objfile () < 0
1866 || gdbpy_initialize_breakpoints () < 0
1867 || gdbpy_initialize_finishbreakpoints () < 0
1868 || gdbpy_initialize_lazy_string () < 0
1869 || gdbpy_initialize_linetable () < 0
1870 || gdbpy_initialize_thread () < 0
1871 || gdbpy_initialize_inferior () < 0
1872 || gdbpy_initialize_eventregistry () < 0
1873 || gdbpy_initialize_py_events () < 0
1874 || gdbpy_initialize_event () < 0
1875 || gdbpy_initialize_arch () < 0
1876 || gdbpy_initialize_registers () < 0
1877 || gdbpy_initialize_xmethods () < 0
1878 || gdbpy_initialize_unwind () < 0
1879 || gdbpy_initialize_membuf () < 0
1880 || gdbpy_initialize_tui () < 0)
1883 #define GDB_PY_DEFINE_EVENT_TYPE(name, py_name, doc, base) \
1884 if (gdbpy_initialize_event_generic (&name##_event_object_type, py_name) < 0) \
1886 #include "py-event-types.def"
1887 #undef GDB_PY_DEFINE_EVENT_TYPE
1889 gdbpy_to_string_cst = PyString_FromString ("to_string");
1890 if (gdbpy_to_string_cst == NULL)
1892 gdbpy_children_cst = PyString_FromString ("children");
1893 if (gdbpy_children_cst == NULL)
1895 gdbpy_display_hint_cst = PyString_FromString ("display_hint");
1896 if (gdbpy_display_hint_cst == NULL)
1898 gdbpy_doc_cst = PyString_FromString ("__doc__");
1899 if (gdbpy_doc_cst == NULL)
1901 gdbpy_enabled_cst = PyString_FromString ("enabled");
1902 if (gdbpy_enabled_cst == NULL)
1904 gdbpy_value_cst = PyString_FromString ("value");
1905 if (gdbpy_value_cst == NULL)
1908 gdb::observers::gdb_exiting.attach (gdbpy_gdb_exiting, "python");
1910 /* Release the GIL while gdb runs. */
1911 PyEval_SaveThread ();
1913 make_final_cleanup (finalize_python, NULL);
1915 /* Only set this when initialization has succeeded. */
1916 gdb_python_initialized = 1;
1921 namespace selftests {
1923 /* Entry point for python unit tests. */
1928 #define CMD(S) execute_command_to_string (S, "python print(5)", 0, true)
1933 SELF_CHECK (output == "5\n");
1936 bool saw_exception = false;
1938 scoped_restore reset_gdb_python_initialized
1939 = make_scoped_restore (&gdb_python_initialized, 0);
1944 catch (const gdb_exception &e)
1946 saw_exception = true;
1947 SELF_CHECK (e.reason == RETURN_ERROR);
1948 SELF_CHECK (e.error == GENERIC_ERROR);
1949 SELF_CHECK (*e.message == "Python not initialized");
1951 SELF_CHECK (saw_exception);
1952 SELF_CHECK (output.empty ());
1955 saw_exception = false;
1957 scoped_restore save_hook
1958 = make_scoped_restore (&hook_set_active_ext_lang,
1959 []() { raise (SIGINT); });
1964 catch (const gdb_exception &e)
1966 saw_exception = true;
1967 SELF_CHECK (e.reason == RETURN_ERROR);
1968 SELF_CHECK (e.error == GENERIC_ERROR);
1969 SELF_CHECK (*e.message == "Error while executing Python code.");
1971 SELF_CHECK (saw_exception);
1972 std::string ref_output("Traceback (most recent call last):\n"
1973 " File \"<string>\", line 1, in <module>\n"
1974 "KeyboardInterrupt\n");
1975 SELF_CHECK (output == ref_output);
1983 } // namespace selftests
1984 #endif /* GDB_SELF_TEST */
1986 #endif /* HAVE_PYTHON */
1989 cmd_list_element *python_cmd_element = nullptr;
1991 void _initialize_python ();
1993 _initialize_python ()
1995 cmd_list_element *python_interactive_cmd
1996 = add_com ("python-interactive", class_obscure,
1997 python_interactive_command,
2000 Start an interactive Python prompt.\n\
2002 To return to GDB, type the EOF character (e.g., Ctrl-D on an empty\n\
2005 Alternatively, a single-line Python command can be given as an\n\
2006 argument, and if the command is an expression, the result will be\n\
2007 printed. For example:\n\
2009 (gdb) python-interactive 2 + 3\n\
2011 #else /* HAVE_PYTHON */
2013 Start a Python interactive prompt.\n\
2015 Python scripting is not supported in this copy of GDB.\n\
2016 This command is only a placeholder.")
2017 #endif /* HAVE_PYTHON */
2019 add_com_alias ("pi", python_interactive_cmd, class_obscure, 1);
2021 python_cmd_element = add_com ("python", class_obscure, python_command,
2024 Evaluate a Python command.\n\
2026 The command can be given as an argument, for instance:\n\
2028 python print (23)\n\
2030 If no argument is given, the following lines are read and used\n\
2031 as the Python commands. Type a line containing \"end\" to indicate\n\
2032 the end of the command.")
2033 #else /* HAVE_PYTHON */
2035 Evaluate a Python command.\n\
2037 Python scripting is not supported in this copy of GDB.\n\
2038 This command is only a placeholder.")
2039 #endif /* HAVE_PYTHON */
2041 add_com_alias ("py", python_cmd_element, class_obscure, 1);
2043 /* Add set/show python print-stack. */
2044 add_basic_prefix_cmd ("python", no_class,
2045 _("Prefix command for python preference settings."),
2046 &user_show_python_list, 0, &showlist);
2048 add_show_prefix_cmd ("python", no_class,
2049 _("Prefix command for python preference settings."),
2050 &user_set_python_list, 0, &setlist);
2052 add_setshow_enum_cmd ("print-stack", no_class, python_excp_enums,
2053 &gdbpy_should_print_stack, _("\
2054 Set mode for Python stack dump on error."), _("\
2055 Show the mode of Python stack printing on error."), _("\
2056 none == no stack or message will be printed.\n\
2057 full == a message and a stack will be printed.\n\
2058 message == an error message without a stack will be printed."),
2060 &user_set_python_list,
2061 &user_show_python_list);
2063 add_setshow_boolean_cmd ("ignore-environment", no_class,
2064 &python_ignore_environment, _("\
2065 Set whether the Python interpreter should ignore environment variables."), _(" \
2066 Show whether the Python interpreter showlist ignore environment variables."), _(" \
2067 When enabled GDB's Python interpreter will ignore any Python related\n \
2068 flags in the environment. This is equivalent to passing `-E' to a\n \
2069 python executable."),
2070 set_python_ignore_environment,
2071 show_python_ignore_environment,
2072 &user_set_python_list,
2073 &user_show_python_list);
2075 add_setshow_auto_boolean_cmd ("dont-write-bytecode", no_class,
2076 &python_dont_write_bytecode, _("\
2077 Set whether the Python interpreter should ignore environment variables."), _(" \
2078 Show whether the Python interpreter showlist ignore environment variables."), _(" \
2079 When enabled GDB's Python interpreter will ignore any Python related\n \
2080 flags in the environment. This is equivalent to passing `-E' to a\n \
2081 python executable."),
2082 set_python_dont_write_bytecode,
2083 show_python_dont_write_bytecode,
2084 &user_set_python_list,
2085 &user_show_python_list);
2089 selftests::register_test ("python", selftests::test_python);
2090 #endif /* GDB_SELF_TEST */
2091 #endif /* HAVE_PYTHON */
2096 /* Helper function for gdbpy_initialize. This does the work and then
2097 returns false if an error has occurred and must be displayed, or true on
2101 do_initialize (const struct extension_language_defn *extlang)
2106 /* Add the initial data-directory to sys.path. */
2108 std::string gdb_pythondir = (std::string (gdb_datadir) + SLASH_STRING
2111 sys_path = PySys_GetObject ("path");
2113 /* If sys.path is not defined yet, define it first. */
2114 if (!(sys_path && PyList_Check (sys_path)))
2117 PySys_SetPath (L"");
2121 sys_path = PySys_GetObject ("path");
2123 if (sys_path && PyList_Check (sys_path))
2125 gdbpy_ref<> pythondir (PyString_FromString (gdb_pythondir.c_str ()));
2126 if (pythondir == NULL || PyList_Insert (sys_path, 0, pythondir.get ()))
2132 /* Import the gdb module to finish the initialization, and
2133 add it to __main__ for convenience. */
2134 m = PyImport_AddModule ("__main__");
2138 /* Keep the reference to gdb_python_module since it is in a global
2140 gdb_python_module = PyImport_ImportModule ("gdb");
2141 if (gdb_python_module == NULL)
2143 gdbpy_print_stack ();
2144 /* This is passed in one call to warning so that blank lines aren't
2145 inserted between each line of text. */
2147 "Could not load the Python gdb module from `%s'.\n"
2148 "Limited Python support is available from the _gdb module.\n"
2149 "Suggest passing --data-directory=/path/to/gdb/data-directory."),
2150 gdb_pythondir.c_str ());
2151 /* We return "success" here as we've already emitted the
2156 return gdb_pymodule_addobject (m, "gdb", gdb_python_module) >= 0;
2159 /* Perform Python initialization. This will be called after GDB has
2160 performed all of its own initialization. This is the
2161 extension_language_ops.initialize "method". */
2164 gdbpy_initialize (const struct extension_language_defn *extlang)
2166 if (!do_start_initialization () && PyErr_Occurred ())
2167 gdbpy_print_stack ();
2169 gdbpy_enter enter_py (get_current_arch (), current_language);
2171 if (!do_initialize (extlang))
2173 gdbpy_print_stack ();
2174 warning (_("internal error: Unhandled Python exception"));
2178 /* Return non-zero if Python has successfully initialized.
2179 This is the extension_languages_ops.initialized "method". */
2182 gdbpy_initialized (const struct extension_language_defn *extlang)
2184 return gdb_python_initialized;
2187 PyMethodDef python_GdbMethods[] =
2189 { "history", gdbpy_history, METH_VARARGS,
2190 "Get a value from history" },
2191 { "add_history", gdbpy_add_history, METH_VARARGS,
2192 "Add a value to the value history list" },
2193 { "execute", (PyCFunction) execute_gdb_command, METH_VARARGS | METH_KEYWORDS,
2194 "execute (command [, from_tty] [, to_string]) -> [String]\n\
2195 Evaluate command, a string, as a gdb CLI command. Optionally returns\n\
2196 a Python String containing the output of the command if to_string is\n\
2198 { "parameter", gdbpy_parameter, METH_VARARGS,
2199 "Return a gdb parameter's value" },
2201 { "breakpoints", gdbpy_breakpoints, METH_NOARGS,
2202 "Return a tuple of all breakpoint objects" },
2204 { "default_visualizer", gdbpy_default_visualizer, METH_VARARGS,
2205 "Find the default visualizer for a Value." },
2207 { "progspaces", gdbpy_progspaces, METH_NOARGS,
2208 "Return a sequence of all progspaces." },
2210 { "current_objfile", gdbpy_get_current_objfile, METH_NOARGS,
2211 "Return the current Objfile being loaded, or None." },
2213 { "newest_frame", gdbpy_newest_frame, METH_NOARGS,
2214 "newest_frame () -> gdb.Frame.\n\
2215 Return the newest frame object." },
2216 { "selected_frame", gdbpy_selected_frame, METH_NOARGS,
2217 "selected_frame () -> gdb.Frame.\n\
2218 Return the selected frame object." },
2219 { "frame_stop_reason_string", gdbpy_frame_stop_reason_string, METH_VARARGS,
2220 "stop_reason_string (Integer) -> String.\n\
2221 Return a string explaining unwind stop reason." },
2223 { "start_recording", gdbpy_start_recording, METH_VARARGS,
2224 "start_recording ([method] [, format]) -> gdb.Record.\n\
2225 Start recording with the given method. If no method is given, will fall back\n\
2226 to the system default method. If no format is given, will fall back to the\n\
2227 default format for the given method."},
2228 { "current_recording", gdbpy_current_recording, METH_NOARGS,
2229 "current_recording () -> gdb.Record.\n\
2230 Return current recording object." },
2231 { "stop_recording", gdbpy_stop_recording, METH_NOARGS,
2232 "stop_recording () -> None.\n\
2233 Stop current recording." },
2235 { "lookup_type", (PyCFunction) gdbpy_lookup_type,
2236 METH_VARARGS | METH_KEYWORDS,
2237 "lookup_type (name [, block]) -> type\n\
2238 Return a Type corresponding to the given name." },
2239 { "lookup_symbol", (PyCFunction) gdbpy_lookup_symbol,
2240 METH_VARARGS | METH_KEYWORDS,
2241 "lookup_symbol (name [, block] [, domain]) -> (symbol, is_field_of_this)\n\
2242 Return a tuple with the symbol corresponding to the given name (or None) and\n\
2243 a boolean indicating if name is a field of the current implied argument\n\
2244 `this' (when the current language is object-oriented)." },
2245 { "lookup_global_symbol", (PyCFunction) gdbpy_lookup_global_symbol,
2246 METH_VARARGS | METH_KEYWORDS,
2247 "lookup_global_symbol (name [, domain]) -> symbol\n\
2248 Return the symbol corresponding to the given name (or None)." },
2249 { "lookup_static_symbol", (PyCFunction) gdbpy_lookup_static_symbol,
2250 METH_VARARGS | METH_KEYWORDS,
2251 "lookup_static_symbol (name [, domain]) -> symbol\n\
2252 Return the static-linkage symbol corresponding to the given name (or None)." },
2253 { "lookup_static_symbols", (PyCFunction) gdbpy_lookup_static_symbols,
2254 METH_VARARGS | METH_KEYWORDS,
2255 "lookup_static_symbols (name [, domain]) -> symbol\n\
2256 Return a list of all static-linkage symbols corresponding to the given name." },
2258 { "lookup_objfile", (PyCFunction) gdbpy_lookup_objfile,
2259 METH_VARARGS | METH_KEYWORDS,
2260 "lookup_objfile (name, [by_build_id]) -> objfile\n\
2261 Look up the specified objfile.\n\
2262 If by_build_id is True, the objfile is looked up by using name\n\
2263 as its build id." },
2265 { "decode_line", gdbpy_decode_line, METH_VARARGS,
2266 "decode_line (String) -> Tuple. Decode a string argument the way\n\
2267 that 'break' or 'edit' does. Return a tuple containing two elements.\n\
2268 The first element contains any unparsed portion of the String parameter\n\
2269 (or None if the string was fully parsed). The second element contains\n\
2270 a tuple that contains all the locations that match, represented as\n\
2271 gdb.Symtab_and_line objects (or None)."},
2272 { "parse_and_eval", gdbpy_parse_and_eval, METH_VARARGS,
2273 "parse_and_eval (String) -> Value.\n\
2274 Parse String as an expression, evaluate it, and return the result as a Value."
2277 { "post_event", gdbpy_post_event, METH_VARARGS,
2278 "Post an event into gdb's event loop." },
2280 { "target_charset", gdbpy_target_charset, METH_NOARGS,
2281 "target_charset () -> string.\n\
2282 Return the name of the current target charset." },
2283 { "target_wide_charset", gdbpy_target_wide_charset, METH_NOARGS,
2284 "target_wide_charset () -> string.\n\
2285 Return the name of the current target wide charset." },
2286 { "rbreak", (PyCFunction) gdbpy_rbreak, METH_VARARGS | METH_KEYWORDS,
2287 "rbreak (Regex) -> List.\n\
2288 Return a Tuple containing gdb.Breakpoint objects that match the given Regex." },
2289 { "string_to_argv", gdbpy_string_to_argv, METH_VARARGS,
2290 "string_to_argv (String) -> Array.\n\
2291 Parse String and return an argv-like array.\n\
2292 Arguments are separate by spaces and may be quoted."
2294 { "write", (PyCFunction)gdbpy_write, METH_VARARGS | METH_KEYWORDS,
2295 "Write a string using gdb's filtered stream." },
2296 { "flush", (PyCFunction)gdbpy_flush, METH_VARARGS | METH_KEYWORDS,
2297 "Flush gdb's filtered stdout stream." },
2298 { "selected_thread", gdbpy_selected_thread, METH_NOARGS,
2299 "selected_thread () -> gdb.InferiorThread.\n\
2300 Return the selected thread object." },
2301 { "selected_inferior", gdbpy_selected_inferior, METH_NOARGS,
2302 "selected_inferior () -> gdb.Inferior.\n\
2303 Return the selected inferior object." },
2304 { "inferiors", gdbpy_inferiors, METH_NOARGS,
2305 "inferiors () -> (gdb.Inferior, ...).\n\
2306 Return a tuple containing all inferiors." },
2308 { "invalidate_cached_frames", gdbpy_invalidate_cached_frames, METH_NOARGS,
2309 "invalidate_cached_frames () -> None.\n\
2310 Invalidate any cached frame objects in gdb.\n\
2311 Intended for internal use only." },
2313 { "convenience_variable", gdbpy_convenience_variable, METH_VARARGS,
2314 "convenience_variable (NAME) -> value.\n\
2315 Return the value of the convenience variable $NAME,\n\
2316 or None if not set." },
2317 { "set_convenience_variable", gdbpy_set_convenience_variable, METH_VARARGS,
2318 "convenience_variable (NAME, VALUE) -> None.\n\
2319 Set the value of the convenience variable $NAME." },
2322 { "register_window_type", (PyCFunction) gdbpy_register_tui_window,
2323 METH_VARARGS | METH_KEYWORDS,
2324 "register_window_type (NAME, CONSTRUCSTOR) -> None\n\
2325 Register a TUI window constructor." },
2328 { "architecture_names", gdbpy_all_architecture_names, METH_NOARGS,
2329 "architecture_names () -> List.\n\
2330 Return a list of all the architecture names GDB understands." },
2332 {NULL, NULL, 0, NULL}
2335 /* Define all the event objects. */
2336 #define GDB_PY_DEFINE_EVENT_TYPE(name, py_name, doc, base) \
2337 PyTypeObject name##_event_object_type \
2338 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("event_object") \
2340 PyVarObject_HEAD_INIT (NULL, 0) \
2341 "gdb." py_name, /* tp_name */ \
2342 sizeof (event_object), /* tp_basicsize */ \
2343 0, /* tp_itemsize */ \
2344 evpy_dealloc, /* tp_dealloc */ \
2346 0, /* tp_getattr */ \
2347 0, /* tp_setattr */ \
2348 0, /* tp_compare */ \
2350 0, /* tp_as_number */ \
2351 0, /* tp_as_sequence */ \
2352 0, /* tp_as_mapping */ \
2356 0, /* tp_getattro */ \
2357 0, /* tp_setattro */ \
2358 0, /* tp_as_buffer */ \
2359 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ \
2361 0, /* tp_traverse */ \
2363 0, /* tp_richcompare */ \
2364 0, /* tp_weaklistoffset */ \
2366 0, /* tp_iternext */ \
2367 0, /* tp_methods */ \
2368 0, /* tp_members */ \
2369 0, /* tp_getset */ \
2370 &base, /* tp_base */ \
2372 0, /* tp_descr_get */ \
2373 0, /* tp_descr_set */ \
2374 0, /* tp_dictoffset */ \
2378 #include "py-event-types.def"
2379 #undef GDB_PY_DEFINE_EVENT_TYPE
2381 #endif /* HAVE_PYTHON */