1 @c Copyright (C) 2008--2020 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.
108 It is also possible to execute a Python script from the @value{GDBN}
112 @item source @file{script-name}
113 The script name must end with @samp{.py} and @value{GDBN} must be configured
114 to recognize the script language based on filename extension using
115 the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
119 @subsection Python API
121 @cindex programming in python
123 You can get quick online help for @value{GDBN}'s Python API by issuing
124 the command @w{@kbd{python help (gdb)}}.
126 Functions and methods which have two or more optional arguments allow
127 them to be specified using keyword syntax. This allows passing some
128 optional arguments while skipping others. Example:
129 @w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
132 * Basic Python:: Basic Python Functions.
133 * Exception Handling:: How Python exceptions are translated.
134 * Values From Inferior:: Python representation of values.
135 * Types In Python:: Python representation of types.
136 * Pretty Printing API:: Pretty-printing values.
137 * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
138 * Writing a Pretty-Printer:: Writing a Pretty-Printer.
139 * Type Printing API:: Pretty-printing types.
140 * Frame Filter API:: Filtering Frames.
141 * Frame Decorator API:: Decorating Frames.
142 * Writing a Frame Filter:: Writing a Frame Filter.
143 * Unwinding Frames in Python:: Writing frame unwinder.
144 * Xmethods In Python:: Adding and replacing methods of C++ classes.
145 * Xmethod API:: Xmethod types.
146 * Writing an Xmethod:: Writing an xmethod.
147 * Inferiors In Python:: Python representation of inferiors (processes)
148 * Events In Python:: Listening for events from @value{GDBN}.
149 * Threads In Python:: Accessing inferior threads from Python.
150 * Recordings In Python:: Accessing recordings from Python.
151 * Commands In Python:: Implementing new commands in Python.
152 * Parameters In Python:: Adding new @value{GDBN} parameters.
153 * Functions In Python:: Writing new convenience functions.
154 * Progspaces In Python:: Program spaces.
155 * Objfiles In Python:: Object files.
156 * Frames In Python:: Accessing inferior stack frames from Python.
157 * Blocks In Python:: Accessing blocks from Python.
158 * Symbols In Python:: Python representation of symbols.
159 * Symbol Tables In Python:: Python representation of symbol tables.
160 * Line Tables In Python:: Python representation of line tables.
161 * Breakpoints In Python:: Manipulating breakpoints using Python.
162 * Finish Breakpoints in Python:: Setting Breakpoints on function return
164 * Lazy Strings In Python:: Python representation of lazy strings.
165 * Architectures In Python:: Python representation of architectures.
166 * TUI Windows In Python:: Implementing new TUI windows.
170 @subsubsection Basic Python
172 @cindex python stdout
173 @cindex python pagination
174 At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
175 @code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
176 A Python program which outputs to one of these streams may have its
177 output interrupted by the user (@pxref{Screen Size}). In this
178 situation, a Python @code{KeyboardInterrupt} exception is thrown.
180 Some care must be taken when writing Python code to run in
181 @value{GDBN}. Two things worth noting in particular:
185 @value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
186 Python code must not override these, or even change the options using
187 @code{sigaction}. If your program changes the handling of these
188 signals, @value{GDBN} will most likely stop working correctly. Note
189 that it is unfortunately common for GUI toolkits to install a
190 @code{SIGCHLD} handler.
193 @value{GDBN} takes care to mark its internal file descriptors as
194 close-on-exec. However, this cannot be done in a thread-safe way on
195 all platforms. Your Python programs should be aware of this and
196 should both create new file descriptors with the close-on-exec flag
197 set and arrange to close unneeded file descriptors before starting a
201 @cindex python functions
202 @cindex python module
204 @value{GDBN} introduces a new Python module, named @code{gdb}. All
205 methods and classes added by @value{GDBN} are placed in this module.
206 @value{GDBN} automatically @code{import}s the @code{gdb} module for
207 use in all scripts evaluated by the @code{python} command.
209 Some types of the @code{gdb} module come with a textual representation
210 (accessible through the @code{repr} or @code{str} functions). These are
211 offered for debugging purposes only, expect them to change over time.
213 @findex gdb.PYTHONDIR
214 @defvar gdb.PYTHONDIR
215 A string containing the python directory (@pxref{Python}).
219 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
220 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
221 If a GDB exception happens while @var{command} runs, it is
222 translated as described in @ref{Exception Handling,,Exception Handling}.
224 The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
225 command as having originated from the user invoking it interactively.
226 It must be a boolean value. If omitted, it defaults to @code{False}.
228 By default, any output produced by @var{command} is sent to
229 @value{GDBN}'s standard output (and to the log output if logging is
230 turned on). If the @var{to_string} parameter is
231 @code{True}, then output will be collected by @code{gdb.execute} and
232 returned as a string. The default is @code{False}, in which case the
233 return value is @code{None}. If @var{to_string} is @code{True}, the
234 @value{GDBN} virtual terminal will be temporarily set to unlimited width
235 and height, and its pagination will be disabled; @pxref{Screen Size}.
238 @findex gdb.breakpoints
239 @defun gdb.breakpoints ()
240 Return a sequence holding all of @value{GDBN}'s breakpoints.
241 @xref{Breakpoints In Python}, for more information. In @value{GDBN}
242 version 7.11 and earlier, this function returned @code{None} if there
243 were no breakpoints. This peculiarity was subsequently fixed, and now
244 @code{gdb.breakpoints} returns an empty sequence in this case.
247 @defun gdb.rbreak (regex @r{[}, minsyms @r{[}, throttle, @r{[}, symtabs @r{]]]})
248 Return a Python list holding a collection of newly set
249 @code{gdb.Breakpoint} objects matching function names defined by the
250 @var{regex} pattern. If the @var{minsyms} keyword is @code{True}, all
251 system functions (those not explicitly defined in the inferior) will
252 also be included in the match. The @var{throttle} keyword takes an
253 integer that defines the maximum number of pattern matches for
254 functions matched by the @var{regex} pattern. If the number of
255 matches exceeds the integer value of @var{throttle}, a
256 @code{RuntimeError} will be raised and no breakpoints will be created.
257 If @var{throttle} is not defined then there is no imposed limit on the
258 maximum number of matches and breakpoints to be created. The
259 @var{symtabs} keyword takes a Python iterable that yields a collection
260 of @code{gdb.Symtab} objects and will restrict the search to those
261 functions only contained within the @code{gdb.Symtab} objects.
264 @findex gdb.parameter
265 @defun gdb.parameter (parameter)
266 Return the value of a @value{GDBN} @var{parameter} given by its name,
267 a string; the parameter name string may contain spaces if the parameter has a
268 multi-part name. For example, @samp{print object} is a valid
271 If the named parameter does not exist, this function throws a
272 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
273 parameter's value is converted to a Python value of the appropriate
278 @defun gdb.history (number)
279 Return a value from @value{GDBN}'s value history (@pxref{Value
280 History}). The @var{number} argument indicates which history element to return.
281 If @var{number} is negative, then @value{GDBN} will take its absolute value
282 and count backward from the last element (i.e., the most recent element) to
283 find the value to return. If @var{number} is zero, then @value{GDBN} will
284 return the most recent element. If the element specified by @var{number}
285 doesn't exist in the value history, a @code{gdb.error} exception will be
288 If no exception is raised, the return value is always an instance of
289 @code{gdb.Value} (@pxref{Values From Inferior}).
292 @findex gdb.convenience_variable
293 @defun gdb.convenience_variable (name)
294 Return the value of the convenience variable (@pxref{Convenience
295 Vars}) named @var{name}. @var{name} must be a string. The name
296 should not include the @samp{$} that is used to mark a convenience
297 variable in an expression. If the convenience variable does not
298 exist, then @code{None} is returned.
301 @findex gdb.set_convenience_variable
302 @defun gdb.set_convenience_variable (name, value)
303 Set the value of the convenience variable (@pxref{Convenience Vars})
304 named @var{name}. @var{name} must be a string. The name should not
305 include the @samp{$} that is used to mark a convenience variable in an
306 expression. If @var{value} is @code{None}, then the convenience
307 variable is removed. Otherwise, if @var{value} is not a
308 @code{gdb.Value} (@pxref{Values From Inferior}), it is is converted
309 using the @code{gdb.Value} constructor.
312 @findex gdb.parse_and_eval
313 @defun gdb.parse_and_eval (expression)
314 Parse @var{expression}, which must be a string, as an expression in
315 the current language, evaluate it, and return the result as a
318 This function can be useful when implementing a new command
319 (@pxref{Commands In Python}), as it provides a way to parse the
320 command's argument as an expression. It is also useful simply to
324 @findex gdb.find_pc_line
325 @defun gdb.find_pc_line (pc)
326 Return the @code{gdb.Symtab_and_line} object corresponding to the
327 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
328 value of @var{pc} is passed as an argument, then the @code{symtab} and
329 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
330 will be @code{None} and 0 respectively. This is identical to
331 @code{gdb.current_progspace().find_pc_line(pc)} and is included for
332 historical compatibility.
335 @findex gdb.post_event
336 @defun gdb.post_event (event)
337 Put @var{event}, a callable object taking no arguments, into
338 @value{GDBN}'s internal event queue. This callable will be invoked at
339 some later point, during @value{GDBN}'s event processing. Events
340 posted using @code{post_event} will be run in the order in which they
341 were posted; however, there is no way to know when they will be
342 processed relative to other events inside @value{GDBN}.
344 @value{GDBN} is not thread-safe. If your Python program uses multiple
345 threads, you must be careful to only call @value{GDBN}-specific
346 functions in the @value{GDBN} thread. @code{post_event} ensures
350 (@value{GDBP}) python
354 > def __init__(self, message):
355 > self.message = message;
356 > def __call__(self):
357 > gdb.write(self.message)
359 >class MyThread1 (threading.Thread):
361 > gdb.post_event(Writer("Hello "))
363 >class MyThread2 (threading.Thread):
365 > gdb.post_event(Writer("World\n"))
370 (@value{GDBP}) Hello World
375 @defun gdb.write (string @r{[}, stream{]})
376 Print a string to @value{GDBN}'s paginated output stream. The
377 optional @var{stream} determines the stream to print to. The default
378 stream is @value{GDBN}'s standard output stream. Possible stream
385 @value{GDBN}'s standard output stream.
390 @value{GDBN}'s standard error stream.
395 @value{GDBN}'s log stream (@pxref{Logging Output}).
398 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
399 call this function and will automatically direct the output to the
405 Flush the buffer of a @value{GDBN} paginated stream so that the
406 contents are displayed immediately. @value{GDBN} will flush the
407 contents of a stream automatically when it encounters a newline in the
408 buffer. The optional @var{stream} determines the stream to flush. The
409 default stream is @value{GDBN}'s standard output stream. Possible
416 @value{GDBN}'s standard output stream.
421 @value{GDBN}'s standard error stream.
426 @value{GDBN}'s log stream (@pxref{Logging Output}).
430 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
431 call this function for the relevant stream.
434 @findex gdb.target_charset
435 @defun gdb.target_charset ()
436 Return the name of the current target character set (@pxref{Character
437 Sets}). This differs from @code{gdb.parameter('target-charset')} in
438 that @samp{auto} is never returned.
441 @findex gdb.target_wide_charset
442 @defun gdb.target_wide_charset ()
443 Return the name of the current target wide character set
444 (@pxref{Character Sets}). This differs from
445 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
449 @findex gdb.solib_name
450 @defun gdb.solib_name (address)
451 Return the name of the shared library holding the given @var{address}
452 as a string, or @code{None}. This is identical to
453 @code{gdb.current_progspace().solib_name(address)} and is included for
454 historical compatibility.
457 @findex gdb.decode_line
458 @defun gdb.decode_line (@r{[}expression@r{]})
459 Return locations of the line specified by @var{expression}, or of the
460 current line if no argument was given. This function returns a Python
461 tuple containing two elements. The first element contains a string
462 holding any unparsed section of @var{expression} (or @code{None} if
463 the expression has been fully parsed). The second element contains
464 either @code{None} or another tuple that contains all the locations
465 that match the expression represented as @code{gdb.Symtab_and_line}
466 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
467 provided, it is decoded the way that @value{GDBN}'s inbuilt
468 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
471 @defun gdb.prompt_hook (current_prompt)
474 If @var{prompt_hook} is callable, @value{GDBN} will call the method
475 assigned to this operation before a prompt is displayed by
478 The parameter @code{current_prompt} contains the current @value{GDBN}
479 prompt. This method must return a Python string, or @code{None}. If
480 a string is returned, the @value{GDBN} prompt will be set to that
481 string. If @code{None} is returned, @value{GDBN} will continue to use
484 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
485 such as those used by readline for command input, and annotation
486 related prompts are prohibited from being changed.
489 @node Exception Handling
490 @subsubsection Exception Handling
491 @cindex python exceptions
492 @cindex exceptions, python
494 When executing the @code{python} command, Python exceptions
495 uncaught within the Python code are translated to calls to
496 @value{GDBN} error-reporting mechanism. If the command that called
497 @code{python} does not handle the error, @value{GDBN} will
498 terminate it and print an error message containing the Python
499 exception name, the associated value, and the Python call stack
500 backtrace at the point where the exception was raised. Example:
503 (@value{GDBP}) python print foo
504 Traceback (most recent call last):
505 File "<string>", line 1, in <module>
506 NameError: name 'foo' is not defined
509 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
510 Python code are converted to Python exceptions. The type of the
511 Python exception depends on the error.
515 This is the base class for most exceptions generated by @value{GDBN}.
516 It is derived from @code{RuntimeError}, for compatibility with earlier
517 versions of @value{GDBN}.
519 If an error occurring in @value{GDBN} does not fit into some more
520 specific category, then the generated exception will have this type.
522 @item gdb.MemoryError
523 This is a subclass of @code{gdb.error} which is thrown when an
524 operation tried to access invalid memory in the inferior.
526 @item KeyboardInterrupt
527 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
528 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
531 In all cases, your exception handler will see the @value{GDBN} error
532 message as its value and the Python call stack backtrace at the Python
533 statement closest to where the @value{GDBN} error occured as the
537 When implementing @value{GDBN} commands in Python via
538 @code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
539 to be able to throw an exception that doesn't cause a traceback to be
540 printed. For example, the user may have invoked the command
541 incorrectly. @value{GDBN} provides a special exception class that can
542 be used for this purpose.
546 When thrown from a command or function, this exception will cause the
547 command or function to fail, but the Python stack will not be
548 displayed. @value{GDBN} does not throw this exception itself, but
549 rather recognizes it when thrown from user Python code. Example:
553 >class HelloWorld (gdb.Command):
554 > """Greet the whole world."""
555 > def __init__ (self):
556 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
557 > def invoke (self, args, from_tty):
558 > argv = gdb.string_to_argv (args)
559 > if len (argv) != 0:
560 > raise gdb.GdbError ("hello-world takes no arguments")
561 > print "Hello, World!"
565 hello-world takes no arguments
569 @node Values From Inferior
570 @subsubsection Values From Inferior
571 @cindex values from inferior, with Python
572 @cindex python, working with values from inferior
574 @cindex @code{gdb.Value}
575 @value{GDBN} provides values it obtains from the inferior program in
576 an object of type @code{gdb.Value}. @value{GDBN} uses this object
577 for its internal bookkeeping of the inferior's values, and for
578 fetching values when necessary.
580 Inferior values that are simple scalars can be used directly in
581 Python expressions that are valid for the value's data type. Here's
582 an example for an integer or floating-point value @code{some_val}:
589 As result of this, @code{bar} will also be a @code{gdb.Value} object
590 whose values are of the same type as those of @code{some_val}. Valid
591 Python operations can also be performed on @code{gdb.Value} objects
592 representing a @code{struct} or @code{class} object. For such cases,
593 the overloaded operator (if present), is used to perform the operation.
594 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
595 representing instances of a @code{class} which overloads the @code{+}
596 operator, then one can use the @code{+} operator in their Python script
604 The result of the operation @code{val3} is also a @code{gdb.Value}
605 object corresponding to the value returned by the overloaded @code{+}
606 operator. In general, overloaded operators are invoked for the
607 following operations: @code{+} (binary addition), @code{-} (binary
608 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
609 @code{>>}, @code{|}, @code{&}, @code{^}.
611 Inferior values that are structures or instances of some class can
612 be accessed using the Python @dfn{dictionary syntax}. For example, if
613 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
614 can access its @code{foo} element with:
617 bar = some_val['foo']
620 @cindex getting structure elements using gdb.Field objects as subscripts
621 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
622 elements can also be accessed by using @code{gdb.Field} objects as
623 subscripts (@pxref{Types In Python}, for more information on
624 @code{gdb.Field} objects). For example, if @code{foo_field} is a
625 @code{gdb.Field} object corresponding to element @code{foo} of the above
626 structure, then @code{bar} can also be accessed as follows:
629 bar = some_val[foo_field]
632 A @code{gdb.Value} that represents a function can be executed via
633 inferior function call. Any arguments provided to the call must match
634 the function's prototype, and must be provided in the order specified
637 For example, @code{some_val} is a @code{gdb.Value} instance
638 representing a function that takes two integers as arguments. To
639 execute this function, call it like so:
642 result = some_val (10,20)
645 Any values returned from a function call will be stored as a
648 The following attributes are provided:
650 @defvar Value.address
651 If this object is addressable, this read-only attribute holds a
652 @code{gdb.Value} object representing the address. Otherwise,
653 this attribute holds @code{None}.
656 @cindex optimized out value in Python
657 @defvar Value.is_optimized_out
658 This read-only boolean attribute is true if the compiler optimized out
659 this value, thus it is not available for fetching from the inferior.
663 The type of this @code{gdb.Value}. The value of this attribute is a
664 @code{gdb.Type} object (@pxref{Types In Python}).
667 @defvar Value.dynamic_type
668 The dynamic type of this @code{gdb.Value}. This uses the object's
669 virtual table and the C@t{++} run-time type information
670 (@acronym{RTTI}) to determine the dynamic type of the value. If this
671 value is of class type, it will return the class in which the value is
672 embedded, if any. If this value is of pointer or reference to a class
673 type, it will compute the dynamic type of the referenced object, and
674 return a pointer or reference to that type, respectively. In all
675 other cases, it will return the value's static type.
677 Note that this feature will only work when debugging a C@t{++} program
678 that includes @acronym{RTTI} for the object in question. Otherwise,
679 it will just return the static type of the value as in @kbd{ptype foo}
680 (@pxref{Symbols, ptype}).
683 @defvar Value.is_lazy
684 The value of this read-only boolean attribute is @code{True} if this
685 @code{gdb.Value} has not yet been fetched from the inferior.
686 @value{GDBN} does not fetch values until necessary, for efficiency.
690 myval = gdb.parse_and_eval ('somevar')
693 The value of @code{somevar} is not fetched at this time. It will be
694 fetched when the value is needed, or when the @code{fetch_lazy}
698 The following methods are provided:
700 @defun Value.__init__ (@var{val})
701 Many Python values can be converted directly to a @code{gdb.Value} via
702 this object initializer. Specifically:
706 A Python boolean is converted to the boolean type from the current
710 A Python integer is converted to the C @code{long} type for the
711 current architecture.
714 A Python long is converted to the C @code{long long} type for the
715 current architecture.
718 A Python float is converted to the C @code{double} type for the
719 current architecture.
722 A Python string is converted to a target string in the current target
723 language using the current target encoding.
724 If a character cannot be represented in the current target encoding,
725 then an exception is thrown.
727 @item @code{gdb.Value}
728 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
730 @item @code{gdb.LazyString}
731 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
732 Python}), then the lazy string's @code{value} method is called, and
737 @defun Value.__init__ (@var{val}, @var{type})
738 This second form of the @code{gdb.Value} constructor returns a
739 @code{gdb.Value} of type @var{type} where the value contents are taken
740 from the Python buffer object specified by @var{val}. The number of
741 bytes in the Python buffer object must be greater than or equal to the
745 @defun Value.cast (type)
746 Return a new instance of @code{gdb.Value} that is the result of
747 casting this instance to the type described by @var{type}, which must
748 be a @code{gdb.Type} object. If the cast cannot be performed for some
749 reason, this method throws an exception.
752 @defun Value.dereference ()
753 For pointer data types, this method returns a new @code{gdb.Value} object
754 whose contents is the object pointed to by the pointer. For example, if
755 @code{foo} is a C pointer to an @code{int}, declared in your C program as
762 then you can use the corresponding @code{gdb.Value} to access what
763 @code{foo} points to like this:
766 bar = foo.dereference ()
769 The result @code{bar} will be a @code{gdb.Value} object holding the
770 value pointed to by @code{foo}.
772 A similar function @code{Value.referenced_value} exists which also
773 returns @code{gdb.Value} objects corresponding to the values pointed to
774 by pointer values (and additionally, values referenced by reference
775 values). However, the behavior of @code{Value.dereference}
776 differs from @code{Value.referenced_value} by the fact that the
777 behavior of @code{Value.dereference} is identical to applying the C
778 unary operator @code{*} on a given value. For example, consider a
779 reference to a pointer @code{ptrref}, declared in your C@t{++} program
787 intptr &ptrref = ptr;
790 Though @code{ptrref} is a reference value, one can apply the method
791 @code{Value.dereference} to the @code{gdb.Value} object corresponding
792 to it and obtain a @code{gdb.Value} which is identical to that
793 corresponding to @code{val}. However, if you apply the method
794 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
795 object identical to that corresponding to @code{ptr}.
798 py_ptrref = gdb.parse_and_eval ("ptrref")
799 py_val = py_ptrref.dereference ()
800 py_ptr = py_ptrref.referenced_value ()
803 The @code{gdb.Value} object @code{py_val} is identical to that
804 corresponding to @code{val}, and @code{py_ptr} is identical to that
805 corresponding to @code{ptr}. In general, @code{Value.dereference} can
806 be applied whenever the C unary operator @code{*} can be applied
807 to the corresponding C value. For those cases where applying both
808 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
809 the results obtained need not be identical (as we have seen in the above
810 example). The results are however identical when applied on
811 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
812 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
815 @defun Value.referenced_value ()
816 For pointer or reference data types, this method returns a new
817 @code{gdb.Value} object corresponding to the value referenced by the
818 pointer/reference value. For pointer data types,
819 @code{Value.dereference} and @code{Value.referenced_value} produce
820 identical results. The difference between these methods is that
821 @code{Value.dereference} cannot get the values referenced by reference
822 values. For example, consider a reference to an @code{int}, declared
823 in your C@t{++} program as
831 then applying @code{Value.dereference} to the @code{gdb.Value} object
832 corresponding to @code{ref} will result in an error, while applying
833 @code{Value.referenced_value} will result in a @code{gdb.Value} object
834 identical to that corresponding to @code{val}.
837 py_ref = gdb.parse_and_eval ("ref")
838 er_ref = py_ref.dereference () # Results in error
839 py_val = py_ref.referenced_value () # Returns the referenced value
842 The @code{gdb.Value} object @code{py_val} is identical to that
843 corresponding to @code{val}.
846 @defun Value.reference_value ()
847 Return a @code{gdb.Value} object which is a reference to the value
848 encapsulated by this instance.
851 @defun Value.const_value ()
852 Return a @code{gdb.Value} object which is a @code{const} version of the
853 value encapsulated by this instance.
856 @defun Value.dynamic_cast (type)
857 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
858 operator were used. Consult a C@t{++} reference for details.
861 @defun Value.reinterpret_cast (type)
862 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
863 operator were used. Consult a C@t{++} reference for details.
866 @defun Value.format_string (...)
867 Convert a @code{gdb.Value} to a string, similarly to what the @code{print}
868 command does. Invoked with no arguments, this is equivalent to calling
869 the @code{str} function on the @code{gdb.Value}. The representation of
870 the same value may change across different versions of @value{GDBN}, so
871 you shouldn't, for instance, parse the strings returned by this method.
873 All the arguments are keyword only. If an argument is not specified, the
874 current global default setting is used.
878 @code{True} if pretty-printers (@pxref{Pretty Printing}) should not be
879 used to format the value. @code{False} if enabled pretty-printers
880 matching the type represented by the @code{gdb.Value} should be used to
884 @code{True} if arrays should be pretty printed to be more convenient to
885 read, @code{False} if they shouldn't (see @code{set print array} in
886 @ref{Print Settings}).
889 @code{True} if structs should be pretty printed to be more convenient to
890 read, @code{False} if they shouldn't (see @code{set print pretty} in
891 @ref{Print Settings}).
894 @code{True} if array indexes should be included in the string
895 representation of arrays, @code{False} if they shouldn't (see @code{set
896 print array-indexes} in @ref{Print Settings}).
899 @code{True} if the string representation of a pointer should include the
900 corresponding symbol name (if one exists), @code{False} if it shouldn't
901 (see @code{set print symbol} in @ref{Print Settings}).
904 @code{True} if unions which are contained in other structures or unions
905 should be expanded, @code{False} if they shouldn't (see @code{set print
906 union} in @ref{Print Settings}).
909 @code{True} if C@t{++} references should be resolved to the value they
910 refer to, @code{False} (the default) if they shouldn't. Note that, unlike
911 for the @code{print} command, references are not automatically expanded
912 when using the @code{format_string} method or the @code{str}
913 function. There is no global @code{print} setting to change the default
917 @code{True} if the representation of a pointer to an object should
918 identify the @emph{actual} (derived) type of the object rather than the
919 @emph{declared} type, using the virtual function table. @code{False} if
920 the @emph{declared} type should be used. (See @code{set print object} in
921 @ref{Print Settings}).
924 @code{True} if static members should be included in the string
925 representation of a C@t{++} object, @code{False} if they shouldn't (see
926 @code{set print static-members} in @ref{Print Settings}).
929 Number of array elements to print, or @code{0} to print an unlimited
930 number of elements (see @code{set print elements} in @ref{Print
934 The maximum depth to print for nested structs and unions, or @code{-1}
935 to print an unlimited number of elements (see @code{set print
936 max-depth} in @ref{Print Settings}).
938 @item repeat_threshold
939 Set the threshold for suppressing display of repeated array elements, or
940 @code{0} to represent all elements, even if repeated. (See @code{set
941 print repeats} in @ref{Print Settings}).
944 A string containing a single character representing the format to use for
945 the returned string. For instance, @code{'x'} is equivalent to using the
946 @value{GDBN} command @code{print} with the @code{/x} option and formats
947 the value as a hexadecimal number.
951 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
952 If this @code{gdb.Value} represents a string, then this method
953 converts the contents to a Python string. Otherwise, this method will
956 Values are interpreted as strings according to the rules of the
957 current language. If the optional length argument is given, the
958 string will be converted to that length, and will include any embedded
959 zeroes that the string may contain. Otherwise, for languages
960 where the string is zero-terminated, the entire string will be
963 For example, in C-like languages, a value is a string if it is a pointer
964 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
967 If the optional @var{encoding} argument is given, it must be a string
968 naming the encoding of the string in the @code{gdb.Value}, such as
969 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
970 the same encodings as the corresponding argument to Python's
971 @code{string.decode} method, and the Python codec machinery will be used
972 to convert the string. If @var{encoding} is not given, or if
973 @var{encoding} is the empty string, then either the @code{target-charset}
974 (@pxref{Character Sets}) will be used, or a language-specific encoding
975 will be used, if the current language is able to supply one.
977 The optional @var{errors} argument is the same as the corresponding
978 argument to Python's @code{string.decode} method.
980 If the optional @var{length} argument is given, the string will be
981 fetched and converted to the given length.
984 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
985 If this @code{gdb.Value} represents a string, then this method
986 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
987 In Python}). Otherwise, this method will throw an exception.
989 If the optional @var{encoding} argument is given, it must be a string
990 naming the encoding of the @code{gdb.LazyString}. Some examples are:
991 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
992 @var{encoding} argument is an encoding that @value{GDBN} does
993 recognize, @value{GDBN} will raise an error.
995 When a lazy string is printed, the @value{GDBN} encoding machinery is
996 used to convert the string during printing. If the optional
997 @var{encoding} argument is not provided, or is an empty string,
998 @value{GDBN} will automatically select the encoding most suitable for
999 the string type. For further information on encoding in @value{GDBN}
1000 please see @ref{Character Sets}.
1002 If the optional @var{length} argument is given, the string will be
1003 fetched and encoded to the length of characters specified. If
1004 the @var{length} argument is not provided, the string will be fetched
1005 and encoded until a null of appropriate width is found.
1008 @defun Value.fetch_lazy ()
1009 If the @code{gdb.Value} object is currently a lazy value
1010 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
1011 fetched from the inferior. Any errors that occur in the process
1012 will produce a Python exception.
1014 If the @code{gdb.Value} object is not a lazy value, this method
1017 This method does not return a value.
1021 @node Types In Python
1022 @subsubsection Types In Python
1023 @cindex types in Python
1024 @cindex Python, working with types
1027 @value{GDBN} represents types from the inferior using the class
1030 The following type-related functions are available in the @code{gdb}
1033 @findex gdb.lookup_type
1034 @defun gdb.lookup_type (name @r{[}, block@r{]})
1035 This function looks up a type by its @var{name}, which must be a string.
1037 If @var{block} is given, then @var{name} is looked up in that scope.
1038 Otherwise, it is searched for globally.
1040 Ordinarily, this function will return an instance of @code{gdb.Type}.
1041 If the named type cannot be found, it will throw an exception.
1044 If the type is a structure or class type, or an enum type, the fields
1045 of that type can be accessed using the Python @dfn{dictionary syntax}.
1046 For example, if @code{some_type} is a @code{gdb.Type} instance holding
1047 a structure type, you can access its @code{foo} field with:
1050 bar = some_type['foo']
1053 @code{bar} will be a @code{gdb.Field} object; see below under the
1054 description of the @code{Type.fields} method for a description of the
1055 @code{gdb.Field} class.
1057 An instance of @code{Type} has the following attributes:
1059 @defvar Type.alignof
1060 The alignment of this type, in bytes. Type alignment comes from the
1061 debugging information; if it was not specified, then @value{GDBN} will
1062 use the relevant ABI to try to determine the alignment. In some
1063 cases, even this is not possible, and zero will be returned.
1067 The type code for this type. The type code will be one of the
1068 @code{TYPE_CODE_} constants defined below.
1071 @defvar Type.dynamic
1072 A boolean indicating whether this type is dynamic. In some
1073 situations, such as Rust @code{enum} types or Ada variant records, the
1074 concrete type of a value may vary depending on its contents. That is,
1075 the declared type of a variable, or the type returned by
1076 @code{gdb.lookup_type} may be dynamic; while the type of the
1077 variable's value will be a concrete instance of that dynamic type.
1079 For example, consider this code:
1085 Here, at least conceptually (whether your compiler actually does this
1086 is a separate issue), examining @w{@code{gdb.lookup_symbol("array", ...).type}}
1087 could yield a @code{gdb.Type} which reports a size of @code{None}.
1088 This is the dynamic type.
1090 However, examining @code{gdb.parse_and_eval("array").type} would yield
1091 a concrete type, whose length would be known.
1095 The name of this type. If this type has no name, then @code{None}
1100 The size of this type, in target @code{char} units. Usually, a
1101 target's @code{char} type will be an 8-bit byte. However, on some
1102 unusual platforms, this type may have a different size. A dynamic
1103 type may not have a fixed size; in this case, this attribute's value
1104 will be @code{None}.
1108 The tag name for this type. The tag name is the name after
1109 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1110 languages have this concept. If this type has no tag name, then
1111 @code{None} is returned.
1114 @defvar Type.objfile
1115 The @code{gdb.Objfile} that this type was defined in, or @code{None} if
1116 there is no associated objfile.
1119 The following methods are provided:
1121 @defun Type.fields ()
1122 For structure and union types, this method returns the fields. Range
1123 types have two fields, the minimum and maximum values. Enum types
1124 have one field per enum constant. Function and method types have one
1125 field per parameter. The base types of C@t{++} classes are also
1126 represented as fields. If the type has no fields, or does not fit
1127 into one of these categories, an empty sequence will be returned.
1129 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
1132 This attribute is not available for @code{enum} or @code{static}
1133 (as in C@t{++}) fields. The value is the position, counting
1134 in bits, from the start of the containing type. Note that, in a
1135 dynamic type, the position of a field may not be constant. In this
1136 case, the value will be @code{None}. Also, a dynamic type may have
1137 fields that do not appear in a corresponding concrete type.
1140 This attribute is only available for @code{enum} fields, and its value
1141 is the enumeration member's integer representation.
1144 The name of the field, or @code{None} for anonymous fields.
1147 This is @code{True} if the field is artificial, usually meaning that
1148 it was provided by the compiler and not the user. This attribute is
1149 always provided, and is @code{False} if the field is not artificial.
1152 This is @code{True} if the field represents a base class of a C@t{++}
1153 structure. This attribute is always provided, and is @code{False}
1154 if the field is not a base class of the type that is the argument of
1155 @code{fields}, or if that type was not a C@t{++} class.
1158 If the field is packed, or is a bitfield, then this will have a
1159 non-zero value, which is the size of the field in bits. Otherwise,
1160 this will be zero; in this case the field's size is given by its type.
1163 The type of the field. This is usually an instance of @code{Type},
1164 but it can be @code{None} in some situations.
1167 The type which contains this field. This is an instance of
1172 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
1173 Return a new @code{gdb.Type} object which represents an array of this
1174 type. If one argument is given, it is the inclusive upper bound of
1175 the array; in this case the lower bound is zero. If two arguments are
1176 given, the first argument is the lower bound of the array, and the
1177 second argument is the upper bound of the array. An array's length
1178 must not be negative, but the bounds can be.
1181 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
1182 Return a new @code{gdb.Type} object which represents a vector of this
1183 type. If one argument is given, it is the inclusive upper bound of
1184 the vector; in this case the lower bound is zero. If two arguments are
1185 given, the first argument is the lower bound of the vector, and the
1186 second argument is the upper bound of the vector. A vector's length
1187 must not be negative, but the bounds can be.
1189 The difference between an @code{array} and a @code{vector} is that
1190 arrays behave like in C: when used in expressions they decay to a pointer
1191 to the first element whereas vectors are treated as first class values.
1194 @defun Type.const ()
1195 Return a new @code{gdb.Type} object which represents a
1196 @code{const}-qualified variant of this type.
1199 @defun Type.volatile ()
1200 Return a new @code{gdb.Type} object which represents a
1201 @code{volatile}-qualified variant of this type.
1204 @defun Type.unqualified ()
1205 Return a new @code{gdb.Type} object which represents an unqualified
1206 variant of this type. That is, the result is neither @code{const} nor
1210 @defun Type.range ()
1211 Return a Python @code{Tuple} object that contains two elements: the
1212 low bound of the argument type and the high bound of that type. If
1213 the type does not have a range, @value{GDBN} will raise a
1214 @code{gdb.error} exception (@pxref{Exception Handling}).
1217 @defun Type.reference ()
1218 Return a new @code{gdb.Type} object which represents a reference to this
1222 @defun Type.pointer ()
1223 Return a new @code{gdb.Type} object which represents a pointer to this
1227 @defun Type.strip_typedefs ()
1228 Return a new @code{gdb.Type} that represents the real type,
1229 after removing all layers of typedefs.
1232 @defun Type.target ()
1233 Return a new @code{gdb.Type} object which represents the target type
1236 For a pointer type, the target type is the type of the pointed-to
1237 object. For an array type (meaning C-like arrays), the target type is
1238 the type of the elements of the array. For a function or method type,
1239 the target type is the type of the return value. For a complex type,
1240 the target type is the type of the elements. For a typedef, the
1241 target type is the aliased type.
1243 If the type does not have a target, this method will throw an
1247 @defun Type.template_argument (n @r{[}, block@r{]})
1248 If this @code{gdb.Type} is an instantiation of a template, this will
1249 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1250 value of the @var{n}th template argument (indexed starting at 0).
1252 If this @code{gdb.Type} is not a template type, or if the type has fewer
1253 than @var{n} template arguments, this will throw an exception.
1254 Ordinarily, only C@t{++} code will have template types.
1256 If @var{block} is given, then @var{name} is looked up in that scope.
1257 Otherwise, it is searched for globally.
1260 @defun Type.optimized_out ()
1261 Return @code{gdb.Value} instance of this type whose value is optimized
1262 out. This allows a frame decorator to indicate that the value of an
1263 argument or a local variable is not known.
1266 Each type has a code, which indicates what category this type falls
1267 into. The available type categories are represented by constants
1268 defined in the @code{gdb} module:
1271 @vindex TYPE_CODE_PTR
1272 @item gdb.TYPE_CODE_PTR
1273 The type is a pointer.
1275 @vindex TYPE_CODE_ARRAY
1276 @item gdb.TYPE_CODE_ARRAY
1277 The type is an array.
1279 @vindex TYPE_CODE_STRUCT
1280 @item gdb.TYPE_CODE_STRUCT
1281 The type is a structure.
1283 @vindex TYPE_CODE_UNION
1284 @item gdb.TYPE_CODE_UNION
1285 The type is a union.
1287 @vindex TYPE_CODE_ENUM
1288 @item gdb.TYPE_CODE_ENUM
1289 The type is an enum.
1291 @vindex TYPE_CODE_FLAGS
1292 @item gdb.TYPE_CODE_FLAGS
1293 A bit flags type, used for things such as status registers.
1295 @vindex TYPE_CODE_FUNC
1296 @item gdb.TYPE_CODE_FUNC
1297 The type is a function.
1299 @vindex TYPE_CODE_INT
1300 @item gdb.TYPE_CODE_INT
1301 The type is an integer type.
1303 @vindex TYPE_CODE_FLT
1304 @item gdb.TYPE_CODE_FLT
1305 A floating point type.
1307 @vindex TYPE_CODE_VOID
1308 @item gdb.TYPE_CODE_VOID
1309 The special type @code{void}.
1311 @vindex TYPE_CODE_SET
1312 @item gdb.TYPE_CODE_SET
1315 @vindex TYPE_CODE_RANGE
1316 @item gdb.TYPE_CODE_RANGE
1317 A range type, that is, an integer type with bounds.
1319 @vindex TYPE_CODE_STRING
1320 @item gdb.TYPE_CODE_STRING
1321 A string type. Note that this is only used for certain languages with
1322 language-defined string types; C strings are not represented this way.
1324 @vindex TYPE_CODE_BITSTRING
1325 @item gdb.TYPE_CODE_BITSTRING
1326 A string of bits. It is deprecated.
1328 @vindex TYPE_CODE_ERROR
1329 @item gdb.TYPE_CODE_ERROR
1330 An unknown or erroneous type.
1332 @vindex TYPE_CODE_METHOD
1333 @item gdb.TYPE_CODE_METHOD
1334 A method type, as found in C@t{++}.
1336 @vindex TYPE_CODE_METHODPTR
1337 @item gdb.TYPE_CODE_METHODPTR
1338 A pointer-to-member-function.
1340 @vindex TYPE_CODE_MEMBERPTR
1341 @item gdb.TYPE_CODE_MEMBERPTR
1342 A pointer-to-member.
1344 @vindex TYPE_CODE_REF
1345 @item gdb.TYPE_CODE_REF
1348 @vindex TYPE_CODE_RVALUE_REF
1349 @item gdb.TYPE_CODE_RVALUE_REF
1350 A C@t{++}11 rvalue reference type.
1352 @vindex TYPE_CODE_CHAR
1353 @item gdb.TYPE_CODE_CHAR
1356 @vindex TYPE_CODE_BOOL
1357 @item gdb.TYPE_CODE_BOOL
1360 @vindex TYPE_CODE_COMPLEX
1361 @item gdb.TYPE_CODE_COMPLEX
1362 A complex float type.
1364 @vindex TYPE_CODE_TYPEDEF
1365 @item gdb.TYPE_CODE_TYPEDEF
1366 A typedef to some other type.
1368 @vindex TYPE_CODE_NAMESPACE
1369 @item gdb.TYPE_CODE_NAMESPACE
1370 A C@t{++} namespace.
1372 @vindex TYPE_CODE_DECFLOAT
1373 @item gdb.TYPE_CODE_DECFLOAT
1374 A decimal floating point type.
1376 @vindex TYPE_CODE_INTERNAL_FUNCTION
1377 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1378 A function internal to @value{GDBN}. This is the type used to represent
1379 convenience functions.
1382 Further support for types is provided in the @code{gdb.types}
1383 Python module (@pxref{gdb.types}).
1385 @node Pretty Printing API
1386 @subsubsection Pretty Printing API
1387 @cindex python pretty printing api
1389 A pretty-printer is just an object that holds a value and implements a
1390 specific interface, defined here. An example output is provided
1391 (@pxref{Pretty Printing}).
1393 @defun pretty_printer.children (self)
1394 @value{GDBN} will call this method on a pretty-printer to compute the
1395 children of the pretty-printer's value.
1397 This method must return an object conforming to the Python iterator
1398 protocol. Each item returned by the iterator must be a tuple holding
1399 two elements. The first element is the ``name'' of the child; the
1400 second element is the child's value. The value can be any Python
1401 object which is convertible to a @value{GDBN} value.
1403 This method is optional. If it does not exist, @value{GDBN} will act
1404 as though the value has no children.
1406 For efficiency, the @code{children} method should lazily compute its
1407 results. This will let @value{GDBN} read as few elements as
1408 necessary, for example when various print settings (@pxref{Print
1409 Settings}) or @code{-var-list-children} (@pxref{GDB/MI Variable
1410 Objects}) limit the number of elements to be displayed.
1412 Children may be hidden from display based on the value of @samp{set
1413 print max-depth} (@pxref{Print Settings}).
1416 @defun pretty_printer.display_hint (self)
1417 The CLI may call this method and use its result to change the
1418 formatting of a value. The result will also be supplied to an MI
1419 consumer as a @samp{displayhint} attribute of the variable being
1422 This method is optional. If it does exist, this method must return a
1423 string or the special value @code{None}.
1425 Some display hints are predefined by @value{GDBN}:
1429 Indicate that the object being printed is ``array-like''. The CLI
1430 uses this to respect parameters such as @code{set print elements} and
1431 @code{set print array}.
1434 Indicate that the object being printed is ``map-like'', and that the
1435 children of this value can be assumed to alternate between keys and
1439 Indicate that the object being printed is ``string-like''. If the
1440 printer's @code{to_string} method returns a Python string of some
1441 kind, then @value{GDBN} will call its internal language-specific
1442 string-printing function to format the string. For the CLI this means
1443 adding quotation marks, possibly escaping some characters, respecting
1444 @code{set print elements}, and the like.
1447 The special value @code{None} causes @value{GDBN} to apply the default
1451 @defun pretty_printer.to_string (self)
1452 @value{GDBN} will call this method to display the string
1453 representation of the value passed to the object's constructor.
1455 When printing from the CLI, if the @code{to_string} method exists,
1456 then @value{GDBN} will prepend its result to the values returned by
1457 @code{children}. Exactly how this formatting is done is dependent on
1458 the display hint, and may change as more hints are added. Also,
1459 depending on the print settings (@pxref{Print Settings}), the CLI may
1460 print just the result of @code{to_string} in a stack trace, omitting
1461 the result of @code{children}.
1463 If this method returns a string, it is printed verbatim.
1465 Otherwise, if this method returns an instance of @code{gdb.Value},
1466 then @value{GDBN} prints this value. This may result in a call to
1467 another pretty-printer.
1469 If instead the method returns a Python value which is convertible to a
1470 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1471 the resulting value. Again, this may result in a call to another
1472 pretty-printer. Python scalars (integers, floats, and booleans) and
1473 strings are convertible to @code{gdb.Value}; other types are not.
1475 Finally, if this method returns @code{None} then no further operations
1476 are peformed in this method and nothing is printed.
1478 If the result is not one of these types, an exception is raised.
1481 @value{GDBN} provides a function which can be used to look up the
1482 default pretty-printer for a @code{gdb.Value}:
1484 @findex gdb.default_visualizer
1485 @defun gdb.default_visualizer (value)
1486 This function takes a @code{gdb.Value} object as an argument. If a
1487 pretty-printer for this value exists, then it is returned. If no such
1488 printer exists, then this returns @code{None}.
1491 @node Selecting Pretty-Printers
1492 @subsubsection Selecting Pretty-Printers
1493 @cindex selecting python pretty-printers
1495 @value{GDBN} provides several ways to register a pretty-printer:
1496 globally, per program space, and per objfile. When choosing how to
1497 register your pretty-printer, a good rule is to register it with the
1498 smallest scope possible: that is prefer a specific objfile first, then
1499 a program space, and only register a printer globally as a last
1502 @findex gdb.pretty_printers
1503 @defvar gdb.pretty_printers
1504 The Python list @code{gdb.pretty_printers} contains an array of
1505 functions or callable objects that have been registered via addition
1506 as a pretty-printer. Printers in this list are called @code{global}
1507 printers, they're available when debugging all inferiors.
1510 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1511 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1514 Each function on these lists is passed a single @code{gdb.Value}
1515 argument and should return a pretty-printer object conforming to the
1516 interface definition above (@pxref{Pretty Printing API}). If a function
1517 cannot create a pretty-printer for the value, it should return
1520 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1521 @code{gdb.Objfile} in the current program space and iteratively calls
1522 each enabled lookup routine in the list for that @code{gdb.Objfile}
1523 until it receives a pretty-printer object.
1524 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1525 searches the pretty-printer list of the current program space,
1526 calling each enabled function until an object is returned.
1527 After these lists have been exhausted, it tries the global
1528 @code{gdb.pretty_printers} list, again calling each enabled function until an
1531 The order in which the objfiles are searched is not specified. For a
1532 given list, functions are always invoked from the head of the list,
1533 and iterated over sequentially until the end of the list, or a printer
1536 For various reasons a pretty-printer may not work.
1537 For example, the underlying data structure may have changed and
1538 the pretty-printer is out of date.
1540 The consequences of a broken pretty-printer are severe enough that
1541 @value{GDBN} provides support for enabling and disabling individual
1542 printers. For example, if @code{print frame-arguments} is on,
1543 a backtrace can become highly illegible if any argument is printed
1544 with a broken printer.
1546 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1547 attribute to the registered function or callable object. If this attribute
1548 is present and its value is @code{False}, the printer is disabled, otherwise
1549 the printer is enabled.
1551 @node Writing a Pretty-Printer
1552 @subsubsection Writing a Pretty-Printer
1553 @cindex writing a pretty-printer
1555 A pretty-printer consists of two parts: a lookup function to detect
1556 if the type is supported, and the printer itself.
1558 Here is an example showing how a @code{std::string} printer might be
1559 written. @xref{Pretty Printing API}, for details on the API this class
1563 class StdStringPrinter(object):
1564 "Print a std::string"
1566 def __init__(self, val):
1569 def to_string(self):
1570 return self.val['_M_dataplus']['_M_p']
1572 def display_hint(self):
1576 And here is an example showing how a lookup function for the printer
1577 example above might be written.
1580 def str_lookup_function(val):
1581 lookup_tag = val.type.tag
1582 if lookup_tag == None:
1584 regex = re.compile("^std::basic_string<char,.*>$")
1585 if regex.match(lookup_tag):
1586 return StdStringPrinter(val)
1590 The example lookup function extracts the value's type, and attempts to
1591 match it to a type that it can pretty-print. If it is a type the
1592 printer can pretty-print, it will return a printer object. If not, it
1593 returns @code{None}.
1595 We recommend that you put your core pretty-printers into a Python
1596 package. If your pretty-printers are for use with a library, we
1597 further recommend embedding a version number into the package name.
1598 This practice will enable @value{GDBN} to load multiple versions of
1599 your pretty-printers at the same time, because they will have
1602 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1603 can be evaluated multiple times without changing its meaning. An
1604 ideal auto-load file will consist solely of @code{import}s of your
1605 printer modules, followed by a call to a register pretty-printers with
1606 the current objfile.
1608 Taken as a whole, this approach will scale nicely to multiple
1609 inferiors, each potentially using a different library version.
1610 Embedding a version number in the Python package name will ensure that
1611 @value{GDBN} is able to load both sets of printers simultaneously.
1612 Then, because the search for pretty-printers is done by objfile, and
1613 because your auto-loaded code took care to register your library's
1614 printers with a specific objfile, @value{GDBN} will find the correct
1615 printers for the specific version of the library used by each
1618 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1619 this code might appear in @code{gdb.libstdcxx.v6}:
1622 def register_printers(objfile):
1623 objfile.pretty_printers.append(str_lookup_function)
1627 And then the corresponding contents of the auto-load file would be:
1630 import gdb.libstdcxx.v6
1631 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1634 The previous example illustrates a basic pretty-printer.
1635 There are a few things that can be improved on.
1636 The printer doesn't have a name, making it hard to identify in a
1637 list of installed printers. The lookup function has a name, but
1638 lookup functions can have arbitrary, even identical, names.
1640 Second, the printer only handles one type, whereas a library typically has
1641 several types. One could install a lookup function for each desired type
1642 in the library, but one could also have a single lookup function recognize
1643 several types. The latter is the conventional way this is handled.
1644 If a pretty-printer can handle multiple data types, then its
1645 @dfn{subprinters} are the printers for the individual data types.
1647 The @code{gdb.printing} module provides a formal way of solving these
1648 problems (@pxref{gdb.printing}).
1649 Here is another example that handles multiple types.
1651 These are the types we are going to pretty-print:
1654 struct foo @{ int a, b; @};
1655 struct bar @{ struct foo x, y; @};
1658 Here are the printers:
1662 """Print a foo object."""
1664 def __init__(self, val):
1667 def to_string(self):
1668 return ("a=<" + str(self.val["a"]) +
1669 "> b=<" + str(self.val["b"]) + ">")
1672 """Print a bar object."""
1674 def __init__(self, val):
1677 def to_string(self):
1678 return ("x=<" + str(self.val["x"]) +
1679 "> y=<" + str(self.val["y"]) + ">")
1682 This example doesn't need a lookup function, that is handled by the
1683 @code{gdb.printing} module. Instead a function is provided to build up
1684 the object that handles the lookup.
1689 def build_pretty_printer():
1690 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1692 pp.add_printer('foo', '^foo$', fooPrinter)
1693 pp.add_printer('bar', '^bar$', barPrinter)
1697 And here is the autoload support:
1702 gdb.printing.register_pretty_printer(
1703 gdb.current_objfile(),
1704 my_library.build_pretty_printer())
1707 Finally, when this printer is loaded into @value{GDBN}, here is the
1708 corresponding output of @samp{info pretty-printer}:
1711 (gdb) info pretty-printer
1718 @node Type Printing API
1719 @subsubsection Type Printing API
1720 @cindex type printing API for Python
1722 @value{GDBN} provides a way for Python code to customize type display.
1723 This is mainly useful for substituting canonical typedef names for
1726 @cindex type printer
1727 A @dfn{type printer} is just a Python object conforming to a certain
1728 protocol. A simple base class implementing the protocol is provided;
1729 see @ref{gdb.types}. A type printer must supply at least:
1731 @defivar type_printer enabled
1732 A boolean which is True if the printer is enabled, and False
1733 otherwise. This is manipulated by the @code{enable type-printer}
1734 and @code{disable type-printer} commands.
1737 @defivar type_printer name
1738 The name of the type printer. This must be a string. This is used by
1739 the @code{enable type-printer} and @code{disable type-printer}
1743 @defmethod type_printer instantiate (self)
1744 This is called by @value{GDBN} at the start of type-printing. It is
1745 only called if the type printer is enabled. This method must return a
1746 new object that supplies a @code{recognize} method, as described below.
1750 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1751 will compute a list of type recognizers. This is done by iterating
1752 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1753 followed by the per-progspace type printers (@pxref{Progspaces In
1754 Python}), and finally the global type printers.
1756 @value{GDBN} will call the @code{instantiate} method of each enabled
1757 type printer. If this method returns @code{None}, then the result is
1758 ignored; otherwise, it is appended to the list of recognizers.
1760 Then, when @value{GDBN} is going to display a type name, it iterates
1761 over the list of recognizers. For each one, it calls the recognition
1762 function, stopping if the function returns a non-@code{None} value.
1763 The recognition function is defined as:
1765 @defmethod type_recognizer recognize (self, type)
1766 If @var{type} is not recognized, return @code{None}. Otherwise,
1767 return a string which is to be printed as the name of @var{type}.
1768 The @var{type} argument will be an instance of @code{gdb.Type}
1769 (@pxref{Types In Python}).
1772 @value{GDBN} uses this two-pass approach so that type printers can
1773 efficiently cache information without holding on to it too long. For
1774 example, it can be convenient to look up type information in a type
1775 printer and hold it for a recognizer's lifetime; if a single pass were
1776 done then type printers would have to make use of the event system in
1777 order to avoid holding information that could become stale as the
1780 @node Frame Filter API
1781 @subsubsection Filtering Frames
1782 @cindex frame filters api
1784 Frame filters are Python objects that manipulate the visibility of a
1785 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1788 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1789 commands (@pxref{GDB/MI}), those that return a collection of frames
1790 are affected. The commands that work with frame filters are:
1792 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1793 @code{-stack-list-frames}
1794 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1795 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1796 -stack-list-variables command}), @code{-stack-list-arguments}
1797 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1798 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1799 -stack-list-locals command}).
1801 A frame filter works by taking an iterator as an argument, applying
1802 actions to the contents of that iterator, and returning another
1803 iterator (or, possibly, the same iterator it was provided in the case
1804 where the filter does not perform any operations). Typically, frame
1805 filters utilize tools such as the Python's @code{itertools} module to
1806 work with and create new iterators from the source iterator.
1807 Regardless of how a filter chooses to apply actions, it must not alter
1808 the underlying @value{GDBN} frame or frames, or attempt to alter the
1809 call-stack within @value{GDBN}. This preserves data integrity within
1810 @value{GDBN}. Frame filters are executed on a priority basis and care
1811 should be taken that some frame filters may have been executed before,
1812 and that some frame filters will be executed after.
1814 An important consideration when designing frame filters, and well
1815 worth reflecting upon, is that frame filters should avoid unwinding
1816 the call stack if possible. Some stacks can run very deep, into the
1817 tens of thousands in some cases. To search every frame when a frame
1818 filter executes may be too expensive at that step. The frame filter
1819 cannot know how many frames it has to iterate over, and it may have to
1820 iterate through them all. This ends up duplicating effort as
1821 @value{GDBN} performs this iteration when it prints the frames. If
1822 the filter can defer unwinding frames until frame decorators are
1823 executed, after the last filter has executed, it should. @xref{Frame
1824 Decorator API}, for more information on decorators. Also, there are
1825 examples for both frame decorators and filters in later chapters.
1826 @xref{Writing a Frame Filter}, for more information.
1828 The Python dictionary @code{gdb.frame_filters} contains key/object
1829 pairings that comprise a frame filter. Frame filters in this
1830 dictionary are called @code{global} frame filters, and they are
1831 available when debugging all inferiors. These frame filters must
1832 register with the dictionary directly. In addition to the
1833 @code{global} dictionary, there are other dictionaries that are loaded
1834 with different inferiors via auto-loading (@pxref{Python
1835 Auto-loading}). The two other areas where frame filter dictionaries
1836 can be found are: @code{gdb.Progspace} which contains a
1837 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1838 object which also contains a @code{frame_filters} dictionary
1841 When a command is executed from @value{GDBN} that is compatible with
1842 frame filters, @value{GDBN} combines the @code{global},
1843 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1844 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1845 several frames, and thus several object files, might be in use.
1846 @value{GDBN} then prunes any frame filter whose @code{enabled}
1847 attribute is @code{False}. This pruned list is then sorted according
1848 to the @code{priority} attribute in each filter.
1850 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1851 creates an iterator which wraps each frame in the call stack in a
1852 @code{FrameDecorator} object, and calls each filter in order. The
1853 output from the previous filter will always be the input to the next
1856 Frame filters have a mandatory interface which each frame filter must
1857 implement, defined here:
1859 @defun FrameFilter.filter (iterator)
1860 @value{GDBN} will call this method on a frame filter when it has
1861 reached the order in the priority list for that filter.
1863 For example, if there are four frame filters:
1874 The order that the frame filters will be called is:
1877 Filter3 -> Filter2 -> Filter1 -> Filter4
1880 Note that the output from @code{Filter3} is passed to the input of
1881 @code{Filter2}, and so on.
1883 This @code{filter} method is passed a Python iterator. This iterator
1884 contains a sequence of frame decorators that wrap each
1885 @code{gdb.Frame}, or a frame decorator that wraps another frame
1886 decorator. The first filter that is executed in the sequence of frame
1887 filters will receive an iterator entirely comprised of default
1888 @code{FrameDecorator} objects. However, after each frame filter is
1889 executed, the previous frame filter may have wrapped some or all of
1890 the frame decorators with their own frame decorator. As frame
1891 decorators must also conform to a mandatory interface, these
1892 decorators can be assumed to act in a uniform manner (@pxref{Frame
1895 This method must return an object conforming to the Python iterator
1896 protocol. Each item in the iterator must be an object conforming to
1897 the frame decorator interface. If a frame filter does not wish to
1898 perform any operations on this iterator, it should return that
1901 This method is not optional. If it does not exist, @value{GDBN} will
1902 raise and print an error.
1905 @defvar FrameFilter.name
1906 The @code{name} attribute must be Python string which contains the
1907 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1908 Management}). This attribute may contain any combination of letters
1909 or numbers. Care should be taken to ensure that it is unique. This
1910 attribute is mandatory.
1913 @defvar FrameFilter.enabled
1914 The @code{enabled} attribute must be Python boolean. This attribute
1915 indicates to @value{GDBN} whether the frame filter is enabled, and
1916 should be considered when frame filters are executed. If
1917 @code{enabled} is @code{True}, then the frame filter will be executed
1918 when any of the backtrace commands detailed earlier in this chapter
1919 are executed. If @code{enabled} is @code{False}, then the frame
1920 filter will not be executed. This attribute is mandatory.
1923 @defvar FrameFilter.priority
1924 The @code{priority} attribute must be Python integer. This attribute
1925 controls the order of execution in relation to other frame filters.
1926 There are no imposed limits on the range of @code{priority} other than
1927 it must be a valid integer. The higher the @code{priority} attribute,
1928 the sooner the frame filter will be executed in relation to other
1929 frame filters. Although @code{priority} can be negative, it is
1930 recommended practice to assume zero is the lowest priority that a
1931 frame filter can be assigned. Frame filters that have the same
1932 priority are executed in unsorted order in that priority slot. This
1933 attribute is mandatory. 100 is a good default priority.
1936 @node Frame Decorator API
1937 @subsubsection Decorating Frames
1938 @cindex frame decorator api
1940 Frame decorators are sister objects to frame filters (@pxref{Frame
1941 Filter API}). Frame decorators are applied by a frame filter and can
1942 only be used in conjunction with frame filters.
1944 The purpose of a frame decorator is to customize the printed content
1945 of each @code{gdb.Frame} in commands where frame filters are executed.
1946 This concept is called decorating a frame. Frame decorators decorate
1947 a @code{gdb.Frame} with Python code contained within each API call.
1948 This separates the actual data contained in a @code{gdb.Frame} from
1949 the decorated data produced by a frame decorator. This abstraction is
1950 necessary to maintain integrity of the data contained in each
1953 Frame decorators have a mandatory interface, defined below.
1955 @value{GDBN} already contains a frame decorator called
1956 @code{FrameDecorator}. This contains substantial amounts of
1957 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
1958 recommended that other frame decorators inherit and extend this
1959 object, and only to override the methods needed.
1961 @tindex gdb.FrameDecorator
1962 @code{FrameDecorator} is defined in the Python module
1963 @code{gdb.FrameDecorator}, so your code can import it like:
1965 from gdb.FrameDecorator import FrameDecorator
1968 @defun FrameDecorator.elided (self)
1970 The @code{elided} method groups frames together in a hierarchical
1971 system. An example would be an interpreter, where multiple low-level
1972 frames make up a single call in the interpreted language. In this
1973 example, the frame filter would elide the low-level frames and present
1974 a single high-level frame, representing the call in the interpreted
1975 language, to the user.
1977 The @code{elided} function must return an iterable and this iterable
1978 must contain the frames that are being elided wrapped in a suitable
1979 frame decorator. If no frames are being elided this function may
1980 return an empty iterable, or @code{None}. Elided frames are indented
1981 from normal frames in a @code{CLI} backtrace, or in the case of
1982 @code{GDB/MI}, are placed in the @code{children} field of the eliding
1985 It is the frame filter's task to also filter out the elided frames from
1986 the source iterator. This will avoid printing the frame twice.
1989 @defun FrameDecorator.function (self)
1991 This method returns the name of the function in the frame that is to
1994 This method must return a Python string describing the function, or
1997 If this function returns @code{None}, @value{GDBN} will not print any
1998 data for this field.
2001 @defun FrameDecorator.address (self)
2003 This method returns the address of the frame that is to be printed.
2005 This method must return a Python numeric integer type of sufficient
2006 size to describe the address of the frame, or @code{None}.
2008 If this function returns a @code{None}, @value{GDBN} will not print
2009 any data for this field.
2012 @defun FrameDecorator.filename (self)
2014 This method returns the filename and path associated with this frame.
2016 This method must return a Python string containing the filename and
2017 the path to the object file backing the frame, or @code{None}.
2019 If this function returns a @code{None}, @value{GDBN} will not print
2020 any data for this field.
2023 @defun FrameDecorator.line (self):
2025 This method returns the line number associated with the current
2026 position within the function addressed by this frame.
2028 This method must return a Python integer type, or @code{None}.
2030 If this function returns a @code{None}, @value{GDBN} will not print
2031 any data for this field.
2034 @defun FrameDecorator.frame_args (self)
2037 This method must return an iterable, or @code{None}. Returning an
2038 empty iterable, or @code{None} means frame arguments will not be
2039 printed for this frame. This iterable must contain objects that
2040 implement two methods, described here.
2042 This object must implement a @code{argument} method which takes a
2043 single @code{self} parameter and must return a @code{gdb.Symbol}
2044 (@pxref{Symbols In Python}), or a Python string. The object must also
2045 implement a @code{value} method which takes a single @code{self}
2046 parameter and must return a @code{gdb.Value} (@pxref{Values From
2047 Inferior}), a Python value, or @code{None}. If the @code{value}
2048 method returns @code{None}, and the @code{argument} method returns a
2049 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
2050 the @code{gdb.Symbol} automatically.
2055 class SymValueWrapper():
2057 def __init__(self, symbol, value):
2067 class SomeFrameDecorator()
2070 def frame_args(self):
2073 block = self.inferior_frame.block()
2077 # Iterate over all symbols in a block. Only add
2078 # symbols that are arguments.
2080 if not sym.is_argument:
2082 args.append(SymValueWrapper(sym,None))
2084 # Add example synthetic argument.
2085 args.append(SymValueWrapper(``foo'', 42))
2091 @defun FrameDecorator.frame_locals (self)
2093 This method must return an iterable or @code{None}. Returning an
2094 empty iterable, or @code{None} means frame local arguments will not be
2095 printed for this frame.
2097 The object interface, the description of the various strategies for
2098 reading frame locals, and the example are largely similar to those
2099 described in the @code{frame_args} function, (@pxref{frame_args,,The
2100 frame filter frame_args function}). Below is a modified example:
2103 class SomeFrameDecorator()
2106 def frame_locals(self):
2109 block = self.inferior_frame.block()
2113 # Iterate over all symbols in a block. Add all
2114 # symbols, except arguments.
2118 vars.append(SymValueWrapper(sym,None))
2120 # Add an example of a synthetic local variable.
2121 vars.append(SymValueWrapper(``bar'', 99))
2127 @defun FrameDecorator.inferior_frame (self):
2129 This method must return the underlying @code{gdb.Frame} that this
2130 frame decorator is decorating. @value{GDBN} requires the underlying
2131 frame for internal frame information to determine how to print certain
2132 values when printing a frame.
2135 @node Writing a Frame Filter
2136 @subsubsection Writing a Frame Filter
2137 @cindex writing a frame filter
2139 There are three basic elements that a frame filter must implement: it
2140 must correctly implement the documented interface (@pxref{Frame Filter
2141 API}), it must register itself with @value{GDBN}, and finally, it must
2142 decide if it is to work on the data provided by @value{GDBN}. In all
2143 cases, whether it works on the iterator or not, each frame filter must
2144 return an iterator. A bare-bones frame filter follows the pattern in
2145 the following example.
2150 class FrameFilter():
2153 # Frame filter attribute creation.
2155 # 'name' is the name of the filter that GDB will display.
2157 # 'priority' is the priority of the filter relative to other
2160 # 'enabled' is a boolean that indicates whether this filter is
2161 # enabled and should be executed.
2167 # Register this frame filter with the global frame_filters
2169 gdb.frame_filters[self.name] = self
2171 def filter(self, frame_iter):
2172 # Just return the iterator.
2176 The frame filter in the example above implements the three
2177 requirements for all frame filters. It implements the API, self
2178 registers, and makes a decision on the iterator (in this case, it just
2179 returns the iterator untouched).
2181 The first step is attribute creation and assignment, and as shown in
2182 the comments the filter assigns the following attributes: @code{name},
2183 @code{priority} and whether the filter should be enabled with the
2184 @code{enabled} attribute.
2186 The second step is registering the frame filter with the dictionary or
2187 dictionaries that the frame filter has interest in. As shown in the
2188 comments, this filter just registers itself with the global dictionary
2189 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
2190 is a dictionary that is initialized in the @code{gdb} module when
2191 @value{GDBN} starts. What dictionary a filter registers with is an
2192 important consideration. Generally, if a filter is specific to a set
2193 of code, it should be registered either in the @code{objfile} or
2194 @code{progspace} dictionaries as they are specific to the program
2195 currently loaded in @value{GDBN}. The global dictionary is always
2196 present in @value{GDBN} and is never unloaded. Any filters registered
2197 with the global dictionary will exist until @value{GDBN} exits. To
2198 avoid filters that may conflict, it is generally better to register
2199 frame filters against the dictionaries that more closely align with
2200 the usage of the filter currently in question. @xref{Python
2201 Auto-loading}, for further information on auto-loading Python scripts.
2203 @value{GDBN} takes a hands-off approach to frame filter registration,
2204 therefore it is the frame filter's responsibility to ensure
2205 registration has occurred, and that any exceptions are handled
2206 appropriately. In particular, you may wish to handle exceptions
2207 relating to Python dictionary key uniqueness. It is mandatory that
2208 the dictionary key is the same as frame filter's @code{name}
2209 attribute. When a user manages frame filters (@pxref{Frame Filter
2210 Management}), the names @value{GDBN} will display are those contained
2211 in the @code{name} attribute.
2213 The final step of this example is the implementation of the
2214 @code{filter} method. As shown in the example comments, we define the
2215 @code{filter} method and note that the method must take an iterator,
2216 and also must return an iterator. In this bare-bones example, the
2217 frame filter is not very useful as it just returns the iterator
2218 untouched. However this is a valid operation for frame filters that
2219 have the @code{enabled} attribute set, but decide not to operate on
2222 In the next example, the frame filter operates on all frames and
2223 utilizes a frame decorator to perform some work on the frames.
2224 @xref{Frame Decorator API}, for further information on the frame
2225 decorator interface.
2227 This example works on inlined frames. It highlights frames which are
2228 inlined by tagging them with an ``[inlined]'' tag. By applying a
2229 frame decorator to all frames with the Python @code{itertools imap}
2230 method, the example defers actions to the frame decorator. Frame
2231 decorators are only processed when @value{GDBN} prints the backtrace.
2233 This introduces a new decision making topic: whether to perform
2234 decision making operations at the filtering step, or at the printing
2235 step. In this example's approach, it does not perform any filtering
2236 decisions at the filtering step beyond mapping a frame decorator to
2237 each frame. This allows the actual decision making to be performed
2238 when each frame is printed. This is an important consideration, and
2239 well worth reflecting upon when designing a frame filter. An issue
2240 that frame filters should avoid is unwinding the stack if possible.
2241 Some stacks can run very deep, into the tens of thousands in some
2242 cases. To search every frame to determine if it is inlined ahead of
2243 time may be too expensive at the filtering step. The frame filter
2244 cannot know how many frames it has to iterate over, and it would have
2245 to iterate through them all. This ends up duplicating effort as
2246 @value{GDBN} performs this iteration when it prints the frames.
2248 In this example decision making can be deferred to the printing step.
2249 As each frame is printed, the frame decorator can examine each frame
2250 in turn when @value{GDBN} iterates. From a performance viewpoint,
2251 this is the most appropriate decision to make as it avoids duplicating
2252 the effort that the printing step would undertake anyway. Also, if
2253 there are many frame filters unwinding the stack during filtering, it
2254 can substantially delay the printing of the backtrace which will
2255 result in large memory usage, and a poor user experience.
2258 class InlineFilter():
2261 self.name = "InlinedFrameFilter"
2264 gdb.frame_filters[self.name] = self
2266 def filter(self, frame_iter):
2267 frame_iter = itertools.imap(InlinedFrameDecorator,
2272 This frame filter is somewhat similar to the earlier example, except
2273 that the @code{filter} method applies a frame decorator object called
2274 @code{InlinedFrameDecorator} to each element in the iterator. The
2275 @code{imap} Python method is light-weight. It does not proactively
2276 iterate over the iterator, but rather creates a new iterator which
2277 wraps the existing one.
2279 Below is the frame decorator for this example.
2282 class InlinedFrameDecorator(FrameDecorator):
2284 def __init__(self, fobj):
2285 super(InlinedFrameDecorator, self).__init__(fobj)
2288 frame = fobj.inferior_frame()
2289 name = str(frame.name())
2291 if frame.type() == gdb.INLINE_FRAME:
2292 name = name + " [inlined]"
2297 This frame decorator only defines and overrides the @code{function}
2298 method. It lets the supplied @code{FrameDecorator}, which is shipped
2299 with @value{GDBN}, perform the other work associated with printing
2302 The combination of these two objects create this output from a
2306 #0 0x004004e0 in bar () at inline.c:11
2307 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2308 #2 0x00400566 in main () at inline.c:31
2311 So in the case of this example, a frame decorator is applied to all
2312 frames, regardless of whether they may be inlined or not. As
2313 @value{GDBN} iterates over the iterator produced by the frame filters,
2314 @value{GDBN} executes each frame decorator which then makes a decision
2315 on what to print in the @code{function} callback. Using a strategy
2316 like this is a way to defer decisions on the frame content to printing
2319 @subheading Eliding Frames
2321 It might be that the above example is not desirable for representing
2322 inlined frames, and a hierarchical approach may be preferred. If we
2323 want to hierarchically represent frames, the @code{elided} frame
2324 decorator interface might be preferable.
2326 This example approaches the issue with the @code{elided} method. This
2327 example is quite long, but very simplistic. It is out-of-scope for
2328 this section to write a complete example that comprehensively covers
2329 all approaches of finding and printing inlined frames. However, this
2330 example illustrates the approach an author might use.
2332 This example comprises of three sections.
2335 class InlineFrameFilter():
2338 self.name = "InlinedFrameFilter"
2341 gdb.frame_filters[self.name] = self
2343 def filter(self, frame_iter):
2344 return ElidingInlineIterator(frame_iter)
2347 This frame filter is very similar to the other examples. The only
2348 difference is this frame filter is wrapping the iterator provided to
2349 it (@code{frame_iter}) with a custom iterator called
2350 @code{ElidingInlineIterator}. This again defers actions to when
2351 @value{GDBN} prints the backtrace, as the iterator is not traversed
2354 The iterator for this example is as follows. It is in this section of
2355 the example where decisions are made on the content of the backtrace.
2358 class ElidingInlineIterator:
2359 def __init__(self, ii):
2360 self.input_iterator = ii
2366 frame = next(self.input_iterator)
2368 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2372 eliding_frame = next(self.input_iterator)
2373 except StopIteration:
2375 return ElidingFrameDecorator(eliding_frame, [frame])
2378 This iterator implements the Python iterator protocol. When the
2379 @code{next} function is called (when @value{GDBN} prints each frame),
2380 the iterator checks if this frame decorator, @code{frame}, is wrapping
2381 an inlined frame. If it is not, it returns the existing frame decorator
2382 untouched. If it is wrapping an inlined frame, it assumes that the
2383 inlined frame was contained within the next oldest frame,
2384 @code{eliding_frame}, which it fetches. It then creates and returns a
2385 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2386 elided frame, and the eliding frame.
2389 class ElidingInlineDecorator(FrameDecorator):
2391 def __init__(self, frame, elided_frames):
2392 super(ElidingInlineDecorator, self).__init__(frame)
2394 self.elided_frames = elided_frames
2397 return iter(self.elided_frames)
2400 This frame decorator overrides one function and returns the inlined
2401 frame in the @code{elided} method. As before it lets
2402 @code{FrameDecorator} do the rest of the work involved in printing
2403 this frame. This produces the following output.
2406 #0 0x004004e0 in bar () at inline.c:11
2407 #2 0x00400529 in main () at inline.c:25
2408 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2411 In that output, @code{max} which has been inlined into @code{main} is
2412 printed hierarchically. Another approach would be to combine the
2413 @code{function} method, and the @code{elided} method to both print a
2414 marker in the inlined frame, and also show the hierarchical
2417 @node Unwinding Frames in Python
2418 @subsubsection Unwinding Frames in Python
2419 @cindex unwinding frames in Python
2421 In @value{GDBN} terminology ``unwinding'' is the process of finding
2422 the previous frame (that is, caller's) from the current one. An
2423 unwinder has three methods. The first one checks if it can handle
2424 given frame (``sniff'' it). For the frames it can sniff an unwinder
2425 provides two additional methods: it can return frame's ID, and it can
2426 fetch registers from the previous frame. A running @value{GDBN}
2427 mantains a list of the unwinders and calls each unwinder's sniffer in
2428 turn until it finds the one that recognizes the current frame. There
2429 is an API to register an unwinder.
2431 The unwinders that come with @value{GDBN} handle standard frames.
2432 However, mixed language applications (for example, an application
2433 running Java Virtual Machine) sometimes use frame layouts that cannot
2434 be handled by the @value{GDBN} unwinders. You can write Python code
2435 that can handle such custom frames.
2437 You implement a frame unwinder in Python as a class with which has two
2438 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2439 a single method @code{__call__}, which examines a given frame and
2440 returns an object (an instance of @code{gdb.UnwindInfo class)}
2441 describing it. If an unwinder does not recognize a frame, it should
2442 return @code{None}. The code in @value{GDBN} that enables writing
2443 unwinders in Python uses this object to return frame's ID and previous
2444 frame registers when @value{GDBN} core asks for them.
2446 An unwinder should do as little work as possible. Some otherwise
2447 innocuous operations can cause problems (even crashes, as this code is
2448 not not well-hardened yet). For example, making an inferior call from
2449 an unwinder is unadvisable, as an inferior call will reset
2450 @value{GDBN}'s stack unwinding process, potentially causing re-entrant
2453 @subheading Unwinder Input
2455 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2456 provides a method to read frame's registers:
2458 @defun PendingFrame.read_register (reg)
2459 This method returns the contents of the register @var{reg} in the
2460 frame as a @code{gdb.Value} object. @var{reg} can be either a
2461 register number or a register name; the values are platform-specific.
2462 They are usually found in the corresponding
2463 @file{@var{platform}-tdep.h} file in the @value{GDBN} source tree. If
2464 @var{reg} does not name a register for the current architecture, this
2465 method will throw an exception.
2467 Note that this method will always return a @code{gdb.Value} for a
2468 valid register name. This does not mean that the value will be valid.
2469 For example, you may request a register that an earlier unwinder could
2470 not unwind---the value will be unavailable. Instead, the
2471 @code{gdb.Value} returned from this method will be lazy; that is, its
2472 underlying bits will not be fetched until it is first used. So,
2473 attempting to use such a value will cause an exception at the point of
2476 The type of the returned @code{gdb.Value} depends on the register and
2477 the architecture. It is common for registers to have a scalar type,
2478 like @code{long long}; but many other types are possible, such as
2479 pointer, pointer-to-function, floating point or vector types.
2482 It also provides a factory method to create a @code{gdb.UnwindInfo}
2483 instance to be returned to @value{GDBN}:
2485 @defun PendingFrame.create_unwind_info (frame_id)
2486 Returns a new @code{gdb.UnwindInfo} instance identified by given
2487 @var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2488 using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2489 determine which function will be used, as follows:
2493 The frame is identified by the given stack address and PC. The stack
2494 address must be chosen so that it is constant throughout the lifetime
2495 of the frame, so a typical choice is the value of the stack pointer at
2496 the start of the function---in the DWARF standard, this would be the
2497 ``Call Frame Address''.
2499 This is the most common case by far. The other cases are documented
2500 for completeness but are only useful in specialized situations.
2502 @item sp, pc, special
2503 The frame is identified by the stack address, the PC, and a
2504 ``special'' address. The special address is used on architectures
2505 that can have frames that do not change the stack, but which are still
2506 distinct, for example the IA-64, which has a second stack for
2507 registers. Both @var{sp} and @var{special} must be constant
2508 throughout the lifetime of the frame.
2511 The frame is identified by the stack address only. Any other stack
2512 frame with a matching @var{sp} will be considered to match this frame.
2513 Inside gdb, this is called a ``wild frame''. You will never need
2517 Each attribute value should be an instance of @code{gdb.Value}.
2521 @subheading Unwinder Output: UnwindInfo
2523 Use @code{PendingFrame.create_unwind_info} method described above to
2524 create a @code{gdb.UnwindInfo} instance. Use the following method to
2525 specify caller registers that have been saved in this frame:
2527 @defun gdb.UnwindInfo.add_saved_register (reg, value)
2528 @var{reg} identifies the register. It can be a number or a name, just
2529 as for the @code{PendingFrame.read_register} method above.
2530 @var{value} is a register value (a @code{gdb.Value} object).
2533 @subheading Unwinder Skeleton Code
2535 @value{GDBN} comes with the module containing the base @code{Unwinder}
2536 class. Derive your unwinder class from it and structure the code as
2540 from gdb.unwinders import Unwinder
2542 class FrameId(object):
2543 def __init__(self, sp, pc):
2548 class MyUnwinder(Unwinder):
2550 super(MyUnwinder, self).__init___(<expects unwinder name argument>)
2552 def __call__(pending_frame):
2553 if not <we recognize frame>:
2555 # Create UnwindInfo. Usually the frame is identified by the stack
2556 # pointer and the program counter.
2557 sp = pending_frame.read_register(<SP number>)
2558 pc = pending_frame.read_register(<PC number>)
2559 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2561 # Find the values of the registers in the caller's frame and
2562 # save them in the result:
2563 unwind_info.add_saved_register(<register>, <value>)
2566 # Return the result:
2571 @subheading Registering a Unwinder
2573 An object file, a program space, and the @value{GDBN} proper can have
2574 unwinders registered with it.
2576 The @code{gdb.unwinders} module provides the function to register a
2579 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2580 @var{locus} is specifies an object file or a program space to which
2581 @var{unwinder} is added. Passing @code{None} or @code{gdb} adds
2582 @var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
2583 added @var{unwinder} will be called before any other unwinder from the
2584 same locus. Two unwinders in the same locus cannot have the same
2585 name. An attempt to add a unwinder with already existing name raises
2586 an exception unless @var{replace} is @code{True}, in which case the
2587 old unwinder is deleted.
2590 @subheading Unwinder Precedence
2592 @value{GDBN} first calls the unwinders from all the object files in no
2593 particular order, then the unwinders from the current program space,
2594 and finally the unwinders from @value{GDBN}.
2596 @node Xmethods In Python
2597 @subsubsection Xmethods In Python
2598 @cindex xmethods in Python
2600 @dfn{Xmethods} are additional methods or replacements for existing
2601 methods of a C@t{++} class. This feature is useful for those cases
2602 where a method defined in C@t{++} source code could be inlined or
2603 optimized out by the compiler, making it unavailable to @value{GDBN}.
2604 For such cases, one can define an xmethod to serve as a replacement
2605 for the method defined in the C@t{++} source code. @value{GDBN} will
2606 then invoke the xmethod, instead of the C@t{++} method, to
2607 evaluate expressions. One can also use xmethods when debugging
2608 with core files. Moreover, when debugging live programs, invoking an
2609 xmethod need not involve running the inferior (which can potentially
2610 perturb its state). Hence, even if the C@t{++} method is available, it
2611 is better to use its replacement xmethod if one is defined.
2613 The xmethods feature in Python is available via the concepts of an
2614 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2615 implement an xmethod, one has to implement a matcher and a
2616 corresponding worker for it (more than one worker can be
2617 implemented, each catering to a different overloaded instance of the
2618 method). Internally, @value{GDBN} invokes the @code{match} method of a
2619 matcher to match the class type and method name. On a match, the
2620 @code{match} method returns a list of matching @emph{worker} objects.
2621 Each worker object typically corresponds to an overloaded instance of
2622 the xmethod. They implement a @code{get_arg_types} method which
2623 returns a sequence of types corresponding to the arguments the xmethod
2624 requires. @value{GDBN} uses this sequence of types to perform
2625 overload resolution and picks a winning xmethod worker. A winner
2626 is also selected from among the methods @value{GDBN} finds in the
2627 C@t{++} source code. Next, the winning xmethod worker and the
2628 winning C@t{++} method are compared to select an overall winner. In
2629 case of a tie between a xmethod worker and a C@t{++} method, the
2630 xmethod worker is selected as the winner. That is, if a winning
2631 xmethod worker is found to be equivalent to the winning C@t{++}
2632 method, then the xmethod worker is treated as a replacement for
2633 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2634 method. If the winning xmethod worker is the overall winner, then
2635 the corresponding xmethod is invoked via the @code{__call__} method
2636 of the worker object.
2638 If one wants to implement an xmethod as a replacement for an
2639 existing C@t{++} method, then they have to implement an equivalent
2640 xmethod which has exactly the same name and takes arguments of
2641 exactly the same type as the C@t{++} method. If the user wants to
2642 invoke the C@t{++} method even though a replacement xmethod is
2643 available for that method, then they can disable the xmethod.
2645 @xref{Xmethod API}, for API to implement xmethods in Python.
2646 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2649 @subsubsection Xmethod API
2652 The @value{GDBN} Python API provides classes, interfaces and functions
2653 to implement, register and manipulate xmethods.
2654 @xref{Xmethods In Python}.
2656 An xmethod matcher should be an instance of a class derived from
2657 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2658 object with similar interface and attributes. An instance of
2659 @code{XMethodMatcher} has the following attributes:
2662 The name of the matcher.
2666 A boolean value indicating whether the matcher is enabled or disabled.
2670 A list of named methods managed by the matcher. Each object in the list
2671 is an instance of the class @code{XMethod} defined in the module
2672 @code{gdb.xmethod}, or any object with the following attributes:
2677 Name of the xmethod which should be unique for each xmethod
2678 managed by the matcher.
2681 A boolean value indicating whether the xmethod is enabled or
2686 The class @code{XMethod} is a convenience class with same
2687 attributes as above along with the following constructor:
2689 @defun XMethod.__init__ (self, name)
2690 Constructs an enabled xmethod with name @var{name}.
2695 The @code{XMethodMatcher} class has the following methods:
2697 @defun XMethodMatcher.__init__ (self, name)
2698 Constructs an enabled xmethod matcher with name @var{name}. The
2699 @code{methods} attribute is initialized to @code{None}.
2702 @defun XMethodMatcher.match (self, class_type, method_name)
2703 Derived classes should override this method. It should return a
2704 xmethod worker object (or a sequence of xmethod worker
2705 objects) matching the @var{class_type} and @var{method_name}.
2706 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2707 is a string value. If the matcher manages named methods as listed in
2708 its @code{methods} attribute, then only those worker objects whose
2709 corresponding entries in the @code{methods} list are enabled should be
2713 An xmethod worker should be an instance of a class derived from
2714 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
2715 or support the following interface:
2717 @defun XMethodWorker.get_arg_types (self)
2718 This method returns a sequence of @code{gdb.Type} objects corresponding
2719 to the arguments that the xmethod takes. It can return an empty
2720 sequence or @code{None} if the xmethod does not take any arguments.
2721 If the xmethod takes a single argument, then a single
2722 @code{gdb.Type} object corresponding to it can be returned.
2725 @defun XMethodWorker.get_result_type (self, *args)
2726 This method returns a @code{gdb.Type} object representing the type
2727 of the result of invoking this xmethod.
2728 The @var{args} argument is the same tuple of arguments that would be
2729 passed to the @code{__call__} method of this worker.
2732 @defun XMethodWorker.__call__ (self, *args)
2733 This is the method which does the @emph{work} of the xmethod. The
2734 @var{args} arguments is the tuple of arguments to the xmethod. Each
2735 element in this tuple is a gdb.Value object. The first element is
2736 always the @code{this} pointer value.
2739 For @value{GDBN} to lookup xmethods, the xmethod matchers
2740 should be registered using the following function defined in the module
2743 @defun register_xmethod_matcher (locus, matcher, replace=False)
2744 The @code{matcher} is registered with @code{locus}, replacing an
2745 existing matcher with the same name as @code{matcher} if
2746 @code{replace} is @code{True}. @code{locus} can be a
2747 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
2748 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
2749 @code{None}. If it is @code{None}, then @code{matcher} is registered
2753 @node Writing an Xmethod
2754 @subsubsection Writing an Xmethod
2755 @cindex writing xmethods in Python
2757 Implementing xmethods in Python will require implementing xmethod
2758 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2759 the following C@t{++} class:
2765 MyClass (int a) : a_(a) @{ @}
2767 int geta (void) @{ return a_; @}
2768 int operator+ (int b);
2775 MyClass::operator+ (int b)
2782 Let us define two xmethods for the class @code{MyClass}, one
2783 replacing the method @code{geta}, and another adding an overloaded
2784 flavor of @code{operator+} which takes a @code{MyClass} argument (the
2785 C@t{++} code above already has an overloaded @code{operator+}
2786 which takes an @code{int} argument). The xmethod matcher can be
2790 class MyClass_geta(gdb.xmethod.XMethod):
2792 gdb.xmethod.XMethod.__init__(self, 'geta')
2794 def get_worker(self, method_name):
2795 if method_name == 'geta':
2796 return MyClassWorker_geta()
2799 class MyClass_sum(gdb.xmethod.XMethod):
2801 gdb.xmethod.XMethod.__init__(self, 'sum')
2803 def get_worker(self, method_name):
2804 if method_name == 'operator+':
2805 return MyClassWorker_plus()
2808 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2810 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2811 # List of methods 'managed' by this matcher
2812 self.methods = [MyClass_geta(), MyClass_sum()]
2814 def match(self, class_type, method_name):
2815 if class_type.tag != 'MyClass':
2818 for method in self.methods:
2820 worker = method.get_worker(method_name)
2822 workers.append(worker)
2828 Notice that the @code{match} method of @code{MyClassMatcher} returns
2829 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
2830 method, and a worker object of type @code{MyClassWorker_plus} for the
2831 @code{operator+} method. This is done indirectly via helper classes
2832 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
2833 @code{methods} attribute in a matcher as it is optional. However, if a
2834 matcher manages more than one xmethod, it is a good practice to list the
2835 xmethods in the @code{methods} attribute of the matcher. This will then
2836 facilitate enabling and disabling individual xmethods via the
2837 @code{enable/disable} commands. Notice also that a worker object is
2838 returned only if the corresponding entry in the @code{methods} attribute
2839 of the matcher is enabled.
2841 The implementation of the worker classes returned by the matcher setup
2842 above is as follows:
2845 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
2846 def get_arg_types(self):
2849 def get_result_type(self, obj):
2850 return gdb.lookup_type('int')
2852 def __call__(self, obj):
2856 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
2857 def get_arg_types(self):
2858 return gdb.lookup_type('MyClass')
2860 def get_result_type(self, obj):
2861 return gdb.lookup_type('int')
2863 def __call__(self, obj, other):
2864 return obj['a_'] + other['a_']
2867 For @value{GDBN} to actually lookup a xmethod, it has to be
2868 registered with it. The matcher defined above is registered with
2869 @value{GDBN} globally as follows:
2872 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
2875 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
2883 then, after loading the Python script defining the xmethod matchers
2884 and workers into @code{GDBN}, invoking the method @code{geta} or using
2885 the operator @code{+} on @code{obj} will invoke the xmethods
2896 Consider another example with a C++ template class:
2903 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
2904 ~MyTemplate () @{ delete [] data_; @}
2906 int footprint (void)
2908 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
2917 Let us implement an xmethod for the above class which serves as a
2918 replacement for the @code{footprint} method. The full code listing
2919 of the xmethod workers and xmethod matchers is as follows:
2922 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
2923 def __init__(self, class_type):
2924 self.class_type = class_type
2926 def get_arg_types(self):
2929 def get_result_type(self):
2930 return gdb.lookup_type('int')
2932 def __call__(self, obj):
2933 return (self.class_type.sizeof +
2935 self.class_type.template_argument(0).sizeof)
2938 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
2940 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
2942 def match(self, class_type, method_name):
2943 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
2945 method_name == 'footprint'):
2946 return MyTemplateWorker_footprint(class_type)
2949 Notice that, in this example, we have not used the @code{methods}
2950 attribute of the matcher as the matcher manages only one xmethod. The
2951 user can enable/disable this xmethod by enabling/disabling the matcher
2954 @node Inferiors In Python
2955 @subsubsection Inferiors In Python
2956 @cindex inferiors in Python
2958 @findex gdb.Inferior
2959 Programs which are being run under @value{GDBN} are called inferiors
2960 (@pxref{Inferiors Connections and Programs}). Python scripts can access
2961 information about and manipulate inferiors controlled by @value{GDBN}
2962 via objects of the @code{gdb.Inferior} class.
2964 The following inferior-related functions are available in the @code{gdb}
2967 @defun gdb.inferiors ()
2968 Return a tuple containing all inferior objects.
2971 @defun gdb.selected_inferior ()
2972 Return an object representing the current inferior.
2975 A @code{gdb.Inferior} object has the following attributes:
2977 @defvar Inferior.num
2978 ID of inferior, as assigned by GDB.
2981 @defvar Inferior.pid
2982 Process ID of the inferior, as assigned by the underlying operating
2986 @defvar Inferior.was_attached
2987 Boolean signaling whether the inferior was created using `attach', or
2988 started by @value{GDBN} itself.
2991 @defvar Inferior.progspace
2992 The inferior's program space. @xref{Progspaces In Python}.
2995 A @code{gdb.Inferior} object has the following methods:
2997 @defun Inferior.is_valid ()
2998 Returns @code{True} if the @code{gdb.Inferior} object is valid,
2999 @code{False} if not. A @code{gdb.Inferior} object will become invalid
3000 if the inferior no longer exists within @value{GDBN}. All other
3001 @code{gdb.Inferior} methods will throw an exception if it is invalid
3002 at the time the method is called.
3005 @defun Inferior.threads ()
3006 This method returns a tuple holding all the threads which are valid
3007 when it is called. If there are no valid threads, the method will
3008 return an empty tuple.
3011 @defun Inferior.architecture ()
3012 Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
3013 for this inferior. This represents the architecture of the inferior
3014 as a whole. Some platforms can have multiple architectures in a
3015 single address space, so this may not match the architecture of a
3016 particular frame (@pxref{Frames In Python}).
3019 @findex Inferior.read_memory
3020 @defun Inferior.read_memory (address, length)
3021 Read @var{length} addressable memory units from the inferior, starting at
3022 @var{address}. Returns a buffer object, which behaves much like an array
3023 or a string. It can be modified and given to the
3024 @code{Inferior.write_memory} function. In Python 3, the return
3025 value is a @code{memoryview} object.
3028 @findex Inferior.write_memory
3029 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
3030 Write the contents of @var{buffer} to the inferior, starting at
3031 @var{address}. The @var{buffer} parameter must be a Python object
3032 which supports the buffer protocol, i.e., a string, an array or the
3033 object returned from @code{Inferior.read_memory}. If given, @var{length}
3034 determines the number of addressable memory units from @var{buffer} to be
3038 @findex gdb.search_memory
3039 @defun Inferior.search_memory (address, length, pattern)
3040 Search a region of the inferior memory starting at @var{address} with
3041 the given @var{length} using the search pattern supplied in
3042 @var{pattern}. The @var{pattern} parameter must be a Python object
3043 which supports the buffer protocol, i.e., a string, an array or the
3044 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
3045 containing the address where the pattern was found, or @code{None} if
3046 the pattern could not be found.
3049 @findex Inferior.thread_from_handle
3050 @findex Inferior.thread_from_thread_handle
3051 @defun Inferior.thread_from_handle (handle)
3052 Return the thread object corresponding to @var{handle}, a thread
3053 library specific data structure such as @code{pthread_t} for pthreads
3054 library implementations.
3056 The function @code{Inferior.thread_from_thread_handle} provides
3057 the same functionality, but use of @code{Inferior.thread_from_thread_handle}
3061 @node Events In Python
3062 @subsubsection Events In Python
3063 @cindex inferior events in Python
3065 @value{GDBN} provides a general event facility so that Python code can be
3066 notified of various state changes, particularly changes that occur in
3069 An @dfn{event} is just an object that describes some state change. The
3070 type of the object and its attributes will vary depending on the details
3071 of the change. All the existing events are described below.
3073 In order to be notified of an event, you must register an event handler
3074 with an @dfn{event registry}. An event registry is an object in the
3075 @code{gdb.events} module which dispatches particular events. A registry
3076 provides methods to register and unregister event handlers:
3078 @defun EventRegistry.connect (object)
3079 Add the given callable @var{object} to the registry. This object will be
3080 called when an event corresponding to this registry occurs.
3083 @defun EventRegistry.disconnect (object)
3084 Remove the given @var{object} from the registry. Once removed, the object
3085 will no longer receive notifications of events.
3091 def exit_handler (event):
3092 print "event type: exit"
3093 print "exit code: %d" % (event.exit_code)
3095 gdb.events.exited.connect (exit_handler)
3098 In the above example we connect our handler @code{exit_handler} to the
3099 registry @code{events.exited}. Once connected, @code{exit_handler} gets
3100 called when the inferior exits. The argument @dfn{event} in this example is
3101 of type @code{gdb.ExitedEvent}. As you can see in the example the
3102 @code{ExitedEvent} object has an attribute which indicates the exit code of
3105 The following is a listing of the event registries that are available and
3106 details of the events they emit:
3111 Emits @code{gdb.ThreadEvent}.
3113 Some events can be thread specific when @value{GDBN} is running in non-stop
3114 mode. When represented in Python, these events all extend
3115 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
3116 events which are emitted by this or other modules might extend this event.
3117 Examples of these events are @code{gdb.BreakpointEvent} and
3118 @code{gdb.ContinueEvent}.
3120 @defvar ThreadEvent.inferior_thread
3121 In non-stop mode this attribute will be set to the specific thread which was
3122 involved in the emitted event. Otherwise, it will be set to @code{None}.
3125 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
3127 This event indicates that the inferior has been continued after a stop. For
3128 inherited attribute refer to @code{gdb.ThreadEvent} above.
3131 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
3132 @code{events.ExitedEvent} has two attributes:
3133 @defvar ExitedEvent.exit_code
3134 An integer representing the exit code, if available, which the inferior
3135 has returned. (The exit code could be unavailable if, for example,
3136 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
3137 the attribute does not exist.
3139 @defvar ExitedEvent.inferior
3140 A reference to the inferior which triggered the @code{exited} event.
3144 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
3146 Indicates that the inferior has stopped. All events emitted by this registry
3147 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
3148 will indicate the stopped thread when @value{GDBN} is running in non-stop
3149 mode. Refer to @code{gdb.ThreadEvent} above for more details.
3151 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
3153 This event indicates that the inferior or one of its threads has received as
3154 signal. @code{gdb.SignalEvent} has the following attributes:
3156 @defvar SignalEvent.stop_signal
3157 A string representing the signal received by the inferior. A list of possible
3158 signal values can be obtained by running the command @code{info signals} in
3159 the @value{GDBN} command prompt.
3162 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
3164 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
3165 been hit, and has the following attributes:
3167 @defvar BreakpointEvent.breakpoints
3168 A sequence containing references to all the breakpoints (type
3169 @code{gdb.Breakpoint}) that were hit.
3170 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
3172 @defvar BreakpointEvent.breakpoint
3173 A reference to the first breakpoint that was hit.
3174 This function is maintained for backward compatibility and is now deprecated
3175 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
3178 @item events.new_objfile
3179 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
3180 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
3182 @defvar NewObjFileEvent.new_objfile
3183 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
3184 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
3187 @item events.clear_objfiles
3188 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
3189 files for a program space has been reset.
3190 @code{gdb.ClearObjFilesEvent} has one attribute:
3192 @defvar ClearObjFilesEvent.progspace
3193 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
3194 been cleared. @xref{Progspaces In Python}.
3197 @item events.inferior_call
3198 Emits events just before and after a function in the inferior is
3199 called by @value{GDBN}. Before an inferior call, this emits an event
3200 of type @code{gdb.InferiorCallPreEvent}, and after an inferior call,
3201 this emits an event of type @code{gdb.InferiorCallPostEvent}.
3204 @tindex gdb.InferiorCallPreEvent
3205 @item @code{gdb.InferiorCallPreEvent}
3206 Indicates that a function in the inferior is about to be called.
3208 @defvar InferiorCallPreEvent.ptid
3209 The thread in which the call will be run.
3212 @defvar InferiorCallPreEvent.address
3213 The location of the function to be called.
3216 @tindex gdb.InferiorCallPostEvent
3217 @item @code{gdb.InferiorCallPostEvent}
3218 Indicates that a function in the inferior has just been called.
3220 @defvar InferiorCallPostEvent.ptid
3221 The thread in which the call was run.
3224 @defvar InferiorCallPostEvent.address
3225 The location of the function that was called.
3229 @item events.memory_changed
3230 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
3231 inferior has been modified by the @value{GDBN} user, for instance via a
3232 command like @w{@code{set *addr = value}}. The event has the following
3235 @defvar MemoryChangedEvent.address
3236 The start address of the changed region.
3239 @defvar MemoryChangedEvent.length
3240 Length in bytes of the changed region.
3243 @item events.register_changed
3244 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
3245 inferior has been modified by the @value{GDBN} user.
3247 @defvar RegisterChangedEvent.frame
3248 A gdb.Frame object representing the frame in which the register was modified.
3250 @defvar RegisterChangedEvent.regnum
3251 Denotes which register was modified.
3254 @item events.breakpoint_created
3255 This is emitted when a new breakpoint has been created. The argument
3256 that is passed is the new @code{gdb.Breakpoint} object.
3258 @item events.breakpoint_modified
3259 This is emitted when a breakpoint has been modified in some way. The
3260 argument that is passed is the new @code{gdb.Breakpoint} object.
3262 @item events.breakpoint_deleted
3263 This is emitted when a breakpoint has been deleted. The argument that
3264 is passed is the @code{gdb.Breakpoint} object. When this event is
3265 emitted, the @code{gdb.Breakpoint} object will already be in its
3266 invalid state; that is, the @code{is_valid} method will return
3269 @item events.before_prompt
3270 This event carries no payload. It is emitted each time @value{GDBN}
3271 presents a prompt to the user.
3273 @item events.new_inferior
3274 This is emitted when a new inferior is created. Note that the
3275 inferior is not necessarily running; in fact, it may not even have an
3276 associated executable.
3278 The event is of type @code{gdb.NewInferiorEvent}. This has a single
3281 @defvar NewInferiorEvent.inferior
3282 The new inferior, a @code{gdb.Inferior} object.
3285 @item events.inferior_deleted
3286 This is emitted when an inferior has been deleted. Note that this is
3287 not the same as process exit; it is notified when the inferior itself
3288 is removed, say via @code{remove-inferiors}.
3290 The event is of type @code{gdb.InferiorDeletedEvent}. This has a single
3293 @defvar NewInferiorEvent.inferior
3294 The inferior that is being removed, a @code{gdb.Inferior} object.
3297 @item events.new_thread
3298 This is emitted when @value{GDBN} notices a new thread. The event is of
3299 type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}.
3300 This has a single attribute:
3302 @defvar NewThreadEvent.inferior_thread
3308 @node Threads In Python
3309 @subsubsection Threads In Python
3310 @cindex threads in python
3312 @findex gdb.InferiorThread
3313 Python scripts can access information about, and manipulate inferior threads
3314 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
3316 The following thread-related functions are available in the @code{gdb}
3319 @findex gdb.selected_thread
3320 @defun gdb.selected_thread ()
3321 This function returns the thread object for the selected thread. If there
3322 is no selected thread, this will return @code{None}.
3325 To get the list of threads for an inferior, use the @code{Inferior.threads()}
3326 method. @xref{Inferiors In Python}.
3328 A @code{gdb.InferiorThread} object has the following attributes:
3330 @defvar InferiorThread.name
3331 The name of the thread. If the user specified a name using
3332 @code{thread name}, then this returns that name. Otherwise, if an
3333 OS-supplied name is available, then it is returned. Otherwise, this
3334 returns @code{None}.
3336 This attribute can be assigned to. The new value must be a string
3337 object, which sets the new name, or @code{None}, which removes any
3338 user-specified thread name.
3341 @defvar InferiorThread.num
3342 The per-inferior number of the thread, as assigned by GDB.
3345 @defvar InferiorThread.global_num
3346 The global ID of the thread, as assigned by GDB. You can use this to
3347 make Python breakpoints thread-specific, for example
3348 (@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
3351 @defvar InferiorThread.ptid
3352 ID of the thread, as assigned by the operating system. This attribute is a
3353 tuple containing three integers. The first is the Process ID (PID); the second
3354 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
3355 Either the LWPID or TID may be 0, which indicates that the operating system
3356 does not use that identifier.
3359 @defvar InferiorThread.inferior
3360 The inferior this thread belongs to. This attribute is represented as
3361 a @code{gdb.Inferior} object. This attribute is not writable.
3364 A @code{gdb.InferiorThread} object has the following methods:
3366 @defun InferiorThread.is_valid ()
3367 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
3368 @code{False} if not. A @code{gdb.InferiorThread} object will become
3369 invalid if the thread exits, or the inferior that the thread belongs
3370 is deleted. All other @code{gdb.InferiorThread} methods will throw an
3371 exception if it is invalid at the time the method is called.
3374 @defun InferiorThread.switch ()
3375 This changes @value{GDBN}'s currently selected thread to the one represented
3379 @defun InferiorThread.is_stopped ()
3380 Return a Boolean indicating whether the thread is stopped.
3383 @defun InferiorThread.is_running ()
3384 Return a Boolean indicating whether the thread is running.
3387 @defun InferiorThread.is_exited ()
3388 Return a Boolean indicating whether the thread is exited.
3391 @defun InferiorThread.handle ()
3392 Return the thread object's handle, represented as a Python @code{bytes}
3393 object. A @code{gdb.Value} representation of the handle may be
3394 constructed via @code{gdb.Value(bufobj, type)} where @var{bufobj} is
3395 the Python @code{bytes} representation of the handle and @var{type} is
3396 a @code{gdb.Type} for the handle type.
3399 @node Recordings In Python
3400 @subsubsection Recordings In Python
3401 @cindex recordings in python
3403 The following recordings-related functions
3404 (@pxref{Process Record and Replay}) are available in the @code{gdb}
3407 @defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
3408 Start a recording using the given @var{method} and @var{format}. If
3409 no @var{format} is given, the default format for the recording method
3410 is used. If no @var{method} is given, the default method will be used.
3411 Returns a @code{gdb.Record} object on success. Throw an exception on
3414 The following strings can be passed as @var{method}:
3420 @code{"btrace"}: Possible values for @var{format}: @code{"pt"},
3421 @code{"bts"} or leave out for default format.
3425 @defun gdb.current_recording ()
3426 Access a currently running recording. Return a @code{gdb.Record}
3427 object on success. Return @code{None} if no recording is currently
3431 @defun gdb.stop_recording ()
3432 Stop the current recording. Throw an exception if no recording is
3433 currently active. All record objects become invalid after this call.
3436 A @code{gdb.Record} object has the following attributes:
3438 @defvar Record.method
3439 A string with the current recording method, e.g.@: @code{full} or
3443 @defvar Record.format
3444 A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
3448 @defvar Record.begin
3449 A method specific instruction object representing the first instruction
3454 A method specific instruction object representing the current
3455 instruction, that is not actually part of the recording.
3458 @defvar Record.replay_position
3459 The instruction representing the current replay position. If there is
3460 no replay active, this will be @code{None}.
3463 @defvar Record.instruction_history
3464 A list with all recorded instructions.
3467 @defvar Record.function_call_history
3468 A list with all recorded function call segments.
3471 A @code{gdb.Record} object has the following methods:
3473 @defun Record.goto (instruction)
3474 Move the replay position to the given @var{instruction}.
3477 The common @code{gdb.Instruction} class that recording method specific
3478 instruction objects inherit from, has the following attributes:
3480 @defvar Instruction.pc
3481 An integer representing this instruction's address.
3484 @defvar Instruction.data
3485 A buffer with the raw instruction data. In Python 3, the return value is a
3486 @code{memoryview} object.
3489 @defvar Instruction.decoded
3490 A human readable string with the disassembled instruction.
3493 @defvar Instruction.size
3494 The size of the instruction in bytes.
3497 Additionally @code{gdb.RecordInstruction} has the following attributes:
3499 @defvar RecordInstruction.number
3500 An integer identifying this instruction. @code{number} corresponds to
3501 the numbers seen in @code{record instruction-history}
3502 (@pxref{Process Record and Replay}).
3505 @defvar RecordInstruction.sal
3506 A @code{gdb.Symtab_and_line} object representing the associated symtab
3507 and line of this instruction. May be @code{None} if no debug information is
3511 @defvar RecordInstruction.is_speculative
3512 A boolean indicating whether the instruction was executed speculatively.
3515 If an error occured during recording or decoding a recording, this error is
3516 represented by a @code{gdb.RecordGap} object in the instruction list. It has
3517 the following attributes:
3519 @defvar RecordGap.number
3520 An integer identifying this gap. @code{number} corresponds to the numbers seen
3521 in @code{record instruction-history} (@pxref{Process Record and Replay}).
3524 @defvar RecordGap.error_code
3525 A numerical representation of the reason for the gap. The value is specific to
3526 the current recording method.
3529 @defvar RecordGap.error_string
3530 A human readable string with the reason for the gap.
3533 A @code{gdb.RecordFunctionSegment} object has the following attributes:
3535 @defvar RecordFunctionSegment.number
3536 An integer identifying this function segment. @code{number} corresponds to
3537 the numbers seen in @code{record function-call-history}
3538 (@pxref{Process Record and Replay}).
3541 @defvar RecordFunctionSegment.symbol
3542 A @code{gdb.Symbol} object representing the associated symbol. May be
3543 @code{None} if no debug information is available.
3546 @defvar RecordFunctionSegment.level
3547 An integer representing the function call's stack level. May be
3548 @code{None} if the function call is a gap.
3551 @defvar RecordFunctionSegment.instructions
3552 A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
3553 associated with this function call.
3556 @defvar RecordFunctionSegment.up
3557 A @code{gdb.RecordFunctionSegment} object representing the caller's
3558 function segment. If the call has not been recorded, this will be the
3559 function segment to which control returns. If neither the call nor the
3560 return have been recorded, this will be @code{None}.
3563 @defvar RecordFunctionSegment.prev
3564 A @code{gdb.RecordFunctionSegment} object representing the previous
3565 segment of this function call. May be @code{None}.
3568 @defvar RecordFunctionSegment.next
3569 A @code{gdb.RecordFunctionSegment} object representing the next segment of
3570 this function call. May be @code{None}.
3573 The following example demonstrates the usage of these objects and
3574 functions to create a function that will rewind a record to the last
3575 time a function in a different file was executed. This would typically
3576 be used to track the execution of user provided callback functions in a
3577 library which typically are not visible in a back trace.
3581 rec = gdb.current_recording ()
3585 insn = rec.instruction_history
3590 position = insn.index (rec.replay_position)
3594 filename = insn[position].sal.symtab.fullname ()
3598 for i in reversed (insn[:position]):
3600 current = i.sal.symtab.fullname ()
3604 if filename == current:
3611 Another possible application is to write a function that counts the
3612 number of code executions in a given line range. This line range can
3613 contain parts of functions or span across several functions and is not
3614 limited to be contiguous.
3617 def countrange (filename, linerange):
3620 def filter_only (file_name):
3621 for call in gdb.current_recording ().function_call_history:
3623 if file_name in call.symbol.symtab.fullname ():
3628 for c in filter_only (filename):
3629 for i in c.instructions:
3631 if i.sal.line in linerange:
3640 @node Commands In Python
3641 @subsubsection Commands In Python
3643 @cindex commands in python
3644 @cindex python commands
3645 You can implement new @value{GDBN} CLI commands in Python. A CLI
3646 command is implemented using an instance of the @code{gdb.Command}
3647 class, most commonly using a subclass.
3649 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
3650 The object initializer for @code{Command} registers the new command
3651 with @value{GDBN}. This initializer is normally invoked from the
3652 subclass' own @code{__init__} method.
3654 @var{name} is the name of the command. If @var{name} consists of
3655 multiple words, then the initial words are looked for as prefix
3656 commands. In this case, if one of the prefix commands does not exist,
3657 an exception is raised.
3659 There is no support for multi-line commands.
3661 @var{command_class} should be one of the @samp{COMMAND_} constants
3662 defined below. This argument tells @value{GDBN} how to categorize the
3663 new command in the help system.
3665 @var{completer_class} is an optional argument. If given, it should be
3666 one of the @samp{COMPLETE_} constants defined below. This argument
3667 tells @value{GDBN} how to perform completion for this command. If not
3668 given, @value{GDBN} will attempt to complete using the object's
3669 @code{complete} method (see below); if no such method is found, an
3670 error will occur when completion is attempted.
3672 @var{prefix} is an optional argument. If @code{True}, then the new
3673 command is a prefix command; sub-commands of this command may be
3676 The help text for the new command is taken from the Python
3677 documentation string for the command's class, if there is one. If no
3678 documentation string is provided, the default value ``This command is
3679 not documented.'' is used.
3682 @cindex don't repeat Python command
3683 @defun Command.dont_repeat ()
3684 By default, a @value{GDBN} command is repeated when the user enters a
3685 blank line at the command prompt. A command can suppress this
3686 behavior by invoking the @code{dont_repeat} method. This is similar
3687 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
3690 @defun Command.invoke (argument, from_tty)
3691 This method is called by @value{GDBN} when this command is invoked.
3693 @var{argument} is a string. It is the argument to the command, after
3694 leading and trailing whitespace has been stripped.
3696 @var{from_tty} is a boolean argument. When true, this means that the
3697 command was entered by the user at the terminal; when false it means
3698 that the command came from elsewhere.
3700 If this method throws an exception, it is turned into a @value{GDBN}
3701 @code{error} call. Otherwise, the return value is ignored.
3703 @findex gdb.string_to_argv
3704 To break @var{argument} up into an argv-like string use
3705 @code{gdb.string_to_argv}. This function behaves identically to
3706 @value{GDBN}'s internal argument lexer @code{buildargv}.
3707 It is recommended to use this for consistency.
3708 Arguments are separated by spaces and may be quoted.
3712 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
3713 ['1', '2 "3', '4 "5', "6 '7"]
3718 @cindex completion of Python commands
3719 @defun Command.complete (text, word)
3720 This method is called by @value{GDBN} when the user attempts
3721 completion on this command. All forms of completion are handled by
3722 this method, that is, the @key{TAB} and @key{M-?} key bindings
3723 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
3726 The arguments @var{text} and @var{word} are both strings; @var{text}
3727 holds the complete command line up to the cursor's location, while
3728 @var{word} holds the last word of the command line; this is computed
3729 using a word-breaking heuristic.
3731 The @code{complete} method can return several values:
3734 If the return value is a sequence, the contents of the sequence are
3735 used as the completions. It is up to @code{complete} to ensure that the
3736 contents actually do complete the word. A zero-length sequence is
3737 allowed, it means that there were no completions available. Only
3738 string elements of the sequence are used; other elements in the
3739 sequence are ignored.
3742 If the return value is one of the @samp{COMPLETE_} constants defined
3743 below, then the corresponding @value{GDBN}-internal completion
3744 function is invoked, and its result is used.
3747 All other results are treated as though there were no available
3752 When a new command is registered, it must be declared as a member of
3753 some general class of commands. This is used to classify top-level
3754 commands in the on-line help system; note that prefix commands are not
3755 listed under their own category but rather that of their top-level
3756 command. The available classifications are represented by constants
3757 defined in the @code{gdb} module:
3760 @findex COMMAND_NONE
3761 @findex gdb.COMMAND_NONE
3762 @item gdb.COMMAND_NONE
3763 The command does not belong to any particular class. A command in
3764 this category will not be displayed in any of the help categories.
3766 @findex COMMAND_RUNNING
3767 @findex gdb.COMMAND_RUNNING
3768 @item gdb.COMMAND_RUNNING
3769 The command is related to running the inferior. For example,
3770 @code{start}, @code{step}, and @code{continue} are in this category.
3771 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
3772 commands in this category.
3774 @findex COMMAND_DATA
3775 @findex gdb.COMMAND_DATA
3776 @item gdb.COMMAND_DATA
3777 The command is related to data or variables. For example,
3778 @code{call}, @code{find}, and @code{print} are in this category. Type
3779 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
3782 @findex COMMAND_STACK
3783 @findex gdb.COMMAND_STACK
3784 @item gdb.COMMAND_STACK
3785 The command has to do with manipulation of the stack. For example,
3786 @code{backtrace}, @code{frame}, and @code{return} are in this
3787 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
3788 list of commands in this category.
3790 @findex COMMAND_FILES
3791 @findex gdb.COMMAND_FILES
3792 @item gdb.COMMAND_FILES
3793 This class is used for file-related commands. For example,
3794 @code{file}, @code{list} and @code{section} are in this category.
3795 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
3796 commands in this category.
3798 @findex COMMAND_SUPPORT
3799 @findex gdb.COMMAND_SUPPORT
3800 @item gdb.COMMAND_SUPPORT
3801 This should be used for ``support facilities'', generally meaning
3802 things that are useful to the user when interacting with @value{GDBN},
3803 but not related to the state of the inferior. For example,
3804 @code{help}, @code{make}, and @code{shell} are in this category. Type
3805 @kbd{help support} at the @value{GDBN} prompt to see a list of
3806 commands in this category.
3808 @findex COMMAND_STATUS
3809 @findex gdb.COMMAND_STATUS
3810 @item gdb.COMMAND_STATUS
3811 The command is an @samp{info}-related command, that is, related to the
3812 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
3813 and @code{show} are in this category. Type @kbd{help status} at the
3814 @value{GDBN} prompt to see a list of commands in this category.
3816 @findex COMMAND_BREAKPOINTS
3817 @findex gdb.COMMAND_BREAKPOINTS
3818 @item gdb.COMMAND_BREAKPOINTS
3819 The command has to do with breakpoints. For example, @code{break},
3820 @code{clear}, and @code{delete} are in this category. Type @kbd{help
3821 breakpoints} at the @value{GDBN} prompt to see a list of commands in
3824 @findex COMMAND_TRACEPOINTS
3825 @findex gdb.COMMAND_TRACEPOINTS
3826 @item gdb.COMMAND_TRACEPOINTS
3827 The command has to do with tracepoints. For example, @code{trace},
3828 @code{actions}, and @code{tfind} are in this category. Type
3829 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
3830 commands in this category.
3833 @findex gdb.COMMAND_TUI
3834 @item gdb.COMMAND_TUI
3835 The command has to do with the text user interface (@pxref{TUI}).
3836 Type @kbd{help tui} at the @value{GDBN} prompt to see a list of
3837 commands in this category.
3839 @findex COMMAND_USER
3840 @findex gdb.COMMAND_USER
3841 @item gdb.COMMAND_USER
3842 The command is a general purpose command for the user, and typically
3843 does not fit in one of the other categories.
3844 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
3845 a list of commands in this category, as well as the list of gdb macros
3846 (@pxref{Sequences}).
3848 @findex COMMAND_OBSCURE
3849 @findex gdb.COMMAND_OBSCURE
3850 @item gdb.COMMAND_OBSCURE
3851 The command is only used in unusual circumstances, or is not of
3852 general interest to users. For example, @code{checkpoint},
3853 @code{fork}, and @code{stop} are in this category. Type @kbd{help
3854 obscure} at the @value{GDBN} prompt to see a list of commands in this
3857 @findex COMMAND_MAINTENANCE
3858 @findex gdb.COMMAND_MAINTENANCE
3859 @item gdb.COMMAND_MAINTENANCE
3860 The command is only useful to @value{GDBN} maintainers. The
3861 @code{maintenance} and @code{flushregs} commands are in this category.
3862 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
3863 commands in this category.
3866 A new command can use a predefined completion function, either by
3867 specifying it via an argument at initialization, or by returning it
3868 from the @code{complete} method. These predefined completion
3869 constants are all defined in the @code{gdb} module:
3872 @vindex COMPLETE_NONE
3873 @item gdb.COMPLETE_NONE
3874 This constant means that no completion should be done.
3876 @vindex COMPLETE_FILENAME
3877 @item gdb.COMPLETE_FILENAME
3878 This constant means that filename completion should be performed.
3880 @vindex COMPLETE_LOCATION
3881 @item gdb.COMPLETE_LOCATION
3882 This constant means that location completion should be done.
3883 @xref{Specify Location}.
3885 @vindex COMPLETE_COMMAND
3886 @item gdb.COMPLETE_COMMAND
3887 This constant means that completion should examine @value{GDBN}
3890 @vindex COMPLETE_SYMBOL
3891 @item gdb.COMPLETE_SYMBOL
3892 This constant means that completion should be done using symbol names
3895 @vindex COMPLETE_EXPRESSION
3896 @item gdb.COMPLETE_EXPRESSION
3897 This constant means that completion should be done on expressions.
3898 Often this means completing on symbol names, but some language
3899 parsers also have support for completing on field names.
3902 The following code snippet shows how a trivial CLI command can be
3903 implemented in Python:
3906 class HelloWorld (gdb.Command):
3907 """Greet the whole world."""
3909 def __init__ (self):
3910 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
3912 def invoke (self, arg, from_tty):
3913 print "Hello, World!"
3918 The last line instantiates the class, and is necessary to trigger the
3919 registration of the command with @value{GDBN}. Depending on how the
3920 Python code is read into @value{GDBN}, you may need to import the
3921 @code{gdb} module explicitly.
3923 @node Parameters In Python
3924 @subsubsection Parameters In Python
3926 @cindex parameters in python
3927 @cindex python parameters
3928 @tindex gdb.Parameter
3930 You can implement new @value{GDBN} parameters using Python. A new
3931 parameter is implemented as an instance of the @code{gdb.Parameter}
3934 Parameters are exposed to the user via the @code{set} and
3935 @code{show} commands. @xref{Help}.
3937 There are many parameters that already exist and can be set in
3938 @value{GDBN}. Two examples are: @code{set follow fork} and
3939 @code{set charset}. Setting these parameters influences certain
3940 behavior in @value{GDBN}. Similarly, you can define parameters that
3941 can be used to influence behavior in custom Python scripts and commands.
3943 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
3944 The object initializer for @code{Parameter} registers the new
3945 parameter with @value{GDBN}. This initializer is normally invoked
3946 from the subclass' own @code{__init__} method.
3948 @var{name} is the name of the new parameter. If @var{name} consists
3949 of multiple words, then the initial words are looked for as prefix
3950 parameters. An example of this can be illustrated with the
3951 @code{set print} set of parameters. If @var{name} is
3952 @code{print foo}, then @code{print} will be searched as the prefix
3953 parameter. In this case the parameter can subsequently be accessed in
3954 @value{GDBN} as @code{set print foo}.
3956 If @var{name} consists of multiple words, and no prefix parameter group
3957 can be found, an exception is raised.
3959 @var{command-class} should be one of the @samp{COMMAND_} constants
3960 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
3961 categorize the new parameter in the help system.
3963 @var{parameter-class} should be one of the @samp{PARAM_} constants
3964 defined below. This argument tells @value{GDBN} the type of the new
3965 parameter; this information is used for input validation and
3968 If @var{parameter-class} is @code{PARAM_ENUM}, then
3969 @var{enum-sequence} must be a sequence of strings. These strings
3970 represent the possible values for the parameter.
3972 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
3973 of a fourth argument will cause an exception to be thrown.
3975 The help text for the new parameter is taken from the Python
3976 documentation string for the parameter's class, if there is one. If
3977 there is no documentation string, a default value is used.
3980 @defvar Parameter.set_doc
3981 If this attribute exists, and is a string, then its value is used as
3982 the help text for this parameter's @code{set} command. The value is
3983 examined when @code{Parameter.__init__} is invoked; subsequent changes
3987 @defvar Parameter.show_doc
3988 If this attribute exists, and is a string, then its value is used as
3989 the help text for this parameter's @code{show} command. The value is
3990 examined when @code{Parameter.__init__} is invoked; subsequent changes
3994 @defvar Parameter.value
3995 The @code{value} attribute holds the underlying value of the
3996 parameter. It can be read and assigned to just as any other
3997 attribute. @value{GDBN} does validation when assignments are made.
4000 There are two methods that may be implemented in any @code{Parameter}
4003 @defun Parameter.get_set_string (self)
4004 If this method exists, @value{GDBN} will call it when a
4005 @var{parameter}'s value has been changed via the @code{set} API (for
4006 example, @kbd{set foo off}). The @code{value} attribute has already
4007 been populated with the new value and may be used in output. This
4008 method must return a string. If the returned string is not empty,
4009 @value{GDBN} will present it to the user.
4011 If this method raises the @code{gdb.GdbError} exception
4012 (@pxref{Exception Handling}), then @value{GDBN} will print the
4013 exception's string and the @code{set} command will fail. Note,
4014 however, that the @code{value} attribute will not be reset in this
4015 case. So, if your parameter must validate values, it should store the
4016 old value internally and reset the exposed value, like so:
4019 class ExampleParam (gdb.Parameter):
4020 def __init__ (self, name):
4021 super (ExampleParam, self).__init__ (name,
4025 self.saved_value = True
4028 def get_set_string (self):
4029 if not self.validate():
4030 self.value = self.saved_value
4031 raise gdb.GdbError('Failed to validate')
4032 self.saved_value = self.value
4036 @defun Parameter.get_show_string (self, svalue)
4037 @value{GDBN} will call this method when a @var{parameter}'s
4038 @code{show} API has been invoked (for example, @kbd{show foo}). The
4039 argument @code{svalue} receives the string representation of the
4040 current value. This method must return a string.
4043 When a new parameter is defined, its type must be specified. The
4044 available types are represented by constants defined in the @code{gdb}
4048 @findex PARAM_BOOLEAN
4049 @findex gdb.PARAM_BOOLEAN
4050 @item gdb.PARAM_BOOLEAN
4051 The value is a plain boolean. The Python boolean values, @code{True}
4052 and @code{False} are the only valid values.
4054 @findex PARAM_AUTO_BOOLEAN
4055 @findex gdb.PARAM_AUTO_BOOLEAN
4056 @item gdb.PARAM_AUTO_BOOLEAN
4057 The value has three possible states: true, false, and @samp{auto}. In
4058 Python, true and false are represented using boolean constants, and
4059 @samp{auto} is represented using @code{None}.
4061 @findex PARAM_UINTEGER
4062 @findex gdb.PARAM_UINTEGER
4063 @item gdb.PARAM_UINTEGER
4064 The value is an unsigned integer. The value of 0 should be
4065 interpreted to mean ``unlimited''.
4067 @findex PARAM_INTEGER
4068 @findex gdb.PARAM_INTEGER
4069 @item gdb.PARAM_INTEGER
4070 The value is a signed integer. The value of 0 should be interpreted
4071 to mean ``unlimited''.
4073 @findex PARAM_STRING
4074 @findex gdb.PARAM_STRING
4075 @item gdb.PARAM_STRING
4076 The value is a string. When the user modifies the string, any escape
4077 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
4078 translated into corresponding characters and encoded into the current
4081 @findex PARAM_STRING_NOESCAPE
4082 @findex gdb.PARAM_STRING_NOESCAPE
4083 @item gdb.PARAM_STRING_NOESCAPE
4084 The value is a string. When the user modifies the string, escapes are
4085 passed through untranslated.
4087 @findex PARAM_OPTIONAL_FILENAME
4088 @findex gdb.PARAM_OPTIONAL_FILENAME
4089 @item gdb.PARAM_OPTIONAL_FILENAME
4090 The value is a either a filename (a string), or @code{None}.
4092 @findex PARAM_FILENAME
4093 @findex gdb.PARAM_FILENAME
4094 @item gdb.PARAM_FILENAME
4095 The value is a filename. This is just like
4096 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
4098 @findex PARAM_ZINTEGER
4099 @findex gdb.PARAM_ZINTEGER
4100 @item gdb.PARAM_ZINTEGER
4101 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
4102 is interpreted as itself.
4104 @findex PARAM_ZUINTEGER
4105 @findex gdb.PARAM_ZUINTEGER
4106 @item gdb.PARAM_ZUINTEGER
4107 The value is an unsigned integer. This is like @code{PARAM_INTEGER},
4108 except 0 is interpreted as itself, and the value cannot be negative.
4110 @findex PARAM_ZUINTEGER_UNLIMITED
4111 @findex gdb.PARAM_ZUINTEGER_UNLIMITED
4112 @item gdb.PARAM_ZUINTEGER_UNLIMITED
4113 The value is a signed integer. This is like @code{PARAM_ZUINTEGER},
4114 except the special value -1 should be interpreted to mean
4115 ``unlimited''. Other negative values are not allowed.
4118 @findex gdb.PARAM_ENUM
4119 @item gdb.PARAM_ENUM
4120 The value is a string, which must be one of a collection string
4121 constants provided when the parameter is created.
4124 @node Functions In Python
4125 @subsubsection Writing new convenience functions
4127 @cindex writing convenience functions
4128 @cindex convenience functions in python
4129 @cindex python convenience functions
4130 @tindex gdb.Function
4132 You can implement new convenience functions (@pxref{Convenience Vars})
4133 in Python. A convenience function is an instance of a subclass of the
4134 class @code{gdb.Function}.
4136 @defun Function.__init__ (name)
4137 The initializer for @code{Function} registers the new function with
4138 @value{GDBN}. The argument @var{name} is the name of the function,
4139 a string. The function will be visible to the user as a convenience
4140 variable of type @code{internal function}, whose name is the same as
4141 the given @var{name}.
4143 The documentation for the new function is taken from the documentation
4144 string for the new class.
4147 @defun Function.invoke (@var{*args})
4148 When a convenience function is evaluated, its arguments are converted
4149 to instances of @code{gdb.Value}, and then the function's
4150 @code{invoke} method is called. Note that @value{GDBN} does not
4151 predetermine the arity of convenience functions. Instead, all
4152 available arguments are passed to @code{invoke}, following the
4153 standard Python calling convention. In particular, a convenience
4154 function can have default values for parameters without ill effect.
4156 The return value of this method is used as its value in the enclosing
4157 expression. If an ordinary Python value is returned, it is converted
4158 to a @code{gdb.Value} following the usual rules.
4161 The following code snippet shows how a trivial convenience function can
4162 be implemented in Python:
4165 class Greet (gdb.Function):
4166 """Return string to greet someone.
4167 Takes a name as argument."""
4169 def __init__ (self):
4170 super (Greet, self).__init__ ("greet")
4172 def invoke (self, name):
4173 return "Hello, %s!" % name.string ()
4178 The last line instantiates the class, and is necessary to trigger the
4179 registration of the function with @value{GDBN}. Depending on how the
4180 Python code is read into @value{GDBN}, you may need to import the
4181 @code{gdb} module explicitly.
4183 Now you can use the function in an expression:
4186 (gdb) print $greet("Bob")
4190 @node Progspaces In Python
4191 @subsubsection Program Spaces In Python
4193 @cindex progspaces in python
4194 @tindex gdb.Progspace
4196 A program space, or @dfn{progspace}, represents a symbolic view
4197 of an address space.
4198 It consists of all of the objfiles of the program.
4199 @xref{Objfiles In Python}.
4200 @xref{Inferiors Connections and Programs, program spaces}, for more details
4201 about program spaces.
4203 The following progspace-related functions are available in the
4206 @findex gdb.current_progspace
4207 @defun gdb.current_progspace ()
4208 This function returns the program space of the currently selected inferior.
4209 @xref{Inferiors Connections and Programs}. This is identical to
4210 @code{gdb.selected_inferior().progspace} (@pxref{Inferiors In Python}) and is
4211 included for historical compatibility.
4214 @findex gdb.progspaces
4215 @defun gdb.progspaces ()
4216 Return a sequence of all the progspaces currently known to @value{GDBN}.
4219 Each progspace is represented by an instance of the @code{gdb.Progspace}
4222 @defvar Progspace.filename
4223 The file name of the progspace as a string.
4226 @defvar Progspace.pretty_printers
4227 The @code{pretty_printers} attribute is a list of functions. It is
4228 used to look up pretty-printers. A @code{Value} is passed to each
4229 function in order; if the function returns @code{None}, then the
4230 search continues. Otherwise, the return value should be an object
4231 which is used to format the value. @xref{Pretty Printing API}, for more
4235 @defvar Progspace.type_printers
4236 The @code{type_printers} attribute is a list of type printer objects.
4237 @xref{Type Printing API}, for more information.
4240 @defvar Progspace.frame_filters
4241 The @code{frame_filters} attribute is a dictionary of frame filter
4242 objects. @xref{Frame Filter API}, for more information.
4245 A program space has the following methods:
4247 @findex Progspace.block_for_pc
4248 @defun Progspace.block_for_pc (pc)
4249 Return the innermost @code{gdb.Block} containing the given @var{pc}
4250 value. If the block cannot be found for the @var{pc} value specified,
4251 the function will return @code{None}.
4254 @findex Progspace.find_pc_line
4255 @defun Progspace.find_pc_line (pc)
4256 Return the @code{gdb.Symtab_and_line} object corresponding to the
4257 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid value
4258 of @var{pc} is passed as an argument, then the @code{symtab} and
4259 @code{line} attributes of the returned @code{gdb.Symtab_and_line}
4260 object will be @code{None} and 0 respectively.
4263 @findex Progspace.is_valid
4264 @defun Progspace.is_valid ()
4265 Returns @code{True} if the @code{gdb.Progspace} object is valid,
4266 @code{False} if not. A @code{gdb.Progspace} object can become invalid
4267 if the program space file it refers to is not referenced by any
4268 inferior. All other @code{gdb.Progspace} methods will throw an
4269 exception if it is invalid at the time the method is called.
4272 @findex Progspace.objfiles
4273 @defun Progspace.objfiles ()
4274 Return a sequence of all the objfiles referenced by this program
4275 space. @xref{Objfiles In Python}.
4278 @findex Progspace.solib_name
4279 @defun Progspace.solib_name (address)
4280 Return the name of the shared library holding the given @var{address}
4281 as a string, or @code{None}.
4284 One may add arbitrary attributes to @code{gdb.Progspace} objects
4285 in the usual Python way.
4286 This is useful if, for example, one needs to do some extra record keeping
4287 associated with the program space.
4289 In this contrived example, we want to perform some processing when
4290 an objfile with a certain symbol is loaded, but we only want to do
4291 this once because it is expensive. To achieve this we record the results
4292 with the program space because we can't predict when the desired objfile
4297 def clear_objfiles_handler(event):
4298 event.progspace.expensive_computation = None
4299 def expensive(symbol):
4300 """A mock routine to perform an "expensive" computation on symbol."""
4301 print "Computing the answer to the ultimate question ..."
4303 def new_objfile_handler(event):
4304 objfile = event.new_objfile
4305 progspace = objfile.progspace
4306 if not hasattr(progspace, 'expensive_computation') or \
4307 progspace.expensive_computation is None:
4308 # We use 'main' for the symbol to keep the example simple.
4309 # Note: There's no current way to constrain the lookup
4311 symbol = gdb.lookup_global_symbol('main')
4312 if symbol is not None:
4313 progspace.expensive_computation = expensive(symbol)
4314 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
4315 gdb.events.new_objfile.connect(new_objfile_handler)
4317 (gdb) file /tmp/hello
4318 Reading symbols from /tmp/hello...
4319 Computing the answer to the ultimate question ...
4320 (gdb) python print gdb.current_progspace().expensive_computation
4323 Starting program: /tmp/hello
4325 [Inferior 1 (process 4242) exited normally]
4328 @node Objfiles In Python
4329 @subsubsection Objfiles In Python
4331 @cindex objfiles in python
4334 @value{GDBN} loads symbols for an inferior from various
4335 symbol-containing files (@pxref{Files}). These include the primary
4336 executable file, any shared libraries used by the inferior, and any
4337 separate debug info files (@pxref{Separate Debug Files}).
4338 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
4340 The following objfile-related functions are available in the
4343 @findex gdb.current_objfile
4344 @defun gdb.current_objfile ()
4345 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
4346 sets the ``current objfile'' to the corresponding objfile. This
4347 function returns the current objfile. If there is no current objfile,
4348 this function returns @code{None}.
4351 @findex gdb.objfiles
4352 @defun gdb.objfiles ()
4353 Return a sequence of objfiles referenced by the current program space.
4354 @xref{Objfiles In Python}, and @ref{Progspaces In Python}. This is identical
4355 to @code{gdb.selected_inferior().progspace.objfiles()} and is included for
4356 historical compatibility.
4359 @findex gdb.lookup_objfile
4360 @defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
4361 Look up @var{name}, a file name or build ID, in the list of objfiles
4362 for the current program space (@pxref{Progspaces In Python}).
4363 If the objfile is not found throw the Python @code{ValueError} exception.
4365 If @var{name} is a relative file name, then it will match any
4366 source file name with the same trailing components. For example, if
4367 @var{name} is @samp{gcc/expr.c}, then it will match source file
4368 name of @file{/build/trunk/gcc/expr.c}, but not
4369 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
4371 If @var{by_build_id} is provided and is @code{True} then @var{name}
4372 is the build ID of the objfile. Otherwise, @var{name} is a file name.
4373 This is supported only on some operating systems, notably those which use
4374 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4375 about this feature, see the description of the @option{--build-id}
4376 command-line option in @ref{Options, , Command Line Options, ld,
4380 Each objfile is represented by an instance of the @code{gdb.Objfile}
4383 @defvar Objfile.filename
4384 The file name of the objfile as a string, with symbolic links resolved.
4386 The value is @code{None} if the objfile is no longer valid.
4387 See the @code{gdb.Objfile.is_valid} method, described below.
4390 @defvar Objfile.username
4391 The file name of the objfile as specified by the user as a string.
4393 The value is @code{None} if the objfile is no longer valid.
4394 See the @code{gdb.Objfile.is_valid} method, described below.
4397 @defvar Objfile.owner
4398 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
4399 object that debug info is being provided for.
4400 Otherwise this is @code{None}.
4401 Separate debug info objfiles are added with the
4402 @code{gdb.Objfile.add_separate_debug_file} method, described below.
4405 @defvar Objfile.build_id
4406 The build ID of the objfile as a string.
4407 If the objfile does not have a build ID then the value is @code{None}.
4409 This is supported only on some operating systems, notably those which use
4410 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4411 about this feature, see the description of the @option{--build-id}
4412 command-line option in @ref{Options, , Command Line Options, ld,
4416 @defvar Objfile.progspace
4417 The containing program space of the objfile as a @code{gdb.Progspace}
4418 object. @xref{Progspaces In Python}.
4421 @defvar Objfile.pretty_printers
4422 The @code{pretty_printers} attribute is a list of functions. It is
4423 used to look up pretty-printers. A @code{Value} is passed to each
4424 function in order; if the function returns @code{None}, then the
4425 search continues. Otherwise, the return value should be an object
4426 which is used to format the value. @xref{Pretty Printing API}, for more
4430 @defvar Objfile.type_printers
4431 The @code{type_printers} attribute is a list of type printer objects.
4432 @xref{Type Printing API}, for more information.
4435 @defvar Objfile.frame_filters
4436 The @code{frame_filters} attribute is a dictionary of frame filter
4437 objects. @xref{Frame Filter API}, for more information.
4440 One may add arbitrary attributes to @code{gdb.Objfile} objects
4441 in the usual Python way.
4442 This is useful if, for example, one needs to do some extra record keeping
4443 associated with the objfile.
4445 In this contrived example we record the time when @value{GDBN}
4451 def new_objfile_handler(event):
4452 # Set the time_loaded attribute of the new objfile.
4453 event.new_objfile.time_loaded = datetime.datetime.today()
4454 gdb.events.new_objfile.connect(new_objfile_handler)
4457 Reading symbols from ./hello...
4458 (gdb) python print gdb.objfiles()[0].time_loaded
4459 2014-10-09 11:41:36.770345
4462 A @code{gdb.Objfile} object has the following methods:
4464 @defun Objfile.is_valid ()
4465 Returns @code{True} if the @code{gdb.Objfile} object is valid,
4466 @code{False} if not. A @code{gdb.Objfile} object can become invalid
4467 if the object file it refers to is not loaded in @value{GDBN} any
4468 longer. All other @code{gdb.Objfile} methods will throw an exception
4469 if it is invalid at the time the method is called.
4472 @defun Objfile.add_separate_debug_file (file)
4473 Add @var{file} to the list of files that @value{GDBN} will search for
4474 debug information for the objfile.
4475 This is useful when the debug info has been removed from the program
4476 and stored in a separate file. @value{GDBN} has built-in support for
4477 finding separate debug info files (@pxref{Separate Debug Files}), but if
4478 the file doesn't live in one of the standard places that @value{GDBN}
4479 searches then this function can be used to add a debug info file
4480 from a different place.
4483 @defun Objfile.lookup_global_symbol (name @r{[}, domain@r{]})
4484 Search for a global symbol named @var{name} in this objfile. Optionally, the
4485 search scope can be restricted with the @var{domain} argument.
4486 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4487 module and described in @ref{Symbols In Python}. This function is similar to
4488 @code{gdb.lookup_global_symbol}, except that the search is limited to this
4491 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4495 @defun Objfile.lookup_static_symbol (name @r{[}, domain@r{]})
4496 Like @code{Objfile.lookup_global_symbol}, but searches for a global
4497 symbol with static linkage named @var{name} in this objfile.
4500 @node Frames In Python
4501 @subsubsection Accessing inferior stack frames from Python
4503 @cindex frames in python
4504 When the debugged program stops, @value{GDBN} is able to analyze its call
4505 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
4506 represents a frame in the stack. A @code{gdb.Frame} object is only valid
4507 while its corresponding frame exists in the inferior's stack. If you try
4508 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
4509 exception (@pxref{Exception Handling}).
4511 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
4515 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
4519 The following frame-related functions are available in the @code{gdb} module:
4521 @findex gdb.selected_frame
4522 @defun gdb.selected_frame ()
4523 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
4526 @findex gdb.newest_frame
4527 @defun gdb.newest_frame ()
4528 Return the newest frame object for the selected thread.
4531 @defun gdb.frame_stop_reason_string (reason)
4532 Return a string explaining the reason why @value{GDBN} stopped unwinding
4533 frames, as expressed by the given @var{reason} code (an integer, see the
4534 @code{unwind_stop_reason} method further down in this section).
4537 @findex gdb.invalidate_cached_frames
4538 @defun gdb.invalidate_cached_frames
4539 @value{GDBN} internally keeps a cache of the frames that have been
4540 unwound. This function invalidates this cache.
4542 This function should not generally be called by ordinary Python code.
4543 It is documented for the sake of completeness.
4546 A @code{gdb.Frame} object has the following methods:
4548 @defun Frame.is_valid ()
4549 Returns true if the @code{gdb.Frame} object is valid, false if not.
4550 A frame object can become invalid if the frame it refers to doesn't
4551 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
4552 an exception if it is invalid at the time the method is called.
4555 @defun Frame.name ()
4556 Returns the function name of the frame, or @code{None} if it can't be
4560 @defun Frame.architecture ()
4561 Returns the @code{gdb.Architecture} object corresponding to the frame's
4562 architecture. @xref{Architectures In Python}.
4565 @defun Frame.type ()
4566 Returns the type of the frame. The value can be one of:
4568 @item gdb.NORMAL_FRAME
4569 An ordinary stack frame.
4571 @item gdb.DUMMY_FRAME
4572 A fake stack frame that was created by @value{GDBN} when performing an
4573 inferior function call.
4575 @item gdb.INLINE_FRAME
4576 A frame representing an inlined function. The function was inlined
4577 into a @code{gdb.NORMAL_FRAME} that is older than this one.
4579 @item gdb.TAILCALL_FRAME
4580 A frame representing a tail call. @xref{Tail Call Frames}.
4582 @item gdb.SIGTRAMP_FRAME
4583 A signal trampoline frame. This is the frame created by the OS when
4584 it calls into a signal handler.
4586 @item gdb.ARCH_FRAME
4587 A fake stack frame representing a cross-architecture call.
4589 @item gdb.SENTINEL_FRAME
4590 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
4595 @defun Frame.unwind_stop_reason ()
4596 Return an integer representing the reason why it's not possible to find
4597 more frames toward the outermost frame. Use
4598 @code{gdb.frame_stop_reason_string} to convert the value returned by this
4599 function to a string. The value can be one of:
4602 @item gdb.FRAME_UNWIND_NO_REASON
4603 No particular reason (older frames should be available).
4605 @item gdb.FRAME_UNWIND_NULL_ID
4606 The previous frame's analyzer returns an invalid result. This is no
4607 longer used by @value{GDBN}, and is kept only for backward
4610 @item gdb.FRAME_UNWIND_OUTERMOST
4611 This frame is the outermost.
4613 @item gdb.FRAME_UNWIND_UNAVAILABLE
4614 Cannot unwind further, because that would require knowing the
4615 values of registers or memory that have not been collected.
4617 @item gdb.FRAME_UNWIND_INNER_ID
4618 This frame ID looks like it ought to belong to a NEXT frame,
4619 but we got it for a PREV frame. Normally, this is a sign of
4620 unwinder failure. It could also indicate stack corruption.
4622 @item gdb.FRAME_UNWIND_SAME_ID
4623 This frame has the same ID as the previous one. That means
4624 that unwinding further would almost certainly give us another
4625 frame with exactly the same ID, so break the chain. Normally,
4626 this is a sign of unwinder failure. It could also indicate
4629 @item gdb.FRAME_UNWIND_NO_SAVED_PC
4630 The frame unwinder did not find any saved PC, but we needed
4631 one to unwind further.
4633 @item gdb.FRAME_UNWIND_MEMORY_ERROR
4634 The frame unwinder caused an error while trying to access memory.
4636 @item gdb.FRAME_UNWIND_FIRST_ERROR
4637 Any stop reason greater or equal to this value indicates some kind
4638 of error. This special value facilitates writing code that tests
4639 for errors in unwinding in a way that will work correctly even if
4640 the list of the other values is modified in future @value{GDBN}
4641 versions. Using it, you could write:
4643 reason = gdb.selected_frame().unwind_stop_reason ()
4644 reason_str = gdb.frame_stop_reason_string (reason)
4645 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
4646 print "An error occured: %s" % reason_str
4653 Returns the frame's resume address.
4656 @defun Frame.block ()
4657 Return the frame's code block. @xref{Blocks In Python}. If the frame
4658 does not have a block -- for example, if there is no debugging
4659 information for the code in question -- then this will throw an
4663 @defun Frame.function ()
4664 Return the symbol for the function corresponding to this frame.
4665 @xref{Symbols In Python}.
4668 @defun Frame.older ()
4669 Return the frame that called this frame.
4672 @defun Frame.newer ()
4673 Return the frame called by this frame.
4676 @defun Frame.find_sal ()
4677 Return the frame's symtab and line object.
4678 @xref{Symbol Tables In Python}.
4681 @defun Frame.read_register (register)
4682 Return the value of @var{register} in this frame. The @var{register}
4683 argument must be a string (e.g., @code{'sp'} or @code{'rax'}).
4684 Returns a @code{Gdb.Value} object. Throws an exception if @var{register}
4688 @defun Frame.read_var (variable @r{[}, block@r{]})
4689 Return the value of @var{variable} in this frame. If the optional
4690 argument @var{block} is provided, search for the variable from that
4691 block; otherwise start at the frame's current block (which is
4692 determined by the frame's current program counter). The @var{variable}
4693 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
4694 @code{gdb.Block} object.
4697 @defun Frame.select ()
4698 Set this frame to be the selected frame. @xref{Stack, ,Examining the
4702 @node Blocks In Python
4703 @subsubsection Accessing blocks from Python
4705 @cindex blocks in python
4708 In @value{GDBN}, symbols are stored in blocks. A block corresponds
4709 roughly to a scope in the source code. Blocks are organized
4710 hierarchically, and are represented individually in Python as a
4711 @code{gdb.Block}. Blocks rely on debugging information being
4714 A frame has a block. Please see @ref{Frames In Python}, for a more
4715 in-depth discussion of frames.
4717 The outermost block is known as the @dfn{global block}. The global
4718 block typically holds public global variables and functions.
4720 The block nested just inside the global block is the @dfn{static
4721 block}. The static block typically holds file-scoped variables and
4724 @value{GDBN} provides a method to get a block's superblock, but there
4725 is currently no way to examine the sub-blocks of a block, or to
4726 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
4729 Here is a short example that should help explain blocks:
4732 /* This is in the global block. */
4735 /* This is in the static block. */
4736 static int file_scope;
4738 /* 'function' is in the global block, and 'argument' is
4739 in a block nested inside of 'function'. */
4740 int function (int argument)
4742 /* 'local' is in a block inside 'function'. It may or may
4743 not be in the same block as 'argument'. */
4747 /* 'inner' is in a block whose superblock is the one holding
4751 /* If this call is expanded by the compiler, you may see
4752 a nested block here whose function is 'inline_function'
4753 and whose superblock is the one holding 'inner'. */
4759 A @code{gdb.Block} is iterable. The iterator returns the symbols
4760 (@pxref{Symbols In Python}) local to the block. Python programs
4761 should not assume that a specific block object will always contain a
4762 given symbol, since changes in @value{GDBN} features and
4763 infrastructure may cause symbols move across blocks in a symbol
4764 table. You can also use Python's @dfn{dictionary syntax} to access
4765 variables in this block, e.g.:
4768 symbol = some_block['variable'] # symbol is of type gdb.Symbol
4771 The following block-related functions are available in the @code{gdb}
4774 @findex gdb.block_for_pc
4775 @defun gdb.block_for_pc (pc)
4776 Return the innermost @code{gdb.Block} containing the given @var{pc}
4777 value. If the block cannot be found for the @var{pc} value specified,
4778 the function will return @code{None}. This is identical to
4779 @code{gdb.current_progspace().block_for_pc(pc)} and is included for
4780 historical compatibility.
4783 A @code{gdb.Block} object has the following methods:
4785 @defun Block.is_valid ()
4786 Returns @code{True} if the @code{gdb.Block} object is valid,
4787 @code{False} if not. A block object can become invalid if the block it
4788 refers to doesn't exist anymore in the inferior. All other
4789 @code{gdb.Block} methods will throw an exception if it is invalid at
4790 the time the method is called. The block's validity is also checked
4791 during iteration over symbols of the block.
4794 A @code{gdb.Block} object has the following attributes:
4797 The start address of the block. This attribute is not writable.
4801 One past the last address that appears in the block. This attribute
4805 @defvar Block.function
4806 The name of the block represented as a @code{gdb.Symbol}. If the
4807 block is not named, then this attribute holds @code{None}. This
4808 attribute is not writable.
4810 For ordinary function blocks, the superblock is the static block.
4811 However, you should note that it is possible for a function block to
4812 have a superblock that is not the static block -- for instance this
4813 happens for an inlined function.
4816 @defvar Block.superblock
4817 The block containing this block. If this parent block does not exist,
4818 this attribute holds @code{None}. This attribute is not writable.
4821 @defvar Block.global_block
4822 The global block associated with this block. This attribute is not
4826 @defvar Block.static_block
4827 The static block associated with this block. This attribute is not
4831 @defvar Block.is_global
4832 @code{True} if the @code{gdb.Block} object is a global block,
4833 @code{False} if not. This attribute is not
4837 @defvar Block.is_static
4838 @code{True} if the @code{gdb.Block} object is a static block,
4839 @code{False} if not. This attribute is not writable.
4842 @node Symbols In Python
4843 @subsubsection Python representation of Symbols
4845 @cindex symbols in python
4848 @value{GDBN} represents every variable, function and type as an
4849 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
4850 Similarly, Python represents these symbols in @value{GDBN} with the
4851 @code{gdb.Symbol} object.
4853 The following symbol-related functions are available in the @code{gdb}
4856 @findex gdb.lookup_symbol
4857 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
4858 This function searches for a symbol by name. The search scope can be
4859 restricted to the parameters defined in the optional domain and block
4862 @var{name} is the name of the symbol. It must be a string. The
4863 optional @var{block} argument restricts the search to symbols visible
4864 in that @var{block}. The @var{block} argument must be a
4865 @code{gdb.Block} object. If omitted, the block for the current frame
4866 is used. The optional @var{domain} argument restricts
4867 the search to the domain type. The @var{domain} argument must be a
4868 domain constant defined in the @code{gdb} module and described later
4871 The result is a tuple of two elements.
4872 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
4874 If the symbol is found, the second element is @code{True} if the symbol
4875 is a field of a method's object (e.g., @code{this} in C@t{++}),
4876 otherwise it is @code{False}.
4877 If the symbol is not found, the second element is @code{False}.
4880 @findex gdb.lookup_global_symbol
4881 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
4882 This function searches for a global symbol by name.
4883 The search scope can be restricted to by the domain argument.
4885 @var{name} is the name of the symbol. It must be a string.
4886 The optional @var{domain} argument restricts the search to the domain type.
4887 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4888 module and described later in this chapter.
4890 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4894 @findex gdb.lookup_static_symbol
4895 @defun gdb.lookup_static_symbol (name @r{[}, domain@r{]})
4896 This function searches for a global symbol with static linkage by name.
4897 The search scope can be restricted to by the domain argument.
4899 @var{name} is the name of the symbol. It must be a string.
4900 The optional @var{domain} argument restricts the search to the domain type.
4901 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4902 module and described later in this chapter.
4904 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4907 Note that this function will not find function-scoped static variables. To look
4908 up such variables, iterate over the variables of the function's
4909 @code{gdb.Block} and check that @code{block.addr_class} is
4910 @code{gdb.SYMBOL_LOC_STATIC}.
4912 There can be multiple global symbols with static linkage with the same
4913 name. This function will only return the first matching symbol that
4914 it finds. Which symbol is found depends on where @value{GDBN} is
4915 currently stopped, as @value{GDBN} will first search for matching
4916 symbols in the current object file, and then search all other object
4917 files. If the application is not yet running then @value{GDBN} will
4918 search all object files in the order they appear in the debug
4922 @findex gdb.lookup_static_symbols
4923 @defun gdb.lookup_static_symbols (name @r{[}, domain@r{]})
4924 Similar to @code{gdb.lookup_static_symbol}, this function searches for
4925 global symbols with static linkage by name, and optionally restricted
4926 by the domain argument. However, this function returns a list of all
4927 matching symbols found, not just the first one.
4929 @var{name} is the name of the symbol. It must be a string.
4930 The optional @var{domain} argument restricts the search to the domain type.
4931 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4932 module and described later in this chapter.
4934 The result is a list of @code{gdb.Symbol} objects which could be empty
4935 if no matching symbols were found.
4937 Note that this function will not find function-scoped static variables. To look
4938 up such variables, iterate over the variables of the function's
4939 @code{gdb.Block} and check that @code{block.addr_class} is
4940 @code{gdb.SYMBOL_LOC_STATIC}.
4943 A @code{gdb.Symbol} object has the following attributes:
4946 The type of the symbol or @code{None} if no type is recorded.
4947 This attribute is represented as a @code{gdb.Type} object.
4948 @xref{Types In Python}. This attribute is not writable.
4951 @defvar Symbol.symtab
4952 The symbol table in which the symbol appears. This attribute is
4953 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
4954 Python}. This attribute is not writable.
4958 The line number in the source code at which the symbol was defined.
4963 The name of the symbol as a string. This attribute is not writable.
4966 @defvar Symbol.linkage_name
4967 The name of the symbol, as used by the linker (i.e., may be mangled).
4968 This attribute is not writable.
4971 @defvar Symbol.print_name
4972 The name of the symbol in a form suitable for output. This is either
4973 @code{name} or @code{linkage_name}, depending on whether the user
4974 asked @value{GDBN} to display demangled or mangled names.
4977 @defvar Symbol.addr_class
4978 The address class of the symbol. This classifies how to find the value
4979 of a symbol. Each address class is a constant defined in the
4980 @code{gdb} module and described later in this chapter.
4983 @defvar Symbol.needs_frame
4984 This is @code{True} if evaluating this symbol's value requires a frame
4985 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
4986 local variables will require a frame, but other symbols will not.
4989 @defvar Symbol.is_argument
4990 @code{True} if the symbol is an argument of a function.
4993 @defvar Symbol.is_constant
4994 @code{True} if the symbol is a constant.
4997 @defvar Symbol.is_function
4998 @code{True} if the symbol is a function or a method.
5001 @defvar Symbol.is_variable
5002 @code{True} if the symbol is a variable.
5005 A @code{gdb.Symbol} object has the following methods:
5007 @defun Symbol.is_valid ()
5008 Returns @code{True} if the @code{gdb.Symbol} object is valid,
5009 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
5010 the symbol it refers to does not exist in @value{GDBN} any longer.
5011 All other @code{gdb.Symbol} methods will throw an exception if it is
5012 invalid at the time the method is called.
5015 @defun Symbol.value (@r{[}frame@r{]})
5016 Compute the value of the symbol, as a @code{gdb.Value}. For
5017 functions, this computes the address of the function, cast to the
5018 appropriate type. If the symbol requires a frame in order to compute
5019 its value, then @var{frame} must be given. If @var{frame} is not
5020 given, or if @var{frame} is invalid, then this method will throw an
5024 The available domain categories in @code{gdb.Symbol} are represented
5025 as constants in the @code{gdb} module:
5028 @vindex SYMBOL_UNDEF_DOMAIN
5029 @item gdb.SYMBOL_UNDEF_DOMAIN
5030 This is used when a domain has not been discovered or none of the
5031 following domains apply. This usually indicates an error either
5032 in the symbol information or in @value{GDBN}'s handling of symbols.
5034 @vindex SYMBOL_VAR_DOMAIN
5035 @item gdb.SYMBOL_VAR_DOMAIN
5036 This domain contains variables, function names, typedef names and enum
5039 @vindex SYMBOL_STRUCT_DOMAIN
5040 @item gdb.SYMBOL_STRUCT_DOMAIN
5041 This domain holds struct, union and enum type names.
5043 @vindex SYMBOL_LABEL_DOMAIN
5044 @item gdb.SYMBOL_LABEL_DOMAIN
5045 This domain contains names of labels (for gotos).
5047 @vindex SYMBOL_MODULE_DOMAIN
5048 @item gdb.SYMBOL_MODULE_DOMAIN
5049 This domain contains names of Fortran module types.
5051 @vindex SYMBOL_COMMON_BLOCK_DOMAIN
5052 @item gdb.SYMBOL_COMMON_BLOCK_DOMAIN
5053 This domain contains names of Fortran common blocks.
5056 The available address class categories in @code{gdb.Symbol} are represented
5057 as constants in the @code{gdb} module:
5060 @vindex SYMBOL_LOC_UNDEF
5061 @item gdb.SYMBOL_LOC_UNDEF
5062 If this is returned by address class, it indicates an error either in
5063 the symbol information or in @value{GDBN}'s handling of symbols.
5065 @vindex SYMBOL_LOC_CONST
5066 @item gdb.SYMBOL_LOC_CONST
5067 Value is constant int.
5069 @vindex SYMBOL_LOC_STATIC
5070 @item gdb.SYMBOL_LOC_STATIC
5071 Value is at a fixed address.
5073 @vindex SYMBOL_LOC_REGISTER
5074 @item gdb.SYMBOL_LOC_REGISTER
5075 Value is in a register.
5077 @vindex SYMBOL_LOC_ARG
5078 @item gdb.SYMBOL_LOC_ARG
5079 Value is an argument. This value is at the offset stored within the
5080 symbol inside the frame's argument list.
5082 @vindex SYMBOL_LOC_REF_ARG
5083 @item gdb.SYMBOL_LOC_REF_ARG
5084 Value address is stored in the frame's argument list. Just like
5085 @code{LOC_ARG} except that the value's address is stored at the
5086 offset, not the value itself.
5088 @vindex SYMBOL_LOC_REGPARM_ADDR
5089 @item gdb.SYMBOL_LOC_REGPARM_ADDR
5090 Value is a specified register. Just like @code{LOC_REGISTER} except
5091 the register holds the address of the argument instead of the argument
5094 @vindex SYMBOL_LOC_LOCAL
5095 @item gdb.SYMBOL_LOC_LOCAL
5096 Value is a local variable.
5098 @vindex SYMBOL_LOC_TYPEDEF
5099 @item gdb.SYMBOL_LOC_TYPEDEF
5100 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
5103 @vindex SYMBOL_LOC_BLOCK
5104 @item gdb.SYMBOL_LOC_BLOCK
5107 @vindex SYMBOL_LOC_CONST_BYTES
5108 @item gdb.SYMBOL_LOC_CONST_BYTES
5109 Value is a byte-sequence.
5111 @vindex SYMBOL_LOC_UNRESOLVED
5112 @item gdb.SYMBOL_LOC_UNRESOLVED
5113 Value is at a fixed address, but the address of the variable has to be
5114 determined from the minimal symbol table whenever the variable is
5117 @vindex SYMBOL_LOC_OPTIMIZED_OUT
5118 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
5119 The value does not actually exist in the program.
5121 @vindex SYMBOL_LOC_COMPUTED
5122 @item gdb.SYMBOL_LOC_COMPUTED
5123 The value's address is a computed location.
5125 @vindex SYMBOL_LOC_COMPUTED
5126 @item gdb.SYMBOL_LOC_COMPUTED
5127 The value's address is a symbol. This is only used for Fortran common
5131 @node Symbol Tables In Python
5132 @subsubsection Symbol table representation in Python
5134 @cindex symbol tables in python
5136 @tindex gdb.Symtab_and_line
5138 Access to symbol table data maintained by @value{GDBN} on the inferior
5139 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
5140 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
5141 from the @code{find_sal} method in @code{gdb.Frame} object.
5142 @xref{Frames In Python}.
5144 For more information on @value{GDBN}'s symbol table management, see
5145 @ref{Symbols, ,Examining the Symbol Table}, for more information.
5147 A @code{gdb.Symtab_and_line} object has the following attributes:
5149 @defvar Symtab_and_line.symtab
5150 The symbol table object (@code{gdb.Symtab}) for this frame.
5151 This attribute is not writable.
5154 @defvar Symtab_and_line.pc
5155 Indicates the start of the address range occupied by code for the
5156 current source line. This attribute is not writable.
5159 @defvar Symtab_and_line.last
5160 Indicates the end of the address range occupied by code for the current
5161 source line. This attribute is not writable.
5164 @defvar Symtab_and_line.line
5165 Indicates the current line number for this object. This
5166 attribute is not writable.
5169 A @code{gdb.Symtab_and_line} object has the following methods:
5171 @defun Symtab_and_line.is_valid ()
5172 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
5173 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
5174 invalid if the Symbol table and line object it refers to does not
5175 exist in @value{GDBN} any longer. All other
5176 @code{gdb.Symtab_and_line} methods will throw an exception if it is
5177 invalid at the time the method is called.
5180 A @code{gdb.Symtab} object has the following attributes:
5182 @defvar Symtab.filename
5183 The symbol table's source filename. This attribute is not writable.
5186 @defvar Symtab.objfile
5187 The symbol table's backing object file. @xref{Objfiles In Python}.
5188 This attribute is not writable.
5191 @defvar Symtab.producer
5192 The name and possibly version number of the program that
5193 compiled the code in the symbol table.
5194 The contents of this string is up to the compiler.
5195 If no producer information is available then @code{None} is returned.
5196 This attribute is not writable.
5199 A @code{gdb.Symtab} object has the following methods:
5201 @defun Symtab.is_valid ()
5202 Returns @code{True} if the @code{gdb.Symtab} object is valid,
5203 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
5204 the symbol table it refers to does not exist in @value{GDBN} any
5205 longer. All other @code{gdb.Symtab} methods will throw an exception
5206 if it is invalid at the time the method is called.
5209 @defun Symtab.fullname ()
5210 Return the symbol table's source absolute file name.
5213 @defun Symtab.global_block ()
5214 Return the global block of the underlying symbol table.
5215 @xref{Blocks In Python}.
5218 @defun Symtab.static_block ()
5219 Return the static block of the underlying symbol table.
5220 @xref{Blocks In Python}.
5223 @defun Symtab.linetable ()
5224 Return the line table associated with the symbol table.
5225 @xref{Line Tables In Python}.
5228 @node Line Tables In Python
5229 @subsubsection Manipulating line tables using Python
5231 @cindex line tables in python
5232 @tindex gdb.LineTable
5234 Python code can request and inspect line table information from a
5235 symbol table that is loaded in @value{GDBN}. A line table is a
5236 mapping of source lines to their executable locations in memory. To
5237 acquire the line table information for a particular symbol table, use
5238 the @code{linetable} function (@pxref{Symbol Tables In Python}).
5240 A @code{gdb.LineTable} is iterable. The iterator returns
5241 @code{LineTableEntry} objects that correspond to the source line and
5242 address for each line table entry. @code{LineTableEntry} objects have
5243 the following attributes:
5245 @defvar LineTableEntry.line
5246 The source line number for this line table entry. This number
5247 corresponds to the actual line of source. This attribute is not
5251 @defvar LineTableEntry.pc
5252 The address that is associated with the line table entry where the
5253 executable code for that source line resides in memory. This
5254 attribute is not writable.
5257 As there can be multiple addresses for a single source line, you may
5258 receive multiple @code{LineTableEntry} objects with matching
5259 @code{line} attributes, but with different @code{pc} attributes. The
5260 iterator is sorted in ascending @code{pc} order. Here is a small
5261 example illustrating iterating over a line table.
5264 symtab = gdb.selected_frame().find_sal().symtab
5265 linetable = symtab.linetable()
5266 for line in linetable:
5267 print "Line: "+str(line.line)+" Address: "+hex(line.pc)
5270 This will have the following output:
5273 Line: 33 Address: 0x4005c8L
5274 Line: 37 Address: 0x4005caL
5275 Line: 39 Address: 0x4005d2L
5276 Line: 40 Address: 0x4005f8L
5277 Line: 42 Address: 0x4005ffL
5278 Line: 44 Address: 0x400608L
5279 Line: 42 Address: 0x40060cL
5280 Line: 45 Address: 0x400615L
5283 In addition to being able to iterate over a @code{LineTable}, it also
5284 has the following direct access methods:
5286 @defun LineTable.line (line)
5287 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
5288 entries in the line table for the given @var{line}, which specifies
5289 the source code line. If there are no entries for that source code
5290 @var{line}, the Python @code{None} is returned.
5293 @defun LineTable.has_line (line)
5294 Return a Python @code{Boolean} indicating whether there is an entry in
5295 the line table for this source line. Return @code{True} if an entry
5296 is found, or @code{False} if not.
5299 @defun LineTable.source_lines ()
5300 Return a Python @code{List} of the source line numbers in the symbol
5301 table. Only lines with executable code locations are returned. The
5302 contents of the @code{List} will just be the source line entries
5303 represented as Python @code{Long} values.
5306 @node Breakpoints In Python
5307 @subsubsection Manipulating breakpoints using Python
5309 @cindex breakpoints in python
5310 @tindex gdb.Breakpoint
5312 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
5315 A breakpoint can be created using one of the two forms of the
5316 @code{gdb.Breakpoint} constructor. The first one accepts a string
5317 like one would pass to the @code{break}
5318 (@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
5319 (@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
5320 create both breakpoints and watchpoints. The second accepts separate Python
5321 arguments similar to @ref{Explicit Locations}, and can only be used to create
5324 @defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]})
5325 Create a new breakpoint according to @var{spec}, which is a string naming the
5326 location of a breakpoint, or an expression that defines a watchpoint. The
5327 string should describe a location in a format recognized by the @code{break}
5328 command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
5329 watchpoint, by the @code{watch} command
5330 (@pxref{Set Watchpoints, , Setting Watchpoints}).
5332 The optional @var{type} argument specifies the type of the breakpoint to create,
5335 The optional @var{wp_class} argument defines the class of watchpoint to create,
5336 if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
5337 defaults to @code{gdb.WP_WRITE}.
5339 The optional @var{internal} argument allows the breakpoint to become invisible
5340 to the user. The breakpoint will neither be reported when created, nor will it
5341 be listed in the output from @code{info breakpoints} (but will be listed with
5342 the @code{maint info breakpoints} command).
5344 The optional @var{temporary} argument makes the breakpoint a temporary
5345 breakpoint. Temporary breakpoints are deleted after they have been hit. Any
5346 further access to the Python breakpoint after it has been hit will result in a
5347 runtime error (as that breakpoint has now been automatically deleted).
5349 The optional @var{qualified} argument is a boolean that allows interpreting
5350 the function passed in @code{spec} as a fully-qualified name. It is equivalent
5351 to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
5352 @ref{Explicit Locations}).
5356 @defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]})
5357 This second form of creating a new breakpoint specifies the explicit
5358 location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
5359 be created in the specified source file @var{source}, at the specified
5360 @var{function}, @var{label} and @var{line}.
5362 @var{internal}, @var{temporary} and @var{qualified} have the same usage as
5363 explained previously.
5366 The available types are represented by constants defined in the @code{gdb}
5370 @vindex BP_BREAKPOINT
5371 @item gdb.BP_BREAKPOINT
5372 Normal code breakpoint.
5374 @vindex BP_WATCHPOINT
5375 @item gdb.BP_WATCHPOINT
5376 Watchpoint breakpoint.
5378 @vindex BP_HARDWARE_WATCHPOINT
5379 @item gdb.BP_HARDWARE_WATCHPOINT
5380 Hardware assisted watchpoint.
5382 @vindex BP_READ_WATCHPOINT
5383 @item gdb.BP_READ_WATCHPOINT
5384 Hardware assisted read watchpoint.
5386 @vindex BP_ACCESS_WATCHPOINT
5387 @item gdb.BP_ACCESS_WATCHPOINT
5388 Hardware assisted access watchpoint.
5391 The available watchpoint types represented by constants are defined in the
5397 Read only watchpoint.
5401 Write only watchpoint.
5405 Read/Write watchpoint.
5408 @defun Breakpoint.stop (self)
5409 The @code{gdb.Breakpoint} class can be sub-classed and, in
5410 particular, you may choose to implement the @code{stop} method.
5411 If this method is defined in a sub-class of @code{gdb.Breakpoint},
5412 it will be called when the inferior reaches any location of a
5413 breakpoint which instantiates that sub-class. If the method returns
5414 @code{True}, the inferior will be stopped at the location of the
5415 breakpoint, otherwise the inferior will continue.
5417 If there are multiple breakpoints at the same location with a
5418 @code{stop} method, each one will be called regardless of the
5419 return status of the previous. This ensures that all @code{stop}
5420 methods have a chance to execute at that location. In this scenario
5421 if one of the methods returns @code{True} but the others return
5422 @code{False}, the inferior will still be stopped.
5424 You should not alter the execution state of the inferior (i.e.@:, step,
5425 next, etc.), alter the current frame context (i.e.@:, change the current
5426 active frame), or alter, add or delete any breakpoint. As a general
5427 rule, you should not alter any data within @value{GDBN} or the inferior
5430 Example @code{stop} implementation:
5433 class MyBreakpoint (gdb.Breakpoint):
5435 inf_val = gdb.parse_and_eval("foo")
5442 @defun Breakpoint.is_valid ()
5443 Return @code{True} if this @code{Breakpoint} object is valid,
5444 @code{False} otherwise. A @code{Breakpoint} object can become invalid
5445 if the user deletes the breakpoint. In this case, the object still
5446 exists, but the underlying breakpoint does not. In the cases of
5447 watchpoint scope, the watchpoint remains valid even if execution of the
5448 inferior leaves the scope of that watchpoint.
5451 @defun Breakpoint.delete ()
5452 Permanently deletes the @value{GDBN} breakpoint. This also
5453 invalidates the Python @code{Breakpoint} object. Any further access
5454 to this object's attributes or methods will raise an error.
5457 @defvar Breakpoint.enabled
5458 This attribute is @code{True} if the breakpoint is enabled, and
5459 @code{False} otherwise. This attribute is writable. You can use it to enable
5460 or disable the breakpoint.
5463 @defvar Breakpoint.silent
5464 This attribute is @code{True} if the breakpoint is silent, and
5465 @code{False} otherwise. This attribute is writable.
5467 Note that a breakpoint can also be silent if it has commands and the
5468 first command is @code{silent}. This is not reported by the
5469 @code{silent} attribute.
5472 @defvar Breakpoint.pending
5473 This attribute is @code{True} if the breakpoint is pending, and
5474 @code{False} otherwise. @xref{Set Breaks}. This attribute is
5478 @anchor{python_breakpoint_thread}
5479 @defvar Breakpoint.thread
5480 If the breakpoint is thread-specific, this attribute holds the
5481 thread's global id. If the breakpoint is not thread-specific, this
5482 attribute is @code{None}. This attribute is writable.
5485 @defvar Breakpoint.task
5486 If the breakpoint is Ada task-specific, this attribute holds the Ada task
5487 id. If the breakpoint is not task-specific (or the underlying
5488 language is not Ada), this attribute is @code{None}. This attribute
5492 @defvar Breakpoint.ignore_count
5493 This attribute holds the ignore count for the breakpoint, an integer.
5494 This attribute is writable.
5497 @defvar Breakpoint.number
5498 This attribute holds the breakpoint's number --- the identifier used by
5499 the user to manipulate the breakpoint. This attribute is not writable.
5502 @defvar Breakpoint.type
5503 This attribute holds the breakpoint's type --- the identifier used to
5504 determine the actual breakpoint type or use-case. This attribute is not
5508 @defvar Breakpoint.visible
5509 This attribute tells whether the breakpoint is visible to the user
5510 when set, or when the @samp{info breakpoints} command is run. This
5511 attribute is not writable.
5514 @defvar Breakpoint.temporary
5515 This attribute indicates whether the breakpoint was created as a
5516 temporary breakpoint. Temporary breakpoints are automatically deleted
5517 after that breakpoint has been hit. Access to this attribute, and all
5518 other attributes and functions other than the @code{is_valid}
5519 function, will result in an error after the breakpoint has been hit
5520 (as it has been automatically deleted). This attribute is not
5524 @defvar Breakpoint.hit_count
5525 This attribute holds the hit count for the breakpoint, an integer.
5526 This attribute is writable, but currently it can only be set to zero.
5529 @defvar Breakpoint.location
5530 This attribute holds the location of the breakpoint, as specified by
5531 the user. It is a string. If the breakpoint does not have a location
5532 (that is, it is a watchpoint) the attribute's value is @code{None}. This
5533 attribute is not writable.
5536 @defvar Breakpoint.expression
5537 This attribute holds a breakpoint expression, as specified by
5538 the user. It is a string. If the breakpoint does not have an
5539 expression (the breakpoint is not a watchpoint) the attribute's value
5540 is @code{None}. This attribute is not writable.
5543 @defvar Breakpoint.condition
5544 This attribute holds the condition of the breakpoint, as specified by
5545 the user. It is a string. If there is no condition, this attribute's
5546 value is @code{None}. This attribute is writable.
5549 @defvar Breakpoint.commands
5550 This attribute holds the commands attached to the breakpoint. If
5551 there are commands, this attribute's value is a string holding all the
5552 commands, separated by newlines. If there are no commands, this
5553 attribute is @code{None}. This attribute is writable.
5556 @node Finish Breakpoints in Python
5557 @subsubsection Finish Breakpoints
5559 @cindex python finish breakpoints
5560 @tindex gdb.FinishBreakpoint
5562 A finish breakpoint is a temporary breakpoint set at the return address of
5563 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
5564 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
5565 and deleted when the execution will run out of the breakpoint scope (i.e.@:
5566 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
5567 Finish breakpoints are thread specific and must be create with the right
5570 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
5571 Create a finish breakpoint at the return address of the @code{gdb.Frame}
5572 object @var{frame}. If @var{frame} is not provided, this defaults to the
5573 newest frame. The optional @var{internal} argument allows the breakpoint to
5574 become invisible to the user. @xref{Breakpoints In Python}, for further
5575 details about this argument.
5578 @defun FinishBreakpoint.out_of_scope (self)
5579 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
5580 @code{return} command, @dots{}), a function may not properly terminate, and
5581 thus never hit the finish breakpoint. When @value{GDBN} notices such a
5582 situation, the @code{out_of_scope} callback will be triggered.
5584 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
5588 class MyFinishBreakpoint (gdb.FinishBreakpoint)
5590 print "normal finish"
5593 def out_of_scope ():
5594 print "abnormal finish"
5598 @defvar FinishBreakpoint.return_value
5599 When @value{GDBN} is stopped at a finish breakpoint and the frame
5600 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
5601 attribute will contain a @code{gdb.Value} object corresponding to the return
5602 value of the function. The value will be @code{None} if the function return
5603 type is @code{void} or if the return value was not computable. This attribute
5607 @node Lazy Strings In Python
5608 @subsubsection Python representation of lazy strings
5610 @cindex lazy strings in python
5611 @tindex gdb.LazyString
5613 A @dfn{lazy string} is a string whose contents is not retrieved or
5614 encoded until it is needed.
5616 A @code{gdb.LazyString} is represented in @value{GDBN} as an
5617 @code{address} that points to a region of memory, an @code{encoding}
5618 that will be used to encode that region of memory, and a @code{length}
5619 to delimit the region of memory that represents the string. The
5620 difference between a @code{gdb.LazyString} and a string wrapped within
5621 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
5622 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
5623 retrieved and encoded during printing, while a @code{gdb.Value}
5624 wrapping a string is immediately retrieved and encoded on creation.
5626 A @code{gdb.LazyString} object has the following functions:
5628 @defun LazyString.value ()
5629 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
5630 will point to the string in memory, but will lose all the delayed
5631 retrieval, encoding and handling that @value{GDBN} applies to a
5632 @code{gdb.LazyString}.
5635 @defvar LazyString.address
5636 This attribute holds the address of the string. This attribute is not
5640 @defvar LazyString.length
5641 This attribute holds the length of the string in characters. If the
5642 length is -1, then the string will be fetched and encoded up to the
5643 first null of appropriate width. This attribute is not writable.
5646 @defvar LazyString.encoding
5647 This attribute holds the encoding that will be applied to the string
5648 when the string is printed by @value{GDBN}. If the encoding is not
5649 set, or contains an empty string, then @value{GDBN} will select the
5650 most appropriate encoding when the string is printed. This attribute
5654 @defvar LazyString.type
5655 This attribute holds the type that is represented by the lazy string's
5656 type. For a lazy string this is a pointer or array type. To
5657 resolve this to the lazy string's character type, use the type's
5658 @code{target} method. @xref{Types In Python}. This attribute is not
5662 @node Architectures In Python
5663 @subsubsection Python representation of architectures
5664 @cindex Python architectures
5666 @value{GDBN} uses architecture specific parameters and artifacts in a
5667 number of its various computations. An architecture is represented
5668 by an instance of the @code{gdb.Architecture} class.
5670 A @code{gdb.Architecture} class has the following methods:
5672 @defun Architecture.name ()
5673 Return the name (string value) of the architecture.
5676 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
5677 Return a list of disassembled instructions starting from the memory
5678 address @var{start_pc}. The optional arguments @var{end_pc} and
5679 @var{count} determine the number of instructions in the returned list.
5680 If both the optional arguments @var{end_pc} and @var{count} are
5681 specified, then a list of at most @var{count} disassembled instructions
5682 whose start address falls in the closed memory address interval from
5683 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
5684 specified, but @var{count} is specified, then @var{count} number of
5685 instructions starting from the address @var{start_pc} are returned. If
5686 @var{count} is not specified but @var{end_pc} is specified, then all
5687 instructions whose start address falls in the closed memory address
5688 interval from @var{start_pc} to @var{end_pc} are returned. If neither
5689 @var{end_pc} nor @var{count} are specified, then a single instruction at
5690 @var{start_pc} is returned. For all of these cases, each element of the
5691 returned list is a Python @code{dict} with the following string keys:
5696 The value corresponding to this key is a Python long integer capturing
5697 the memory address of the instruction.
5700 The value corresponding to this key is a string value which represents
5701 the instruction with assembly language mnemonics. The assembly
5702 language flavor used is the same as that specified by the current CLI
5703 variable @code{disassembly-flavor}. @xref{Machine Code}.
5706 The value corresponding to this key is the length (integer value) of the
5707 instruction in bytes.
5712 @node TUI Windows In Python
5713 @subsubsection Implementing new TUI windows
5714 @cindex Python TUI Windows
5716 New TUI (@pxref{TUI}) windows can be implemented in Python.
5718 @findex gdb.register_window_type
5719 @defun gdb.register_window_type (@var{name}, @var{factory})
5720 Because TUI windows are created and destroyed depending on the layout
5721 the user chooses, new window types are implemented by registering a
5722 factory function with @value{GDBN}.
5724 @var{name} is the name of the new window. It's an error to try to
5725 replace one of the built-in windows, but other window types can be
5728 @var{function} is a factory function that is called to create the TUI
5729 window. This is called with a single argument of type
5730 @code{gdb.TuiWindow}, described below. It should return an object
5731 that implements the TUI window protocol, also described below.
5734 As mentioned above, when a factory function is called, it is passed a
5735 an object of type @code{gdb.TuiWindow}. This object has these
5736 methods and attributes:
5738 @defun TuiWindow.is_valid ()
5739 This method returns @code{True} when this window is valid. When the
5740 user changes the TUI layout, windows no longer visible in the new
5741 layout will be destroyed. At this point, the @code{gdb.TuiWindow}
5742 will no longer be valid, and methods (and attributes) other than
5743 @code{is_valid} will throw an exception.
5746 @defvar TuiWindow.width
5747 This attribute holds the width of the window. It is not writable.
5750 @defvar TuiWindow.height
5751 This attribute holds the height of the window. It is not writable.
5754 @defvar TuiWindow.title
5755 This attribute holds the window's title, a string. This is normally
5756 displayed above the window. This attribute can be modified.
5759 @defun TuiWindow.erase ()
5760 Remove all the contents of the window.
5763 @defun TuiWindow.write (@var{string})
5764 Write @var{string} to the window. @var{string} can contain ANSI
5765 terminal escape styling sequences; @value{GDBN} will translate these
5766 as appropriate for the terminal.
5769 The factory function that you supply should return an object
5770 conforming to the TUI window protocol. These are the method that can
5771 be called on this object, which is referred to below as the ``window
5772 object''. The methods documented below are optional; if the object
5773 does not implement one of these methods, @value{GDBN} will not attempt
5774 to call it. Additional new methods may be added to the window
5775 protocol in the future. @value{GDBN} guarantees that they will begin
5776 with a lower-case letter, so you can start implementation methods with
5777 upper-case letters or underscore to avoid any future conflicts.
5779 @defun Window.close ()
5780 When the TUI window is closed, the @code{gdb.TuiWindow} object will be
5781 put into an invalid state. At this time, @value{GDBN} will call
5782 @code{close} method on the window object.
5784 After this method is called, @value{GDBN} will discard any references
5785 it holds on this window object, and will no longer call methods on
5789 @defun Window.render ()
5790 In some situations, a TUI window can change size. For example, this
5791 can happen if the user resizes the terminal, or changes the layout.
5792 When this happens, @value{GDBN} will call the @code{render} method on
5795 If your window is intended to update in response to changes in the
5796 inferior, you will probably also want to register event listeners and
5797 send output to the @code{gdb.TuiWindow}.
5800 @defun Window.hscroll (@var{num})
5801 This is a request to scroll the window horizontally. @var{num} is the
5802 amount by which to scroll, with negative numbers meaning to scroll
5803 right. In the TUI model, it is the viewport that moves, not the
5804 contents. A positive argument should cause the viewport to move
5805 right, and so the content should appear to move to the left.
5808 @defun Window.vscroll (@var{num})
5809 This is a request to scroll the window vertically. @var{num} is the
5810 amount by which to scroll, with negative numbers meaning to scroll
5811 backward. In the TUI model, it is the viewport that moves, not the
5812 contents. A positive argument should cause the viewport to move down,
5813 and so the content should appear to move up.
5816 @node Python Auto-loading
5817 @subsection Python Auto-loading
5818 @cindex Python auto-loading
5820 When a new object file is read (for example, due to the @code{file}
5821 command, or because the inferior has loaded a shared library),
5822 @value{GDBN} will look for Python support scripts in several ways:
5823 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
5824 @xref{Auto-loading extensions}.
5826 The auto-loading feature is useful for supplying application-specific
5827 debugging commands and scripts.
5829 Auto-loading can be enabled or disabled,
5830 and the list of auto-loaded scripts can be printed.
5833 @anchor{set auto-load python-scripts}
5834 @kindex set auto-load python-scripts
5835 @item set auto-load python-scripts [on|off]
5836 Enable or disable the auto-loading of Python scripts.
5838 @anchor{show auto-load python-scripts}
5839 @kindex show auto-load python-scripts
5840 @item show auto-load python-scripts
5841 Show whether auto-loading of Python scripts is enabled or disabled.
5843 @anchor{info auto-load python-scripts}
5844 @kindex info auto-load python-scripts
5845 @cindex print list of auto-loaded Python scripts
5846 @item info auto-load python-scripts [@var{regexp}]
5847 Print the list of all Python scripts that @value{GDBN} auto-loaded.
5849 Also printed is the list of Python scripts that were mentioned in
5850 the @code{.debug_gdb_scripts} section and were either not found
5851 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
5852 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
5853 This is useful because their names are not printed when @value{GDBN}
5854 tries to load them and fails. There may be many of them, and printing
5855 an error message for each one is problematic.
5857 If @var{regexp} is supplied only Python scripts with matching names are printed.
5862 (gdb) info auto-load python-scripts
5864 Yes py-section-script.py
5865 full name: /tmp/py-section-script.py
5866 No my-foo-pretty-printers.py
5870 When reading an auto-loaded file or script, @value{GDBN} sets the
5871 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
5872 function (@pxref{Objfiles In Python}). This can be useful for
5873 registering objfile-specific pretty-printers and frame-filters.
5875 @node Python modules
5876 @subsection Python modules
5877 @cindex python modules
5879 @value{GDBN} comes with several modules to assist writing Python code.
5882 * gdb.printing:: Building and registering pretty-printers.
5883 * gdb.types:: Utilities for working with types.
5884 * gdb.prompt:: Utilities for prompt value substitution.
5888 @subsubsection gdb.printing
5889 @cindex gdb.printing
5891 This module provides a collection of utilities for working with
5895 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
5896 This class specifies the API that makes @samp{info pretty-printer},
5897 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
5898 Pretty-printers should generally inherit from this class.
5900 @item SubPrettyPrinter (@var{name})
5901 For printers that handle multiple types, this class specifies the
5902 corresponding API for the subprinters.
5904 @item RegexpCollectionPrettyPrinter (@var{name})
5905 Utility class for handling multiple printers, all recognized via
5906 regular expressions.
5907 @xref{Writing a Pretty-Printer}, for an example.
5909 @item FlagEnumerationPrinter (@var{name})
5910 A pretty-printer which handles printing of @code{enum} values. Unlike
5911 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
5912 work properly when there is some overlap between the enumeration
5913 constants. The argument @var{name} is the name of the printer and
5914 also the name of the @code{enum} type to look up.
5916 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
5917 Register @var{printer} with the pretty-printer list of @var{obj}.
5918 If @var{replace} is @code{True} then any existing copy of the printer
5919 is replaced. Otherwise a @code{RuntimeError} exception is raised
5920 if a printer with the same name already exists.
5924 @subsubsection gdb.types
5927 This module provides a collection of utilities for working with
5928 @code{gdb.Type} objects.
5931 @item get_basic_type (@var{type})
5932 Return @var{type} with const and volatile qualifiers stripped,
5933 and with typedefs and C@t{++} references converted to the underlying type.
5938 typedef const int const_int;
5940 const_int& foo_ref (foo);
5941 int main () @{ return 0; @}
5948 (gdb) python import gdb.types
5949 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
5950 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
5954 @item has_field (@var{type}, @var{field})
5955 Return @code{True} if @var{type}, assumed to be a type with fields
5956 (e.g., a structure or union), has field @var{field}.
5958 @item make_enum_dict (@var{enum_type})
5959 Return a Python @code{dictionary} type produced from @var{enum_type}.
5961 @item deep_items (@var{type})
5962 Returns a Python iterator similar to the standard
5963 @code{gdb.Type.iteritems} method, except that the iterator returned
5964 by @code{deep_items} will recursively traverse anonymous struct or
5965 union fields. For example:
5979 Then in @value{GDBN}:
5981 (@value{GDBP}) python import gdb.types
5982 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
5983 (@value{GDBP}) python print struct_a.keys ()
5985 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
5986 @{['a', 'b0', 'b1']@}
5989 @item get_type_recognizers ()
5990 Return a list of the enabled type recognizers for the current context.
5991 This is called by @value{GDBN} during the type-printing process
5992 (@pxref{Type Printing API}).
5994 @item apply_type_recognizers (recognizers, type_obj)
5995 Apply the type recognizers, @var{recognizers}, to the type object
5996 @var{type_obj}. If any recognizer returns a string, return that
5997 string. Otherwise, return @code{None}. This is called by
5998 @value{GDBN} during the type-printing process (@pxref{Type Printing
6001 @item register_type_printer (locus, printer)
6002 This is a convenience function to register a type printer
6003 @var{printer}. The printer must implement the type printer protocol.
6004 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
6005 the printer is registered with that objfile; a @code{gdb.Progspace},
6006 in which case the printer is registered with that progspace; or
6007 @code{None}, in which case the printer is registered globally.
6010 This is a base class that implements the type printer protocol. Type
6011 printers are encouraged, but not required, to derive from this class.
6012 It defines a constructor:
6014 @defmethod TypePrinter __init__ (self, name)
6015 Initialize the type printer with the given name. The new printer
6016 starts in the enabled state.
6022 @subsubsection gdb.prompt
6025 This module provides a method for prompt value-substitution.
6028 @item substitute_prompt (@var{string})
6029 Return @var{string} with escape sequences substituted by values. Some
6030 escape sequences take arguments. You can specify arguments inside
6031 ``@{@}'' immediately following the escape sequence.
6033 The escape sequences you can pass to this function are:
6037 Substitute a backslash.
6039 Substitute an ESC character.
6041 Substitute the selected frame; an argument names a frame parameter.
6043 Substitute a newline.
6045 Substitute a parameter's value; the argument names the parameter.
6047 Substitute a carriage return.
6049 Substitute the selected thread; an argument names a thread parameter.
6051 Substitute the version of GDB.
6053 Substitute the current working directory.
6055 Begin a sequence of non-printing characters. These sequences are
6056 typically used with the ESC character, and are not counted in the string
6057 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
6058 blue-colored ``(gdb)'' prompt where the length is five.
6060 End a sequence of non-printing characters.
6066 substitute_prompt ("frame: \f, args: \p@{print frame-arguments@}")
6069 @exdent will return the string:
6072 "frame: main, args: scalars"