1 @c Copyright (C) 2008--2021 Free Software Foundation, Inc.
2 @c Permission is granted to copy, distribute and/or modify this document
3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
4 @c any later version published by the Free Software Foundation; with the
5 @c Invariant Sections being ``Free Software'' and ``Free Software Needs
6 @c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
7 @c and with the Back-Cover Texts as in (a) below.
9 @c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
10 @c this GNU Manual. Buying copies from GNU Press supports the FSF in
11 @c developing GNU and promoting software freedom.''
14 @section Extending @value{GDBN} using Python
15 @cindex python scripting
16 @cindex scripting with python
18 You can extend @value{GDBN} using the @uref{http://www.python.org/,
19 Python programming language}. This feature is available only if
20 @value{GDBN} was configured using @option{--with-python}.
21 @value{GDBN} can be built against either Python 2 or Python 3; which
22 one you have depends on this configure-time option.
24 @cindex python directory
25 Python scripts used by @value{GDBN} should be installed in
26 @file{@var{data-directory}/python}, where @var{data-directory} is
27 the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
28 This directory, known as the @dfn{python directory},
29 is automatically added to the Python Search Path in order to allow
30 the Python interpreter to locate all scripts installed at this location.
32 Additionally, @value{GDBN} commands and convenience functions which
33 are written in Python and are located in the
34 @file{@var{data-directory}/python/gdb/command} or
35 @file{@var{data-directory}/python/gdb/function} directories are
36 automatically imported when @value{GDBN} starts.
39 * Python Commands:: Accessing Python from @value{GDBN}.
40 * Python API:: Accessing @value{GDBN} from Python.
41 * Python Auto-loading:: Automatically loading Python code.
42 * Python modules:: Python modules provided by @value{GDBN}.
46 @subsection Python Commands
47 @cindex python commands
48 @cindex commands to access python
50 @value{GDBN} provides two commands for accessing the Python interpreter,
51 and one related setting:
54 @kindex python-interactive
56 @item python-interactive @r{[}@var{command}@r{]}
57 @itemx pi @r{[}@var{command}@r{]}
58 Without an argument, the @code{python-interactive} command can be used
59 to start an interactive Python prompt. To return to @value{GDBN},
60 type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
62 Alternatively, a single-line Python command can be given as an
63 argument and evaluated. If the command is an expression, the result
64 will be printed; otherwise, nothing will be printed. For example:
67 (@value{GDBP}) python-interactive 2 + 3
73 @item python @r{[}@var{command}@r{]}
74 @itemx py @r{[}@var{command}@r{]}
75 The @code{python} command can be used to evaluate Python code.
77 If given an argument, the @code{python} command will evaluate the
78 argument as a Python command. For example:
81 (@value{GDBP}) python print 23
85 If you do not provide an argument to @code{python}, it will act as a
86 multi-line command, like @code{define}. In this case, the Python
87 script is made up of subsequent command lines, given after the
88 @code{python} command. This command list is terminated using a line
89 containing @code{end}. For example:
98 @kindex set python print-stack
99 @item set python print-stack
100 By default, @value{GDBN} will print only the message component of a
101 Python exception when an error occurs in a Python script. This can be
102 controlled using @code{set python print-stack}: if @code{full}, then
103 full Python stack printing is enabled; if @code{none}, then Python stack
104 and message printing is disabled; if @code{message}, the default, only
105 the message component of the error is printed.
107 @kindex set python ignore-environment
108 @item set python ignore-environment @r{[}on@r{|}off@r{]}
109 By default this option is @samp{off}, and, when @value{GDBN}
110 initializes its internal Python interpreter, the Python interpreter
111 will check the environment for variables that will effect how it
112 behaves, for example @env{PYTHONHOME}, and
113 @env{PYTHONPATH}@footnote{See the ENVIRONMENT VARIABLES section of
114 @command{man 1 python} for a comprehensive list.}.
116 If this option is set to @samp{on} before Python is initialized then
117 Python will ignore all such environment variables. As Python is
118 initialized early during @value{GDBN}'s startup process, then this
119 option must be placed into the early initialization file
120 (@pxref{Initialization Files}) to have the desired effect.
122 This option is equivalent to passing @option{-E} to the real
123 @command{python} executable.
125 @kindex set python dont-write-bytecode
126 @item set python dont-write-bytecode @r{[}auto@r{|}on@r{|}off@r{]}
127 When this option is @samp{off}, then, once @value{GDBN} has
128 initialized the Python interpreter, the interpreter will byte-compile
129 any Python modules that it imports and write the byte code to disk in
132 If this option is set to @samp{on} before Python is initialized then
133 Python will no longer write the byte code to disk. As Python is
134 initialized early during @value{GDBN}'s startup process, then this
135 option must be placed into the early initialization file
136 (@pxref{Initialization Files}) to have the desired effect.
138 By default this option is set to @samp{auto}, in this mode Python will
139 check the environment variable @env{PYTHONDONTWRITEBYTECODE} to see
140 if it should write out byte-code or not.
142 This option is equivalent to passing @option{-B} to the real
143 @command{python} executable.
146 It is also possible to execute a Python script from the @value{GDBN}
150 @item source @file{script-name}
151 The script name must end with @samp{.py} and @value{GDBN} must be configured
152 to recognize the script language based on filename extension using
153 the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
156 The following commands are intended to help debug @value{GDBN} itself:
159 @kindex set debug py-breakpoint
160 @kindex show debug py-breakpoint
161 @item set debug py-breakpoint on@r{|}off
162 @itemx show debug py-breakpoint
163 When @samp{on}, @value{GDBN} prints debug messages related to the
164 Python breakpoint API. This is @samp{off} by default.
166 @kindex set debug py-unwind
167 @kindex show debug py-unwind
168 @item set debug py-unwind on@r{|}off
169 @itemx show debug py-unwind
170 When @samp{on}, @value{GDBN} prints debug messages related to the
171 Python unwinder API. This is @samp{off} by default.
175 @subsection Python API
177 @cindex programming in python
179 You can get quick online help for @value{GDBN}'s Python API by issuing
180 the command @w{@kbd{python help (gdb)}}.
182 Functions and methods which have two or more optional arguments allow
183 them to be specified using keyword syntax. This allows passing some
184 optional arguments while skipping others. Example:
185 @w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
188 * Basic Python:: Basic Python Functions.
189 * Exception Handling:: How Python exceptions are translated.
190 * Values From Inferior:: Python representation of values.
191 * Types In Python:: Python representation of types.
192 * Pretty Printing API:: Pretty-printing values.
193 * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
194 * Writing a Pretty-Printer:: Writing a Pretty-Printer.
195 * Type Printing API:: Pretty-printing types.
196 * Frame Filter API:: Filtering Frames.
197 * Frame Decorator API:: Decorating Frames.
198 * Writing a Frame Filter:: Writing a Frame Filter.
199 * Unwinding Frames in Python:: Writing frame unwinder.
200 * Xmethods In Python:: Adding and replacing methods of C++ classes.
201 * Xmethod API:: Xmethod types.
202 * Writing an Xmethod:: Writing an xmethod.
203 * Inferiors In Python:: Python representation of inferiors (processes)
204 * Events In Python:: Listening for events from @value{GDBN}.
205 * Threads In Python:: Accessing inferior threads from Python.
206 * Recordings In Python:: Accessing recordings from Python.
207 * Commands In Python:: Implementing new commands in Python.
208 * Parameters In Python:: Adding new @value{GDBN} parameters.
209 * Functions In Python:: Writing new convenience functions.
210 * Progspaces In Python:: Program spaces.
211 * Objfiles In Python:: Object files.
212 * Frames In Python:: Accessing inferior stack frames from Python.
213 * Blocks In Python:: Accessing blocks from Python.
214 * Symbols In Python:: Python representation of symbols.
215 * Symbol Tables In Python:: Python representation of symbol tables.
216 * Line Tables In Python:: Python representation of line tables.
217 * Breakpoints In Python:: Manipulating breakpoints using Python.
218 * Finish Breakpoints in Python:: Setting Breakpoints on function return
220 * Lazy Strings In Python:: Python representation of lazy strings.
221 * Architectures In Python:: Python representation of architectures.
222 * Registers In Python:: Python representation of registers.
223 * TUI Windows In Python:: Implementing new TUI windows.
227 @subsubsection Basic Python
229 @cindex python stdout
230 @cindex python pagination
231 At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
232 @code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
233 A Python program which outputs to one of these streams may have its
234 output interrupted by the user (@pxref{Screen Size}). In this
235 situation, a Python @code{KeyboardInterrupt} exception is thrown.
237 Some care must be taken when writing Python code to run in
238 @value{GDBN}. Two things worth noting in particular:
242 @value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
243 Python code must not override these, or even change the options using
244 @code{sigaction}. If your program changes the handling of these
245 signals, @value{GDBN} will most likely stop working correctly. Note
246 that it is unfortunately common for GUI toolkits to install a
247 @code{SIGCHLD} handler.
250 @value{GDBN} takes care to mark its internal file descriptors as
251 close-on-exec. However, this cannot be done in a thread-safe way on
252 all platforms. Your Python programs should be aware of this and
253 should both create new file descriptors with the close-on-exec flag
254 set and arrange to close unneeded file descriptors before starting a
258 @cindex python functions
259 @cindex python module
261 @value{GDBN} introduces a new Python module, named @code{gdb}. All
262 methods and classes added by @value{GDBN} are placed in this module.
263 @value{GDBN} automatically @code{import}s the @code{gdb} module for
264 use in all scripts evaluated by the @code{python} command.
266 Some types of the @code{gdb} module come with a textual representation
267 (accessible through the @code{repr} or @code{str} functions). These are
268 offered for debugging purposes only, expect them to change over time.
270 @findex gdb.PYTHONDIR
271 @defvar gdb.PYTHONDIR
272 A string containing the python directory (@pxref{Python}).
276 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
277 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
278 If a GDB exception happens while @var{command} runs, it is
279 translated as described in @ref{Exception Handling,,Exception Handling}.
281 The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
282 command as having originated from the user invoking it interactively.
283 It must be a boolean value. If omitted, it defaults to @code{False}.
285 By default, any output produced by @var{command} is sent to
286 @value{GDBN}'s standard output (and to the log output if logging is
287 turned on). If the @var{to_string} parameter is
288 @code{True}, then output will be collected by @code{gdb.execute} and
289 returned as a string. The default is @code{False}, in which case the
290 return value is @code{None}. If @var{to_string} is @code{True}, the
291 @value{GDBN} virtual terminal will be temporarily set to unlimited width
292 and height, and its pagination will be disabled; @pxref{Screen Size}.
295 @findex gdb.breakpoints
296 @defun gdb.breakpoints ()
297 Return a sequence holding all of @value{GDBN}'s breakpoints.
298 @xref{Breakpoints In Python}, for more information. In @value{GDBN}
299 version 7.11 and earlier, this function returned @code{None} if there
300 were no breakpoints. This peculiarity was subsequently fixed, and now
301 @code{gdb.breakpoints} returns an empty sequence in this case.
304 @defun gdb.rbreak (regex @r{[}, minsyms @r{[}, throttle, @r{[}, symtabs @r{]]]})
305 Return a Python list holding a collection of newly set
306 @code{gdb.Breakpoint} objects matching function names defined by the
307 @var{regex} pattern. If the @var{minsyms} keyword is @code{True}, all
308 system functions (those not explicitly defined in the inferior) will
309 also be included in the match. The @var{throttle} keyword takes an
310 integer that defines the maximum number of pattern matches for
311 functions matched by the @var{regex} pattern. If the number of
312 matches exceeds the integer value of @var{throttle}, a
313 @code{RuntimeError} will be raised and no breakpoints will be created.
314 If @var{throttle} is not defined then there is no imposed limit on the
315 maximum number of matches and breakpoints to be created. The
316 @var{symtabs} keyword takes a Python iterable that yields a collection
317 of @code{gdb.Symtab} objects and will restrict the search to those
318 functions only contained within the @code{gdb.Symtab} objects.
321 @findex gdb.parameter
322 @defun gdb.parameter (parameter)
323 Return the value of a @value{GDBN} @var{parameter} given by its name,
324 a string; the parameter name string may contain spaces if the parameter has a
325 multi-part name. For example, @samp{print object} is a valid
328 If the named parameter does not exist, this function throws a
329 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
330 parameter's value is converted to a Python value of the appropriate
335 @defun gdb.history (number)
336 Return a value from @value{GDBN}'s value history (@pxref{Value
337 History}). The @var{number} argument indicates which history element to return.
338 If @var{number} is negative, then @value{GDBN} will take its absolute value
339 and count backward from the last element (i.e., the most recent element) to
340 find the value to return. If @var{number} is zero, then @value{GDBN} will
341 return the most recent element. If the element specified by @var{number}
342 doesn't exist in the value history, a @code{gdb.error} exception will be
345 If no exception is raised, the return value is always an instance of
346 @code{gdb.Value} (@pxref{Values From Inferior}).
349 @findex gdb.convenience_variable
350 @defun gdb.convenience_variable (name)
351 Return the value of the convenience variable (@pxref{Convenience
352 Vars}) named @var{name}. @var{name} must be a string. The name
353 should not include the @samp{$} that is used to mark a convenience
354 variable in an expression. If the convenience variable does not
355 exist, then @code{None} is returned.
358 @findex gdb.set_convenience_variable
359 @defun gdb.set_convenience_variable (name, value)
360 Set the value of the convenience variable (@pxref{Convenience Vars})
361 named @var{name}. @var{name} must be a string. The name should not
362 include the @samp{$} that is used to mark a convenience variable in an
363 expression. If @var{value} is @code{None}, then the convenience
364 variable is removed. Otherwise, if @var{value} is not a
365 @code{gdb.Value} (@pxref{Values From Inferior}), it is is converted
366 using the @code{gdb.Value} constructor.
369 @findex gdb.parse_and_eval
370 @defun gdb.parse_and_eval (expression)
371 Parse @var{expression}, which must be a string, as an expression in
372 the current language, evaluate it, and return the result as a
375 This function can be useful when implementing a new command
376 (@pxref{Commands In Python}), as it provides a way to parse the
377 command's argument as an expression. It is also useful simply to
381 @findex gdb.find_pc_line
382 @defun gdb.find_pc_line (pc)
383 Return the @code{gdb.Symtab_and_line} object corresponding to the
384 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
385 value of @var{pc} is passed as an argument, then the @code{symtab} and
386 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
387 will be @code{None} and 0 respectively. This is identical to
388 @code{gdb.current_progspace().find_pc_line(pc)} and is included for
389 historical compatibility.
392 @findex gdb.post_event
393 @defun gdb.post_event (event)
394 Put @var{event}, a callable object taking no arguments, into
395 @value{GDBN}'s internal event queue. This callable will be invoked at
396 some later point, during @value{GDBN}'s event processing. Events
397 posted using @code{post_event} will be run in the order in which they
398 were posted; however, there is no way to know when they will be
399 processed relative to other events inside @value{GDBN}.
401 @value{GDBN} is not thread-safe. If your Python program uses multiple
402 threads, you must be careful to only call @value{GDBN}-specific
403 functions in the @value{GDBN} thread. @code{post_event} ensures
407 (@value{GDBP}) python
411 > def __init__(self, message):
412 > self.message = message;
413 > def __call__(self):
414 > gdb.write(self.message)
416 >class MyThread1 (threading.Thread):
418 > gdb.post_event(Writer("Hello "))
420 >class MyThread2 (threading.Thread):
422 > gdb.post_event(Writer("World\n"))
427 (@value{GDBP}) Hello World
432 @defun gdb.write (string @r{[}, stream{]})
433 Print a string to @value{GDBN}'s paginated output stream. The
434 optional @var{stream} determines the stream to print to. The default
435 stream is @value{GDBN}'s standard output stream. Possible stream
442 @value{GDBN}'s standard output stream.
447 @value{GDBN}'s standard error stream.
452 @value{GDBN}'s log stream (@pxref{Logging Output}).
455 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
456 call this function and will automatically direct the output to the
462 Flush the buffer of a @value{GDBN} paginated stream so that the
463 contents are displayed immediately. @value{GDBN} will flush the
464 contents of a stream automatically when it encounters a newline in the
465 buffer. The optional @var{stream} determines the stream to flush. The
466 default stream is @value{GDBN}'s standard output stream. Possible
473 @value{GDBN}'s standard output stream.
478 @value{GDBN}'s standard error stream.
483 @value{GDBN}'s log stream (@pxref{Logging Output}).
487 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
488 call this function for the relevant stream.
491 @findex gdb.target_charset
492 @defun gdb.target_charset ()
493 Return the name of the current target character set (@pxref{Character
494 Sets}). This differs from @code{gdb.parameter('target-charset')} in
495 that @samp{auto} is never returned.
498 @findex gdb.target_wide_charset
499 @defun gdb.target_wide_charset ()
500 Return the name of the current target wide character set
501 (@pxref{Character Sets}). This differs from
502 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
506 @findex gdb.solib_name
507 @defun gdb.solib_name (address)
508 Return the name of the shared library holding the given @var{address}
509 as a string, or @code{None}. This is identical to
510 @code{gdb.current_progspace().solib_name(address)} and is included for
511 historical compatibility.
514 @findex gdb.decode_line
515 @defun gdb.decode_line (@r{[}expression@r{]})
516 Return locations of the line specified by @var{expression}, or of the
517 current line if no argument was given. This function returns a Python
518 tuple containing two elements. The first element contains a string
519 holding any unparsed section of @var{expression} (or @code{None} if
520 the expression has been fully parsed). The second element contains
521 either @code{None} or another tuple that contains all the locations
522 that match the expression represented as @code{gdb.Symtab_and_line}
523 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
524 provided, it is decoded the way that @value{GDBN}'s inbuilt
525 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
528 @defun gdb.prompt_hook (current_prompt)
531 If @var{prompt_hook} is callable, @value{GDBN} will call the method
532 assigned to this operation before a prompt is displayed by
535 The parameter @code{current_prompt} contains the current @value{GDBN}
536 prompt. This method must return a Python string, or @code{None}. If
537 a string is returned, the @value{GDBN} prompt will be set to that
538 string. If @code{None} is returned, @value{GDBN} will continue to use
541 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
542 such as those used by readline for command input, and annotation
543 related prompts are prohibited from being changed.
546 @node Exception Handling
547 @subsubsection Exception Handling
548 @cindex python exceptions
549 @cindex exceptions, python
551 When executing the @code{python} command, Python exceptions
552 uncaught within the Python code are translated to calls to
553 @value{GDBN} error-reporting mechanism. If the command that called
554 @code{python} does not handle the error, @value{GDBN} will
555 terminate it and print an error message containing the Python
556 exception name, the associated value, and the Python call stack
557 backtrace at the point where the exception was raised. Example:
560 (@value{GDBP}) python print foo
561 Traceback (most recent call last):
562 File "<string>", line 1, in <module>
563 NameError: name 'foo' is not defined
566 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
567 Python code are converted to Python exceptions. The type of the
568 Python exception depends on the error.
572 This is the base class for most exceptions generated by @value{GDBN}.
573 It is derived from @code{RuntimeError}, for compatibility with earlier
574 versions of @value{GDBN}.
576 If an error occurring in @value{GDBN} does not fit into some more
577 specific category, then the generated exception will have this type.
579 @item gdb.MemoryError
580 This is a subclass of @code{gdb.error} which is thrown when an
581 operation tried to access invalid memory in the inferior.
583 @item KeyboardInterrupt
584 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
585 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
588 In all cases, your exception handler will see the @value{GDBN} error
589 message as its value and the Python call stack backtrace at the Python
590 statement closest to where the @value{GDBN} error occured as the
594 When implementing @value{GDBN} commands in Python via
595 @code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
596 to be able to throw an exception that doesn't cause a traceback to be
597 printed. For example, the user may have invoked the command
598 incorrectly. @value{GDBN} provides a special exception class that can
599 be used for this purpose.
603 When thrown from a command or function, this exception will cause the
604 command or function to fail, but the Python stack will not be
605 displayed. @value{GDBN} does not throw this exception itself, but
606 rather recognizes it when thrown from user Python code. Example:
610 >class HelloWorld (gdb.Command):
611 > """Greet the whole world."""
612 > def __init__ (self):
613 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
614 > def invoke (self, args, from_tty):
615 > argv = gdb.string_to_argv (args)
616 > if len (argv) != 0:
617 > raise gdb.GdbError ("hello-world takes no arguments")
618 > print ("Hello, World!")
622 hello-world takes no arguments
626 @node Values From Inferior
627 @subsubsection Values From Inferior
628 @cindex values from inferior, with Python
629 @cindex python, working with values from inferior
631 @cindex @code{gdb.Value}
632 @value{GDBN} provides values it obtains from the inferior program in
633 an object of type @code{gdb.Value}. @value{GDBN} uses this object
634 for its internal bookkeeping of the inferior's values, and for
635 fetching values when necessary.
637 Inferior values that are simple scalars can be used directly in
638 Python expressions that are valid for the value's data type. Here's
639 an example for an integer or floating-point value @code{some_val}:
646 As result of this, @code{bar} will also be a @code{gdb.Value} object
647 whose values are of the same type as those of @code{some_val}. Valid
648 Python operations can also be performed on @code{gdb.Value} objects
649 representing a @code{struct} or @code{class} object. For such cases,
650 the overloaded operator (if present), is used to perform the operation.
651 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
652 representing instances of a @code{class} which overloads the @code{+}
653 operator, then one can use the @code{+} operator in their Python script
661 The result of the operation @code{val3} is also a @code{gdb.Value}
662 object corresponding to the value returned by the overloaded @code{+}
663 operator. In general, overloaded operators are invoked for the
664 following operations: @code{+} (binary addition), @code{-} (binary
665 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
666 @code{>>}, @code{|}, @code{&}, @code{^}.
668 Inferior values that are structures or instances of some class can
669 be accessed using the Python @dfn{dictionary syntax}. For example, if
670 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
671 can access its @code{foo} element with:
674 bar = some_val['foo']
677 @cindex getting structure elements using gdb.Field objects as subscripts
678 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
679 elements can also be accessed by using @code{gdb.Field} objects as
680 subscripts (@pxref{Types In Python}, for more information on
681 @code{gdb.Field} objects). For example, if @code{foo_field} is a
682 @code{gdb.Field} object corresponding to element @code{foo} of the above
683 structure, then @code{bar} can also be accessed as follows:
686 bar = some_val[foo_field]
689 A @code{gdb.Value} that represents a function can be executed via
690 inferior function call. Any arguments provided to the call must match
691 the function's prototype, and must be provided in the order specified
694 For example, @code{some_val} is a @code{gdb.Value} instance
695 representing a function that takes two integers as arguments. To
696 execute this function, call it like so:
699 result = some_val (10,20)
702 Any values returned from a function call will be stored as a
705 The following attributes are provided:
707 @defvar Value.address
708 If this object is addressable, this read-only attribute holds a
709 @code{gdb.Value} object representing the address. Otherwise,
710 this attribute holds @code{None}.
713 @cindex optimized out value in Python
714 @defvar Value.is_optimized_out
715 This read-only boolean attribute is true if the compiler optimized out
716 this value, thus it is not available for fetching from the inferior.
720 The type of this @code{gdb.Value}. The value of this attribute is a
721 @code{gdb.Type} object (@pxref{Types In Python}).
724 @defvar Value.dynamic_type
725 The dynamic type of this @code{gdb.Value}. This uses the object's
726 virtual table and the C@t{++} run-time type information
727 (@acronym{RTTI}) to determine the dynamic type of the value. If this
728 value is of class type, it will return the class in which the value is
729 embedded, if any. If this value is of pointer or reference to a class
730 type, it will compute the dynamic type of the referenced object, and
731 return a pointer or reference to that type, respectively. In all
732 other cases, it will return the value's static type.
734 Note that this feature will only work when debugging a C@t{++} program
735 that includes @acronym{RTTI} for the object in question. Otherwise,
736 it will just return the static type of the value as in @kbd{ptype foo}
737 (@pxref{Symbols, ptype}).
740 @defvar Value.is_lazy
741 The value of this read-only boolean attribute is @code{True} if this
742 @code{gdb.Value} has not yet been fetched from the inferior.
743 @value{GDBN} does not fetch values until necessary, for efficiency.
747 myval = gdb.parse_and_eval ('somevar')
750 The value of @code{somevar} is not fetched at this time. It will be
751 fetched when the value is needed, or when the @code{fetch_lazy}
755 The following methods are provided:
757 @defun Value.__init__ (@var{val})
758 Many Python values can be converted directly to a @code{gdb.Value} via
759 this object initializer. Specifically:
763 A Python boolean is converted to the boolean type from the current
767 A Python integer is converted to the C @code{long} type for the
768 current architecture.
771 A Python long is converted to the C @code{long long} type for the
772 current architecture.
775 A Python float is converted to the C @code{double} type for the
776 current architecture.
779 A Python string is converted to a target string in the current target
780 language using the current target encoding.
781 If a character cannot be represented in the current target encoding,
782 then an exception is thrown.
784 @item @code{gdb.Value}
785 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
787 @item @code{gdb.LazyString}
788 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
789 Python}), then the lazy string's @code{value} method is called, and
794 @defun Value.__init__ (@var{val}, @var{type})
795 This second form of the @code{gdb.Value} constructor returns a
796 @code{gdb.Value} of type @var{type} where the value contents are taken
797 from the Python buffer object specified by @var{val}. The number of
798 bytes in the Python buffer object must be greater than or equal to the
802 @defun Value.cast (type)
803 Return a new instance of @code{gdb.Value} that is the result of
804 casting this instance to the type described by @var{type}, which must
805 be a @code{gdb.Type} object. If the cast cannot be performed for some
806 reason, this method throws an exception.
809 @defun Value.dereference ()
810 For pointer data types, this method returns a new @code{gdb.Value} object
811 whose contents is the object pointed to by the pointer. For example, if
812 @code{foo} is a C pointer to an @code{int}, declared in your C program as
819 then you can use the corresponding @code{gdb.Value} to access what
820 @code{foo} points to like this:
823 bar = foo.dereference ()
826 The result @code{bar} will be a @code{gdb.Value} object holding the
827 value pointed to by @code{foo}.
829 A similar function @code{Value.referenced_value} exists which also
830 returns @code{gdb.Value} objects corresponding to the values pointed to
831 by pointer values (and additionally, values referenced by reference
832 values). However, the behavior of @code{Value.dereference}
833 differs from @code{Value.referenced_value} by the fact that the
834 behavior of @code{Value.dereference} is identical to applying the C
835 unary operator @code{*} on a given value. For example, consider a
836 reference to a pointer @code{ptrref}, declared in your C@t{++} program
844 intptr &ptrref = ptr;
847 Though @code{ptrref} is a reference value, one can apply the method
848 @code{Value.dereference} to the @code{gdb.Value} object corresponding
849 to it and obtain a @code{gdb.Value} which is identical to that
850 corresponding to @code{val}. However, if you apply the method
851 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
852 object identical to that corresponding to @code{ptr}.
855 py_ptrref = gdb.parse_and_eval ("ptrref")
856 py_val = py_ptrref.dereference ()
857 py_ptr = py_ptrref.referenced_value ()
860 The @code{gdb.Value} object @code{py_val} is identical to that
861 corresponding to @code{val}, and @code{py_ptr} is identical to that
862 corresponding to @code{ptr}. In general, @code{Value.dereference} can
863 be applied whenever the C unary operator @code{*} can be applied
864 to the corresponding C value. For those cases where applying both
865 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
866 the results obtained need not be identical (as we have seen in the above
867 example). The results are however identical when applied on
868 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
869 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
872 @defun Value.referenced_value ()
873 For pointer or reference data types, this method returns a new
874 @code{gdb.Value} object corresponding to the value referenced by the
875 pointer/reference value. For pointer data types,
876 @code{Value.dereference} and @code{Value.referenced_value} produce
877 identical results. The difference between these methods is that
878 @code{Value.dereference} cannot get the values referenced by reference
879 values. For example, consider a reference to an @code{int}, declared
880 in your C@t{++} program as
888 then applying @code{Value.dereference} to the @code{gdb.Value} object
889 corresponding to @code{ref} will result in an error, while applying
890 @code{Value.referenced_value} will result in a @code{gdb.Value} object
891 identical to that corresponding to @code{val}.
894 py_ref = gdb.parse_and_eval ("ref")
895 er_ref = py_ref.dereference () # Results in error
896 py_val = py_ref.referenced_value () # Returns the referenced value
899 The @code{gdb.Value} object @code{py_val} is identical to that
900 corresponding to @code{val}.
903 @defun Value.reference_value ()
904 Return a @code{gdb.Value} object which is a reference to the value
905 encapsulated by this instance.
908 @defun Value.const_value ()
909 Return a @code{gdb.Value} object which is a @code{const} version of the
910 value encapsulated by this instance.
913 @defun Value.dynamic_cast (type)
914 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
915 operator were used. Consult a C@t{++} reference for details.
918 @defun Value.reinterpret_cast (type)
919 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
920 operator were used. Consult a C@t{++} reference for details.
923 @defun Value.format_string (...)
924 Convert a @code{gdb.Value} to a string, similarly to what the @code{print}
925 command does. Invoked with no arguments, this is equivalent to calling
926 the @code{str} function on the @code{gdb.Value}. The representation of
927 the same value may change across different versions of @value{GDBN}, so
928 you shouldn't, for instance, parse the strings returned by this method.
930 All the arguments are keyword only. If an argument is not specified, the
931 current global default setting is used.
935 @code{True} if pretty-printers (@pxref{Pretty Printing}) should not be
936 used to format the value. @code{False} if enabled pretty-printers
937 matching the type represented by the @code{gdb.Value} should be used to
941 @code{True} if arrays should be pretty printed to be more convenient to
942 read, @code{False} if they shouldn't (see @code{set print array} in
943 @ref{Print Settings}).
946 @code{True} if structs should be pretty printed to be more convenient to
947 read, @code{False} if they shouldn't (see @code{set print pretty} in
948 @ref{Print Settings}).
951 @code{True} if array indexes should be included in the string
952 representation of arrays, @code{False} if they shouldn't (see @code{set
953 print array-indexes} in @ref{Print Settings}).
956 @code{True} if the string representation of a pointer should include the
957 corresponding symbol name (if one exists), @code{False} if it shouldn't
958 (see @code{set print symbol} in @ref{Print Settings}).
961 @code{True} if unions which are contained in other structures or unions
962 should be expanded, @code{False} if they shouldn't (see @code{set print
963 union} in @ref{Print Settings}).
966 @code{True} if the string representation of a pointer should include the
967 address, @code{False} if it shouldn't (see @code{set print address} in
968 @ref{Print Settings}).
971 @code{True} if C@t{++} references should be resolved to the value they
972 refer to, @code{False} (the default) if they shouldn't. Note that, unlike
973 for the @code{print} command, references are not automatically expanded
974 when using the @code{format_string} method or the @code{str}
975 function. There is no global @code{print} setting to change the default
979 @code{True} if the representation of a pointer to an object should
980 identify the @emph{actual} (derived) type of the object rather than the
981 @emph{declared} type, using the virtual function table. @code{False} if
982 the @emph{declared} type should be used. (See @code{set print object} in
983 @ref{Print Settings}).
986 @code{True} if static members should be included in the string
987 representation of a C@t{++} object, @code{False} if they shouldn't (see
988 @code{set print static-members} in @ref{Print Settings}).
991 Number of array elements to print, or @code{0} to print an unlimited
992 number of elements (see @code{set print elements} in @ref{Print
996 The maximum depth to print for nested structs and unions, or @code{-1}
997 to print an unlimited number of elements (see @code{set print
998 max-depth} in @ref{Print Settings}).
1000 @item repeat_threshold
1001 Set the threshold for suppressing display of repeated array elements, or
1002 @code{0} to represent all elements, even if repeated. (See @code{set
1003 print repeats} in @ref{Print Settings}).
1006 A string containing a single character representing the format to use for
1007 the returned string. For instance, @code{'x'} is equivalent to using the
1008 @value{GDBN} command @code{print} with the @code{/x} option and formats
1009 the value as a hexadecimal number.
1013 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
1014 If this @code{gdb.Value} represents a string, then this method
1015 converts the contents to a Python string. Otherwise, this method will
1018 Values are interpreted as strings according to the rules of the
1019 current language. If the optional length argument is given, the
1020 string will be converted to that length, and will include any embedded
1021 zeroes that the string may contain. Otherwise, for languages
1022 where the string is zero-terminated, the entire string will be
1025 For example, in C-like languages, a value is a string if it is a pointer
1026 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
1029 If the optional @var{encoding} argument is given, it must be a string
1030 naming the encoding of the string in the @code{gdb.Value}, such as
1031 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
1032 the same encodings as the corresponding argument to Python's
1033 @code{string.decode} method, and the Python codec machinery will be used
1034 to convert the string. If @var{encoding} is not given, or if
1035 @var{encoding} is the empty string, then either the @code{target-charset}
1036 (@pxref{Character Sets}) will be used, or a language-specific encoding
1037 will be used, if the current language is able to supply one.
1039 The optional @var{errors} argument is the same as the corresponding
1040 argument to Python's @code{string.decode} method.
1042 If the optional @var{length} argument is given, the string will be
1043 fetched and converted to the given length.
1046 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
1047 If this @code{gdb.Value} represents a string, then this method
1048 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
1049 In Python}). Otherwise, this method will throw an exception.
1051 If the optional @var{encoding} argument is given, it must be a string
1052 naming the encoding of the @code{gdb.LazyString}. Some examples are:
1053 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
1054 @var{encoding} argument is an encoding that @value{GDBN} does
1055 recognize, @value{GDBN} will raise an error.
1057 When a lazy string is printed, the @value{GDBN} encoding machinery is
1058 used to convert the string during printing. If the optional
1059 @var{encoding} argument is not provided, or is an empty string,
1060 @value{GDBN} will automatically select the encoding most suitable for
1061 the string type. For further information on encoding in @value{GDBN}
1062 please see @ref{Character Sets}.
1064 If the optional @var{length} argument is given, the string will be
1065 fetched and encoded to the length of characters specified. If
1066 the @var{length} argument is not provided, the string will be fetched
1067 and encoded until a null of appropriate width is found.
1070 @defun Value.fetch_lazy ()
1071 If the @code{gdb.Value} object is currently a lazy value
1072 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
1073 fetched from the inferior. Any errors that occur in the process
1074 will produce a Python exception.
1076 If the @code{gdb.Value} object is not a lazy value, this method
1079 This method does not return a value.
1083 @node Types In Python
1084 @subsubsection Types In Python
1085 @cindex types in Python
1086 @cindex Python, working with types
1089 @value{GDBN} represents types from the inferior using the class
1092 The following type-related functions are available in the @code{gdb}
1095 @findex gdb.lookup_type
1096 @defun gdb.lookup_type (name @r{[}, block@r{]})
1097 This function looks up a type by its @var{name}, which must be a string.
1099 If @var{block} is given, then @var{name} is looked up in that scope.
1100 Otherwise, it is searched for globally.
1102 Ordinarily, this function will return an instance of @code{gdb.Type}.
1103 If the named type cannot be found, it will throw an exception.
1106 If the type is a structure or class type, or an enum type, the fields
1107 of that type can be accessed using the Python @dfn{dictionary syntax}.
1108 For example, if @code{some_type} is a @code{gdb.Type} instance holding
1109 a structure type, you can access its @code{foo} field with:
1112 bar = some_type['foo']
1115 @code{bar} will be a @code{gdb.Field} object; see below under the
1116 description of the @code{Type.fields} method for a description of the
1117 @code{gdb.Field} class.
1119 An instance of @code{Type} has the following attributes:
1121 @defvar Type.alignof
1122 The alignment of this type, in bytes. Type alignment comes from the
1123 debugging information; if it was not specified, then @value{GDBN} will
1124 use the relevant ABI to try to determine the alignment. In some
1125 cases, even this is not possible, and zero will be returned.
1129 The type code for this type. The type code will be one of the
1130 @code{TYPE_CODE_} constants defined below.
1133 @defvar Type.dynamic
1134 A boolean indicating whether this type is dynamic. In some
1135 situations, such as Rust @code{enum} types or Ada variant records, the
1136 concrete type of a value may vary depending on its contents. That is,
1137 the declared type of a variable, or the type returned by
1138 @code{gdb.lookup_type} may be dynamic; while the type of the
1139 variable's value will be a concrete instance of that dynamic type.
1141 For example, consider this code:
1147 Here, at least conceptually (whether your compiler actually does this
1148 is a separate issue), examining @w{@code{gdb.lookup_symbol("array", ...).type}}
1149 could yield a @code{gdb.Type} which reports a size of @code{None}.
1150 This is the dynamic type.
1152 However, examining @code{gdb.parse_and_eval("array").type} would yield
1153 a concrete type, whose length would be known.
1157 The name of this type. If this type has no name, then @code{None}
1162 The size of this type, in target @code{char} units. Usually, a
1163 target's @code{char} type will be an 8-bit byte. However, on some
1164 unusual platforms, this type may have a different size. A dynamic
1165 type may not have a fixed size; in this case, this attribute's value
1166 will be @code{None}.
1170 The tag name for this type. The tag name is the name after
1171 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1172 languages have this concept. If this type has no tag name, then
1173 @code{None} is returned.
1176 @defvar Type.objfile
1177 The @code{gdb.Objfile} that this type was defined in, or @code{None} if
1178 there is no associated objfile.
1181 The following methods are provided:
1183 @defun Type.fields ()
1185 Return the fields of this type. The behavior depends on the type code:
1190 For structure and union types, this method returns the fields.
1193 Range types have two fields, the minimum and maximum values.
1196 Enum types have one field per enum constant.
1199 Function and method types have one field per parameter. The base types of
1200 C@t{++} classes are also represented as fields.
1203 Array types have one field representing the array's range.
1206 If the type does not fit into one of these categories, a @code{TypeError}
1211 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
1214 This attribute is not available for @code{enum} or @code{static}
1215 (as in C@t{++}) fields. The value is the position, counting
1216 in bits, from the start of the containing type. Note that, in a
1217 dynamic type, the position of a field may not be constant. In this
1218 case, the value will be @code{None}. Also, a dynamic type may have
1219 fields that do not appear in a corresponding concrete type.
1222 This attribute is only available for @code{enum} fields, and its value
1223 is the enumeration member's integer representation.
1226 The name of the field, or @code{None} for anonymous fields.
1229 This is @code{True} if the field is artificial, usually meaning that
1230 it was provided by the compiler and not the user. This attribute is
1231 always provided, and is @code{False} if the field is not artificial.
1234 This is @code{True} if the field represents a base class of a C@t{++}
1235 structure. This attribute is always provided, and is @code{False}
1236 if the field is not a base class of the type that is the argument of
1237 @code{fields}, or if that type was not a C@t{++} class.
1240 If the field is packed, or is a bitfield, then this will have a
1241 non-zero value, which is the size of the field in bits. Otherwise,
1242 this will be zero; in this case the field's size is given by its type.
1245 The type of the field. This is usually an instance of @code{Type},
1246 but it can be @code{None} in some situations.
1249 The type which contains this field. This is an instance of
1254 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
1255 Return a new @code{gdb.Type} object which represents an array of this
1256 type. If one argument is given, it is the inclusive upper bound of
1257 the array; in this case the lower bound is zero. If two arguments are
1258 given, the first argument is the lower bound of the array, and the
1259 second argument is the upper bound of the array. An array's length
1260 must not be negative, but the bounds can be.
1263 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
1264 Return a new @code{gdb.Type} object which represents a vector of this
1265 type. If one argument is given, it is the inclusive upper bound of
1266 the vector; in this case the lower bound is zero. If two arguments are
1267 given, the first argument is the lower bound of the vector, and the
1268 second argument is the upper bound of the vector. A vector's length
1269 must not be negative, but the bounds can be.
1271 The difference between an @code{array} and a @code{vector} is that
1272 arrays behave like in C: when used in expressions they decay to a pointer
1273 to the first element whereas vectors are treated as first class values.
1276 @defun Type.const ()
1277 Return a new @code{gdb.Type} object which represents a
1278 @code{const}-qualified variant of this type.
1281 @defun Type.volatile ()
1282 Return a new @code{gdb.Type} object which represents a
1283 @code{volatile}-qualified variant of this type.
1286 @defun Type.unqualified ()
1287 Return a new @code{gdb.Type} object which represents an unqualified
1288 variant of this type. That is, the result is neither @code{const} nor
1292 @defun Type.range ()
1293 Return a Python @code{Tuple} object that contains two elements: the
1294 low bound of the argument type and the high bound of that type. If
1295 the type does not have a range, @value{GDBN} will raise a
1296 @code{gdb.error} exception (@pxref{Exception Handling}).
1299 @defun Type.reference ()
1300 Return a new @code{gdb.Type} object which represents a reference to this
1304 @defun Type.pointer ()
1305 Return a new @code{gdb.Type} object which represents a pointer to this
1309 @defun Type.strip_typedefs ()
1310 Return a new @code{gdb.Type} that represents the real type,
1311 after removing all layers of typedefs.
1314 @defun Type.target ()
1315 Return a new @code{gdb.Type} object which represents the target type
1318 For a pointer type, the target type is the type of the pointed-to
1319 object. For an array type (meaning C-like arrays), the target type is
1320 the type of the elements of the array. For a function or method type,
1321 the target type is the type of the return value. For a complex type,
1322 the target type is the type of the elements. For a typedef, the
1323 target type is the aliased type.
1325 If the type does not have a target, this method will throw an
1329 @defun Type.template_argument (n @r{[}, block@r{]})
1330 If this @code{gdb.Type} is an instantiation of a template, this will
1331 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1332 value of the @var{n}th template argument (indexed starting at 0).
1334 If this @code{gdb.Type} is not a template type, or if the type has fewer
1335 than @var{n} template arguments, this will throw an exception.
1336 Ordinarily, only C@t{++} code will have template types.
1338 If @var{block} is given, then @var{name} is looked up in that scope.
1339 Otherwise, it is searched for globally.
1342 @defun Type.optimized_out ()
1343 Return @code{gdb.Value} instance of this type whose value is optimized
1344 out. This allows a frame decorator to indicate that the value of an
1345 argument or a local variable is not known.
1348 Each type has a code, which indicates what category this type falls
1349 into. The available type categories are represented by constants
1350 defined in the @code{gdb} module:
1353 @vindex TYPE_CODE_PTR
1354 @item gdb.TYPE_CODE_PTR
1355 The type is a pointer.
1357 @vindex TYPE_CODE_ARRAY
1358 @item gdb.TYPE_CODE_ARRAY
1359 The type is an array.
1361 @vindex TYPE_CODE_STRUCT
1362 @item gdb.TYPE_CODE_STRUCT
1363 The type is a structure.
1365 @vindex TYPE_CODE_UNION
1366 @item gdb.TYPE_CODE_UNION
1367 The type is a union.
1369 @vindex TYPE_CODE_ENUM
1370 @item gdb.TYPE_CODE_ENUM
1371 The type is an enum.
1373 @vindex TYPE_CODE_FLAGS
1374 @item gdb.TYPE_CODE_FLAGS
1375 A bit flags type, used for things such as status registers.
1377 @vindex TYPE_CODE_FUNC
1378 @item gdb.TYPE_CODE_FUNC
1379 The type is a function.
1381 @vindex TYPE_CODE_INT
1382 @item gdb.TYPE_CODE_INT
1383 The type is an integer type.
1385 @vindex TYPE_CODE_FLT
1386 @item gdb.TYPE_CODE_FLT
1387 A floating point type.
1389 @vindex TYPE_CODE_VOID
1390 @item gdb.TYPE_CODE_VOID
1391 The special type @code{void}.
1393 @vindex TYPE_CODE_SET
1394 @item gdb.TYPE_CODE_SET
1397 @vindex TYPE_CODE_RANGE
1398 @item gdb.TYPE_CODE_RANGE
1399 A range type, that is, an integer type with bounds.
1401 @vindex TYPE_CODE_STRING
1402 @item gdb.TYPE_CODE_STRING
1403 A string type. Note that this is only used for certain languages with
1404 language-defined string types; C strings are not represented this way.
1406 @vindex TYPE_CODE_BITSTRING
1407 @item gdb.TYPE_CODE_BITSTRING
1408 A string of bits. It is deprecated.
1410 @vindex TYPE_CODE_ERROR
1411 @item gdb.TYPE_CODE_ERROR
1412 An unknown or erroneous type.
1414 @vindex TYPE_CODE_METHOD
1415 @item gdb.TYPE_CODE_METHOD
1416 A method type, as found in C@t{++}.
1418 @vindex TYPE_CODE_METHODPTR
1419 @item gdb.TYPE_CODE_METHODPTR
1420 A pointer-to-member-function.
1422 @vindex TYPE_CODE_MEMBERPTR
1423 @item gdb.TYPE_CODE_MEMBERPTR
1424 A pointer-to-member.
1426 @vindex TYPE_CODE_REF
1427 @item gdb.TYPE_CODE_REF
1430 @vindex TYPE_CODE_RVALUE_REF
1431 @item gdb.TYPE_CODE_RVALUE_REF
1432 A C@t{++}11 rvalue reference type.
1434 @vindex TYPE_CODE_CHAR
1435 @item gdb.TYPE_CODE_CHAR
1438 @vindex TYPE_CODE_BOOL
1439 @item gdb.TYPE_CODE_BOOL
1442 @vindex TYPE_CODE_COMPLEX
1443 @item gdb.TYPE_CODE_COMPLEX
1444 A complex float type.
1446 @vindex TYPE_CODE_TYPEDEF
1447 @item gdb.TYPE_CODE_TYPEDEF
1448 A typedef to some other type.
1450 @vindex TYPE_CODE_NAMESPACE
1451 @item gdb.TYPE_CODE_NAMESPACE
1452 A C@t{++} namespace.
1454 @vindex TYPE_CODE_DECFLOAT
1455 @item gdb.TYPE_CODE_DECFLOAT
1456 A decimal floating point type.
1458 @vindex TYPE_CODE_INTERNAL_FUNCTION
1459 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1460 A function internal to @value{GDBN}. This is the type used to represent
1461 convenience functions.
1464 Further support for types is provided in the @code{gdb.types}
1465 Python module (@pxref{gdb.types}).
1467 @node Pretty Printing API
1468 @subsubsection Pretty Printing API
1469 @cindex python pretty printing api
1471 A pretty-printer is just an object that holds a value and implements a
1472 specific interface, defined here. An example output is provided
1473 (@pxref{Pretty Printing}).
1475 @defun pretty_printer.children (self)
1476 @value{GDBN} will call this method on a pretty-printer to compute the
1477 children of the pretty-printer's value.
1479 This method must return an object conforming to the Python iterator
1480 protocol. Each item returned by the iterator must be a tuple holding
1481 two elements. The first element is the ``name'' of the child; the
1482 second element is the child's value. The value can be any Python
1483 object which is convertible to a @value{GDBN} value.
1485 This method is optional. If it does not exist, @value{GDBN} will act
1486 as though the value has no children.
1488 For efficiency, the @code{children} method should lazily compute its
1489 results. This will let @value{GDBN} read as few elements as
1490 necessary, for example when various print settings (@pxref{Print
1491 Settings}) or @code{-var-list-children} (@pxref{GDB/MI Variable
1492 Objects}) limit the number of elements to be displayed.
1494 Children may be hidden from display based on the value of @samp{set
1495 print max-depth} (@pxref{Print Settings}).
1498 @defun pretty_printer.display_hint (self)
1499 The CLI may call this method and use its result to change the
1500 formatting of a value. The result will also be supplied to an MI
1501 consumer as a @samp{displayhint} attribute of the variable being
1504 This method is optional. If it does exist, this method must return a
1505 string or the special value @code{None}.
1507 Some display hints are predefined by @value{GDBN}:
1511 Indicate that the object being printed is ``array-like''. The CLI
1512 uses this to respect parameters such as @code{set print elements} and
1513 @code{set print array}.
1516 Indicate that the object being printed is ``map-like'', and that the
1517 children of this value can be assumed to alternate between keys and
1521 Indicate that the object being printed is ``string-like''. If the
1522 printer's @code{to_string} method returns a Python string of some
1523 kind, then @value{GDBN} will call its internal language-specific
1524 string-printing function to format the string. For the CLI this means
1525 adding quotation marks, possibly escaping some characters, respecting
1526 @code{set print elements}, and the like.
1529 The special value @code{None} causes @value{GDBN} to apply the default
1533 @defun pretty_printer.to_string (self)
1534 @value{GDBN} will call this method to display the string
1535 representation of the value passed to the object's constructor.
1537 When printing from the CLI, if the @code{to_string} method exists,
1538 then @value{GDBN} will prepend its result to the values returned by
1539 @code{children}. Exactly how this formatting is done is dependent on
1540 the display hint, and may change as more hints are added. Also,
1541 depending on the print settings (@pxref{Print Settings}), the CLI may
1542 print just the result of @code{to_string} in a stack trace, omitting
1543 the result of @code{children}.
1545 If this method returns a string, it is printed verbatim.
1547 Otherwise, if this method returns an instance of @code{gdb.Value},
1548 then @value{GDBN} prints this value. This may result in a call to
1549 another pretty-printer.
1551 If instead the method returns a Python value which is convertible to a
1552 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1553 the resulting value. Again, this may result in a call to another
1554 pretty-printer. Python scalars (integers, floats, and booleans) and
1555 strings are convertible to @code{gdb.Value}; other types are not.
1557 Finally, if this method returns @code{None} then no further operations
1558 are peformed in this method and nothing is printed.
1560 If the result is not one of these types, an exception is raised.
1563 @value{GDBN} provides a function which can be used to look up the
1564 default pretty-printer for a @code{gdb.Value}:
1566 @findex gdb.default_visualizer
1567 @defun gdb.default_visualizer (value)
1568 This function takes a @code{gdb.Value} object as an argument. If a
1569 pretty-printer for this value exists, then it is returned. If no such
1570 printer exists, then this returns @code{None}.
1573 @node Selecting Pretty-Printers
1574 @subsubsection Selecting Pretty-Printers
1575 @cindex selecting python pretty-printers
1577 @value{GDBN} provides several ways to register a pretty-printer:
1578 globally, per program space, and per objfile. When choosing how to
1579 register your pretty-printer, a good rule is to register it with the
1580 smallest scope possible: that is prefer a specific objfile first, then
1581 a program space, and only register a printer globally as a last
1584 @findex gdb.pretty_printers
1585 @defvar gdb.pretty_printers
1586 The Python list @code{gdb.pretty_printers} contains an array of
1587 functions or callable objects that have been registered via addition
1588 as a pretty-printer. Printers in this list are called @code{global}
1589 printers, they're available when debugging all inferiors.
1592 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1593 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1596 Each function on these lists is passed a single @code{gdb.Value}
1597 argument and should return a pretty-printer object conforming to the
1598 interface definition above (@pxref{Pretty Printing API}). If a function
1599 cannot create a pretty-printer for the value, it should return
1602 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1603 @code{gdb.Objfile} in the current program space and iteratively calls
1604 each enabled lookup routine in the list for that @code{gdb.Objfile}
1605 until it receives a pretty-printer object.
1606 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1607 searches the pretty-printer list of the current program space,
1608 calling each enabled function until an object is returned.
1609 After these lists have been exhausted, it tries the global
1610 @code{gdb.pretty_printers} list, again calling each enabled function until an
1613 The order in which the objfiles are searched is not specified. For a
1614 given list, functions are always invoked from the head of the list,
1615 and iterated over sequentially until the end of the list, or a printer
1618 For various reasons a pretty-printer may not work.
1619 For example, the underlying data structure may have changed and
1620 the pretty-printer is out of date.
1622 The consequences of a broken pretty-printer are severe enough that
1623 @value{GDBN} provides support for enabling and disabling individual
1624 printers. For example, if @code{print frame-arguments} is on,
1625 a backtrace can become highly illegible if any argument is printed
1626 with a broken printer.
1628 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1629 attribute to the registered function or callable object. If this attribute
1630 is present and its value is @code{False}, the printer is disabled, otherwise
1631 the printer is enabled.
1633 @node Writing a Pretty-Printer
1634 @subsubsection Writing a Pretty-Printer
1635 @cindex writing a pretty-printer
1637 A pretty-printer consists of two parts: a lookup function to detect
1638 if the type is supported, and the printer itself.
1640 Here is an example showing how a @code{std::string} printer might be
1641 written. @xref{Pretty Printing API}, for details on the API this class
1645 class StdStringPrinter(object):
1646 "Print a std::string"
1648 def __init__(self, val):
1651 def to_string(self):
1652 return self.val['_M_dataplus']['_M_p']
1654 def display_hint(self):
1658 And here is an example showing how a lookup function for the printer
1659 example above might be written.
1662 def str_lookup_function(val):
1663 lookup_tag = val.type.tag
1664 if lookup_tag is None:
1666 regex = re.compile("^std::basic_string<char,.*>$")
1667 if regex.match(lookup_tag):
1668 return StdStringPrinter(val)
1672 The example lookup function extracts the value's type, and attempts to
1673 match it to a type that it can pretty-print. If it is a type the
1674 printer can pretty-print, it will return a printer object. If not, it
1675 returns @code{None}.
1677 We recommend that you put your core pretty-printers into a Python
1678 package. If your pretty-printers are for use with a library, we
1679 further recommend embedding a version number into the package name.
1680 This practice will enable @value{GDBN} to load multiple versions of
1681 your pretty-printers at the same time, because they will have
1684 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1685 can be evaluated multiple times without changing its meaning. An
1686 ideal auto-load file will consist solely of @code{import}s of your
1687 printer modules, followed by a call to a register pretty-printers with
1688 the current objfile.
1690 Taken as a whole, this approach will scale nicely to multiple
1691 inferiors, each potentially using a different library version.
1692 Embedding a version number in the Python package name will ensure that
1693 @value{GDBN} is able to load both sets of printers simultaneously.
1694 Then, because the search for pretty-printers is done by objfile, and
1695 because your auto-loaded code took care to register your library's
1696 printers with a specific objfile, @value{GDBN} will find the correct
1697 printers for the specific version of the library used by each
1700 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1701 this code might appear in @code{gdb.libstdcxx.v6}:
1704 def register_printers(objfile):
1705 objfile.pretty_printers.append(str_lookup_function)
1709 And then the corresponding contents of the auto-load file would be:
1712 import gdb.libstdcxx.v6
1713 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1716 The previous example illustrates a basic pretty-printer.
1717 There are a few things that can be improved on.
1718 The printer doesn't have a name, making it hard to identify in a
1719 list of installed printers. The lookup function has a name, but
1720 lookup functions can have arbitrary, even identical, names.
1722 Second, the printer only handles one type, whereas a library typically has
1723 several types. One could install a lookup function for each desired type
1724 in the library, but one could also have a single lookup function recognize
1725 several types. The latter is the conventional way this is handled.
1726 If a pretty-printer can handle multiple data types, then its
1727 @dfn{subprinters} are the printers for the individual data types.
1729 The @code{gdb.printing} module provides a formal way of solving these
1730 problems (@pxref{gdb.printing}).
1731 Here is another example that handles multiple types.
1733 These are the types we are going to pretty-print:
1736 struct foo @{ int a, b; @};
1737 struct bar @{ struct foo x, y; @};
1740 Here are the printers:
1744 """Print a foo object."""
1746 def __init__(self, val):
1749 def to_string(self):
1750 return ("a=<" + str(self.val["a"]) +
1751 "> b=<" + str(self.val["b"]) + ">")
1754 """Print a bar object."""
1756 def __init__(self, val):
1759 def to_string(self):
1760 return ("x=<" + str(self.val["x"]) +
1761 "> y=<" + str(self.val["y"]) + ">")
1764 This example doesn't need a lookup function, that is handled by the
1765 @code{gdb.printing} module. Instead a function is provided to build up
1766 the object that handles the lookup.
1771 def build_pretty_printer():
1772 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1774 pp.add_printer('foo', '^foo$', fooPrinter)
1775 pp.add_printer('bar', '^bar$', barPrinter)
1779 And here is the autoload support:
1784 gdb.printing.register_pretty_printer(
1785 gdb.current_objfile(),
1786 my_library.build_pretty_printer())
1789 Finally, when this printer is loaded into @value{GDBN}, here is the
1790 corresponding output of @samp{info pretty-printer}:
1793 (gdb) info pretty-printer
1800 @node Type Printing API
1801 @subsubsection Type Printing API
1802 @cindex type printing API for Python
1804 @value{GDBN} provides a way for Python code to customize type display.
1805 This is mainly useful for substituting canonical typedef names for
1808 @cindex type printer
1809 A @dfn{type printer} is just a Python object conforming to a certain
1810 protocol. A simple base class implementing the protocol is provided;
1811 see @ref{gdb.types}. A type printer must supply at least:
1813 @defivar type_printer enabled
1814 A boolean which is True if the printer is enabled, and False
1815 otherwise. This is manipulated by the @code{enable type-printer}
1816 and @code{disable type-printer} commands.
1819 @defivar type_printer name
1820 The name of the type printer. This must be a string. This is used by
1821 the @code{enable type-printer} and @code{disable type-printer}
1825 @defmethod type_printer instantiate (self)
1826 This is called by @value{GDBN} at the start of type-printing. It is
1827 only called if the type printer is enabled. This method must return a
1828 new object that supplies a @code{recognize} method, as described below.
1832 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1833 will compute a list of type recognizers. This is done by iterating
1834 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1835 followed by the per-progspace type printers (@pxref{Progspaces In
1836 Python}), and finally the global type printers.
1838 @value{GDBN} will call the @code{instantiate} method of each enabled
1839 type printer. If this method returns @code{None}, then the result is
1840 ignored; otherwise, it is appended to the list of recognizers.
1842 Then, when @value{GDBN} is going to display a type name, it iterates
1843 over the list of recognizers. For each one, it calls the recognition
1844 function, stopping if the function returns a non-@code{None} value.
1845 The recognition function is defined as:
1847 @defmethod type_recognizer recognize (self, type)
1848 If @var{type} is not recognized, return @code{None}. Otherwise,
1849 return a string which is to be printed as the name of @var{type}.
1850 The @var{type} argument will be an instance of @code{gdb.Type}
1851 (@pxref{Types In Python}).
1854 @value{GDBN} uses this two-pass approach so that type printers can
1855 efficiently cache information without holding on to it too long. For
1856 example, it can be convenient to look up type information in a type
1857 printer and hold it for a recognizer's lifetime; if a single pass were
1858 done then type printers would have to make use of the event system in
1859 order to avoid holding information that could become stale as the
1862 @node Frame Filter API
1863 @subsubsection Filtering Frames
1864 @cindex frame filters api
1866 Frame filters are Python objects that manipulate the visibility of a
1867 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1870 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1871 commands (@pxref{GDB/MI}), those that return a collection of frames
1872 are affected. The commands that work with frame filters are:
1874 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1875 @code{-stack-list-frames}
1876 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1877 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1878 -stack-list-variables command}), @code{-stack-list-arguments}
1879 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1880 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1881 -stack-list-locals command}).
1883 A frame filter works by taking an iterator as an argument, applying
1884 actions to the contents of that iterator, and returning another
1885 iterator (or, possibly, the same iterator it was provided in the case
1886 where the filter does not perform any operations). Typically, frame
1887 filters utilize tools such as the Python's @code{itertools} module to
1888 work with and create new iterators from the source iterator.
1889 Regardless of how a filter chooses to apply actions, it must not alter
1890 the underlying @value{GDBN} frame or frames, or attempt to alter the
1891 call-stack within @value{GDBN}. This preserves data integrity within
1892 @value{GDBN}. Frame filters are executed on a priority basis and care
1893 should be taken that some frame filters may have been executed before,
1894 and that some frame filters will be executed after.
1896 An important consideration when designing frame filters, and well
1897 worth reflecting upon, is that frame filters should avoid unwinding
1898 the call stack if possible. Some stacks can run very deep, into the
1899 tens of thousands in some cases. To search every frame when a frame
1900 filter executes may be too expensive at that step. The frame filter
1901 cannot know how many frames it has to iterate over, and it may have to
1902 iterate through them all. This ends up duplicating effort as
1903 @value{GDBN} performs this iteration when it prints the frames. If
1904 the filter can defer unwinding frames until frame decorators are
1905 executed, after the last filter has executed, it should. @xref{Frame
1906 Decorator API}, for more information on decorators. Also, there are
1907 examples for both frame decorators and filters in later chapters.
1908 @xref{Writing a Frame Filter}, for more information.
1910 The Python dictionary @code{gdb.frame_filters} contains key/object
1911 pairings that comprise a frame filter. Frame filters in this
1912 dictionary are called @code{global} frame filters, and they are
1913 available when debugging all inferiors. These frame filters must
1914 register with the dictionary directly. In addition to the
1915 @code{global} dictionary, there are other dictionaries that are loaded
1916 with different inferiors via auto-loading (@pxref{Python
1917 Auto-loading}). The two other areas where frame filter dictionaries
1918 can be found are: @code{gdb.Progspace} which contains a
1919 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1920 object which also contains a @code{frame_filters} dictionary
1923 When a command is executed from @value{GDBN} that is compatible with
1924 frame filters, @value{GDBN} combines the @code{global},
1925 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1926 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1927 several frames, and thus several object files, might be in use.
1928 @value{GDBN} then prunes any frame filter whose @code{enabled}
1929 attribute is @code{False}. This pruned list is then sorted according
1930 to the @code{priority} attribute in each filter.
1932 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1933 creates an iterator which wraps each frame in the call stack in a
1934 @code{FrameDecorator} object, and calls each filter in order. The
1935 output from the previous filter will always be the input to the next
1938 Frame filters have a mandatory interface which each frame filter must
1939 implement, defined here:
1941 @defun FrameFilter.filter (iterator)
1942 @value{GDBN} will call this method on a frame filter when it has
1943 reached the order in the priority list for that filter.
1945 For example, if there are four frame filters:
1956 The order that the frame filters will be called is:
1959 Filter3 -> Filter2 -> Filter1 -> Filter4
1962 Note that the output from @code{Filter3} is passed to the input of
1963 @code{Filter2}, and so on.
1965 This @code{filter} method is passed a Python iterator. This iterator
1966 contains a sequence of frame decorators that wrap each
1967 @code{gdb.Frame}, or a frame decorator that wraps another frame
1968 decorator. The first filter that is executed in the sequence of frame
1969 filters will receive an iterator entirely comprised of default
1970 @code{FrameDecorator} objects. However, after each frame filter is
1971 executed, the previous frame filter may have wrapped some or all of
1972 the frame decorators with their own frame decorator. As frame
1973 decorators must also conform to a mandatory interface, these
1974 decorators can be assumed to act in a uniform manner (@pxref{Frame
1977 This method must return an object conforming to the Python iterator
1978 protocol. Each item in the iterator must be an object conforming to
1979 the frame decorator interface. If a frame filter does not wish to
1980 perform any operations on this iterator, it should return that
1983 This method is not optional. If it does not exist, @value{GDBN} will
1984 raise and print an error.
1987 @defvar FrameFilter.name
1988 The @code{name} attribute must be Python string which contains the
1989 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1990 Management}). This attribute may contain any combination of letters
1991 or numbers. Care should be taken to ensure that it is unique. This
1992 attribute is mandatory.
1995 @defvar FrameFilter.enabled
1996 The @code{enabled} attribute must be Python boolean. This attribute
1997 indicates to @value{GDBN} whether the frame filter is enabled, and
1998 should be considered when frame filters are executed. If
1999 @code{enabled} is @code{True}, then the frame filter will be executed
2000 when any of the backtrace commands detailed earlier in this chapter
2001 are executed. If @code{enabled} is @code{False}, then the frame
2002 filter will not be executed. This attribute is mandatory.
2005 @defvar FrameFilter.priority
2006 The @code{priority} attribute must be Python integer. This attribute
2007 controls the order of execution in relation to other frame filters.
2008 There are no imposed limits on the range of @code{priority} other than
2009 it must be a valid integer. The higher the @code{priority} attribute,
2010 the sooner the frame filter will be executed in relation to other
2011 frame filters. Although @code{priority} can be negative, it is
2012 recommended practice to assume zero is the lowest priority that a
2013 frame filter can be assigned. Frame filters that have the same
2014 priority are executed in unsorted order in that priority slot. This
2015 attribute is mandatory. 100 is a good default priority.
2018 @node Frame Decorator API
2019 @subsubsection Decorating Frames
2020 @cindex frame decorator api
2022 Frame decorators are sister objects to frame filters (@pxref{Frame
2023 Filter API}). Frame decorators are applied by a frame filter and can
2024 only be used in conjunction with frame filters.
2026 The purpose of a frame decorator is to customize the printed content
2027 of each @code{gdb.Frame} in commands where frame filters are executed.
2028 This concept is called decorating a frame. Frame decorators decorate
2029 a @code{gdb.Frame} with Python code contained within each API call.
2030 This separates the actual data contained in a @code{gdb.Frame} from
2031 the decorated data produced by a frame decorator. This abstraction is
2032 necessary to maintain integrity of the data contained in each
2035 Frame decorators have a mandatory interface, defined below.
2037 @value{GDBN} already contains a frame decorator called
2038 @code{FrameDecorator}. This contains substantial amounts of
2039 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
2040 recommended that other frame decorators inherit and extend this
2041 object, and only to override the methods needed.
2043 @tindex gdb.FrameDecorator
2044 @code{FrameDecorator} is defined in the Python module
2045 @code{gdb.FrameDecorator}, so your code can import it like:
2047 from gdb.FrameDecorator import FrameDecorator
2050 @defun FrameDecorator.elided (self)
2052 The @code{elided} method groups frames together in a hierarchical
2053 system. An example would be an interpreter, where multiple low-level
2054 frames make up a single call in the interpreted language. In this
2055 example, the frame filter would elide the low-level frames and present
2056 a single high-level frame, representing the call in the interpreted
2057 language, to the user.
2059 The @code{elided} function must return an iterable and this iterable
2060 must contain the frames that are being elided wrapped in a suitable
2061 frame decorator. If no frames are being elided this function may
2062 return an empty iterable, or @code{None}. Elided frames are indented
2063 from normal frames in a @code{CLI} backtrace, or in the case of
2064 @code{GDB/MI}, are placed in the @code{children} field of the eliding
2067 It is the frame filter's task to also filter out the elided frames from
2068 the source iterator. This will avoid printing the frame twice.
2071 @defun FrameDecorator.function (self)
2073 This method returns the name of the function in the frame that is to
2076 This method must return a Python string describing the function, or
2079 If this function returns @code{None}, @value{GDBN} will not print any
2080 data for this field.
2083 @defun FrameDecorator.address (self)
2085 This method returns the address of the frame that is to be printed.
2087 This method must return a Python numeric integer type of sufficient
2088 size to describe the address of the frame, or @code{None}.
2090 If this function returns a @code{None}, @value{GDBN} will not print
2091 any data for this field.
2094 @defun FrameDecorator.filename (self)
2096 This method returns the filename and path associated with this frame.
2098 This method must return a Python string containing the filename and
2099 the path to the object file backing the frame, or @code{None}.
2101 If this function returns a @code{None}, @value{GDBN} will not print
2102 any data for this field.
2105 @defun FrameDecorator.line (self):
2107 This method returns the line number associated with the current
2108 position within the function addressed by this frame.
2110 This method must return a Python integer type, or @code{None}.
2112 If this function returns a @code{None}, @value{GDBN} will not print
2113 any data for this field.
2116 @defun FrameDecorator.frame_args (self)
2119 This method must return an iterable, or @code{None}. Returning an
2120 empty iterable, or @code{None} means frame arguments will not be
2121 printed for this frame. This iterable must contain objects that
2122 implement two methods, described here.
2124 This object must implement a @code{symbol} method which takes a
2125 single @code{self} parameter and must return a @code{gdb.Symbol}
2126 (@pxref{Symbols In Python}), or a Python string. The object must also
2127 implement a @code{value} method which takes a single @code{self}
2128 parameter and must return a @code{gdb.Value} (@pxref{Values From
2129 Inferior}), a Python value, or @code{None}. If the @code{value}
2130 method returns @code{None}, and the @code{argument} method returns a
2131 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
2132 the @code{gdb.Symbol} automatically.
2137 class SymValueWrapper():
2139 def __init__(self, symbol, value):
2149 class SomeFrameDecorator()
2152 def frame_args(self):
2155 block = self.inferior_frame.block()
2159 # Iterate over all symbols in a block. Only add
2160 # symbols that are arguments.
2162 if not sym.is_argument:
2164 args.append(SymValueWrapper(sym,None))
2166 # Add example synthetic argument.
2167 args.append(SymValueWrapper(``foo'', 42))
2173 @defun FrameDecorator.frame_locals (self)
2175 This method must return an iterable or @code{None}. Returning an
2176 empty iterable, or @code{None} means frame local arguments will not be
2177 printed for this frame.
2179 The object interface, the description of the various strategies for
2180 reading frame locals, and the example are largely similar to those
2181 described in the @code{frame_args} function, (@pxref{frame_args,,The
2182 frame filter frame_args function}). Below is a modified example:
2185 class SomeFrameDecorator()
2188 def frame_locals(self):
2191 block = self.inferior_frame.block()
2195 # Iterate over all symbols in a block. Add all
2196 # symbols, except arguments.
2200 vars.append(SymValueWrapper(sym,None))
2202 # Add an example of a synthetic local variable.
2203 vars.append(SymValueWrapper(``bar'', 99))
2209 @defun FrameDecorator.inferior_frame (self):
2211 This method must return the underlying @code{gdb.Frame} that this
2212 frame decorator is decorating. @value{GDBN} requires the underlying
2213 frame for internal frame information to determine how to print certain
2214 values when printing a frame.
2217 @node Writing a Frame Filter
2218 @subsubsection Writing a Frame Filter
2219 @cindex writing a frame filter
2221 There are three basic elements that a frame filter must implement: it
2222 must correctly implement the documented interface (@pxref{Frame Filter
2223 API}), it must register itself with @value{GDBN}, and finally, it must
2224 decide if it is to work on the data provided by @value{GDBN}. In all
2225 cases, whether it works on the iterator or not, each frame filter must
2226 return an iterator. A bare-bones frame filter follows the pattern in
2227 the following example.
2232 class FrameFilter():
2235 # Frame filter attribute creation.
2237 # 'name' is the name of the filter that GDB will display.
2239 # 'priority' is the priority of the filter relative to other
2242 # 'enabled' is a boolean that indicates whether this filter is
2243 # enabled and should be executed.
2249 # Register this frame filter with the global frame_filters
2251 gdb.frame_filters[self.name] = self
2253 def filter(self, frame_iter):
2254 # Just return the iterator.
2258 The frame filter in the example above implements the three
2259 requirements for all frame filters. It implements the API, self
2260 registers, and makes a decision on the iterator (in this case, it just
2261 returns the iterator untouched).
2263 The first step is attribute creation and assignment, and as shown in
2264 the comments the filter assigns the following attributes: @code{name},
2265 @code{priority} and whether the filter should be enabled with the
2266 @code{enabled} attribute.
2268 The second step is registering the frame filter with the dictionary or
2269 dictionaries that the frame filter has interest in. As shown in the
2270 comments, this filter just registers itself with the global dictionary
2271 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
2272 is a dictionary that is initialized in the @code{gdb} module when
2273 @value{GDBN} starts. What dictionary a filter registers with is an
2274 important consideration. Generally, if a filter is specific to a set
2275 of code, it should be registered either in the @code{objfile} or
2276 @code{progspace} dictionaries as they are specific to the program
2277 currently loaded in @value{GDBN}. The global dictionary is always
2278 present in @value{GDBN} and is never unloaded. Any filters registered
2279 with the global dictionary will exist until @value{GDBN} exits. To
2280 avoid filters that may conflict, it is generally better to register
2281 frame filters against the dictionaries that more closely align with
2282 the usage of the filter currently in question. @xref{Python
2283 Auto-loading}, for further information on auto-loading Python scripts.
2285 @value{GDBN} takes a hands-off approach to frame filter registration,
2286 therefore it is the frame filter's responsibility to ensure
2287 registration has occurred, and that any exceptions are handled
2288 appropriately. In particular, you may wish to handle exceptions
2289 relating to Python dictionary key uniqueness. It is mandatory that
2290 the dictionary key is the same as frame filter's @code{name}
2291 attribute. When a user manages frame filters (@pxref{Frame Filter
2292 Management}), the names @value{GDBN} will display are those contained
2293 in the @code{name} attribute.
2295 The final step of this example is the implementation of the
2296 @code{filter} method. As shown in the example comments, we define the
2297 @code{filter} method and note that the method must take an iterator,
2298 and also must return an iterator. In this bare-bones example, the
2299 frame filter is not very useful as it just returns the iterator
2300 untouched. However this is a valid operation for frame filters that
2301 have the @code{enabled} attribute set, but decide not to operate on
2304 In the next example, the frame filter operates on all frames and
2305 utilizes a frame decorator to perform some work on the frames.
2306 @xref{Frame Decorator API}, for further information on the frame
2307 decorator interface.
2309 This example works on inlined frames. It highlights frames which are
2310 inlined by tagging them with an ``[inlined]'' tag. By applying a
2311 frame decorator to all frames with the Python @code{itertools imap}
2312 method, the example defers actions to the frame decorator. Frame
2313 decorators are only processed when @value{GDBN} prints the backtrace.
2315 This introduces a new decision making topic: whether to perform
2316 decision making operations at the filtering step, or at the printing
2317 step. In this example's approach, it does not perform any filtering
2318 decisions at the filtering step beyond mapping a frame decorator to
2319 each frame. This allows the actual decision making to be performed
2320 when each frame is printed. This is an important consideration, and
2321 well worth reflecting upon when designing a frame filter. An issue
2322 that frame filters should avoid is unwinding the stack if possible.
2323 Some stacks can run very deep, into the tens of thousands in some
2324 cases. To search every frame to determine if it is inlined ahead of
2325 time may be too expensive at the filtering step. The frame filter
2326 cannot know how many frames it has to iterate over, and it would have
2327 to iterate through them all. This ends up duplicating effort as
2328 @value{GDBN} performs this iteration when it prints the frames.
2330 In this example decision making can be deferred to the printing step.
2331 As each frame is printed, the frame decorator can examine each frame
2332 in turn when @value{GDBN} iterates. From a performance viewpoint,
2333 this is the most appropriate decision to make as it avoids duplicating
2334 the effort that the printing step would undertake anyway. Also, if
2335 there are many frame filters unwinding the stack during filtering, it
2336 can substantially delay the printing of the backtrace which will
2337 result in large memory usage, and a poor user experience.
2340 class InlineFilter():
2343 self.name = "InlinedFrameFilter"
2346 gdb.frame_filters[self.name] = self
2348 def filter(self, frame_iter):
2349 frame_iter = itertools.imap(InlinedFrameDecorator,
2354 This frame filter is somewhat similar to the earlier example, except
2355 that the @code{filter} method applies a frame decorator object called
2356 @code{InlinedFrameDecorator} to each element in the iterator. The
2357 @code{imap} Python method is light-weight. It does not proactively
2358 iterate over the iterator, but rather creates a new iterator which
2359 wraps the existing one.
2361 Below is the frame decorator for this example.
2364 class InlinedFrameDecorator(FrameDecorator):
2366 def __init__(self, fobj):
2367 super(InlinedFrameDecorator, self).__init__(fobj)
2370 frame = self.inferior_frame()
2371 name = str(frame.name())
2373 if frame.type() == gdb.INLINE_FRAME:
2374 name = name + " [inlined]"
2379 This frame decorator only defines and overrides the @code{function}
2380 method. It lets the supplied @code{FrameDecorator}, which is shipped
2381 with @value{GDBN}, perform the other work associated with printing
2384 The combination of these two objects create this output from a
2388 #0 0x004004e0 in bar () at inline.c:11
2389 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2390 #2 0x00400566 in main () at inline.c:31
2393 So in the case of this example, a frame decorator is applied to all
2394 frames, regardless of whether they may be inlined or not. As
2395 @value{GDBN} iterates over the iterator produced by the frame filters,
2396 @value{GDBN} executes each frame decorator which then makes a decision
2397 on what to print in the @code{function} callback. Using a strategy
2398 like this is a way to defer decisions on the frame content to printing
2401 @subheading Eliding Frames
2403 It might be that the above example is not desirable for representing
2404 inlined frames, and a hierarchical approach may be preferred. If we
2405 want to hierarchically represent frames, the @code{elided} frame
2406 decorator interface might be preferable.
2408 This example approaches the issue with the @code{elided} method. This
2409 example is quite long, but very simplistic. It is out-of-scope for
2410 this section to write a complete example that comprehensively covers
2411 all approaches of finding and printing inlined frames. However, this
2412 example illustrates the approach an author might use.
2414 This example comprises of three sections.
2417 class InlineFrameFilter():
2420 self.name = "InlinedFrameFilter"
2423 gdb.frame_filters[self.name] = self
2425 def filter(self, frame_iter):
2426 return ElidingInlineIterator(frame_iter)
2429 This frame filter is very similar to the other examples. The only
2430 difference is this frame filter is wrapping the iterator provided to
2431 it (@code{frame_iter}) with a custom iterator called
2432 @code{ElidingInlineIterator}. This again defers actions to when
2433 @value{GDBN} prints the backtrace, as the iterator is not traversed
2436 The iterator for this example is as follows. It is in this section of
2437 the example where decisions are made on the content of the backtrace.
2440 class ElidingInlineIterator:
2441 def __init__(self, ii):
2442 self.input_iterator = ii
2448 frame = next(self.input_iterator)
2450 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2454 eliding_frame = next(self.input_iterator)
2455 except StopIteration:
2457 return ElidingFrameDecorator(eliding_frame, [frame])
2460 This iterator implements the Python iterator protocol. When the
2461 @code{next} function is called (when @value{GDBN} prints each frame),
2462 the iterator checks if this frame decorator, @code{frame}, is wrapping
2463 an inlined frame. If it is not, it returns the existing frame decorator
2464 untouched. If it is wrapping an inlined frame, it assumes that the
2465 inlined frame was contained within the next oldest frame,
2466 @code{eliding_frame}, which it fetches. It then creates and returns a
2467 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2468 elided frame, and the eliding frame.
2471 class ElidingInlineDecorator(FrameDecorator):
2473 def __init__(self, frame, elided_frames):
2474 super(ElidingInlineDecorator, self).__init__(frame)
2476 self.elided_frames = elided_frames
2479 return iter(self.elided_frames)
2482 This frame decorator overrides one function and returns the inlined
2483 frame in the @code{elided} method. As before it lets
2484 @code{FrameDecorator} do the rest of the work involved in printing
2485 this frame. This produces the following output.
2488 #0 0x004004e0 in bar () at inline.c:11
2489 #2 0x00400529 in main () at inline.c:25
2490 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2493 In that output, @code{max} which has been inlined into @code{main} is
2494 printed hierarchically. Another approach would be to combine the
2495 @code{function} method, and the @code{elided} method to both print a
2496 marker in the inlined frame, and also show the hierarchical
2499 @node Unwinding Frames in Python
2500 @subsubsection Unwinding Frames in Python
2501 @cindex unwinding frames in Python
2503 In @value{GDBN} terminology ``unwinding'' is the process of finding
2504 the previous frame (that is, caller's) from the current one. An
2505 unwinder has three methods. The first one checks if it can handle
2506 given frame (``sniff'' it). For the frames it can sniff an unwinder
2507 provides two additional methods: it can return frame's ID, and it can
2508 fetch registers from the previous frame. A running @value{GDBN}
2509 mantains a list of the unwinders and calls each unwinder's sniffer in
2510 turn until it finds the one that recognizes the current frame. There
2511 is an API to register an unwinder.
2513 The unwinders that come with @value{GDBN} handle standard frames.
2514 However, mixed language applications (for example, an application
2515 running Java Virtual Machine) sometimes use frame layouts that cannot
2516 be handled by the @value{GDBN} unwinders. You can write Python code
2517 that can handle such custom frames.
2519 You implement a frame unwinder in Python as a class with which has two
2520 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2521 a single method @code{__call__}, which examines a given frame and
2522 returns an object (an instance of @code{gdb.UnwindInfo class)}
2523 describing it. If an unwinder does not recognize a frame, it should
2524 return @code{None}. The code in @value{GDBN} that enables writing
2525 unwinders in Python uses this object to return frame's ID and previous
2526 frame registers when @value{GDBN} core asks for them.
2528 An unwinder should do as little work as possible. Some otherwise
2529 innocuous operations can cause problems (even crashes, as this code is
2530 not not well-hardened yet). For example, making an inferior call from
2531 an unwinder is unadvisable, as an inferior call will reset
2532 @value{GDBN}'s stack unwinding process, potentially causing re-entrant
2535 @subheading Unwinder Input
2537 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2538 provides a method to read frame's registers:
2540 @defun PendingFrame.read_register (reg)
2541 This method returns the contents of the register @var{reg} in the
2542 frame as a @code{gdb.Value} object. For a description of the
2543 acceptable values of @var{reg} see
2544 @ref{gdbpy_frame_read_register,,Frame.read_register}. If @var{reg}
2545 does not name a register for the current architecture, this method
2546 will throw an exception.
2548 Note that this method will always return a @code{gdb.Value} for a
2549 valid register name. This does not mean that the value will be valid.
2550 For example, you may request a register that an earlier unwinder could
2551 not unwind---the value will be unavailable. Instead, the
2552 @code{gdb.Value} returned from this method will be lazy; that is, its
2553 underlying bits will not be fetched until it is first used. So,
2554 attempting to use such a value will cause an exception at the point of
2557 The type of the returned @code{gdb.Value} depends on the register and
2558 the architecture. It is common for registers to have a scalar type,
2559 like @code{long long}; but many other types are possible, such as
2560 pointer, pointer-to-function, floating point or vector types.
2563 It also provides a factory method to create a @code{gdb.UnwindInfo}
2564 instance to be returned to @value{GDBN}:
2566 @defun PendingFrame.create_unwind_info (frame_id)
2567 Returns a new @code{gdb.UnwindInfo} instance identified by given
2568 @var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2569 using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2570 determine which function will be used, as follows:
2574 The frame is identified by the given stack address and PC. The stack
2575 address must be chosen so that it is constant throughout the lifetime
2576 of the frame, so a typical choice is the value of the stack pointer at
2577 the start of the function---in the DWARF standard, this would be the
2578 ``Call Frame Address''.
2580 This is the most common case by far. The other cases are documented
2581 for completeness but are only useful in specialized situations.
2583 @item sp, pc, special
2584 The frame is identified by the stack address, the PC, and a
2585 ``special'' address. The special address is used on architectures
2586 that can have frames that do not change the stack, but which are still
2587 distinct, for example the IA-64, which has a second stack for
2588 registers. Both @var{sp} and @var{special} must be constant
2589 throughout the lifetime of the frame.
2592 The frame is identified by the stack address only. Any other stack
2593 frame with a matching @var{sp} will be considered to match this frame.
2594 Inside gdb, this is called a ``wild frame''. You will never need
2598 Each attribute value should be an instance of @code{gdb.Value}.
2602 @defun PendingFrame.architecture ()
2603 Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
2604 for this @code{gdb.PendingFrame}. This represents the architecture of
2605 the particular frame being unwound.
2608 @defun PendingFrame.level ()
2609 Return an integer, the stack frame level for this frame.
2610 @xref{Frames, ,Stack Frames}.
2613 @subheading Unwinder Output: UnwindInfo
2615 Use @code{PendingFrame.create_unwind_info} method described above to
2616 create a @code{gdb.UnwindInfo} instance. Use the following method to
2617 specify caller registers that have been saved in this frame:
2619 @defun gdb.UnwindInfo.add_saved_register (reg, value)
2620 @var{reg} identifies the register, for a description of the acceptable
2621 values see @ref{gdbpy_frame_read_register,,Frame.read_register}.
2622 @var{value} is a register value (a @code{gdb.Value} object).
2625 @subheading Unwinder Skeleton Code
2627 @value{GDBN} comes with the module containing the base @code{Unwinder}
2628 class. Derive your unwinder class from it and structure the code as
2632 from gdb.unwinders import Unwinder
2634 class FrameId(object):
2635 def __init__(self, sp, pc):
2640 class MyUnwinder(Unwinder):
2642 super(MyUnwinder, self).__init___(<expects unwinder name argument>)
2644 def __call__(pending_frame):
2645 if not <we recognize frame>:
2647 # Create UnwindInfo. Usually the frame is identified by the stack
2648 # pointer and the program counter.
2649 sp = pending_frame.read_register(<SP number>)
2650 pc = pending_frame.read_register(<PC number>)
2651 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2653 # Find the values of the registers in the caller's frame and
2654 # save them in the result:
2655 unwind_info.add_saved_register(<register>, <value>)
2658 # Return the result:
2663 @subheading Registering a Unwinder
2665 An object file, a program space, and the @value{GDBN} proper can have
2666 unwinders registered with it.
2668 The @code{gdb.unwinders} module provides the function to register a
2671 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2672 @var{locus} is specifies an object file or a program space to which
2673 @var{unwinder} is added. Passing @code{None} or @code{gdb} adds
2674 @var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
2675 added @var{unwinder} will be called before any other unwinder from the
2676 same locus. Two unwinders in the same locus cannot have the same
2677 name. An attempt to add a unwinder with already existing name raises
2678 an exception unless @var{replace} is @code{True}, in which case the
2679 old unwinder is deleted.
2682 @subheading Unwinder Precedence
2684 @value{GDBN} first calls the unwinders from all the object files in no
2685 particular order, then the unwinders from the current program space,
2686 and finally the unwinders from @value{GDBN}.
2688 @node Xmethods In Python
2689 @subsubsection Xmethods In Python
2690 @cindex xmethods in Python
2692 @dfn{Xmethods} are additional methods or replacements for existing
2693 methods of a C@t{++} class. This feature is useful for those cases
2694 where a method defined in C@t{++} source code could be inlined or
2695 optimized out by the compiler, making it unavailable to @value{GDBN}.
2696 For such cases, one can define an xmethod to serve as a replacement
2697 for the method defined in the C@t{++} source code. @value{GDBN} will
2698 then invoke the xmethod, instead of the C@t{++} method, to
2699 evaluate expressions. One can also use xmethods when debugging
2700 with core files. Moreover, when debugging live programs, invoking an
2701 xmethod need not involve running the inferior (which can potentially
2702 perturb its state). Hence, even if the C@t{++} method is available, it
2703 is better to use its replacement xmethod if one is defined.
2705 The xmethods feature in Python is available via the concepts of an
2706 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2707 implement an xmethod, one has to implement a matcher and a
2708 corresponding worker for it (more than one worker can be
2709 implemented, each catering to a different overloaded instance of the
2710 method). Internally, @value{GDBN} invokes the @code{match} method of a
2711 matcher to match the class type and method name. On a match, the
2712 @code{match} method returns a list of matching @emph{worker} objects.
2713 Each worker object typically corresponds to an overloaded instance of
2714 the xmethod. They implement a @code{get_arg_types} method which
2715 returns a sequence of types corresponding to the arguments the xmethod
2716 requires. @value{GDBN} uses this sequence of types to perform
2717 overload resolution and picks a winning xmethod worker. A winner
2718 is also selected from among the methods @value{GDBN} finds in the
2719 C@t{++} source code. Next, the winning xmethod worker and the
2720 winning C@t{++} method are compared to select an overall winner. In
2721 case of a tie between a xmethod worker and a C@t{++} method, the
2722 xmethod worker is selected as the winner. That is, if a winning
2723 xmethod worker is found to be equivalent to the winning C@t{++}
2724 method, then the xmethod worker is treated as a replacement for
2725 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2726 method. If the winning xmethod worker is the overall winner, then
2727 the corresponding xmethod is invoked via the @code{__call__} method
2728 of the worker object.
2730 If one wants to implement an xmethod as a replacement for an
2731 existing C@t{++} method, then they have to implement an equivalent
2732 xmethod which has exactly the same name and takes arguments of
2733 exactly the same type as the C@t{++} method. If the user wants to
2734 invoke the C@t{++} method even though a replacement xmethod is
2735 available for that method, then they can disable the xmethod.
2737 @xref{Xmethod API}, for API to implement xmethods in Python.
2738 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2741 @subsubsection Xmethod API
2744 The @value{GDBN} Python API provides classes, interfaces and functions
2745 to implement, register and manipulate xmethods.
2746 @xref{Xmethods In Python}.
2748 An xmethod matcher should be an instance of a class derived from
2749 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2750 object with similar interface and attributes. An instance of
2751 @code{XMethodMatcher} has the following attributes:
2754 The name of the matcher.
2758 A boolean value indicating whether the matcher is enabled or disabled.
2762 A list of named methods managed by the matcher. Each object in the list
2763 is an instance of the class @code{XMethod} defined in the module
2764 @code{gdb.xmethod}, or any object with the following attributes:
2769 Name of the xmethod which should be unique for each xmethod
2770 managed by the matcher.
2773 A boolean value indicating whether the xmethod is enabled or
2778 The class @code{XMethod} is a convenience class with same
2779 attributes as above along with the following constructor:
2781 @defun XMethod.__init__ (self, name)
2782 Constructs an enabled xmethod with name @var{name}.
2787 The @code{XMethodMatcher} class has the following methods:
2789 @defun XMethodMatcher.__init__ (self, name)
2790 Constructs an enabled xmethod matcher with name @var{name}. The
2791 @code{methods} attribute is initialized to @code{None}.
2794 @defun XMethodMatcher.match (self, class_type, method_name)
2795 Derived classes should override this method. It should return a
2796 xmethod worker object (or a sequence of xmethod worker
2797 objects) matching the @var{class_type} and @var{method_name}.
2798 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2799 is a string value. If the matcher manages named methods as listed in
2800 its @code{methods} attribute, then only those worker objects whose
2801 corresponding entries in the @code{methods} list are enabled should be
2805 An xmethod worker should be an instance of a class derived from
2806 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
2807 or support the following interface:
2809 @defun XMethodWorker.get_arg_types (self)
2810 This method returns a sequence of @code{gdb.Type} objects corresponding
2811 to the arguments that the xmethod takes. It can return an empty
2812 sequence or @code{None} if the xmethod does not take any arguments.
2813 If the xmethod takes a single argument, then a single
2814 @code{gdb.Type} object corresponding to it can be returned.
2817 @defun XMethodWorker.get_result_type (self, *args)
2818 This method returns a @code{gdb.Type} object representing the type
2819 of the result of invoking this xmethod.
2820 The @var{args} argument is the same tuple of arguments that would be
2821 passed to the @code{__call__} method of this worker.
2824 @defun XMethodWorker.__call__ (self, *args)
2825 This is the method which does the @emph{work} of the xmethod. The
2826 @var{args} arguments is the tuple of arguments to the xmethod. Each
2827 element in this tuple is a gdb.Value object. The first element is
2828 always the @code{this} pointer value.
2831 For @value{GDBN} to lookup xmethods, the xmethod matchers
2832 should be registered using the following function defined in the module
2835 @defun register_xmethod_matcher (locus, matcher, replace=False)
2836 The @code{matcher} is registered with @code{locus}, replacing an
2837 existing matcher with the same name as @code{matcher} if
2838 @code{replace} is @code{True}. @code{locus} can be a
2839 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
2840 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
2841 @code{None}. If it is @code{None}, then @code{matcher} is registered
2845 @node Writing an Xmethod
2846 @subsubsection Writing an Xmethod
2847 @cindex writing xmethods in Python
2849 Implementing xmethods in Python will require implementing xmethod
2850 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2851 the following C@t{++} class:
2857 MyClass (int a) : a_(a) @{ @}
2859 int geta (void) @{ return a_; @}
2860 int operator+ (int b);
2867 MyClass::operator+ (int b)
2874 Let us define two xmethods for the class @code{MyClass}, one
2875 replacing the method @code{geta}, and another adding an overloaded
2876 flavor of @code{operator+} which takes a @code{MyClass} argument (the
2877 C@t{++} code above already has an overloaded @code{operator+}
2878 which takes an @code{int} argument). The xmethod matcher can be
2882 class MyClass_geta(gdb.xmethod.XMethod):
2884 gdb.xmethod.XMethod.__init__(self, 'geta')
2886 def get_worker(self, method_name):
2887 if method_name == 'geta':
2888 return MyClassWorker_geta()
2891 class MyClass_sum(gdb.xmethod.XMethod):
2893 gdb.xmethod.XMethod.__init__(self, 'sum')
2895 def get_worker(self, method_name):
2896 if method_name == 'operator+':
2897 return MyClassWorker_plus()
2900 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2902 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2903 # List of methods 'managed' by this matcher
2904 self.methods = [MyClass_geta(), MyClass_sum()]
2906 def match(self, class_type, method_name):
2907 if class_type.tag != 'MyClass':
2910 for method in self.methods:
2912 worker = method.get_worker(method_name)
2914 workers.append(worker)
2920 Notice that the @code{match} method of @code{MyClassMatcher} returns
2921 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
2922 method, and a worker object of type @code{MyClassWorker_plus} for the
2923 @code{operator+} method. This is done indirectly via helper classes
2924 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
2925 @code{methods} attribute in a matcher as it is optional. However, if a
2926 matcher manages more than one xmethod, it is a good practice to list the
2927 xmethods in the @code{methods} attribute of the matcher. This will then
2928 facilitate enabling and disabling individual xmethods via the
2929 @code{enable/disable} commands. Notice also that a worker object is
2930 returned only if the corresponding entry in the @code{methods} attribute
2931 of the matcher is enabled.
2933 The implementation of the worker classes returned by the matcher setup
2934 above is as follows:
2937 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
2938 def get_arg_types(self):
2941 def get_result_type(self, obj):
2942 return gdb.lookup_type('int')
2944 def __call__(self, obj):
2948 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
2949 def get_arg_types(self):
2950 return gdb.lookup_type('MyClass')
2952 def get_result_type(self, obj):
2953 return gdb.lookup_type('int')
2955 def __call__(self, obj, other):
2956 return obj['a_'] + other['a_']
2959 For @value{GDBN} to actually lookup a xmethod, it has to be
2960 registered with it. The matcher defined above is registered with
2961 @value{GDBN} globally as follows:
2964 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
2967 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
2975 then, after loading the Python script defining the xmethod matchers
2976 and workers into @code{GDBN}, invoking the method @code{geta} or using
2977 the operator @code{+} on @code{obj} will invoke the xmethods
2988 Consider another example with a C++ template class:
2995 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
2996 ~MyTemplate () @{ delete [] data_; @}
2998 int footprint (void)
3000 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
3009 Let us implement an xmethod for the above class which serves as a
3010 replacement for the @code{footprint} method. The full code listing
3011 of the xmethod workers and xmethod matchers is as follows:
3014 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
3015 def __init__(self, class_type):
3016 self.class_type = class_type
3018 def get_arg_types(self):
3021 def get_result_type(self):
3022 return gdb.lookup_type('int')
3024 def __call__(self, obj):
3025 return (self.class_type.sizeof +
3027 self.class_type.template_argument(0).sizeof)
3030 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
3032 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
3034 def match(self, class_type, method_name):
3035 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
3037 method_name == 'footprint'):
3038 return MyTemplateWorker_footprint(class_type)
3041 Notice that, in this example, we have not used the @code{methods}
3042 attribute of the matcher as the matcher manages only one xmethod. The
3043 user can enable/disable this xmethod by enabling/disabling the matcher
3046 @node Inferiors In Python
3047 @subsubsection Inferiors In Python
3048 @cindex inferiors in Python
3050 @findex gdb.Inferior
3051 Programs which are being run under @value{GDBN} are called inferiors
3052 (@pxref{Inferiors Connections and Programs}). Python scripts can access
3053 information about and manipulate inferiors controlled by @value{GDBN}
3054 via objects of the @code{gdb.Inferior} class.
3056 The following inferior-related functions are available in the @code{gdb}
3059 @defun gdb.inferiors ()
3060 Return a tuple containing all inferior objects.
3063 @defun gdb.selected_inferior ()
3064 Return an object representing the current inferior.
3067 A @code{gdb.Inferior} object has the following attributes:
3069 @defvar Inferior.num
3070 ID of inferior, as assigned by GDB.
3073 @defvar Inferior.connection_num
3074 ID of inferior's connection as assigned by @value{GDBN}, or None if
3075 the inferior is not connected to a target.
3076 @xref{Inferiors Connections and Programs}.
3079 @defvar Inferior.pid
3080 Process ID of the inferior, as assigned by the underlying operating
3084 @defvar Inferior.was_attached
3085 Boolean signaling whether the inferior was created using `attach', or
3086 started by @value{GDBN} itself.
3089 @defvar Inferior.progspace
3090 The inferior's program space. @xref{Progspaces In Python}.
3093 A @code{gdb.Inferior} object has the following methods:
3095 @defun Inferior.is_valid ()
3096 Returns @code{True} if the @code{gdb.Inferior} object is valid,
3097 @code{False} if not. A @code{gdb.Inferior} object will become invalid
3098 if the inferior no longer exists within @value{GDBN}. All other
3099 @code{gdb.Inferior} methods will throw an exception if it is invalid
3100 at the time the method is called.
3103 @defun Inferior.threads ()
3104 This method returns a tuple holding all the threads which are valid
3105 when it is called. If there are no valid threads, the method will
3106 return an empty tuple.
3109 @defun Inferior.architecture ()
3110 Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
3111 for this inferior. This represents the architecture of the inferior
3112 as a whole. Some platforms can have multiple architectures in a
3113 single address space, so this may not match the architecture of a
3114 particular frame (@pxref{Frames In Python}).
3117 @findex Inferior.read_memory
3118 @defun Inferior.read_memory (address, length)
3119 Read @var{length} addressable memory units from the inferior, starting at
3120 @var{address}. Returns a buffer object, which behaves much like an array
3121 or a string. It can be modified and given to the
3122 @code{Inferior.write_memory} function. In Python 3, the return
3123 value is a @code{memoryview} object.
3126 @findex Inferior.write_memory
3127 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
3128 Write the contents of @var{buffer} to the inferior, starting at
3129 @var{address}. The @var{buffer} parameter must be a Python object
3130 which supports the buffer protocol, i.e., a string, an array or the
3131 object returned from @code{Inferior.read_memory}. If given, @var{length}
3132 determines the number of addressable memory units from @var{buffer} to be
3136 @findex gdb.search_memory
3137 @defun Inferior.search_memory (address, length, pattern)
3138 Search a region of the inferior memory starting at @var{address} with
3139 the given @var{length} using the search pattern supplied in
3140 @var{pattern}. The @var{pattern} parameter must be a Python object
3141 which supports the buffer protocol, i.e., a string, an array or the
3142 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
3143 containing the address where the pattern was found, or @code{None} if
3144 the pattern could not be found.
3147 @findex Inferior.thread_from_handle
3148 @findex Inferior.thread_from_thread_handle
3149 @defun Inferior.thread_from_handle (handle)
3150 Return the thread object corresponding to @var{handle}, a thread
3151 library specific data structure such as @code{pthread_t} for pthreads
3152 library implementations.
3154 The function @code{Inferior.thread_from_thread_handle} provides
3155 the same functionality, but use of @code{Inferior.thread_from_thread_handle}
3159 @node Events In Python
3160 @subsubsection Events In Python
3161 @cindex inferior events in Python
3163 @value{GDBN} provides a general event facility so that Python code can be
3164 notified of various state changes, particularly changes that occur in
3167 An @dfn{event} is just an object that describes some state change. The
3168 type of the object and its attributes will vary depending on the details
3169 of the change. All the existing events are described below.
3171 In order to be notified of an event, you must register an event handler
3172 with an @dfn{event registry}. An event registry is an object in the
3173 @code{gdb.events} module which dispatches particular events. A registry
3174 provides methods to register and unregister event handlers:
3176 @defun EventRegistry.connect (object)
3177 Add the given callable @var{object} to the registry. This object will be
3178 called when an event corresponding to this registry occurs.
3181 @defun EventRegistry.disconnect (object)
3182 Remove the given @var{object} from the registry. Once removed, the object
3183 will no longer receive notifications of events.
3189 def exit_handler (event):
3190 print ("event type: exit")
3191 print ("exit code: %d" % (event.exit_code))
3193 gdb.events.exited.connect (exit_handler)
3196 In the above example we connect our handler @code{exit_handler} to the
3197 registry @code{events.exited}. Once connected, @code{exit_handler} gets
3198 called when the inferior exits. The argument @dfn{event} in this example is
3199 of type @code{gdb.ExitedEvent}. As you can see in the example the
3200 @code{ExitedEvent} object has an attribute which indicates the exit code of
3203 The following is a listing of the event registries that are available and
3204 details of the events they emit:
3209 Emits @code{gdb.ThreadEvent}.
3211 Some events can be thread specific when @value{GDBN} is running in non-stop
3212 mode. When represented in Python, these events all extend
3213 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
3214 events which are emitted by this or other modules might extend this event.
3215 Examples of these events are @code{gdb.BreakpointEvent} and
3216 @code{gdb.ContinueEvent}.
3218 @defvar ThreadEvent.inferior_thread
3219 In non-stop mode this attribute will be set to the specific thread which was
3220 involved in the emitted event. Otherwise, it will be set to @code{None}.
3223 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
3225 This event indicates that the inferior has been continued after a stop. For
3226 inherited attribute refer to @code{gdb.ThreadEvent} above.
3229 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
3230 @code{events.ExitedEvent} has two attributes:
3231 @defvar ExitedEvent.exit_code
3232 An integer representing the exit code, if available, which the inferior
3233 has returned. (The exit code could be unavailable if, for example,
3234 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
3235 the attribute does not exist.
3237 @defvar ExitedEvent.inferior
3238 A reference to the inferior which triggered the @code{exited} event.
3242 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
3244 Indicates that the inferior has stopped. All events emitted by this registry
3245 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
3246 will indicate the stopped thread when @value{GDBN} is running in non-stop
3247 mode. Refer to @code{gdb.ThreadEvent} above for more details.
3249 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
3251 This event indicates that the inferior or one of its threads has received as
3252 signal. @code{gdb.SignalEvent} has the following attributes:
3254 @defvar SignalEvent.stop_signal
3255 A string representing the signal received by the inferior. A list of possible
3256 signal values can be obtained by running the command @code{info signals} in
3257 the @value{GDBN} command prompt.
3260 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
3262 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
3263 been hit, and has the following attributes:
3265 @defvar BreakpointEvent.breakpoints
3266 A sequence containing references to all the breakpoints (type
3267 @code{gdb.Breakpoint}) that were hit.
3268 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
3270 @defvar BreakpointEvent.breakpoint
3271 A reference to the first breakpoint that was hit.
3272 This function is maintained for backward compatibility and is now deprecated
3273 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
3276 @item events.new_objfile
3277 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
3278 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
3280 @defvar NewObjFileEvent.new_objfile
3281 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
3282 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
3285 @item events.clear_objfiles
3286 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
3287 files for a program space has been reset.
3288 @code{gdb.ClearObjFilesEvent} has one attribute:
3290 @defvar ClearObjFilesEvent.progspace
3291 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
3292 been cleared. @xref{Progspaces In Python}.
3295 @item events.inferior_call
3296 Emits events just before and after a function in the inferior is
3297 called by @value{GDBN}. Before an inferior call, this emits an event
3298 of type @code{gdb.InferiorCallPreEvent}, and after an inferior call,
3299 this emits an event of type @code{gdb.InferiorCallPostEvent}.
3302 @tindex gdb.InferiorCallPreEvent
3303 @item @code{gdb.InferiorCallPreEvent}
3304 Indicates that a function in the inferior is about to be called.
3306 @defvar InferiorCallPreEvent.ptid
3307 The thread in which the call will be run.
3310 @defvar InferiorCallPreEvent.address
3311 The location of the function to be called.
3314 @tindex gdb.InferiorCallPostEvent
3315 @item @code{gdb.InferiorCallPostEvent}
3316 Indicates that a function in the inferior has just been called.
3318 @defvar InferiorCallPostEvent.ptid
3319 The thread in which the call was run.
3322 @defvar InferiorCallPostEvent.address
3323 The location of the function that was called.
3327 @item events.memory_changed
3328 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
3329 inferior has been modified by the @value{GDBN} user, for instance via a
3330 command like @w{@code{set *addr = value}}. The event has the following
3333 @defvar MemoryChangedEvent.address
3334 The start address of the changed region.
3337 @defvar MemoryChangedEvent.length
3338 Length in bytes of the changed region.
3341 @item events.register_changed
3342 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
3343 inferior has been modified by the @value{GDBN} user.
3345 @defvar RegisterChangedEvent.frame
3346 A gdb.Frame object representing the frame in which the register was modified.
3348 @defvar RegisterChangedEvent.regnum
3349 Denotes which register was modified.
3352 @item events.breakpoint_created
3353 This is emitted when a new breakpoint has been created. The argument
3354 that is passed is the new @code{gdb.Breakpoint} object.
3356 @item events.breakpoint_modified
3357 This is emitted when a breakpoint has been modified in some way. The
3358 argument that is passed is the new @code{gdb.Breakpoint} object.
3360 @item events.breakpoint_deleted
3361 This is emitted when a breakpoint has been deleted. The argument that
3362 is passed is the @code{gdb.Breakpoint} object. When this event is
3363 emitted, the @code{gdb.Breakpoint} object will already be in its
3364 invalid state; that is, the @code{is_valid} method will return
3367 @item events.before_prompt
3368 This event carries no payload. It is emitted each time @value{GDBN}
3369 presents a prompt to the user.
3371 @item events.new_inferior
3372 This is emitted when a new inferior is created. Note that the
3373 inferior is not necessarily running; in fact, it may not even have an
3374 associated executable.
3376 The event is of type @code{gdb.NewInferiorEvent}. This has a single
3379 @defvar NewInferiorEvent.inferior
3380 The new inferior, a @code{gdb.Inferior} object.
3383 @item events.inferior_deleted
3384 This is emitted when an inferior has been deleted. Note that this is
3385 not the same as process exit; it is notified when the inferior itself
3386 is removed, say via @code{remove-inferiors}.
3388 The event is of type @code{gdb.InferiorDeletedEvent}. This has a single
3391 @defvar NewInferiorEvent.inferior
3392 The inferior that is being removed, a @code{gdb.Inferior} object.
3395 @item events.new_thread
3396 This is emitted when @value{GDBN} notices a new thread. The event is of
3397 type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}.
3398 This has a single attribute:
3400 @defvar NewThreadEvent.inferior_thread
3406 @node Threads In Python
3407 @subsubsection Threads In Python
3408 @cindex threads in python
3410 @findex gdb.InferiorThread
3411 Python scripts can access information about, and manipulate inferior threads
3412 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
3414 The following thread-related functions are available in the @code{gdb}
3417 @findex gdb.selected_thread
3418 @defun gdb.selected_thread ()
3419 This function returns the thread object for the selected thread. If there
3420 is no selected thread, this will return @code{None}.
3423 To get the list of threads for an inferior, use the @code{Inferior.threads()}
3424 method. @xref{Inferiors In Python}.
3426 A @code{gdb.InferiorThread} object has the following attributes:
3428 @defvar InferiorThread.name
3429 The name of the thread. If the user specified a name using
3430 @code{thread name}, then this returns that name. Otherwise, if an
3431 OS-supplied name is available, then it is returned. Otherwise, this
3432 returns @code{None}.
3434 This attribute can be assigned to. The new value must be a string
3435 object, which sets the new name, or @code{None}, which removes any
3436 user-specified thread name.
3439 @defvar InferiorThread.num
3440 The per-inferior number of the thread, as assigned by GDB.
3443 @defvar InferiorThread.global_num
3444 The global ID of the thread, as assigned by GDB. You can use this to
3445 make Python breakpoints thread-specific, for example
3446 (@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
3449 @defvar InferiorThread.ptid
3450 ID of the thread, as assigned by the operating system. This attribute is a
3451 tuple containing three integers. The first is the Process ID (PID); the second
3452 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
3453 Either the LWPID or TID may be 0, which indicates that the operating system
3454 does not use that identifier.
3457 @defvar InferiorThread.inferior
3458 The inferior this thread belongs to. This attribute is represented as
3459 a @code{gdb.Inferior} object. This attribute is not writable.
3462 A @code{gdb.InferiorThread} object has the following methods:
3464 @defun InferiorThread.is_valid ()
3465 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
3466 @code{False} if not. A @code{gdb.InferiorThread} object will become
3467 invalid if the thread exits, or the inferior that the thread belongs
3468 is deleted. All other @code{gdb.InferiorThread} methods will throw an
3469 exception if it is invalid at the time the method is called.
3472 @defun InferiorThread.switch ()
3473 This changes @value{GDBN}'s currently selected thread to the one represented
3477 @defun InferiorThread.is_stopped ()
3478 Return a Boolean indicating whether the thread is stopped.
3481 @defun InferiorThread.is_running ()
3482 Return a Boolean indicating whether the thread is running.
3485 @defun InferiorThread.is_exited ()
3486 Return a Boolean indicating whether the thread is exited.
3489 @defun InferiorThread.handle ()
3490 Return the thread object's handle, represented as a Python @code{bytes}
3491 object. A @code{gdb.Value} representation of the handle may be
3492 constructed via @code{gdb.Value(bufobj, type)} where @var{bufobj} is
3493 the Python @code{bytes} representation of the handle and @var{type} is
3494 a @code{gdb.Type} for the handle type.
3497 @node Recordings In Python
3498 @subsubsection Recordings In Python
3499 @cindex recordings in python
3501 The following recordings-related functions
3502 (@pxref{Process Record and Replay}) are available in the @code{gdb}
3505 @defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
3506 Start a recording using the given @var{method} and @var{format}. If
3507 no @var{format} is given, the default format for the recording method
3508 is used. If no @var{method} is given, the default method will be used.
3509 Returns a @code{gdb.Record} object on success. Throw an exception on
3512 The following strings can be passed as @var{method}:
3518 @code{"btrace"}: Possible values for @var{format}: @code{"pt"},
3519 @code{"bts"} or leave out for default format.
3523 @defun gdb.current_recording ()
3524 Access a currently running recording. Return a @code{gdb.Record}
3525 object on success. Return @code{None} if no recording is currently
3529 @defun gdb.stop_recording ()
3530 Stop the current recording. Throw an exception if no recording is
3531 currently active. All record objects become invalid after this call.
3534 A @code{gdb.Record} object has the following attributes:
3536 @defvar Record.method
3537 A string with the current recording method, e.g.@: @code{full} or
3541 @defvar Record.format
3542 A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
3546 @defvar Record.begin
3547 A method specific instruction object representing the first instruction
3552 A method specific instruction object representing the current
3553 instruction, that is not actually part of the recording.
3556 @defvar Record.replay_position
3557 The instruction representing the current replay position. If there is
3558 no replay active, this will be @code{None}.
3561 @defvar Record.instruction_history
3562 A list with all recorded instructions.
3565 @defvar Record.function_call_history
3566 A list with all recorded function call segments.
3569 A @code{gdb.Record} object has the following methods:
3571 @defun Record.goto (instruction)
3572 Move the replay position to the given @var{instruction}.
3575 The common @code{gdb.Instruction} class that recording method specific
3576 instruction objects inherit from, has the following attributes:
3578 @defvar Instruction.pc
3579 An integer representing this instruction's address.
3582 @defvar Instruction.data
3583 A buffer with the raw instruction data. In Python 3, the return value is a
3584 @code{memoryview} object.
3587 @defvar Instruction.decoded
3588 A human readable string with the disassembled instruction.
3591 @defvar Instruction.size
3592 The size of the instruction in bytes.
3595 Additionally @code{gdb.RecordInstruction} has the following attributes:
3597 @defvar RecordInstruction.number
3598 An integer identifying this instruction. @code{number} corresponds to
3599 the numbers seen in @code{record instruction-history}
3600 (@pxref{Process Record and Replay}).
3603 @defvar RecordInstruction.sal
3604 A @code{gdb.Symtab_and_line} object representing the associated symtab
3605 and line of this instruction. May be @code{None} if no debug information is
3609 @defvar RecordInstruction.is_speculative
3610 A boolean indicating whether the instruction was executed speculatively.
3613 If an error occured during recording or decoding a recording, this error is
3614 represented by a @code{gdb.RecordGap} object in the instruction list. It has
3615 the following attributes:
3617 @defvar RecordGap.number
3618 An integer identifying this gap. @code{number} corresponds to the numbers seen
3619 in @code{record instruction-history} (@pxref{Process Record and Replay}).
3622 @defvar RecordGap.error_code
3623 A numerical representation of the reason for the gap. The value is specific to
3624 the current recording method.
3627 @defvar RecordGap.error_string
3628 A human readable string with the reason for the gap.
3631 A @code{gdb.RecordFunctionSegment} object has the following attributes:
3633 @defvar RecordFunctionSegment.number
3634 An integer identifying this function segment. @code{number} corresponds to
3635 the numbers seen in @code{record function-call-history}
3636 (@pxref{Process Record and Replay}).
3639 @defvar RecordFunctionSegment.symbol
3640 A @code{gdb.Symbol} object representing the associated symbol. May be
3641 @code{None} if no debug information is available.
3644 @defvar RecordFunctionSegment.level
3645 An integer representing the function call's stack level. May be
3646 @code{None} if the function call is a gap.
3649 @defvar RecordFunctionSegment.instructions
3650 A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
3651 associated with this function call.
3654 @defvar RecordFunctionSegment.up
3655 A @code{gdb.RecordFunctionSegment} object representing the caller's
3656 function segment. If the call has not been recorded, this will be the
3657 function segment to which control returns. If neither the call nor the
3658 return have been recorded, this will be @code{None}.
3661 @defvar RecordFunctionSegment.prev
3662 A @code{gdb.RecordFunctionSegment} object representing the previous
3663 segment of this function call. May be @code{None}.
3666 @defvar RecordFunctionSegment.next
3667 A @code{gdb.RecordFunctionSegment} object representing the next segment of
3668 this function call. May be @code{None}.
3671 The following example demonstrates the usage of these objects and
3672 functions to create a function that will rewind a record to the last
3673 time a function in a different file was executed. This would typically
3674 be used to track the execution of user provided callback functions in a
3675 library which typically are not visible in a back trace.
3679 rec = gdb.current_recording ()
3683 insn = rec.instruction_history
3688 position = insn.index (rec.replay_position)
3692 filename = insn[position].sal.symtab.fullname ()
3696 for i in reversed (insn[:position]):
3698 current = i.sal.symtab.fullname ()
3702 if filename == current:
3709 Another possible application is to write a function that counts the
3710 number of code executions in a given line range. This line range can
3711 contain parts of functions or span across several functions and is not
3712 limited to be contiguous.
3715 def countrange (filename, linerange):
3718 def filter_only (file_name):
3719 for call in gdb.current_recording ().function_call_history:
3721 if file_name in call.symbol.symtab.fullname ():
3726 for c in filter_only (filename):
3727 for i in c.instructions:
3729 if i.sal.line in linerange:
3738 @node Commands In Python
3739 @subsubsection Commands In Python
3741 @cindex commands in python
3742 @cindex python commands
3743 You can implement new @value{GDBN} CLI commands in Python. A CLI
3744 command is implemented using an instance of the @code{gdb.Command}
3745 class, most commonly using a subclass.
3747 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
3748 The object initializer for @code{Command} registers the new command
3749 with @value{GDBN}. This initializer is normally invoked from the
3750 subclass' own @code{__init__} method.
3752 @var{name} is the name of the command. If @var{name} consists of
3753 multiple words, then the initial words are looked for as prefix
3754 commands. In this case, if one of the prefix commands does not exist,
3755 an exception is raised.
3757 There is no support for multi-line commands.
3759 @var{command_class} should be one of the @samp{COMMAND_} constants
3760 defined below. This argument tells @value{GDBN} how to categorize the
3761 new command in the help system.
3763 @var{completer_class} is an optional argument. If given, it should be
3764 one of the @samp{COMPLETE_} constants defined below. This argument
3765 tells @value{GDBN} how to perform completion for this command. If not
3766 given, @value{GDBN} will attempt to complete using the object's
3767 @code{complete} method (see below); if no such method is found, an
3768 error will occur when completion is attempted.
3770 @var{prefix} is an optional argument. If @code{True}, then the new
3771 command is a prefix command; sub-commands of this command may be
3774 The help text for the new command is taken from the Python
3775 documentation string for the command's class, if there is one. If no
3776 documentation string is provided, the default value ``This command is
3777 not documented.'' is used.
3780 @cindex don't repeat Python command
3781 @defun Command.dont_repeat ()
3782 By default, a @value{GDBN} command is repeated when the user enters a
3783 blank line at the command prompt. A command can suppress this
3784 behavior by invoking the @code{dont_repeat} method. This is similar
3785 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
3788 @defun Command.invoke (argument, from_tty)
3789 This method is called by @value{GDBN} when this command is invoked.
3791 @var{argument} is a string. It is the argument to the command, after
3792 leading and trailing whitespace has been stripped.
3794 @var{from_tty} is a boolean argument. When true, this means that the
3795 command was entered by the user at the terminal; when false it means
3796 that the command came from elsewhere.
3798 If this method throws an exception, it is turned into a @value{GDBN}
3799 @code{error} call. Otherwise, the return value is ignored.
3801 @findex gdb.string_to_argv
3802 To break @var{argument} up into an argv-like string use
3803 @code{gdb.string_to_argv}. This function behaves identically to
3804 @value{GDBN}'s internal argument lexer @code{buildargv}.
3805 It is recommended to use this for consistency.
3806 Arguments are separated by spaces and may be quoted.
3810 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
3811 ['1', '2 "3', '4 "5', "6 '7"]
3816 @cindex completion of Python commands
3817 @defun Command.complete (text, word)
3818 This method is called by @value{GDBN} when the user attempts
3819 completion on this command. All forms of completion are handled by
3820 this method, that is, the @key{TAB} and @key{M-?} key bindings
3821 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
3824 The arguments @var{text} and @var{word} are both strings; @var{text}
3825 holds the complete command line up to the cursor's location, while
3826 @var{word} holds the last word of the command line; this is computed
3827 using a word-breaking heuristic.
3829 The @code{complete} method can return several values:
3832 If the return value is a sequence, the contents of the sequence are
3833 used as the completions. It is up to @code{complete} to ensure that the
3834 contents actually do complete the word. A zero-length sequence is
3835 allowed, it means that there were no completions available. Only
3836 string elements of the sequence are used; other elements in the
3837 sequence are ignored.
3840 If the return value is one of the @samp{COMPLETE_} constants defined
3841 below, then the corresponding @value{GDBN}-internal completion
3842 function is invoked, and its result is used.
3845 All other results are treated as though there were no available
3850 When a new command is registered, it must be declared as a member of
3851 some general class of commands. This is used to classify top-level
3852 commands in the on-line help system; note that prefix commands are not
3853 listed under their own category but rather that of their top-level
3854 command. The available classifications are represented by constants
3855 defined in the @code{gdb} module:
3858 @findex COMMAND_NONE
3859 @findex gdb.COMMAND_NONE
3860 @item gdb.COMMAND_NONE
3861 The command does not belong to any particular class. A command in
3862 this category will not be displayed in any of the help categories.
3864 @findex COMMAND_RUNNING
3865 @findex gdb.COMMAND_RUNNING
3866 @item gdb.COMMAND_RUNNING
3867 The command is related to running the inferior. For example,
3868 @code{start}, @code{step}, and @code{continue} are in this category.
3869 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
3870 commands in this category.
3872 @findex COMMAND_DATA
3873 @findex gdb.COMMAND_DATA
3874 @item gdb.COMMAND_DATA
3875 The command is related to data or variables. For example,
3876 @code{call}, @code{find}, and @code{print} are in this category. Type
3877 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
3880 @findex COMMAND_STACK
3881 @findex gdb.COMMAND_STACK
3882 @item gdb.COMMAND_STACK
3883 The command has to do with manipulation of the stack. For example,
3884 @code{backtrace}, @code{frame}, and @code{return} are in this
3885 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
3886 list of commands in this category.
3888 @findex COMMAND_FILES
3889 @findex gdb.COMMAND_FILES
3890 @item gdb.COMMAND_FILES
3891 This class is used for file-related commands. For example,
3892 @code{file}, @code{list} and @code{section} are in this category.
3893 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
3894 commands in this category.
3896 @findex COMMAND_SUPPORT
3897 @findex gdb.COMMAND_SUPPORT
3898 @item gdb.COMMAND_SUPPORT
3899 This should be used for ``support facilities'', generally meaning
3900 things that are useful to the user when interacting with @value{GDBN},
3901 but not related to the state of the inferior. For example,
3902 @code{help}, @code{make}, and @code{shell} are in this category. Type
3903 @kbd{help support} at the @value{GDBN} prompt to see a list of
3904 commands in this category.
3906 @findex COMMAND_STATUS
3907 @findex gdb.COMMAND_STATUS
3908 @item gdb.COMMAND_STATUS
3909 The command is an @samp{info}-related command, that is, related to the
3910 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
3911 and @code{show} are in this category. Type @kbd{help status} at the
3912 @value{GDBN} prompt to see a list of commands in this category.
3914 @findex COMMAND_BREAKPOINTS
3915 @findex gdb.COMMAND_BREAKPOINTS
3916 @item gdb.COMMAND_BREAKPOINTS
3917 The command has to do with breakpoints. For example, @code{break},
3918 @code{clear}, and @code{delete} are in this category. Type @kbd{help
3919 breakpoints} at the @value{GDBN} prompt to see a list of commands in
3922 @findex COMMAND_TRACEPOINTS
3923 @findex gdb.COMMAND_TRACEPOINTS
3924 @item gdb.COMMAND_TRACEPOINTS
3925 The command has to do with tracepoints. For example, @code{trace},
3926 @code{actions}, and @code{tfind} are in this category. Type
3927 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
3928 commands in this category.
3931 @findex gdb.COMMAND_TUI
3932 @item gdb.COMMAND_TUI
3933 The command has to do with the text user interface (@pxref{TUI}).
3934 Type @kbd{help tui} at the @value{GDBN} prompt to see a list of
3935 commands in this category.
3937 @findex COMMAND_USER
3938 @findex gdb.COMMAND_USER
3939 @item gdb.COMMAND_USER
3940 The command is a general purpose command for the user, and typically
3941 does not fit in one of the other categories.
3942 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
3943 a list of commands in this category, as well as the list of gdb macros
3944 (@pxref{Sequences}).
3946 @findex COMMAND_OBSCURE
3947 @findex gdb.COMMAND_OBSCURE
3948 @item gdb.COMMAND_OBSCURE
3949 The command is only used in unusual circumstances, or is not of
3950 general interest to users. For example, @code{checkpoint},
3951 @code{fork}, and @code{stop} are in this category. Type @kbd{help
3952 obscure} at the @value{GDBN} prompt to see a list of commands in this
3955 @findex COMMAND_MAINTENANCE
3956 @findex gdb.COMMAND_MAINTENANCE
3957 @item gdb.COMMAND_MAINTENANCE
3958 The command is only useful to @value{GDBN} maintainers. The
3959 @code{maintenance} and @code{flushregs} commands are in this category.
3960 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
3961 commands in this category.
3964 A new command can use a predefined completion function, either by
3965 specifying it via an argument at initialization, or by returning it
3966 from the @code{complete} method. These predefined completion
3967 constants are all defined in the @code{gdb} module:
3970 @vindex COMPLETE_NONE
3971 @item gdb.COMPLETE_NONE
3972 This constant means that no completion should be done.
3974 @vindex COMPLETE_FILENAME
3975 @item gdb.COMPLETE_FILENAME
3976 This constant means that filename completion should be performed.
3978 @vindex COMPLETE_LOCATION
3979 @item gdb.COMPLETE_LOCATION
3980 This constant means that location completion should be done.
3981 @xref{Specify Location}.
3983 @vindex COMPLETE_COMMAND
3984 @item gdb.COMPLETE_COMMAND
3985 This constant means that completion should examine @value{GDBN}
3988 @vindex COMPLETE_SYMBOL
3989 @item gdb.COMPLETE_SYMBOL
3990 This constant means that completion should be done using symbol names
3993 @vindex COMPLETE_EXPRESSION
3994 @item gdb.COMPLETE_EXPRESSION
3995 This constant means that completion should be done on expressions.
3996 Often this means completing on symbol names, but some language
3997 parsers also have support for completing on field names.
4000 The following code snippet shows how a trivial CLI command can be
4001 implemented in Python:
4004 class HelloWorld (gdb.Command):
4005 """Greet the whole world."""
4007 def __init__ (self):
4008 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
4010 def invoke (self, arg, from_tty):
4011 print ("Hello, World!")
4016 The last line instantiates the class, and is necessary to trigger the
4017 registration of the command with @value{GDBN}. Depending on how the
4018 Python code is read into @value{GDBN}, you may need to import the
4019 @code{gdb} module explicitly.
4021 @node Parameters In Python
4022 @subsubsection Parameters In Python
4024 @cindex parameters in python
4025 @cindex python parameters
4026 @tindex gdb.Parameter
4028 You can implement new @value{GDBN} parameters using Python. A new
4029 parameter is implemented as an instance of the @code{gdb.Parameter}
4032 Parameters are exposed to the user via the @code{set} and
4033 @code{show} commands. @xref{Help}.
4035 There are many parameters that already exist and can be set in
4036 @value{GDBN}. Two examples are: @code{set follow fork} and
4037 @code{set charset}. Setting these parameters influences certain
4038 behavior in @value{GDBN}. Similarly, you can define parameters that
4039 can be used to influence behavior in custom Python scripts and commands.
4041 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
4042 The object initializer for @code{Parameter} registers the new
4043 parameter with @value{GDBN}. This initializer is normally invoked
4044 from the subclass' own @code{__init__} method.
4046 @var{name} is the name of the new parameter. If @var{name} consists
4047 of multiple words, then the initial words are looked for as prefix
4048 parameters. An example of this can be illustrated with the
4049 @code{set print} set of parameters. If @var{name} is
4050 @code{print foo}, then @code{print} will be searched as the prefix
4051 parameter. In this case the parameter can subsequently be accessed in
4052 @value{GDBN} as @code{set print foo}.
4054 If @var{name} consists of multiple words, and no prefix parameter group
4055 can be found, an exception is raised.
4057 @var{command-class} should be one of the @samp{COMMAND_} constants
4058 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
4059 categorize the new parameter in the help system.
4061 @var{parameter-class} should be one of the @samp{PARAM_} constants
4062 defined below. This argument tells @value{GDBN} the type of the new
4063 parameter; this information is used for input validation and
4066 If @var{parameter-class} is @code{PARAM_ENUM}, then
4067 @var{enum-sequence} must be a sequence of strings. These strings
4068 represent the possible values for the parameter.
4070 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
4071 of a fourth argument will cause an exception to be thrown.
4073 The help text for the new parameter is taken from the Python
4074 documentation string for the parameter's class, if there is one. If
4075 there is no documentation string, a default value is used.
4078 @defvar Parameter.set_doc
4079 If this attribute exists, and is a string, then its value is used as
4080 the help text for this parameter's @code{set} command. The value is
4081 examined when @code{Parameter.__init__} is invoked; subsequent changes
4085 @defvar Parameter.show_doc
4086 If this attribute exists, and is a string, then its value is used as
4087 the help text for this parameter's @code{show} command. The value is
4088 examined when @code{Parameter.__init__} is invoked; subsequent changes
4092 @defvar Parameter.value
4093 The @code{value} attribute holds the underlying value of the
4094 parameter. It can be read and assigned to just as any other
4095 attribute. @value{GDBN} does validation when assignments are made.
4098 There are two methods that may be implemented in any @code{Parameter}
4101 @defun Parameter.get_set_string (self)
4102 If this method exists, @value{GDBN} will call it when a
4103 @var{parameter}'s value has been changed via the @code{set} API (for
4104 example, @kbd{set foo off}). The @code{value} attribute has already
4105 been populated with the new value and may be used in output. This
4106 method must return a string. If the returned string is not empty,
4107 @value{GDBN} will present it to the user.
4109 If this method raises the @code{gdb.GdbError} exception
4110 (@pxref{Exception Handling}), then @value{GDBN} will print the
4111 exception's string and the @code{set} command will fail. Note,
4112 however, that the @code{value} attribute will not be reset in this
4113 case. So, if your parameter must validate values, it should store the
4114 old value internally and reset the exposed value, like so:
4117 class ExampleParam (gdb.Parameter):
4118 def __init__ (self, name):
4119 super (ExampleParam, self).__init__ (name,
4123 self.saved_value = True
4126 def get_set_string (self):
4127 if not self.validate():
4128 self.value = self.saved_value
4129 raise gdb.GdbError('Failed to validate')
4130 self.saved_value = self.value
4135 @defun Parameter.get_show_string (self, svalue)
4136 @value{GDBN} will call this method when a @var{parameter}'s
4137 @code{show} API has been invoked (for example, @kbd{show foo}). The
4138 argument @code{svalue} receives the string representation of the
4139 current value. This method must return a string.
4142 When a new parameter is defined, its type must be specified. The
4143 available types are represented by constants defined in the @code{gdb}
4147 @findex PARAM_BOOLEAN
4148 @findex gdb.PARAM_BOOLEAN
4149 @item gdb.PARAM_BOOLEAN
4150 The value is a plain boolean. The Python boolean values, @code{True}
4151 and @code{False} are the only valid values.
4153 @findex PARAM_AUTO_BOOLEAN
4154 @findex gdb.PARAM_AUTO_BOOLEAN
4155 @item gdb.PARAM_AUTO_BOOLEAN
4156 The value has three possible states: true, false, and @samp{auto}. In
4157 Python, true and false are represented using boolean constants, and
4158 @samp{auto} is represented using @code{None}.
4160 @findex PARAM_UINTEGER
4161 @findex gdb.PARAM_UINTEGER
4162 @item gdb.PARAM_UINTEGER
4163 The value is an unsigned integer. The value of 0 should be
4164 interpreted to mean ``unlimited''.
4166 @findex PARAM_INTEGER
4167 @findex gdb.PARAM_INTEGER
4168 @item gdb.PARAM_INTEGER
4169 The value is a signed integer. The value of 0 should be interpreted
4170 to mean ``unlimited''.
4172 @findex PARAM_STRING
4173 @findex gdb.PARAM_STRING
4174 @item gdb.PARAM_STRING
4175 The value is a string. When the user modifies the string, any escape
4176 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
4177 translated into corresponding characters and encoded into the current
4180 @findex PARAM_STRING_NOESCAPE
4181 @findex gdb.PARAM_STRING_NOESCAPE
4182 @item gdb.PARAM_STRING_NOESCAPE
4183 The value is a string. When the user modifies the string, escapes are
4184 passed through untranslated.
4186 @findex PARAM_OPTIONAL_FILENAME
4187 @findex gdb.PARAM_OPTIONAL_FILENAME
4188 @item gdb.PARAM_OPTIONAL_FILENAME
4189 The value is a either a filename (a string), or @code{None}.
4191 @findex PARAM_FILENAME
4192 @findex gdb.PARAM_FILENAME
4193 @item gdb.PARAM_FILENAME
4194 The value is a filename. This is just like
4195 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
4197 @findex PARAM_ZINTEGER
4198 @findex gdb.PARAM_ZINTEGER
4199 @item gdb.PARAM_ZINTEGER
4200 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
4201 is interpreted as itself.
4203 @findex PARAM_ZUINTEGER
4204 @findex gdb.PARAM_ZUINTEGER
4205 @item gdb.PARAM_ZUINTEGER
4206 The value is an unsigned integer. This is like @code{PARAM_INTEGER},
4207 except 0 is interpreted as itself, and the value cannot be negative.
4209 @findex PARAM_ZUINTEGER_UNLIMITED
4210 @findex gdb.PARAM_ZUINTEGER_UNLIMITED
4211 @item gdb.PARAM_ZUINTEGER_UNLIMITED
4212 The value is a signed integer. This is like @code{PARAM_ZUINTEGER},
4213 except the special value -1 should be interpreted to mean
4214 ``unlimited''. Other negative values are not allowed.
4217 @findex gdb.PARAM_ENUM
4218 @item gdb.PARAM_ENUM
4219 The value is a string, which must be one of a collection string
4220 constants provided when the parameter is created.
4223 @node Functions In Python
4224 @subsubsection Writing new convenience functions
4226 @cindex writing convenience functions
4227 @cindex convenience functions in python
4228 @cindex python convenience functions
4229 @tindex gdb.Function
4231 You can implement new convenience functions (@pxref{Convenience Vars})
4232 in Python. A convenience function is an instance of a subclass of the
4233 class @code{gdb.Function}.
4235 @defun Function.__init__ (name)
4236 The initializer for @code{Function} registers the new function with
4237 @value{GDBN}. The argument @var{name} is the name of the function,
4238 a string. The function will be visible to the user as a convenience
4239 variable of type @code{internal function}, whose name is the same as
4240 the given @var{name}.
4242 The documentation for the new function is taken from the documentation
4243 string for the new class.
4246 @defun Function.invoke (@var{*args})
4247 When a convenience function is evaluated, its arguments are converted
4248 to instances of @code{gdb.Value}, and then the function's
4249 @code{invoke} method is called. Note that @value{GDBN} does not
4250 predetermine the arity of convenience functions. Instead, all
4251 available arguments are passed to @code{invoke}, following the
4252 standard Python calling convention. In particular, a convenience
4253 function can have default values for parameters without ill effect.
4255 The return value of this method is used as its value in the enclosing
4256 expression. If an ordinary Python value is returned, it is converted
4257 to a @code{gdb.Value} following the usual rules.
4260 The following code snippet shows how a trivial convenience function can
4261 be implemented in Python:
4264 class Greet (gdb.Function):
4265 """Return string to greet someone.
4266 Takes a name as argument."""
4268 def __init__ (self):
4269 super (Greet, self).__init__ ("greet")
4271 def invoke (self, name):
4272 return "Hello, %s!" % name.string ()
4277 The last line instantiates the class, and is necessary to trigger the
4278 registration of the function with @value{GDBN}. Depending on how the
4279 Python code is read into @value{GDBN}, you may need to import the
4280 @code{gdb} module explicitly.
4282 Now you can use the function in an expression:
4285 (gdb) print $greet("Bob")
4289 @node Progspaces In Python
4290 @subsubsection Program Spaces In Python
4292 @cindex progspaces in python
4293 @tindex gdb.Progspace
4295 A program space, or @dfn{progspace}, represents a symbolic view
4296 of an address space.
4297 It consists of all of the objfiles of the program.
4298 @xref{Objfiles In Python}.
4299 @xref{Inferiors Connections and Programs, program spaces}, for more details
4300 about program spaces.
4302 The following progspace-related functions are available in the
4305 @findex gdb.current_progspace
4306 @defun gdb.current_progspace ()
4307 This function returns the program space of the currently selected inferior.
4308 @xref{Inferiors Connections and Programs}. This is identical to
4309 @code{gdb.selected_inferior().progspace} (@pxref{Inferiors In Python}) and is
4310 included for historical compatibility.
4313 @findex gdb.progspaces
4314 @defun gdb.progspaces ()
4315 Return a sequence of all the progspaces currently known to @value{GDBN}.
4318 Each progspace is represented by an instance of the @code{gdb.Progspace}
4321 @defvar Progspace.filename
4322 The file name of the progspace as a string.
4325 @defvar Progspace.pretty_printers
4326 The @code{pretty_printers} attribute is a list of functions. It is
4327 used to look up pretty-printers. A @code{Value} is passed to each
4328 function in order; if the function returns @code{None}, then the
4329 search continues. Otherwise, the return value should be an object
4330 which is used to format the value. @xref{Pretty Printing API}, for more
4334 @defvar Progspace.type_printers
4335 The @code{type_printers} attribute is a list of type printer objects.
4336 @xref{Type Printing API}, for more information.
4339 @defvar Progspace.frame_filters
4340 The @code{frame_filters} attribute is a dictionary of frame filter
4341 objects. @xref{Frame Filter API}, for more information.
4344 A program space has the following methods:
4346 @findex Progspace.block_for_pc
4347 @defun Progspace.block_for_pc (pc)
4348 Return the innermost @code{gdb.Block} containing the given @var{pc}
4349 value. If the block cannot be found for the @var{pc} value specified,
4350 the function will return @code{None}.
4353 @findex Progspace.find_pc_line
4354 @defun Progspace.find_pc_line (pc)
4355 Return the @code{gdb.Symtab_and_line} object corresponding to the
4356 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid value
4357 of @var{pc} is passed as an argument, then the @code{symtab} and
4358 @code{line} attributes of the returned @code{gdb.Symtab_and_line}
4359 object will be @code{None} and 0 respectively.
4362 @findex Progspace.is_valid
4363 @defun Progspace.is_valid ()
4364 Returns @code{True} if the @code{gdb.Progspace} object is valid,
4365 @code{False} if not. A @code{gdb.Progspace} object can become invalid
4366 if the program space file it refers to is not referenced by any
4367 inferior. All other @code{gdb.Progspace} methods will throw an
4368 exception if it is invalid at the time the method is called.
4371 @findex Progspace.objfiles
4372 @defun Progspace.objfiles ()
4373 Return a sequence of all the objfiles referenced by this program
4374 space. @xref{Objfiles In Python}.
4377 @findex Progspace.solib_name
4378 @defun Progspace.solib_name (address)
4379 Return the name of the shared library holding the given @var{address}
4380 as a string, or @code{None}.
4383 One may add arbitrary attributes to @code{gdb.Progspace} objects
4384 in the usual Python way.
4385 This is useful if, for example, one needs to do some extra record keeping
4386 associated with the program space.
4388 In this contrived example, we want to perform some processing when
4389 an objfile with a certain symbol is loaded, but we only want to do
4390 this once because it is expensive. To achieve this we record the results
4391 with the program space because we can't predict when the desired objfile
4396 def clear_objfiles_handler(event):
4397 event.progspace.expensive_computation = None
4398 def expensive(symbol):
4399 """A mock routine to perform an "expensive" computation on symbol."""
4400 print ("Computing the answer to the ultimate question ...")
4402 def new_objfile_handler(event):
4403 objfile = event.new_objfile
4404 progspace = objfile.progspace
4405 if not hasattr(progspace, 'expensive_computation') or \
4406 progspace.expensive_computation is None:
4407 # We use 'main' for the symbol to keep the example simple.
4408 # Note: There's no current way to constrain the lookup
4410 symbol = gdb.lookup_global_symbol('main')
4411 if symbol is not None:
4412 progspace.expensive_computation = expensive(symbol)
4413 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
4414 gdb.events.new_objfile.connect(new_objfile_handler)
4416 (gdb) file /tmp/hello
4417 Reading symbols from /tmp/hello...
4418 Computing the answer to the ultimate question ...
4419 (gdb) python print gdb.current_progspace().expensive_computation
4422 Starting program: /tmp/hello
4424 [Inferior 1 (process 4242) exited normally]
4427 @node Objfiles In Python
4428 @subsubsection Objfiles In Python
4430 @cindex objfiles in python
4433 @value{GDBN} loads symbols for an inferior from various
4434 symbol-containing files (@pxref{Files}). These include the primary
4435 executable file, any shared libraries used by the inferior, and any
4436 separate debug info files (@pxref{Separate Debug Files}).
4437 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
4439 The following objfile-related functions are available in the
4442 @findex gdb.current_objfile
4443 @defun gdb.current_objfile ()
4444 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
4445 sets the ``current objfile'' to the corresponding objfile. This
4446 function returns the current objfile. If there is no current objfile,
4447 this function returns @code{None}.
4450 @findex gdb.objfiles
4451 @defun gdb.objfiles ()
4452 Return a sequence of objfiles referenced by the current program space.
4453 @xref{Objfiles In Python}, and @ref{Progspaces In Python}. This is identical
4454 to @code{gdb.selected_inferior().progspace.objfiles()} and is included for
4455 historical compatibility.
4458 @findex gdb.lookup_objfile
4459 @defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
4460 Look up @var{name}, a file name or build ID, in the list of objfiles
4461 for the current program space (@pxref{Progspaces In Python}).
4462 If the objfile is not found throw the Python @code{ValueError} exception.
4464 If @var{name} is a relative file name, then it will match any
4465 source file name with the same trailing components. For example, if
4466 @var{name} is @samp{gcc/expr.c}, then it will match source file
4467 name of @file{/build/trunk/gcc/expr.c}, but not
4468 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
4470 If @var{by_build_id} is provided and is @code{True} then @var{name}
4471 is the build ID of the objfile. Otherwise, @var{name} is a file name.
4472 This is supported only on some operating systems, notably those which use
4473 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4474 about this feature, see the description of the @option{--build-id}
4475 command-line option in @ref{Options, , Command Line Options, ld,
4479 Each objfile is represented by an instance of the @code{gdb.Objfile}
4482 @defvar Objfile.filename
4483 The file name of the objfile as a string, with symbolic links resolved.
4485 The value is @code{None} if the objfile is no longer valid.
4486 See the @code{gdb.Objfile.is_valid} method, described below.
4489 @defvar Objfile.username
4490 The file name of the objfile as specified by the user as a string.
4492 The value is @code{None} if the objfile is no longer valid.
4493 See the @code{gdb.Objfile.is_valid} method, described below.
4496 @defvar Objfile.owner
4497 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
4498 object that debug info is being provided for.
4499 Otherwise this is @code{None}.
4500 Separate debug info objfiles are added with the
4501 @code{gdb.Objfile.add_separate_debug_file} method, described below.
4504 @defvar Objfile.build_id
4505 The build ID of the objfile as a string.
4506 If the objfile does not have a build ID then the value is @code{None}.
4508 This is supported only on some operating systems, notably those which use
4509 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4510 about this feature, see the description of the @option{--build-id}
4511 command-line option in @ref{Options, , Command Line Options, ld,
4515 @defvar Objfile.progspace
4516 The containing program space of the objfile as a @code{gdb.Progspace}
4517 object. @xref{Progspaces In Python}.
4520 @defvar Objfile.pretty_printers
4521 The @code{pretty_printers} attribute is a list of functions. It is
4522 used to look up pretty-printers. A @code{Value} is passed to each
4523 function in order; if the function returns @code{None}, then the
4524 search continues. Otherwise, the return value should be an object
4525 which is used to format the value. @xref{Pretty Printing API}, for more
4529 @defvar Objfile.type_printers
4530 The @code{type_printers} attribute is a list of type printer objects.
4531 @xref{Type Printing API}, for more information.
4534 @defvar Objfile.frame_filters
4535 The @code{frame_filters} attribute is a dictionary of frame filter
4536 objects. @xref{Frame Filter API}, for more information.
4539 One may add arbitrary attributes to @code{gdb.Objfile} objects
4540 in the usual Python way.
4541 This is useful if, for example, one needs to do some extra record keeping
4542 associated with the objfile.
4544 In this contrived example we record the time when @value{GDBN}
4550 def new_objfile_handler(event):
4551 # Set the time_loaded attribute of the new objfile.
4552 event.new_objfile.time_loaded = datetime.datetime.today()
4553 gdb.events.new_objfile.connect(new_objfile_handler)
4556 Reading symbols from ./hello...
4557 (gdb) python print gdb.objfiles()[0].time_loaded
4558 2014-10-09 11:41:36.770345
4561 A @code{gdb.Objfile} object has the following methods:
4563 @defun Objfile.is_valid ()
4564 Returns @code{True} if the @code{gdb.Objfile} object is valid,
4565 @code{False} if not. A @code{gdb.Objfile} object can become invalid
4566 if the object file it refers to is not loaded in @value{GDBN} any
4567 longer. All other @code{gdb.Objfile} methods will throw an exception
4568 if it is invalid at the time the method is called.
4571 @defun Objfile.add_separate_debug_file (file)
4572 Add @var{file} to the list of files that @value{GDBN} will search for
4573 debug information for the objfile.
4574 This is useful when the debug info has been removed from the program
4575 and stored in a separate file. @value{GDBN} has built-in support for
4576 finding separate debug info files (@pxref{Separate Debug Files}), but if
4577 the file doesn't live in one of the standard places that @value{GDBN}
4578 searches then this function can be used to add a debug info file
4579 from a different place.
4582 @defun Objfile.lookup_global_symbol (name @r{[}, domain@r{]})
4583 Search for a global symbol named @var{name} in this objfile. Optionally, the
4584 search scope can be restricted with the @var{domain} argument.
4585 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4586 module and described in @ref{Symbols In Python}. This function is similar to
4587 @code{gdb.lookup_global_symbol}, except that the search is limited to this
4590 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4594 @defun Objfile.lookup_static_symbol (name @r{[}, domain@r{]})
4595 Like @code{Objfile.lookup_global_symbol}, but searches for a global
4596 symbol with static linkage named @var{name} in this objfile.
4599 @node Frames In Python
4600 @subsubsection Accessing inferior stack frames from Python
4602 @cindex frames in python
4603 When the debugged program stops, @value{GDBN} is able to analyze its call
4604 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
4605 represents a frame in the stack. A @code{gdb.Frame} object is only valid
4606 while its corresponding frame exists in the inferior's stack. If you try
4607 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
4608 exception (@pxref{Exception Handling}).
4610 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
4614 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
4618 The following frame-related functions are available in the @code{gdb} module:
4620 @findex gdb.selected_frame
4621 @defun gdb.selected_frame ()
4622 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
4625 @findex gdb.newest_frame
4626 @defun gdb.newest_frame ()
4627 Return the newest frame object for the selected thread.
4630 @defun gdb.frame_stop_reason_string (reason)
4631 Return a string explaining the reason why @value{GDBN} stopped unwinding
4632 frames, as expressed by the given @var{reason} code (an integer, see the
4633 @code{unwind_stop_reason} method further down in this section).
4636 @findex gdb.invalidate_cached_frames
4637 @defun gdb.invalidate_cached_frames
4638 @value{GDBN} internally keeps a cache of the frames that have been
4639 unwound. This function invalidates this cache.
4641 This function should not generally be called by ordinary Python code.
4642 It is documented for the sake of completeness.
4645 A @code{gdb.Frame} object has the following methods:
4647 @defun Frame.is_valid ()
4648 Returns true if the @code{gdb.Frame} object is valid, false if not.
4649 A frame object can become invalid if the frame it refers to doesn't
4650 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
4651 an exception if it is invalid at the time the method is called.
4654 @defun Frame.name ()
4655 Returns the function name of the frame, or @code{None} if it can't be
4659 @defun Frame.architecture ()
4660 Returns the @code{gdb.Architecture} object corresponding to the frame's
4661 architecture. @xref{Architectures In Python}.
4664 @defun Frame.type ()
4665 Returns the type of the frame. The value can be one of:
4667 @item gdb.NORMAL_FRAME
4668 An ordinary stack frame.
4670 @item gdb.DUMMY_FRAME
4671 A fake stack frame that was created by @value{GDBN} when performing an
4672 inferior function call.
4674 @item gdb.INLINE_FRAME
4675 A frame representing an inlined function. The function was inlined
4676 into a @code{gdb.NORMAL_FRAME} that is older than this one.
4678 @item gdb.TAILCALL_FRAME
4679 A frame representing a tail call. @xref{Tail Call Frames}.
4681 @item gdb.SIGTRAMP_FRAME
4682 A signal trampoline frame. This is the frame created by the OS when
4683 it calls into a signal handler.
4685 @item gdb.ARCH_FRAME
4686 A fake stack frame representing a cross-architecture call.
4688 @item gdb.SENTINEL_FRAME
4689 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
4694 @defun Frame.unwind_stop_reason ()
4695 Return an integer representing the reason why it's not possible to find
4696 more frames toward the outermost frame. Use
4697 @code{gdb.frame_stop_reason_string} to convert the value returned by this
4698 function to a string. The value can be one of:
4701 @item gdb.FRAME_UNWIND_NO_REASON
4702 No particular reason (older frames should be available).
4704 @item gdb.FRAME_UNWIND_NULL_ID
4705 The previous frame's analyzer returns an invalid result. This is no
4706 longer used by @value{GDBN}, and is kept only for backward
4709 @item gdb.FRAME_UNWIND_OUTERMOST
4710 This frame is the outermost.
4712 @item gdb.FRAME_UNWIND_UNAVAILABLE
4713 Cannot unwind further, because that would require knowing the
4714 values of registers or memory that have not been collected.
4716 @item gdb.FRAME_UNWIND_INNER_ID
4717 This frame ID looks like it ought to belong to a NEXT frame,
4718 but we got it for a PREV frame. Normally, this is a sign of
4719 unwinder failure. It could also indicate stack corruption.
4721 @item gdb.FRAME_UNWIND_SAME_ID
4722 This frame has the same ID as the previous one. That means
4723 that unwinding further would almost certainly give us another
4724 frame with exactly the same ID, so break the chain. Normally,
4725 this is a sign of unwinder failure. It could also indicate
4728 @item gdb.FRAME_UNWIND_NO_SAVED_PC
4729 The frame unwinder did not find any saved PC, but we needed
4730 one to unwind further.
4732 @item gdb.FRAME_UNWIND_MEMORY_ERROR
4733 The frame unwinder caused an error while trying to access memory.
4735 @item gdb.FRAME_UNWIND_FIRST_ERROR
4736 Any stop reason greater or equal to this value indicates some kind
4737 of error. This special value facilitates writing code that tests
4738 for errors in unwinding in a way that will work correctly even if
4739 the list of the other values is modified in future @value{GDBN}
4740 versions. Using it, you could write:
4742 reason = gdb.selected_frame().unwind_stop_reason ()
4743 reason_str = gdb.frame_stop_reason_string (reason)
4744 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
4745 print ("An error occured: %s" % reason_str)
4752 Returns the frame's resume address.
4755 @defun Frame.block ()
4756 Return the frame's code block. @xref{Blocks In Python}. If the frame
4757 does not have a block -- for example, if there is no debugging
4758 information for the code in question -- then this will throw an
4762 @defun Frame.function ()
4763 Return the symbol for the function corresponding to this frame.
4764 @xref{Symbols In Python}.
4767 @defun Frame.older ()
4768 Return the frame that called this frame.
4771 @defun Frame.newer ()
4772 Return the frame called by this frame.
4775 @defun Frame.find_sal ()
4776 Return the frame's symtab and line object.
4777 @xref{Symbol Tables In Python}.
4780 @anchor{gdbpy_frame_read_register}
4781 @defun Frame.read_register (register)
4782 Return the value of @var{register} in this frame. Returns a
4783 @code{Gdb.Value} object. Throws an exception if @var{register} does
4784 not exist. The @var{register} argument must be one of the following:
4787 A string that is the name of a valid register (e.g., @code{'sp'} or
4790 A @code{gdb.RegisterDescriptor} object (@pxref{Registers In Python}).
4792 A @value{GDBN} internal, platform specific number. Using these
4793 numbers is supported for historic reasons, but is not recommended as
4794 future changes to @value{GDBN} could change the mapping between
4795 numbers and the registers they represent, breaking any Python code
4796 that uses the platform-specific numbers. The numbers are usually
4797 found in the corresponding @file{@var{platform}-tdep.h} file in the
4798 @value{GDBN} source tree.
4800 Using a string to access registers will be slightly slower than the
4801 other two methods as @value{GDBN} must look up the mapping between
4802 name and internal register number. If performance is critical
4803 consider looking up and caching a @code{gdb.RegisterDescriptor}
4807 @defun Frame.read_var (variable @r{[}, block@r{]})
4808 Return the value of @var{variable} in this frame. If the optional
4809 argument @var{block} is provided, search for the variable from that
4810 block; otherwise start at the frame's current block (which is
4811 determined by the frame's current program counter). The @var{variable}
4812 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
4813 @code{gdb.Block} object.
4816 @defun Frame.select ()
4817 Set this frame to be the selected frame. @xref{Stack, ,Examining the
4821 @defun Frame.level ()
4822 Return an integer, the stack frame level for this frame. @xref{Frames, ,Stack Frames}.
4825 @node Blocks In Python
4826 @subsubsection Accessing blocks from Python
4828 @cindex blocks in python
4831 In @value{GDBN}, symbols are stored in blocks. A block corresponds
4832 roughly to a scope in the source code. Blocks are organized
4833 hierarchically, and are represented individually in Python as a
4834 @code{gdb.Block}. Blocks rely on debugging information being
4837 A frame has a block. Please see @ref{Frames In Python}, for a more
4838 in-depth discussion of frames.
4840 The outermost block is known as the @dfn{global block}. The global
4841 block typically holds public global variables and functions.
4843 The block nested just inside the global block is the @dfn{static
4844 block}. The static block typically holds file-scoped variables and
4847 @value{GDBN} provides a method to get a block's superblock, but there
4848 is currently no way to examine the sub-blocks of a block, or to
4849 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
4852 Here is a short example that should help explain blocks:
4855 /* This is in the global block. */
4858 /* This is in the static block. */
4859 static int file_scope;
4861 /* 'function' is in the global block, and 'argument' is
4862 in a block nested inside of 'function'. */
4863 int function (int argument)
4865 /* 'local' is in a block inside 'function'. It may or may
4866 not be in the same block as 'argument'. */
4870 /* 'inner' is in a block whose superblock is the one holding
4874 /* If this call is expanded by the compiler, you may see
4875 a nested block here whose function is 'inline_function'
4876 and whose superblock is the one holding 'inner'. */
4882 A @code{gdb.Block} is iterable. The iterator returns the symbols
4883 (@pxref{Symbols In Python}) local to the block. Python programs
4884 should not assume that a specific block object will always contain a
4885 given symbol, since changes in @value{GDBN} features and
4886 infrastructure may cause symbols move across blocks in a symbol
4887 table. You can also use Python's @dfn{dictionary syntax} to access
4888 variables in this block, e.g.:
4891 symbol = some_block['variable'] # symbol is of type gdb.Symbol
4894 The following block-related functions are available in the @code{gdb}
4897 @findex gdb.block_for_pc
4898 @defun gdb.block_for_pc (pc)
4899 Return the innermost @code{gdb.Block} containing the given @var{pc}
4900 value. If the block cannot be found for the @var{pc} value specified,
4901 the function will return @code{None}. This is identical to
4902 @code{gdb.current_progspace().block_for_pc(pc)} and is included for
4903 historical compatibility.
4906 A @code{gdb.Block} object has the following methods:
4908 @defun Block.is_valid ()
4909 Returns @code{True} if the @code{gdb.Block} object is valid,
4910 @code{False} if not. A block object can become invalid if the block it
4911 refers to doesn't exist anymore in the inferior. All other
4912 @code{gdb.Block} methods will throw an exception if it is invalid at
4913 the time the method is called. The block's validity is also checked
4914 during iteration over symbols of the block.
4917 A @code{gdb.Block} object has the following attributes:
4920 The start address of the block. This attribute is not writable.
4924 One past the last address that appears in the block. This attribute
4928 @defvar Block.function
4929 The name of the block represented as a @code{gdb.Symbol}. If the
4930 block is not named, then this attribute holds @code{None}. This
4931 attribute is not writable.
4933 For ordinary function blocks, the superblock is the static block.
4934 However, you should note that it is possible for a function block to
4935 have a superblock that is not the static block -- for instance this
4936 happens for an inlined function.
4939 @defvar Block.superblock
4940 The block containing this block. If this parent block does not exist,
4941 this attribute holds @code{None}. This attribute is not writable.
4944 @defvar Block.global_block
4945 The global block associated with this block. This attribute is not
4949 @defvar Block.static_block
4950 The static block associated with this block. This attribute is not
4954 @defvar Block.is_global
4955 @code{True} if the @code{gdb.Block} object is a global block,
4956 @code{False} if not. This attribute is not
4960 @defvar Block.is_static
4961 @code{True} if the @code{gdb.Block} object is a static block,
4962 @code{False} if not. This attribute is not writable.
4965 @node Symbols In Python
4966 @subsubsection Python representation of Symbols
4968 @cindex symbols in python
4971 @value{GDBN} represents every variable, function and type as an
4972 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
4973 Similarly, Python represents these symbols in @value{GDBN} with the
4974 @code{gdb.Symbol} object.
4976 The following symbol-related functions are available in the @code{gdb}
4979 @findex gdb.lookup_symbol
4980 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
4981 This function searches for a symbol by name. The search scope can be
4982 restricted to the parameters defined in the optional domain and block
4985 @var{name} is the name of the symbol. It must be a string. The
4986 optional @var{block} argument restricts the search to symbols visible
4987 in that @var{block}. The @var{block} argument must be a
4988 @code{gdb.Block} object. If omitted, the block for the current frame
4989 is used. The optional @var{domain} argument restricts
4990 the search to the domain type. The @var{domain} argument must be a
4991 domain constant defined in the @code{gdb} module and described later
4994 The result is a tuple of two elements.
4995 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
4997 If the symbol is found, the second element is @code{True} if the symbol
4998 is a field of a method's object (e.g., @code{this} in C@t{++}),
4999 otherwise it is @code{False}.
5000 If the symbol is not found, the second element is @code{False}.
5003 @findex gdb.lookup_global_symbol
5004 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
5005 This function searches for a global symbol by name.
5006 The search scope can be restricted to by the domain argument.
5008 @var{name} is the name of the symbol. It must be a string.
5009 The optional @var{domain} argument restricts the search to the domain type.
5010 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5011 module and described later in this chapter.
5013 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
5017 @findex gdb.lookup_static_symbol
5018 @defun gdb.lookup_static_symbol (name @r{[}, domain@r{]})
5019 This function searches for a global symbol with static linkage by name.
5020 The search scope can be restricted to by the domain argument.
5022 @var{name} is the name of the symbol. It must be a string.
5023 The optional @var{domain} argument restricts the search to the domain type.
5024 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5025 module and described later in this chapter.
5027 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
5030 Note that this function will not find function-scoped static variables. To look
5031 up such variables, iterate over the variables of the function's
5032 @code{gdb.Block} and check that @code{block.addr_class} is
5033 @code{gdb.SYMBOL_LOC_STATIC}.
5035 There can be multiple global symbols with static linkage with the same
5036 name. This function will only return the first matching symbol that
5037 it finds. Which symbol is found depends on where @value{GDBN} is
5038 currently stopped, as @value{GDBN} will first search for matching
5039 symbols in the current object file, and then search all other object
5040 files. If the application is not yet running then @value{GDBN} will
5041 search all object files in the order they appear in the debug
5045 @findex gdb.lookup_static_symbols
5046 @defun gdb.lookup_static_symbols (name @r{[}, domain@r{]})
5047 Similar to @code{gdb.lookup_static_symbol}, this function searches for
5048 global symbols with static linkage by name, and optionally restricted
5049 by the domain argument. However, this function returns a list of all
5050 matching symbols found, not just the first one.
5052 @var{name} is the name of the symbol. It must be a string.
5053 The optional @var{domain} argument restricts the search to the domain type.
5054 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5055 module and described later in this chapter.
5057 The result is a list of @code{gdb.Symbol} objects which could be empty
5058 if no matching symbols were found.
5060 Note that this function will not find function-scoped static variables. To look
5061 up such variables, iterate over the variables of the function's
5062 @code{gdb.Block} and check that @code{block.addr_class} is
5063 @code{gdb.SYMBOL_LOC_STATIC}.
5066 A @code{gdb.Symbol} object has the following attributes:
5069 The type of the symbol or @code{None} if no type is recorded.
5070 This attribute is represented as a @code{gdb.Type} object.
5071 @xref{Types In Python}. This attribute is not writable.
5074 @defvar Symbol.symtab
5075 The symbol table in which the symbol appears. This attribute is
5076 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
5077 Python}. This attribute is not writable.
5081 The line number in the source code at which the symbol was defined.
5086 The name of the symbol as a string. This attribute is not writable.
5089 @defvar Symbol.linkage_name
5090 The name of the symbol, as used by the linker (i.e., may be mangled).
5091 This attribute is not writable.
5094 @defvar Symbol.print_name
5095 The name of the symbol in a form suitable for output. This is either
5096 @code{name} or @code{linkage_name}, depending on whether the user
5097 asked @value{GDBN} to display demangled or mangled names.
5100 @defvar Symbol.addr_class
5101 The address class of the symbol. This classifies how to find the value
5102 of a symbol. Each address class is a constant defined in the
5103 @code{gdb} module and described later in this chapter.
5106 @defvar Symbol.needs_frame
5107 This is @code{True} if evaluating this symbol's value requires a frame
5108 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
5109 local variables will require a frame, but other symbols will not.
5112 @defvar Symbol.is_argument
5113 @code{True} if the symbol is an argument of a function.
5116 @defvar Symbol.is_constant
5117 @code{True} if the symbol is a constant.
5120 @defvar Symbol.is_function
5121 @code{True} if the symbol is a function or a method.
5124 @defvar Symbol.is_variable
5125 @code{True} if the symbol is a variable.
5128 A @code{gdb.Symbol} object has the following methods:
5130 @defun Symbol.is_valid ()
5131 Returns @code{True} if the @code{gdb.Symbol} object is valid,
5132 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
5133 the symbol it refers to does not exist in @value{GDBN} any longer.
5134 All other @code{gdb.Symbol} methods will throw an exception if it is
5135 invalid at the time the method is called.
5138 @defun Symbol.value (@r{[}frame@r{]})
5139 Compute the value of the symbol, as a @code{gdb.Value}. For
5140 functions, this computes the address of the function, cast to the
5141 appropriate type. If the symbol requires a frame in order to compute
5142 its value, then @var{frame} must be given. If @var{frame} is not
5143 given, or if @var{frame} is invalid, then this method will throw an
5147 The available domain categories in @code{gdb.Symbol} are represented
5148 as constants in the @code{gdb} module:
5151 @vindex SYMBOL_UNDEF_DOMAIN
5152 @item gdb.SYMBOL_UNDEF_DOMAIN
5153 This is used when a domain has not been discovered or none of the
5154 following domains apply. This usually indicates an error either
5155 in the symbol information or in @value{GDBN}'s handling of symbols.
5157 @vindex SYMBOL_VAR_DOMAIN
5158 @item gdb.SYMBOL_VAR_DOMAIN
5159 This domain contains variables, function names, typedef names and enum
5162 @vindex SYMBOL_STRUCT_DOMAIN
5163 @item gdb.SYMBOL_STRUCT_DOMAIN
5164 This domain holds struct, union and enum type names.
5166 @vindex SYMBOL_LABEL_DOMAIN
5167 @item gdb.SYMBOL_LABEL_DOMAIN
5168 This domain contains names of labels (for gotos).
5170 @vindex SYMBOL_MODULE_DOMAIN
5171 @item gdb.SYMBOL_MODULE_DOMAIN
5172 This domain contains names of Fortran module types.
5174 @vindex SYMBOL_COMMON_BLOCK_DOMAIN
5175 @item gdb.SYMBOL_COMMON_BLOCK_DOMAIN
5176 This domain contains names of Fortran common blocks.
5179 The available address class categories in @code{gdb.Symbol} are represented
5180 as constants in the @code{gdb} module:
5183 @vindex SYMBOL_LOC_UNDEF
5184 @item gdb.SYMBOL_LOC_UNDEF
5185 If this is returned by address class, it indicates an error either in
5186 the symbol information or in @value{GDBN}'s handling of symbols.
5188 @vindex SYMBOL_LOC_CONST
5189 @item gdb.SYMBOL_LOC_CONST
5190 Value is constant int.
5192 @vindex SYMBOL_LOC_STATIC
5193 @item gdb.SYMBOL_LOC_STATIC
5194 Value is at a fixed address.
5196 @vindex SYMBOL_LOC_REGISTER
5197 @item gdb.SYMBOL_LOC_REGISTER
5198 Value is in a register.
5200 @vindex SYMBOL_LOC_ARG
5201 @item gdb.SYMBOL_LOC_ARG
5202 Value is an argument. This value is at the offset stored within the
5203 symbol inside the frame's argument list.
5205 @vindex SYMBOL_LOC_REF_ARG
5206 @item gdb.SYMBOL_LOC_REF_ARG
5207 Value address is stored in the frame's argument list. Just like
5208 @code{LOC_ARG} except that the value's address is stored at the
5209 offset, not the value itself.
5211 @vindex SYMBOL_LOC_REGPARM_ADDR
5212 @item gdb.SYMBOL_LOC_REGPARM_ADDR
5213 Value is a specified register. Just like @code{LOC_REGISTER} except
5214 the register holds the address of the argument instead of the argument
5217 @vindex SYMBOL_LOC_LOCAL
5218 @item gdb.SYMBOL_LOC_LOCAL
5219 Value is a local variable.
5221 @vindex SYMBOL_LOC_TYPEDEF
5222 @item gdb.SYMBOL_LOC_TYPEDEF
5223 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
5226 @vindex SYMBOL_LOC_LABEL
5227 @item gdb.SYMBOL_LOC_LABEL
5230 @vindex SYMBOL_LOC_BLOCK
5231 @item gdb.SYMBOL_LOC_BLOCK
5234 @vindex SYMBOL_LOC_CONST_BYTES
5235 @item gdb.SYMBOL_LOC_CONST_BYTES
5236 Value is a byte-sequence.
5238 @vindex SYMBOL_LOC_UNRESOLVED
5239 @item gdb.SYMBOL_LOC_UNRESOLVED
5240 Value is at a fixed address, but the address of the variable has to be
5241 determined from the minimal symbol table whenever the variable is
5244 @vindex SYMBOL_LOC_OPTIMIZED_OUT
5245 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
5246 The value does not actually exist in the program.
5248 @vindex SYMBOL_LOC_COMPUTED
5249 @item gdb.SYMBOL_LOC_COMPUTED
5250 The value's address is a computed location.
5252 @vindex SYMBOL_LOC_COMMON_BLOCK
5253 @item gdb.SYMBOL_LOC_COMMON_BLOCK
5254 The value's address is a symbol. This is only used for Fortran common
5258 @node Symbol Tables In Python
5259 @subsubsection Symbol table representation in Python
5261 @cindex symbol tables in python
5263 @tindex gdb.Symtab_and_line
5265 Access to symbol table data maintained by @value{GDBN} on the inferior
5266 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
5267 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
5268 from the @code{find_sal} method in @code{gdb.Frame} object.
5269 @xref{Frames In Python}.
5271 For more information on @value{GDBN}'s symbol table management, see
5272 @ref{Symbols, ,Examining the Symbol Table}, for more information.
5274 A @code{gdb.Symtab_and_line} object has the following attributes:
5276 @defvar Symtab_and_line.symtab
5277 The symbol table object (@code{gdb.Symtab}) for this frame.
5278 This attribute is not writable.
5281 @defvar Symtab_and_line.pc
5282 Indicates the start of the address range occupied by code for the
5283 current source line. This attribute is not writable.
5286 @defvar Symtab_and_line.last
5287 Indicates the end of the address range occupied by code for the current
5288 source line. This attribute is not writable.
5291 @defvar Symtab_and_line.line
5292 Indicates the current line number for this object. This
5293 attribute is not writable.
5296 A @code{gdb.Symtab_and_line} object has the following methods:
5298 @defun Symtab_and_line.is_valid ()
5299 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
5300 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
5301 invalid if the Symbol table and line object it refers to does not
5302 exist in @value{GDBN} any longer. All other
5303 @code{gdb.Symtab_and_line} methods will throw an exception if it is
5304 invalid at the time the method is called.
5307 A @code{gdb.Symtab} object has the following attributes:
5309 @defvar Symtab.filename
5310 The symbol table's source filename. This attribute is not writable.
5313 @defvar Symtab.objfile
5314 The symbol table's backing object file. @xref{Objfiles In Python}.
5315 This attribute is not writable.
5318 @defvar Symtab.producer
5319 The name and possibly version number of the program that
5320 compiled the code in the symbol table.
5321 The contents of this string is up to the compiler.
5322 If no producer information is available then @code{None} is returned.
5323 This attribute is not writable.
5326 A @code{gdb.Symtab} object has the following methods:
5328 @defun Symtab.is_valid ()
5329 Returns @code{True} if the @code{gdb.Symtab} object is valid,
5330 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
5331 the symbol table it refers to does not exist in @value{GDBN} any
5332 longer. All other @code{gdb.Symtab} methods will throw an exception
5333 if it is invalid at the time the method is called.
5336 @defun Symtab.fullname ()
5337 Return the symbol table's source absolute file name.
5340 @defun Symtab.global_block ()
5341 Return the global block of the underlying symbol table.
5342 @xref{Blocks In Python}.
5345 @defun Symtab.static_block ()
5346 Return the static block of the underlying symbol table.
5347 @xref{Blocks In Python}.
5350 @defun Symtab.linetable ()
5351 Return the line table associated with the symbol table.
5352 @xref{Line Tables In Python}.
5355 @node Line Tables In Python
5356 @subsubsection Manipulating line tables using Python
5358 @cindex line tables in python
5359 @tindex gdb.LineTable
5361 Python code can request and inspect line table information from a
5362 symbol table that is loaded in @value{GDBN}. A line table is a
5363 mapping of source lines to their executable locations in memory. To
5364 acquire the line table information for a particular symbol table, use
5365 the @code{linetable} function (@pxref{Symbol Tables In Python}).
5367 A @code{gdb.LineTable} is iterable. The iterator returns
5368 @code{LineTableEntry} objects that correspond to the source line and
5369 address for each line table entry. @code{LineTableEntry} objects have
5370 the following attributes:
5372 @defvar LineTableEntry.line
5373 The source line number for this line table entry. This number
5374 corresponds to the actual line of source. This attribute is not
5378 @defvar LineTableEntry.pc
5379 The address that is associated with the line table entry where the
5380 executable code for that source line resides in memory. This
5381 attribute is not writable.
5384 As there can be multiple addresses for a single source line, you may
5385 receive multiple @code{LineTableEntry} objects with matching
5386 @code{line} attributes, but with different @code{pc} attributes. The
5387 iterator is sorted in ascending @code{pc} order. Here is a small
5388 example illustrating iterating over a line table.
5391 symtab = gdb.selected_frame().find_sal().symtab
5392 linetable = symtab.linetable()
5393 for line in linetable:
5394 print ("Line: "+str(line.line)+" Address: "+hex(line.pc))
5397 This will have the following output:
5400 Line: 33 Address: 0x4005c8L
5401 Line: 37 Address: 0x4005caL
5402 Line: 39 Address: 0x4005d2L
5403 Line: 40 Address: 0x4005f8L
5404 Line: 42 Address: 0x4005ffL
5405 Line: 44 Address: 0x400608L
5406 Line: 42 Address: 0x40060cL
5407 Line: 45 Address: 0x400615L
5410 In addition to being able to iterate over a @code{LineTable}, it also
5411 has the following direct access methods:
5413 @defun LineTable.line (line)
5414 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
5415 entries in the line table for the given @var{line}, which specifies
5416 the source code line. If there are no entries for that source code
5417 @var{line}, the Python @code{None} is returned.
5420 @defun LineTable.has_line (line)
5421 Return a Python @code{Boolean} indicating whether there is an entry in
5422 the line table for this source line. Return @code{True} if an entry
5423 is found, or @code{False} if not.
5426 @defun LineTable.source_lines ()
5427 Return a Python @code{List} of the source line numbers in the symbol
5428 table. Only lines with executable code locations are returned. The
5429 contents of the @code{List} will just be the source line entries
5430 represented as Python @code{Long} values.
5433 @node Breakpoints In Python
5434 @subsubsection Manipulating breakpoints using Python
5436 @cindex breakpoints in python
5437 @tindex gdb.Breakpoint
5439 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
5442 A breakpoint can be created using one of the two forms of the
5443 @code{gdb.Breakpoint} constructor. The first one accepts a string
5444 like one would pass to the @code{break}
5445 (@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
5446 (@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
5447 create both breakpoints and watchpoints. The second accepts separate Python
5448 arguments similar to @ref{Explicit Locations}, and can only be used to create
5451 @defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]})
5452 Create a new breakpoint according to @var{spec}, which is a string naming the
5453 location of a breakpoint, or an expression that defines a watchpoint. The
5454 string should describe a location in a format recognized by the @code{break}
5455 command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
5456 watchpoint, by the @code{watch} command
5457 (@pxref{Set Watchpoints, , Setting Watchpoints}).
5459 The optional @var{type} argument specifies the type of the breakpoint to create,
5462 The optional @var{wp_class} argument defines the class of watchpoint to create,
5463 if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
5464 defaults to @code{gdb.WP_WRITE}.
5466 The optional @var{internal} argument allows the breakpoint to become invisible
5467 to the user. The breakpoint will neither be reported when created, nor will it
5468 be listed in the output from @code{info breakpoints} (but will be listed with
5469 the @code{maint info breakpoints} command).
5471 The optional @var{temporary} argument makes the breakpoint a temporary
5472 breakpoint. Temporary breakpoints are deleted after they have been hit. Any
5473 further access to the Python breakpoint after it has been hit will result in a
5474 runtime error (as that breakpoint has now been automatically deleted).
5476 The optional @var{qualified} argument is a boolean that allows interpreting
5477 the function passed in @code{spec} as a fully-qualified name. It is equivalent
5478 to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
5479 @ref{Explicit Locations}).
5483 @defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]})
5484 This second form of creating a new breakpoint specifies the explicit
5485 location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
5486 be created in the specified source file @var{source}, at the specified
5487 @var{function}, @var{label} and @var{line}.
5489 @var{internal}, @var{temporary} and @var{qualified} have the same usage as
5490 explained previously.
5493 The available types are represented by constants defined in the @code{gdb}
5497 @vindex BP_BREAKPOINT
5498 @item gdb.BP_BREAKPOINT
5499 Normal code breakpoint.
5501 @vindex BP_HARDWARE_BREAKPOINT
5502 @item gdb.BP_HARDWARE_BREAKPOINT
5503 Hardware assisted code breakpoint.
5505 @vindex BP_WATCHPOINT
5506 @item gdb.BP_WATCHPOINT
5507 Watchpoint breakpoint.
5509 @vindex BP_HARDWARE_WATCHPOINT
5510 @item gdb.BP_HARDWARE_WATCHPOINT
5511 Hardware assisted watchpoint.
5513 @vindex BP_READ_WATCHPOINT
5514 @item gdb.BP_READ_WATCHPOINT
5515 Hardware assisted read watchpoint.
5517 @vindex BP_ACCESS_WATCHPOINT
5518 @item gdb.BP_ACCESS_WATCHPOINT
5519 Hardware assisted access watchpoint.
5522 The available watchpoint types are represented by constants defined in the
5528 Read only watchpoint.
5532 Write only watchpoint.
5536 Read/Write watchpoint.
5539 @defun Breakpoint.stop (self)
5540 The @code{gdb.Breakpoint} class can be sub-classed and, in
5541 particular, you may choose to implement the @code{stop} method.
5542 If this method is defined in a sub-class of @code{gdb.Breakpoint},
5543 it will be called when the inferior reaches any location of a
5544 breakpoint which instantiates that sub-class. If the method returns
5545 @code{True}, the inferior will be stopped at the location of the
5546 breakpoint, otherwise the inferior will continue.
5548 If there are multiple breakpoints at the same location with a
5549 @code{stop} method, each one will be called regardless of the
5550 return status of the previous. This ensures that all @code{stop}
5551 methods have a chance to execute at that location. In this scenario
5552 if one of the methods returns @code{True} but the others return
5553 @code{False}, the inferior will still be stopped.
5555 You should not alter the execution state of the inferior (i.e.@:, step,
5556 next, etc.), alter the current frame context (i.e.@:, change the current
5557 active frame), or alter, add or delete any breakpoint. As a general
5558 rule, you should not alter any data within @value{GDBN} or the inferior
5561 Example @code{stop} implementation:
5564 class MyBreakpoint (gdb.Breakpoint):
5566 inf_val = gdb.parse_and_eval("foo")
5573 @defun Breakpoint.is_valid ()
5574 Return @code{True} if this @code{Breakpoint} object is valid,
5575 @code{False} otherwise. A @code{Breakpoint} object can become invalid
5576 if the user deletes the breakpoint. In this case, the object still
5577 exists, but the underlying breakpoint does not. In the cases of
5578 watchpoint scope, the watchpoint remains valid even if execution of the
5579 inferior leaves the scope of that watchpoint.
5582 @defun Breakpoint.delete ()
5583 Permanently deletes the @value{GDBN} breakpoint. This also
5584 invalidates the Python @code{Breakpoint} object. Any further access
5585 to this object's attributes or methods will raise an error.
5588 @defvar Breakpoint.enabled
5589 This attribute is @code{True} if the breakpoint is enabled, and
5590 @code{False} otherwise. This attribute is writable. You can use it to enable
5591 or disable the breakpoint.
5594 @defvar Breakpoint.silent
5595 This attribute is @code{True} if the breakpoint is silent, and
5596 @code{False} otherwise. This attribute is writable.
5598 Note that a breakpoint can also be silent if it has commands and the
5599 first command is @code{silent}. This is not reported by the
5600 @code{silent} attribute.
5603 @defvar Breakpoint.pending
5604 This attribute is @code{True} if the breakpoint is pending, and
5605 @code{False} otherwise. @xref{Set Breaks}. This attribute is
5609 @anchor{python_breakpoint_thread}
5610 @defvar Breakpoint.thread
5611 If the breakpoint is thread-specific, this attribute holds the
5612 thread's global id. If the breakpoint is not thread-specific, this
5613 attribute is @code{None}. This attribute is writable.
5616 @defvar Breakpoint.task
5617 If the breakpoint is Ada task-specific, this attribute holds the Ada task
5618 id. If the breakpoint is not task-specific (or the underlying
5619 language is not Ada), this attribute is @code{None}. This attribute
5623 @defvar Breakpoint.ignore_count
5624 This attribute holds the ignore count for the breakpoint, an integer.
5625 This attribute is writable.
5628 @defvar Breakpoint.number
5629 This attribute holds the breakpoint's number --- the identifier used by
5630 the user to manipulate the breakpoint. This attribute is not writable.
5633 @defvar Breakpoint.type
5634 This attribute holds the breakpoint's type --- the identifier used to
5635 determine the actual breakpoint type or use-case. This attribute is not
5639 @defvar Breakpoint.visible
5640 This attribute tells whether the breakpoint is visible to the user
5641 when set, or when the @samp{info breakpoints} command is run. This
5642 attribute is not writable.
5645 @defvar Breakpoint.temporary
5646 This attribute indicates whether the breakpoint was created as a
5647 temporary breakpoint. Temporary breakpoints are automatically deleted
5648 after that breakpoint has been hit. Access to this attribute, and all
5649 other attributes and functions other than the @code{is_valid}
5650 function, will result in an error after the breakpoint has been hit
5651 (as it has been automatically deleted). This attribute is not
5655 @defvar Breakpoint.hit_count
5656 This attribute holds the hit count for the breakpoint, an integer.
5657 This attribute is writable, but currently it can only be set to zero.
5660 @defvar Breakpoint.location
5661 This attribute holds the location of the breakpoint, as specified by
5662 the user. It is a string. If the breakpoint does not have a location
5663 (that is, it is a watchpoint) the attribute's value is @code{None}. This
5664 attribute is not writable.
5667 @defvar Breakpoint.expression
5668 This attribute holds a breakpoint expression, as specified by
5669 the user. It is a string. If the breakpoint does not have an
5670 expression (the breakpoint is not a watchpoint) the attribute's value
5671 is @code{None}. This attribute is not writable.
5674 @defvar Breakpoint.condition
5675 This attribute holds the condition of the breakpoint, as specified by
5676 the user. It is a string. If there is no condition, this attribute's
5677 value is @code{None}. This attribute is writable.
5680 @defvar Breakpoint.commands
5681 This attribute holds the commands attached to the breakpoint. If
5682 there are commands, this attribute's value is a string holding all the
5683 commands, separated by newlines. If there are no commands, this
5684 attribute is @code{None}. This attribute is writable.
5687 @node Finish Breakpoints in Python
5688 @subsubsection Finish Breakpoints
5690 @cindex python finish breakpoints
5691 @tindex gdb.FinishBreakpoint
5693 A finish breakpoint is a temporary breakpoint set at the return address of
5694 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
5695 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
5696 and deleted when the execution will run out of the breakpoint scope (i.e.@:
5697 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
5698 Finish breakpoints are thread specific and must be create with the right
5701 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
5702 Create a finish breakpoint at the return address of the @code{gdb.Frame}
5703 object @var{frame}. If @var{frame} is not provided, this defaults to the
5704 newest frame. The optional @var{internal} argument allows the breakpoint to
5705 become invisible to the user. @xref{Breakpoints In Python}, for further
5706 details about this argument.
5709 @defun FinishBreakpoint.out_of_scope (self)
5710 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
5711 @code{return} command, @dots{}), a function may not properly terminate, and
5712 thus never hit the finish breakpoint. When @value{GDBN} notices such a
5713 situation, the @code{out_of_scope} callback will be triggered.
5715 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
5719 class MyFinishBreakpoint (gdb.FinishBreakpoint)
5721 print ("normal finish")
5724 def out_of_scope ():
5725 print ("abnormal finish")
5729 @defvar FinishBreakpoint.return_value
5730 When @value{GDBN} is stopped at a finish breakpoint and the frame
5731 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
5732 attribute will contain a @code{gdb.Value} object corresponding to the return
5733 value of the function. The value will be @code{None} if the function return
5734 type is @code{void} or if the return value was not computable. This attribute
5738 @node Lazy Strings In Python
5739 @subsubsection Python representation of lazy strings
5741 @cindex lazy strings in python
5742 @tindex gdb.LazyString
5744 A @dfn{lazy string} is a string whose contents is not retrieved or
5745 encoded until it is needed.
5747 A @code{gdb.LazyString} is represented in @value{GDBN} as an
5748 @code{address} that points to a region of memory, an @code{encoding}
5749 that will be used to encode that region of memory, and a @code{length}
5750 to delimit the region of memory that represents the string. The
5751 difference between a @code{gdb.LazyString} and a string wrapped within
5752 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
5753 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
5754 retrieved and encoded during printing, while a @code{gdb.Value}
5755 wrapping a string is immediately retrieved and encoded on creation.
5757 A @code{gdb.LazyString} object has the following functions:
5759 @defun LazyString.value ()
5760 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
5761 will point to the string in memory, but will lose all the delayed
5762 retrieval, encoding and handling that @value{GDBN} applies to a
5763 @code{gdb.LazyString}.
5766 @defvar LazyString.address
5767 This attribute holds the address of the string. This attribute is not
5771 @defvar LazyString.length
5772 This attribute holds the length of the string in characters. If the
5773 length is -1, then the string will be fetched and encoded up to the
5774 first null of appropriate width. This attribute is not writable.
5777 @defvar LazyString.encoding
5778 This attribute holds the encoding that will be applied to the string
5779 when the string is printed by @value{GDBN}. If the encoding is not
5780 set, or contains an empty string, then @value{GDBN} will select the
5781 most appropriate encoding when the string is printed. This attribute
5785 @defvar LazyString.type
5786 This attribute holds the type that is represented by the lazy string's
5787 type. For a lazy string this is a pointer or array type. To
5788 resolve this to the lazy string's character type, use the type's
5789 @code{target} method. @xref{Types In Python}. This attribute is not
5793 @node Architectures In Python
5794 @subsubsection Python representation of architectures
5795 @cindex Python architectures
5797 @value{GDBN} uses architecture specific parameters and artifacts in a
5798 number of its various computations. An architecture is represented
5799 by an instance of the @code{gdb.Architecture} class.
5801 A @code{gdb.Architecture} class has the following methods:
5803 @defun Architecture.name ()
5804 Return the name (string value) of the architecture.
5807 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
5808 Return a list of disassembled instructions starting from the memory
5809 address @var{start_pc}. The optional arguments @var{end_pc} and
5810 @var{count} determine the number of instructions in the returned list.
5811 If both the optional arguments @var{end_pc} and @var{count} are
5812 specified, then a list of at most @var{count} disassembled instructions
5813 whose start address falls in the closed memory address interval from
5814 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
5815 specified, but @var{count} is specified, then @var{count} number of
5816 instructions starting from the address @var{start_pc} are returned. If
5817 @var{count} is not specified but @var{end_pc} is specified, then all
5818 instructions whose start address falls in the closed memory address
5819 interval from @var{start_pc} to @var{end_pc} are returned. If neither
5820 @var{end_pc} nor @var{count} are specified, then a single instruction at
5821 @var{start_pc} is returned. For all of these cases, each element of the
5822 returned list is a Python @code{dict} with the following string keys:
5827 The value corresponding to this key is a Python long integer capturing
5828 the memory address of the instruction.
5831 The value corresponding to this key is a string value which represents
5832 the instruction with assembly language mnemonics. The assembly
5833 language flavor used is the same as that specified by the current CLI
5834 variable @code{disassembly-flavor}. @xref{Machine Code}.
5837 The value corresponding to this key is the length (integer value) of the
5838 instruction in bytes.
5843 @anchor{gdbpy_architecture_registers}
5844 @defun Architecture.registers (@r{[} @var{reggroup} @r{]})
5845 Return a @code{gdb.RegisterDescriptorIterator} (@pxref{Registers In
5846 Python}) for all of the registers in @var{reggroup}, a string that is
5847 the name of a register group. If @var{reggroup} is omitted, or is the
5848 empty string, then the register group @samp{all} is assumed.
5851 @anchor{gdbpy_architecture_reggroups}
5852 @defun Architecture.register_groups ()
5853 Return a @code{gdb.RegisterGroupsIterator} (@pxref{Registers In
5854 Python}) for all of the register groups available for the
5855 @code{gdb.Architecture}.
5858 @node Registers In Python
5859 @subsubsection Registers In Python
5860 @cindex Registers In Python
5862 Python code can request from a @code{gdb.Architecture} information
5863 about the set of registers available
5864 (@pxref{gdbpy_architecture_registers,,@code{Architecture.registers}}).
5865 The register information is returned as a
5866 @code{gdb.RegisterDescriptorIterator}, which is an iterator that in
5867 turn returns @code{gdb.RegisterDescriptor} objects.
5869 A @code{gdb.RegisterDescriptor} does not provide the value of a
5870 register (@pxref{gdbpy_frame_read_register,,@code{Frame.read_register}}
5871 for reading a register's value), instead the @code{RegisterDescriptor}
5872 is a way to discover which registers are available for a particular
5875 A @code{gdb.RegisterDescriptor} has the following read-only properties:
5877 @defvar RegisterDescriptor.name
5878 The name of this register.
5881 It is also possible to lookup a register descriptor based on its name
5882 using the following @code{gdb.RegisterDescriptorIterator} function:
5884 @defun RegisterDescriptorIterator.find (@var{name})
5885 Takes @var{name} as an argument, which must be a string, and returns a
5886 @code{gdb.RegisterDescriptor} for the register with that name, or
5887 @code{None} if there is no register with that name.
5890 Python code can also request from a @code{gdb.Architecture}
5891 information about the set of register groups available on a given
5893 (@pxref{gdbpy_architecture_reggroups,,@code{Architecture.register_groups}}).
5895 Every register can be a member of zero or more register groups. Some
5896 register groups are used internally within @value{GDBN} to control
5897 things like which registers must be saved when calling into the
5898 program being debugged (@pxref{Calling,,Calling Program Functions}).
5899 Other register groups exist to allow users to easily see related sets
5900 of registers in commands like @code{info registers}
5901 (@pxref{info_registers_reggroup,,@code{info registers
5904 The register groups information is returned as a
5905 @code{gdb.RegisterGroupsIterator}, which is an iterator that in turn
5906 returns @code{gdb.RegisterGroup} objects.
5908 A @code{gdb.RegisterGroup} object has the following read-only
5911 @defvar RegisterGroup.name
5912 A string that is the name of this register group.
5915 @node TUI Windows In Python
5916 @subsubsection Implementing new TUI windows
5917 @cindex Python TUI Windows
5919 New TUI (@pxref{TUI}) windows can be implemented in Python.
5921 @findex gdb.register_window_type
5922 @defun gdb.register_window_type (@var{name}, @var{factory})
5923 Because TUI windows are created and destroyed depending on the layout
5924 the user chooses, new window types are implemented by registering a
5925 factory function with @value{GDBN}.
5927 @var{name} is the name of the new window. It's an error to try to
5928 replace one of the built-in windows, but other window types can be
5931 @var{function} is a factory function that is called to create the TUI
5932 window. This is called with a single argument of type
5933 @code{gdb.TuiWindow}, described below. It should return an object
5934 that implements the TUI window protocol, also described below.
5937 As mentioned above, when a factory function is called, it is passed
5938 an object of type @code{gdb.TuiWindow}. This object has these
5939 methods and attributes:
5941 @defun TuiWindow.is_valid ()
5942 This method returns @code{True} when this window is valid. When the
5943 user changes the TUI layout, windows no longer visible in the new
5944 layout will be destroyed. At this point, the @code{gdb.TuiWindow}
5945 will no longer be valid, and methods (and attributes) other than
5946 @code{is_valid} will throw an exception.
5948 When the TUI is disabled using @code{tui disable} (@pxref{TUI
5949 Commands,,tui disable}) the window is hidden rather than destroyed,
5950 but @code{is_valid} will still return @code{False} and other methods
5951 (and attributes) will still throw an exception.
5954 @defvar TuiWindow.width
5955 This attribute holds the width of the window. It is not writable.
5958 @defvar TuiWindow.height
5959 This attribute holds the height of the window. It is not writable.
5962 @defvar TuiWindow.title
5963 This attribute holds the window's title, a string. This is normally
5964 displayed above the window. This attribute can be modified.
5967 @defun TuiWindow.erase ()
5968 Remove all the contents of the window.
5971 @defun TuiWindow.write (@var{string} @r{[}, @var{full_window}@r{]})
5972 Write @var{string} to the window. @var{string} can contain ANSI
5973 terminal escape styling sequences; @value{GDBN} will translate these
5974 as appropriate for the terminal.
5976 If the @var{full_window} parameter is @code{True}, then @var{string}
5977 contains the full contents of the window. This is similar to calling
5978 @code{erase} before @code{write}, but avoids the flickering.
5981 The factory function that you supply should return an object
5982 conforming to the TUI window protocol. These are the method that can
5983 be called on this object, which is referred to below as the ``window
5984 object''. The methods documented below are optional; if the object
5985 does not implement one of these methods, @value{GDBN} will not attempt
5986 to call it. Additional new methods may be added to the window
5987 protocol in the future. @value{GDBN} guarantees that they will begin
5988 with a lower-case letter, so you can start implementation methods with
5989 upper-case letters or underscore to avoid any future conflicts.
5991 @defun Window.close ()
5992 When the TUI window is closed, the @code{gdb.TuiWindow} object will be
5993 put into an invalid state. At this time, @value{GDBN} will call
5994 @code{close} method on the window object.
5996 After this method is called, @value{GDBN} will discard any references
5997 it holds on this window object, and will no longer call methods on
6001 @defun Window.render ()
6002 In some situations, a TUI window can change size. For example, this
6003 can happen if the user resizes the terminal, or changes the layout.
6004 When this happens, @value{GDBN} will call the @code{render} method on
6007 If your window is intended to update in response to changes in the
6008 inferior, you will probably also want to register event listeners and
6009 send output to the @code{gdb.TuiWindow}.
6012 @defun Window.hscroll (@var{num})
6013 This is a request to scroll the window horizontally. @var{num} is the
6014 amount by which to scroll, with negative numbers meaning to scroll
6015 right. In the TUI model, it is the viewport that moves, not the
6016 contents. A positive argument should cause the viewport to move
6017 right, and so the content should appear to move to the left.
6020 @defun Window.vscroll (@var{num})
6021 This is a request to scroll the window vertically. @var{num} is the
6022 amount by which to scroll, with negative numbers meaning to scroll
6023 backward. In the TUI model, it is the viewport that moves, not the
6024 contents. A positive argument should cause the viewport to move down,
6025 and so the content should appear to move up.
6028 @defun Window.click (@var{x}, @var{y}, @var{button})
6029 This is called on a mouse click in this window. @var{x} and @var{y} are
6030 the mouse coordinates inside the window (0-based), and @var{button}
6031 specifies which mouse button was used, whose values can be 1 (left),
6032 2 (middle), or 3 (right).
6035 @node Python Auto-loading
6036 @subsection Python Auto-loading
6037 @cindex Python auto-loading
6039 When a new object file is read (for example, due to the @code{file}
6040 command, or because the inferior has loaded a shared library),
6041 @value{GDBN} will look for Python support scripts in several ways:
6042 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
6043 @xref{Auto-loading extensions}.
6045 The auto-loading feature is useful for supplying application-specific
6046 debugging commands and scripts.
6048 Auto-loading can be enabled or disabled,
6049 and the list of auto-loaded scripts can be printed.
6052 @anchor{set auto-load python-scripts}
6053 @kindex set auto-load python-scripts
6054 @item set auto-load python-scripts [on|off]
6055 Enable or disable the auto-loading of Python scripts.
6057 @anchor{show auto-load python-scripts}
6058 @kindex show auto-load python-scripts
6059 @item show auto-load python-scripts
6060 Show whether auto-loading of Python scripts is enabled or disabled.
6062 @anchor{info auto-load python-scripts}
6063 @kindex info auto-load python-scripts
6064 @cindex print list of auto-loaded Python scripts
6065 @item info auto-load python-scripts [@var{regexp}]
6066 Print the list of all Python scripts that @value{GDBN} auto-loaded.
6068 Also printed is the list of Python scripts that were mentioned in
6069 the @code{.debug_gdb_scripts} section and were either not found
6070 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
6071 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
6072 This is useful because their names are not printed when @value{GDBN}
6073 tries to load them and fails. There may be many of them, and printing
6074 an error message for each one is problematic.
6076 If @var{regexp} is supplied only Python scripts with matching names are printed.
6081 (gdb) info auto-load python-scripts
6083 Yes py-section-script.py
6084 full name: /tmp/py-section-script.py
6085 No my-foo-pretty-printers.py
6089 When reading an auto-loaded file or script, @value{GDBN} sets the
6090 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
6091 function (@pxref{Objfiles In Python}). This can be useful for
6092 registering objfile-specific pretty-printers and frame-filters.
6094 @node Python modules
6095 @subsection Python modules
6096 @cindex python modules
6098 @value{GDBN} comes with several modules to assist writing Python code.
6101 * gdb.printing:: Building and registering pretty-printers.
6102 * gdb.types:: Utilities for working with types.
6103 * gdb.prompt:: Utilities for prompt value substitution.
6107 @subsubsection gdb.printing
6108 @cindex gdb.printing
6110 This module provides a collection of utilities for working with
6114 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
6115 This class specifies the API that makes @samp{info pretty-printer},
6116 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
6117 Pretty-printers should generally inherit from this class.
6119 @item SubPrettyPrinter (@var{name})
6120 For printers that handle multiple types, this class specifies the
6121 corresponding API for the subprinters.
6123 @item RegexpCollectionPrettyPrinter (@var{name})
6124 Utility class for handling multiple printers, all recognized via
6125 regular expressions.
6126 @xref{Writing a Pretty-Printer}, for an example.
6128 @item FlagEnumerationPrinter (@var{name})
6129 A pretty-printer which handles printing of @code{enum} values. Unlike
6130 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
6131 work properly when there is some overlap between the enumeration
6132 constants. The argument @var{name} is the name of the printer and
6133 also the name of the @code{enum} type to look up.
6135 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
6136 Register @var{printer} with the pretty-printer list of @var{obj}.
6137 If @var{replace} is @code{True} then any existing copy of the printer
6138 is replaced. Otherwise a @code{RuntimeError} exception is raised
6139 if a printer with the same name already exists.
6143 @subsubsection gdb.types
6146 This module provides a collection of utilities for working with
6147 @code{gdb.Type} objects.
6150 @item get_basic_type (@var{type})
6151 Return @var{type} with const and volatile qualifiers stripped,
6152 and with typedefs and C@t{++} references converted to the underlying type.
6157 typedef const int const_int;
6159 const_int& foo_ref (foo);
6160 int main () @{ return 0; @}
6167 (gdb) python import gdb.types
6168 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
6169 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
6173 @item has_field (@var{type}, @var{field})
6174 Return @code{True} if @var{type}, assumed to be a type with fields
6175 (e.g., a structure or union), has field @var{field}.
6177 @item make_enum_dict (@var{enum_type})
6178 Return a Python @code{dictionary} type produced from @var{enum_type}.
6180 @item deep_items (@var{type})
6181 Returns a Python iterator similar to the standard
6182 @code{gdb.Type.iteritems} method, except that the iterator returned
6183 by @code{deep_items} will recursively traverse anonymous struct or
6184 union fields. For example:
6198 Then in @value{GDBN}:
6200 (@value{GDBP}) python import gdb.types
6201 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
6202 (@value{GDBP}) python print struct_a.keys ()
6204 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
6205 @{['a', 'b0', 'b1']@}
6208 @item get_type_recognizers ()
6209 Return a list of the enabled type recognizers for the current context.
6210 This is called by @value{GDBN} during the type-printing process
6211 (@pxref{Type Printing API}).
6213 @item apply_type_recognizers (recognizers, type_obj)
6214 Apply the type recognizers, @var{recognizers}, to the type object
6215 @var{type_obj}. If any recognizer returns a string, return that
6216 string. Otherwise, return @code{None}. This is called by
6217 @value{GDBN} during the type-printing process (@pxref{Type Printing
6220 @item register_type_printer (locus, printer)
6221 This is a convenience function to register a type printer
6222 @var{printer}. The printer must implement the type printer protocol.
6223 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
6224 the printer is registered with that objfile; a @code{gdb.Progspace},
6225 in which case the printer is registered with that progspace; or
6226 @code{None}, in which case the printer is registered globally.
6229 This is a base class that implements the type printer protocol. Type
6230 printers are encouraged, but not required, to derive from this class.
6231 It defines a constructor:
6233 @defmethod TypePrinter __init__ (self, name)
6234 Initialize the type printer with the given name. The new printer
6235 starts in the enabled state.
6241 @subsubsection gdb.prompt
6244 This module provides a method for prompt value-substitution.
6247 @item substitute_prompt (@var{string})
6248 Return @var{string} with escape sequences substituted by values. Some
6249 escape sequences take arguments. You can specify arguments inside
6250 ``@{@}'' immediately following the escape sequence.
6252 The escape sequences you can pass to this function are:
6256 Substitute a backslash.
6258 Substitute an ESC character.
6260 Substitute the selected frame; an argument names a frame parameter.
6262 Substitute a newline.
6264 Substitute a parameter's value; the argument names the parameter.
6266 Substitute a carriage return.
6268 Substitute the selected thread; an argument names a thread parameter.
6270 Substitute the version of GDB.
6272 Substitute the current working directory.
6274 Begin a sequence of non-printing characters. These sequences are
6275 typically used with the ESC character, and are not counted in the string
6276 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
6277 blue-colored ``(gdb)'' prompt where the length is five.
6279 End a sequence of non-printing characters.
6285 substitute_prompt ("frame: \f, args: \p@{print frame-arguments@}")
6288 @exdent will return the string:
6291 "frame: main, args: scalars"