gdb/python/lib/gdb/__init__.py

   1 # Copyright (C) 2010-2022 Free Software Foundation, Inc.
   2
   3 # This program is free software; you can redistribute it and/or modify
   4 # it under the terms of the GNU General Public License as published by
   5 # the Free Software Foundation; either version 3 of the License, or
   6 # (at your option) any later version.
   7 #
   8 # This program is distributed in the hope that it will be useful,
   9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 # GNU General Public License for more details.
  12 #
  13 # You should have received a copy of the GNU General Public License
  14 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  15
  16 import traceback
  17 import os
  18 import sys
  19 import _gdb
  20 from contextlib import contextmanager
  21
  22 # Python 3 moved "reload"
  23 if sys.version_info >= (3, 4):
  24     from importlib import reload
  25 else:
  26     from imp import reload
  27
  28 from _gdb import *
  29
  30 # Historically, gdb.events was always available, so ensure it's
  31 # still available without an explicit import.
  32 import _gdbevents as events
  33
  34 sys.modules["gdb.events"] = events
  35
  36
  37 class _GdbFile(object):
  38     # These two are needed in Python 3
  39     encoding = "UTF-8"
  40     errors = "strict"
  41
  42     def close(self):
  43         # Do nothing.
  44         return None
  45
  46     def isatty(self):
  47         return False
  48
  49     def writelines(self, iterable):
  50         for line in iterable:
  51             self.write(line)
  52
  53     def flush(self):
  54         flush()
  55
  56
  57 class _GdbOutputFile(_GdbFile):
  58     def write(self, s):
  59         write(s, stream=STDOUT)
  60
  61
  62 sys.stdout = _GdbOutputFile()
  63
  64
  65 class _GdbOutputErrorFile(_GdbFile):
  66     def write(self, s):
  67         write(s, stream=STDERR)
  68
  69
  70 sys.stderr = _GdbOutputErrorFile()
  71
  72 # Default prompt hook does nothing.
  73 prompt_hook = None
  74
  75 # Ensure that sys.argv is set to something.
  76 # We do not use PySys_SetArgvEx because it did not appear until 2.6.6.
  77 sys.argv = [""]
  78
  79 # Initial pretty printers.
  80 pretty_printers = []
  81
  82 # Initial type printers.
  83 type_printers = []
  84 # Initial xmethod matchers.
  85 xmethods = []
  86 # Initial frame filters.
  87 frame_filters = {}
  88 # Initial frame unwinders.
  89 frame_unwinders = []
  90
  91
  92 def _execute_unwinders(pending_frame):
  93     """Internal function called from GDB to execute all unwinders.
  94
  95     Runs each currently enabled unwinder until it finds the one that
  96     can unwind given frame.
  97
  98     Arguments:
  99         pending_frame: gdb.PendingFrame instance.
 100
 101     Returns:
 102         Tuple with:
 103
 104           [0] gdb.UnwindInfo instance
 105           [1] Name of unwinder that claimed the frame (type `str`)
 106
 107         or None, if no unwinder has claimed the frame.
 108     """
 109     for objfile in objfiles():
 110         for unwinder in objfile.frame_unwinders:
 111             if unwinder.enabled:
 112                 unwind_info = unwinder(pending_frame)
 113                 if unwind_info is not None:
 114                     return (unwind_info, unwinder.name)
 115
 116     for unwinder in current_progspace().frame_unwinders:
 117         if unwinder.enabled:
 118             unwind_info = unwinder(pending_frame)
 119             if unwind_info is not None:
 120                 return (unwind_info, unwinder.name)
 121
 122     for unwinder in frame_unwinders:
 123         if unwinder.enabled:
 124             unwind_info = unwinder(pending_frame)
 125             if unwind_info is not None:
 126                 return (unwind_info, unwinder.name)
 127
 128     return None
 129
 130
 131 def _execute_file(filepath):
 132     """This function is used to replace Python 2's PyRun_SimpleFile.
 133
 134     Loads and executes the given file.
 135
 136     We could use the runpy module, but its documentation says:
 137     "Furthermore, any functions and classes defined by the executed code are
 138     not guaranteed to work correctly after a runpy function has returned."
 139     """
 140     globals = sys.modules["__main__"].__dict__
 141     set_file = False
 142     # Set file (if not set) so that the imported file can use it (e.g. to
 143     # access file-relative paths). This matches what PyRun_SimpleFile does.
 144     if not hasattr(globals, "__file__"):
 145         globals["__file__"] = filepath
 146         set_file = True
 147     try:
 148         with open(filepath, "rb") as file:
 149             # We pass globals also as locals to match what Python does
 150             # in PyRun_SimpleFile.
 151             compiled = compile(file.read(), filepath, "exec")
 152             exec(compiled, globals, globals)
 153     finally:
 154         if set_file:
 155             del globals["__file__"]
 156
 157
 158 # Convenience variable to GDB's python directory
 159 PYTHONDIR = os.path.dirname(os.path.dirname(__file__))
 160
 161 # Auto-load all functions/commands.
 162
 163 # Packages to auto-load.
 164
 165 packages = ["function", "command", "printer"]
 166
 167 # pkgutil.iter_modules is not available prior to Python 2.6.  Instead,
 168 # manually iterate the list, collating the Python files in each module
 169 # path.  Construct the module name, and import.
 170
 171
 172 def _auto_load_packages():
 173     for package in packages:
 174         location = os.path.join(os.path.dirname(__file__), package)
 175         if os.path.exists(location):
 176             py_files = filter(
 177                 lambda x: x.endswith(".py") and x != "__init__.py", os.listdir(location)
 178             )
 179
 180             for py_file in py_files:
 181                 # Construct from foo.py, gdb.module.foo
 182                 modname = "%s.%s.%s" % (__name__, package, py_file[:-3])
 183                 try:
 184                     if modname in sys.modules:
 185                         # reload modules with duplicate names
 186                         reload(__import__(modname))
 187                     else:
 188                         __import__(modname)
 189                 except:
 190                     sys.stderr.write(traceback.format_exc() + "\n")
 191
 192
 193 _auto_load_packages()
 194
 195
 196 def GdbSetPythonDirectory(dir):
 197     """Update sys.path, reload gdb and auto-load packages."""
 198     global PYTHONDIR
 199
 200     try:
 201         sys.path.remove(PYTHONDIR)
 202     except ValueError:
 203         pass
 204     sys.path.insert(0, dir)
 205
 206     PYTHONDIR = dir
 207
 208     # note that reload overwrites the gdb module without deleting existing
 209     # attributes
 210     reload(__import__(__name__))
 211     _auto_load_packages()
 212
 213
 214 def current_progspace():
 215     "Return the current Progspace."
 216     return selected_inferior().progspace
 217
 218
 219 def objfiles():
 220     "Return a sequence of the current program space's objfiles."
 221     return current_progspace().objfiles()
 222
 223
 224 def solib_name(addr):
 225     """solib_name (Long) -> String.\n\
 226 Return the name of the shared library holding a given address, or None."""
 227     return current_progspace().solib_name(addr)
 228
 229
 230 def block_for_pc(pc):
 231     "Return the block containing the given pc value, or None."
 232     return current_progspace().block_for_pc(pc)
 233
 234
 235 def find_pc_line(pc):
 236     """find_pc_line (pc) -> Symtab_and_line.
 237     Return the gdb.Symtab_and_line object corresponding to the pc value."""
 238     return current_progspace().find_pc_line(pc)
 239
 240
 241 def set_parameter(name, value):
 242     """Set the GDB parameter NAME to VALUE."""
 243     # Handle the specific case of booleans here, because gdb.parameter
 244     # can return them, but they can't be passed to 'set' this way.
 245     if isinstance(value, bool):
 246         if value:
 247             value = "on"
 248         else:
 249             value = "off"
 250     execute("set " + name + " " + str(value), to_string=True)
 251
 252
 253 @contextmanager
 254 def with_parameter(name, value):
 255     """Temporarily set the GDB parameter NAME to VALUE.
 256     Note that this is a context manager."""
 257     old_value = parameter(name)
 258     set_parameter(name, value)
 259     try:
 260         # Nothing that useful to return.
 261         yield None
 262     finally:
 263         set_parameter(name, old_value)