1 @c Copyright (C) 2008-2017 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}.
22 @cindex python directory
23 Python scripts used by @value{GDBN} should be installed in
24 @file{@var{data-directory}/python}, where @var{data-directory} is
25 the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
26 This directory, known as the @dfn{python directory},
27 is automatically added to the Python Search Path in order to allow
28 the Python interpreter to locate all scripts installed at this location.
30 Additionally, @value{GDBN} commands and convenience functions which
31 are written in Python and are located in the
32 @file{@var{data-directory}/python/gdb/command} or
33 @file{@var{data-directory}/python/gdb/function} directories are
34 automatically imported when @value{GDBN} starts.
37 * Python Commands:: Accessing Python from @value{GDBN}.
38 * Python API:: Accessing @value{GDBN} from Python.
39 * Python Auto-loading:: Automatically loading Python code.
40 * Python modules:: Python modules provided by @value{GDBN}.
44 @subsection Python Commands
45 @cindex python commands
46 @cindex commands to access python
48 @value{GDBN} provides two commands for accessing the Python interpreter,
49 and one related setting:
52 @kindex python-interactive
54 @item python-interactive @r{[}@var{command}@r{]}
55 @itemx pi @r{[}@var{command}@r{]}
56 Without an argument, the @code{python-interactive} command can be used
57 to start an interactive Python prompt. To return to @value{GDBN},
58 type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
60 Alternatively, a single-line Python command can be given as an
61 argument and evaluated. If the command is an expression, the result
62 will be printed; otherwise, nothing will be printed. For example:
65 (@value{GDBP}) python-interactive 2 + 3
71 @item python @r{[}@var{command}@r{]}
72 @itemx py @r{[}@var{command}@r{]}
73 The @code{python} command can be used to evaluate Python code.
75 If given an argument, the @code{python} command will evaluate the
76 argument as a Python command. For example:
79 (@value{GDBP}) python print 23
83 If you do not provide an argument to @code{python}, it will act as a
84 multi-line command, like @code{define}. In this case, the Python
85 script is made up of subsequent command lines, given after the
86 @code{python} command. This command list is terminated using a line
87 containing @code{end}. For example:
92 End with a line saying just "end".
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}.
117 @item python execfile ("script-name")
118 This method is based on the @code{execfile} Python built-in function,
119 and thus is always available.
123 @subsection Python API
125 @cindex programming in python
127 You can get quick online help for @value{GDBN}'s Python API by issuing
128 the command @w{@kbd{python help (gdb)}}.
130 Functions and methods which have two or more optional arguments allow
131 them to be specified using keyword syntax. This allows passing some
132 optional arguments while skipping others. Example:
133 @w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
136 * Basic Python:: Basic Python Functions.
137 * Exception Handling:: How Python exceptions are translated.
138 * Values From Inferior:: Python representation of values.
139 * Types In Python:: Python representation of types.
140 * Pretty Printing API:: Pretty-printing values.
141 * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
142 * Writing a Pretty-Printer:: Writing a Pretty-Printer.
143 * Type Printing API:: Pretty-printing types.
144 * Frame Filter API:: Filtering Frames.
145 * Frame Decorator API:: Decorating Frames.
146 * Writing a Frame Filter:: Writing a Frame Filter.
147 * Unwinding Frames in Python:: Writing frame unwinder.
148 * Xmethods In Python:: Adding and replacing methods of C++ classes.
149 * Xmethod API:: Xmethod types.
150 * Writing an Xmethod:: Writing an xmethod.
151 * Inferiors In Python:: Python representation of inferiors (processes)
152 * Events In Python:: Listening for events from @value{GDBN}.
153 * Threads In Python:: Accessing inferior threads from Python.
154 * Recordings In Python:: Accessing recordings from Python.
155 * Commands In Python:: Implementing new commands in Python.
156 * Parameters In Python:: Adding new @value{GDBN} parameters.
157 * Functions In Python:: Writing new convenience functions.
158 * Progspaces In Python:: Program spaces.
159 * Objfiles In Python:: Object files.
160 * Frames In Python:: Accessing inferior stack frames from Python.
161 * Blocks In Python:: Accessing blocks from Python.
162 * Symbols In Python:: Python representation of symbols.
163 * Symbol Tables In Python:: Python representation of symbol tables.
164 * Line Tables In Python:: Python representation of line tables.
165 * Breakpoints In Python:: Manipulating breakpoints using Python.
166 * Finish Breakpoints in Python:: Setting Breakpoints on function return
168 * Lazy Strings In Python:: Python representation of lazy strings.
169 * Architectures In Python:: Python representation of architectures.
173 @subsubsection Basic Python
175 @cindex python stdout
176 @cindex python pagination
177 At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
178 @code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
179 A Python program which outputs to one of these streams may have its
180 output interrupted by the user (@pxref{Screen Size}). In this
181 situation, a Python @code{KeyboardInterrupt} exception is thrown.
183 Some care must be taken when writing Python code to run in
184 @value{GDBN}. Two things worth noting in particular:
188 @value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
189 Python code must not override these, or even change the options using
190 @code{sigaction}. If your program changes the handling of these
191 signals, @value{GDBN} will most likely stop working correctly. Note
192 that it is unfortunately common for GUI toolkits to install a
193 @code{SIGCHLD} handler.
196 @value{GDBN} takes care to mark its internal file descriptors as
197 close-on-exec. However, this cannot be done in a thread-safe way on
198 all platforms. Your Python programs should be aware of this and
199 should both create new file descriptors with the close-on-exec flag
200 set and arrange to close unneeded file descriptors before starting a
204 @cindex python functions
205 @cindex python module
207 @value{GDBN} introduces a new Python module, named @code{gdb}. All
208 methods and classes added by @value{GDBN} are placed in this module.
209 @value{GDBN} automatically @code{import}s the @code{gdb} module for
210 use in all scripts evaluated by the @code{python} command.
212 @findex gdb.PYTHONDIR
213 @defvar gdb.PYTHONDIR
214 A string containing the python directory (@pxref{Python}).
218 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
219 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
220 If a GDB exception happens while @var{command} runs, it is
221 translated as described in @ref{Exception Handling,,Exception Handling}.
223 The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
224 command as having originated from the user invoking it interactively.
225 It must be a boolean value. If omitted, it defaults to @code{False}.
227 By default, any output produced by @var{command} is sent to
228 @value{GDBN}'s standard output (and to the log output if logging is
229 turned on). If the @var{to_string} parameter is
230 @code{True}, then output will be collected by @code{gdb.execute} and
231 returned as a string. The default is @code{False}, in which case the
232 return value is @code{None}. If @var{to_string} is @code{True}, the
233 @value{GDBN} virtual terminal will be temporarily set to unlimited width
234 and height, and its pagination will be disabled; @pxref{Screen Size}.
237 @findex gdb.breakpoints
238 @defun gdb.breakpoints ()
239 Return a sequence holding all of @value{GDBN}'s breakpoints.
240 @xref{Breakpoints In Python}, for more information. In @value{GDBN}
241 version 7.11 and earlier, this function returned @code{None} if there
242 were no breakpoints. This peculiarity was subsequently fixed, and now
243 @code{gdb.breakpoints} returns an empty sequence in this case.
246 @findex gdb.parameter
247 @defun gdb.parameter (parameter)
248 Return the value of a @value{GDBN} @var{parameter} given by its name,
249 a string; the parameter name string may contain spaces if the parameter has a
250 multi-part name. For example, @samp{print object} is a valid
253 If the named parameter does not exist, this function throws a
254 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
255 parameter's value is converted to a Python value of the appropriate
260 @defun gdb.history (number)
261 Return a value from @value{GDBN}'s value history (@pxref{Value
262 History}). The @var{number} argument indicates which history element to return.
263 If @var{number} is negative, then @value{GDBN} will take its absolute value
264 and count backward from the last element (i.e., the most recent element) to
265 find the value to return. If @var{number} is zero, then @value{GDBN} will
266 return the most recent element. If the element specified by @var{number}
267 doesn't exist in the value history, a @code{gdb.error} exception will be
270 If no exception is raised, the return value is always an instance of
271 @code{gdb.Value} (@pxref{Values From Inferior}).
274 @findex gdb.parse_and_eval
275 @defun gdb.parse_and_eval (expression)
276 Parse @var{expression}, which must be a string, as an expression in
277 the current language, evaluate it, and return the result as a
280 This function can be useful when implementing a new command
281 (@pxref{Commands In Python}), as it provides a way to parse the
282 command's argument as an expression. It is also useful simply to
283 compute values, for example, it is the only way to get the value of a
284 convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
287 @findex gdb.find_pc_line
288 @defun gdb.find_pc_line (pc)
289 Return the @code{gdb.Symtab_and_line} object corresponding to the
290 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
291 value of @var{pc} is passed as an argument, then the @code{symtab} and
292 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
293 will be @code{None} and 0 respectively.
296 @findex gdb.post_event
297 @defun gdb.post_event (event)
298 Put @var{event}, a callable object taking no arguments, into
299 @value{GDBN}'s internal event queue. This callable will be invoked at
300 some later point, during @value{GDBN}'s event processing. Events
301 posted using @code{post_event} will be run in the order in which they
302 were posted; however, there is no way to know when they will be
303 processed relative to other events inside @value{GDBN}.
305 @value{GDBN} is not thread-safe. If your Python program uses multiple
306 threads, you must be careful to only call @value{GDBN}-specific
307 functions in the @value{GDBN} thread. @code{post_event} ensures
311 (@value{GDBP}) python
315 > def __init__(self, message):
316 > self.message = message;
317 > def __call__(self):
318 > gdb.write(self.message)
320 >class MyThread1 (threading.Thread):
322 > gdb.post_event(Writer("Hello "))
324 >class MyThread2 (threading.Thread):
326 > gdb.post_event(Writer("World\n"))
331 (@value{GDBP}) Hello World
336 @defun gdb.write (string @r{[}, stream{]})
337 Print a string to @value{GDBN}'s paginated output stream. The
338 optional @var{stream} determines the stream to print to. The default
339 stream is @value{GDBN}'s standard output stream. Possible stream
346 @value{GDBN}'s standard output stream.
351 @value{GDBN}'s standard error stream.
356 @value{GDBN}'s log stream (@pxref{Logging Output}).
359 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
360 call this function and will automatically direct the output to the
366 Flush the buffer of a @value{GDBN} paginated stream so that the
367 contents are displayed immediately. @value{GDBN} will flush the
368 contents of a stream automatically when it encounters a newline in the
369 buffer. The optional @var{stream} determines the stream to flush. The
370 default stream is @value{GDBN}'s standard output stream. Possible
377 @value{GDBN}'s standard output stream.
382 @value{GDBN}'s standard error stream.
387 @value{GDBN}'s log stream (@pxref{Logging Output}).
391 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
392 call this function for the relevant stream.
395 @findex gdb.target_charset
396 @defun gdb.target_charset ()
397 Return the name of the current target character set (@pxref{Character
398 Sets}). This differs from @code{gdb.parameter('target-charset')} in
399 that @samp{auto} is never returned.
402 @findex gdb.target_wide_charset
403 @defun gdb.target_wide_charset ()
404 Return the name of the current target wide character set
405 (@pxref{Character Sets}). This differs from
406 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
410 @findex gdb.solib_name
411 @defun gdb.solib_name (address)
412 Return the name of the shared library holding the given @var{address}
413 as a string, or @code{None}.
416 @findex gdb.decode_line
417 @defun gdb.decode_line @r{[}expression@r{]}
418 Return locations of the line specified by @var{expression}, or of the
419 current line if no argument was given. This function returns a Python
420 tuple containing two elements. The first element contains a string
421 holding any unparsed section of @var{expression} (or @code{None} if
422 the expression has been fully parsed). The second element contains
423 either @code{None} or another tuple that contains all the locations
424 that match the expression represented as @code{gdb.Symtab_and_line}
425 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
426 provided, it is decoded the way that @value{GDBN}'s inbuilt
427 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
430 @defun gdb.prompt_hook (current_prompt)
433 If @var{prompt_hook} is callable, @value{GDBN} will call the method
434 assigned to this operation before a prompt is displayed by
437 The parameter @code{current_prompt} contains the current @value{GDBN}
438 prompt. This method must return a Python string, or @code{None}. If
439 a string is returned, the @value{GDBN} prompt will be set to that
440 string. If @code{None} is returned, @value{GDBN} will continue to use
443 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
444 such as those used by readline for command input, and annotation
445 related prompts are prohibited from being changed.
448 @node Exception Handling
449 @subsubsection Exception Handling
450 @cindex python exceptions
451 @cindex exceptions, python
453 When executing the @code{python} command, Python exceptions
454 uncaught within the Python code are translated to calls to
455 @value{GDBN} error-reporting mechanism. If the command that called
456 @code{python} does not handle the error, @value{GDBN} will
457 terminate it and print an error message containing the Python
458 exception name, the associated value, and the Python call stack
459 backtrace at the point where the exception was raised. Example:
462 (@value{GDBP}) python print foo
463 Traceback (most recent call last):
464 File "<string>", line 1, in <module>
465 NameError: name 'foo' is not defined
468 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
469 Python code are converted to Python exceptions. The type of the
470 Python exception depends on the error.
474 This is the base class for most exceptions generated by @value{GDBN}.
475 It is derived from @code{RuntimeError}, for compatibility with earlier
476 versions of @value{GDBN}.
478 If an error occurring in @value{GDBN} does not fit into some more
479 specific category, then the generated exception will have this type.
481 @item gdb.MemoryError
482 This is a subclass of @code{gdb.error} which is thrown when an
483 operation tried to access invalid memory in the inferior.
485 @item KeyboardInterrupt
486 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
487 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
490 In all cases, your exception handler will see the @value{GDBN} error
491 message as its value and the Python call stack backtrace at the Python
492 statement closest to where the @value{GDBN} error occured as the
496 When implementing @value{GDBN} commands in Python via @code{gdb.Command},
497 it is useful to be able to throw an exception that doesn't cause a
498 traceback to be printed. For example, the user may have invoked the
499 command incorrectly. Use the @code{gdb.GdbError} exception
500 to handle this case. Example:
504 >class HelloWorld (gdb.Command):
505 > """Greet the whole world."""
506 > def __init__ (self):
507 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
508 > def invoke (self, args, from_tty):
509 > argv = gdb.string_to_argv (args)
510 > if len (argv) != 0:
511 > raise gdb.GdbError ("hello-world takes no arguments")
512 > print "Hello, World!"
516 hello-world takes no arguments
519 @node Values From Inferior
520 @subsubsection Values From Inferior
521 @cindex values from inferior, with Python
522 @cindex python, working with values from inferior
524 @cindex @code{gdb.Value}
525 @value{GDBN} provides values it obtains from the inferior program in
526 an object of type @code{gdb.Value}. @value{GDBN} uses this object
527 for its internal bookkeeping of the inferior's values, and for
528 fetching values when necessary.
530 Inferior values that are simple scalars can be used directly in
531 Python expressions that are valid for the value's data type. Here's
532 an example for an integer or floating-point value @code{some_val}:
539 As result of this, @code{bar} will also be a @code{gdb.Value} object
540 whose values are of the same type as those of @code{some_val}. Valid
541 Python operations can also be performed on @code{gdb.Value} objects
542 representing a @code{struct} or @code{class} object. For such cases,
543 the overloaded operator (if present), is used to perform the operation.
544 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
545 representing instances of a @code{class} which overloads the @code{+}
546 operator, then one can use the @code{+} operator in their Python script
554 The result of the operation @code{val3} is also a @code{gdb.Value}
555 object corresponding to the value returned by the overloaded @code{+}
556 operator. In general, overloaded operators are invoked for the
557 following operations: @code{+} (binary addition), @code{-} (binary
558 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
559 @code{>>}, @code{|}, @code{&}, @code{^}.
561 Inferior values that are structures or instances of some class can
562 be accessed using the Python @dfn{dictionary syntax}. For example, if
563 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
564 can access its @code{foo} element with:
567 bar = some_val['foo']
570 @cindex getting structure elements using gdb.Field objects as subscripts
571 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
572 elements can also be accessed by using @code{gdb.Field} objects as
573 subscripts (@pxref{Types In Python}, for more information on
574 @code{gdb.Field} objects). For example, if @code{foo_field} is a
575 @code{gdb.Field} object corresponding to element @code{foo} of the above
576 structure, then @code{bar} can also be accessed as follows:
579 bar = some_val[foo_field]
582 A @code{gdb.Value} that represents a function can be executed via
583 inferior function call. Any arguments provided to the call must match
584 the function's prototype, and must be provided in the order specified
587 For example, @code{some_val} is a @code{gdb.Value} instance
588 representing a function that takes two integers as arguments. To
589 execute this function, call it like so:
592 result = some_val (10,20)
595 Any values returned from a function call will be stored as a
598 The following attributes are provided:
600 @defvar Value.address
601 If this object is addressable, this read-only attribute holds a
602 @code{gdb.Value} object representing the address. Otherwise,
603 this attribute holds @code{None}.
606 @cindex optimized out value in Python
607 @defvar Value.is_optimized_out
608 This read-only boolean attribute is true if the compiler optimized out
609 this value, thus it is not available for fetching from the inferior.
613 The type of this @code{gdb.Value}. The value of this attribute is a
614 @code{gdb.Type} object (@pxref{Types In Python}).
617 @defvar Value.dynamic_type
618 The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time
619 type information (@acronym{RTTI}) to determine the dynamic type of the
620 value. If this value is of class type, it will return the class in
621 which the value is embedded, if any. If this value is of pointer or
622 reference to a class type, it will compute the dynamic type of the
623 referenced object, and return a pointer or reference to that type,
624 respectively. In all other cases, it will return the value's static
627 Note that this feature will only work when debugging a C@t{++} program
628 that includes @acronym{RTTI} for the object in question. Otherwise,
629 it will just return the static type of the value as in @kbd{ptype foo}
630 (@pxref{Symbols, ptype}).
633 @defvar Value.is_lazy
634 The value of this read-only boolean attribute is @code{True} if this
635 @code{gdb.Value} has not yet been fetched from the inferior.
636 @value{GDBN} does not fetch values until necessary, for efficiency.
640 myval = gdb.parse_and_eval ('somevar')
643 The value of @code{somevar} is not fetched at this time. It will be
644 fetched when the value is needed, or when the @code{fetch_lazy}
648 The following methods are provided:
650 @defun Value.__init__ (@var{val})
651 Many Python values can be converted directly to a @code{gdb.Value} via
652 this object initializer. Specifically:
656 A Python boolean is converted to the boolean type from the current
660 A Python integer is converted to the C @code{long} type for the
661 current architecture.
664 A Python long is converted to the C @code{long long} type for the
665 current architecture.
668 A Python float is converted to the C @code{double} type for the
669 current architecture.
672 A Python string is converted to a target string in the current target
673 language using the current target encoding.
674 If a character cannot be represented in the current target encoding,
675 then an exception is thrown.
677 @item @code{gdb.Value}
678 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
680 @item @code{gdb.LazyString}
681 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
682 Python}), then the lazy string's @code{value} method is called, and
687 @defun Value.cast (type)
688 Return a new instance of @code{gdb.Value} that is the result of
689 casting this instance to the type described by @var{type}, which must
690 be a @code{gdb.Type} object. If the cast cannot be performed for some
691 reason, this method throws an exception.
694 @defun Value.dereference ()
695 For pointer data types, this method returns a new @code{gdb.Value} object
696 whose contents is the object pointed to by the pointer. For example, if
697 @code{foo} is a C pointer to an @code{int}, declared in your C program as
704 then you can use the corresponding @code{gdb.Value} to access what
705 @code{foo} points to like this:
708 bar = foo.dereference ()
711 The result @code{bar} will be a @code{gdb.Value} object holding the
712 value pointed to by @code{foo}.
714 A similar function @code{Value.referenced_value} exists which also
715 returns @code{gdb.Value} objects corresonding to the values pointed to
716 by pointer values (and additionally, values referenced by reference
717 values). However, the behavior of @code{Value.dereference}
718 differs from @code{Value.referenced_value} by the fact that the
719 behavior of @code{Value.dereference} is identical to applying the C
720 unary operator @code{*} on a given value. For example, consider a
721 reference to a pointer @code{ptrref}, declared in your C@t{++} program
729 intptr &ptrref = ptr;
732 Though @code{ptrref} is a reference value, one can apply the method
733 @code{Value.dereference} to the @code{gdb.Value} object corresponding
734 to it and obtain a @code{gdb.Value} which is identical to that
735 corresponding to @code{val}. However, if you apply the method
736 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
737 object identical to that corresponding to @code{ptr}.
740 py_ptrref = gdb.parse_and_eval ("ptrref")
741 py_val = py_ptrref.dereference ()
742 py_ptr = py_ptrref.referenced_value ()
745 The @code{gdb.Value} object @code{py_val} is identical to that
746 corresponding to @code{val}, and @code{py_ptr} is identical to that
747 corresponding to @code{ptr}. In general, @code{Value.dereference} can
748 be applied whenever the C unary operator @code{*} can be applied
749 to the corresponding C value. For those cases where applying both
750 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
751 the results obtained need not be identical (as we have seen in the above
752 example). The results are however identical when applied on
753 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
754 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
757 @defun Value.referenced_value ()
758 For pointer or reference data types, this method returns a new
759 @code{gdb.Value} object corresponding to the value referenced by the
760 pointer/reference value. For pointer data types,
761 @code{Value.dereference} and @code{Value.referenced_value} produce
762 identical results. The difference between these methods is that
763 @code{Value.dereference} cannot get the values referenced by reference
764 values. For example, consider a reference to an @code{int}, declared
765 in your C@t{++} program as
773 then applying @code{Value.dereference} to the @code{gdb.Value} object
774 corresponding to @code{ref} will result in an error, while applying
775 @code{Value.referenced_value} will result in a @code{gdb.Value} object
776 identical to that corresponding to @code{val}.
779 py_ref = gdb.parse_and_eval ("ref")
780 er_ref = py_ref.dereference () # Results in error
781 py_val = py_ref.referenced_value () # Returns the referenced value
784 The @code{gdb.Value} object @code{py_val} is identical to that
785 corresponding to @code{val}.
788 @defun Value.reference_value ()
789 Return a @code{gdb.Value} object which is a reference to the value
790 encapsulated by this instance.
793 @defun Value.const_value ()
794 Return a @code{gdb.Value} object which is a @code{const} version of the
795 value encapsulated by this instance.
798 @defun Value.dynamic_cast (type)
799 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
800 operator were used. Consult a C@t{++} reference for details.
803 @defun Value.reinterpret_cast (type)
804 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
805 operator were used. Consult a C@t{++} reference for details.
808 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
809 If this @code{gdb.Value} represents a string, then this method
810 converts the contents to a Python string. Otherwise, this method will
813 Values are interpreted as strings according to the rules of the
814 current language. If the optional length argument is given, the
815 string will be converted to that length, and will include any embedded
816 zeroes that the string may contain. Otherwise, for languages
817 where the string is zero-terminated, the entire string will be
820 For example, in C-like languages, a value is a string if it is a pointer
821 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
824 If the optional @var{encoding} argument is given, it must be a string
825 naming the encoding of the string in the @code{gdb.Value}, such as
826 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
827 the same encodings as the corresponding argument to Python's
828 @code{string.decode} method, and the Python codec machinery will be used
829 to convert the string. If @var{encoding} is not given, or if
830 @var{encoding} is the empty string, then either the @code{target-charset}
831 (@pxref{Character Sets}) will be used, or a language-specific encoding
832 will be used, if the current language is able to supply one.
834 The optional @var{errors} argument is the same as the corresponding
835 argument to Python's @code{string.decode} method.
837 If the optional @var{length} argument is given, the string will be
838 fetched and converted to the given length.
841 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
842 If this @code{gdb.Value} represents a string, then this method
843 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
844 In Python}). Otherwise, this method will throw an exception.
846 If the optional @var{encoding} argument is given, it must be a string
847 naming the encoding of the @code{gdb.LazyString}. Some examples are:
848 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
849 @var{encoding} argument is an encoding that @value{GDBN} does
850 recognize, @value{GDBN} will raise an error.
852 When a lazy string is printed, the @value{GDBN} encoding machinery is
853 used to convert the string during printing. If the optional
854 @var{encoding} argument is not provided, or is an empty string,
855 @value{GDBN} will automatically select the encoding most suitable for
856 the string type. For further information on encoding in @value{GDBN}
857 please see @ref{Character Sets}.
859 If the optional @var{length} argument is given, the string will be
860 fetched and encoded to the length of characters specified. If
861 the @var{length} argument is not provided, the string will be fetched
862 and encoded until a null of appropriate width is found.
865 @defun Value.fetch_lazy ()
866 If the @code{gdb.Value} object is currently a lazy value
867 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
868 fetched from the inferior. Any errors that occur in the process
869 will produce a Python exception.
871 If the @code{gdb.Value} object is not a lazy value, this method
874 This method does not return a value.
878 @node Types In Python
879 @subsubsection Types In Python
880 @cindex types in Python
881 @cindex Python, working with types
884 @value{GDBN} represents types from the inferior using the class
887 The following type-related functions are available in the @code{gdb}
890 @findex gdb.lookup_type
891 @defun gdb.lookup_type (name @r{[}, block@r{]})
892 This function looks up a type by its @var{name}, which must be a string.
894 If @var{block} is given, then @var{name} is looked up in that scope.
895 Otherwise, it is searched for globally.
897 Ordinarily, this function will return an instance of @code{gdb.Type}.
898 If the named type cannot be found, it will throw an exception.
901 If the type is a structure or class type, or an enum type, the fields
902 of that type can be accessed using the Python @dfn{dictionary syntax}.
903 For example, if @code{some_type} is a @code{gdb.Type} instance holding
904 a structure type, you can access its @code{foo} field with:
907 bar = some_type['foo']
910 @code{bar} will be a @code{gdb.Field} object; see below under the
911 description of the @code{Type.fields} method for a description of the
912 @code{gdb.Field} class.
914 An instance of @code{Type} has the following attributes:
917 The type code for this type. The type code will be one of the
918 @code{TYPE_CODE_} constants defined below.
922 The name of this type. If this type has no name, then @code{None}
927 The size of this type, in target @code{char} units. Usually, a
928 target's @code{char} type will be an 8-bit byte. However, on some
929 unusual platforms, this type may have a different size.
933 The tag name for this type. The tag name is the name after
934 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
935 languages have this concept. If this type has no tag name, then
936 @code{None} is returned.
939 The following methods are provided:
941 @defun Type.fields ()
942 For structure and union types, this method returns the fields. Range
943 types have two fields, the minimum and maximum values. Enum types
944 have one field per enum constant. Function and method types have one
945 field per parameter. The base types of C@t{++} classes are also
946 represented as fields. If the type has no fields, or does not fit
947 into one of these categories, an empty sequence will be returned.
949 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
952 This attribute is not available for @code{enum} or @code{static}
953 (as in C@t{++}) fields. The value is the position, counting
954 in bits, from the start of the containing type.
957 This attribute is only available for @code{enum} fields, and its value
958 is the enumeration member's integer representation.
961 The name of the field, or @code{None} for anonymous fields.
964 This is @code{True} if the field is artificial, usually meaning that
965 it was provided by the compiler and not the user. This attribute is
966 always provided, and is @code{False} if the field is not artificial.
969 This is @code{True} if the field represents a base class of a C@t{++}
970 structure. This attribute is always provided, and is @code{False}
971 if the field is not a base class of the type that is the argument of
972 @code{fields}, or if that type was not a C@t{++} class.
975 If the field is packed, or is a bitfield, then this will have a
976 non-zero value, which is the size of the field in bits. Otherwise,
977 this will be zero; in this case the field's size is given by its type.
980 The type of the field. This is usually an instance of @code{Type},
981 but it can be @code{None} in some situations.
984 The type which contains this field. This is an instance of
989 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
990 Return a new @code{gdb.Type} object which represents an array of this
991 type. If one argument is given, it is the inclusive upper bound of
992 the array; in this case the lower bound is zero. If two arguments are
993 given, the first argument is the lower bound of the array, and the
994 second argument is the upper bound of the array. An array's length
995 must not be negative, but the bounds can be.
998 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
999 Return a new @code{gdb.Type} object which represents a vector of this
1000 type. If one argument is given, it is the inclusive upper bound of
1001 the vector; in this case the lower bound is zero. If two arguments are
1002 given, the first argument is the lower bound of the vector, and the
1003 second argument is the upper bound of the vector. A vector's length
1004 must not be negative, but the bounds can be.
1006 The difference between an @code{array} and a @code{vector} is that
1007 arrays behave like in C: when used in expressions they decay to a pointer
1008 to the first element whereas vectors are treated as first class values.
1011 @defun Type.const ()
1012 Return a new @code{gdb.Type} object which represents a
1013 @code{const}-qualified variant of this type.
1016 @defun Type.volatile ()
1017 Return a new @code{gdb.Type} object which represents a
1018 @code{volatile}-qualified variant of this type.
1021 @defun Type.unqualified ()
1022 Return a new @code{gdb.Type} object which represents an unqualified
1023 variant of this type. That is, the result is neither @code{const} nor
1027 @defun Type.range ()
1028 Return a Python @code{Tuple} object that contains two elements: the
1029 low bound of the argument type and the high bound of that type. If
1030 the type does not have a range, @value{GDBN} will raise a
1031 @code{gdb.error} exception (@pxref{Exception Handling}).
1034 @defun Type.reference ()
1035 Return a new @code{gdb.Type} object which represents a reference to this
1039 @defun Type.pointer ()
1040 Return a new @code{gdb.Type} object which represents a pointer to this
1044 @defun Type.strip_typedefs ()
1045 Return a new @code{gdb.Type} that represents the real type,
1046 after removing all layers of typedefs.
1049 @defun Type.target ()
1050 Return a new @code{gdb.Type} object which represents the target type
1053 For a pointer type, the target type is the type of the pointed-to
1054 object. For an array type (meaning C-like arrays), the target type is
1055 the type of the elements of the array. For a function or method type,
1056 the target type is the type of the return value. For a complex type,
1057 the target type is the type of the elements. For a typedef, the
1058 target type is the aliased type.
1060 If the type does not have a target, this method will throw an
1064 @defun Type.template_argument (n @r{[}, block@r{]})
1065 If this @code{gdb.Type} is an instantiation of a template, this will
1066 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1067 value of the @var{n}th template argument (indexed starting at 0).
1069 If this @code{gdb.Type} is not a template type, or if the type has fewer
1070 than @var{n} template arguments, this will throw an exception.
1071 Ordinarily, only C@t{++} code will have template types.
1073 If @var{block} is given, then @var{name} is looked up in that scope.
1074 Otherwise, it is searched for globally.
1077 @defun Type.optimized_out ()
1078 Return @code{gdb.Value} instance of this type whose value is optimized
1079 out. This allows a frame decorator to indicate that the value of an
1080 argument or a local variable is not known.
1083 Each type has a code, which indicates what category this type falls
1084 into. The available type categories are represented by constants
1085 defined in the @code{gdb} module:
1088 @vindex TYPE_CODE_PTR
1089 @item gdb.TYPE_CODE_PTR
1090 The type is a pointer.
1092 @vindex TYPE_CODE_ARRAY
1093 @item gdb.TYPE_CODE_ARRAY
1094 The type is an array.
1096 @vindex TYPE_CODE_STRUCT
1097 @item gdb.TYPE_CODE_STRUCT
1098 The type is a structure.
1100 @vindex TYPE_CODE_UNION
1101 @item gdb.TYPE_CODE_UNION
1102 The type is a union.
1104 @vindex TYPE_CODE_ENUM
1105 @item gdb.TYPE_CODE_ENUM
1106 The type is an enum.
1108 @vindex TYPE_CODE_FLAGS
1109 @item gdb.TYPE_CODE_FLAGS
1110 A bit flags type, used for things such as status registers.
1112 @vindex TYPE_CODE_FUNC
1113 @item gdb.TYPE_CODE_FUNC
1114 The type is a function.
1116 @vindex TYPE_CODE_INT
1117 @item gdb.TYPE_CODE_INT
1118 The type is an integer type.
1120 @vindex TYPE_CODE_FLT
1121 @item gdb.TYPE_CODE_FLT
1122 A floating point type.
1124 @vindex TYPE_CODE_VOID
1125 @item gdb.TYPE_CODE_VOID
1126 The special type @code{void}.
1128 @vindex TYPE_CODE_SET
1129 @item gdb.TYPE_CODE_SET
1132 @vindex TYPE_CODE_RANGE
1133 @item gdb.TYPE_CODE_RANGE
1134 A range type, that is, an integer type with bounds.
1136 @vindex TYPE_CODE_STRING
1137 @item gdb.TYPE_CODE_STRING
1138 A string type. Note that this is only used for certain languages with
1139 language-defined string types; C strings are not represented this way.
1141 @vindex TYPE_CODE_BITSTRING
1142 @item gdb.TYPE_CODE_BITSTRING
1143 A string of bits. It is deprecated.
1145 @vindex TYPE_CODE_ERROR
1146 @item gdb.TYPE_CODE_ERROR
1147 An unknown or erroneous type.
1149 @vindex TYPE_CODE_METHOD
1150 @item gdb.TYPE_CODE_METHOD
1151 A method type, as found in C@t{++}.
1153 @vindex TYPE_CODE_METHODPTR
1154 @item gdb.TYPE_CODE_METHODPTR
1155 A pointer-to-member-function.
1157 @vindex TYPE_CODE_MEMBERPTR
1158 @item gdb.TYPE_CODE_MEMBERPTR
1159 A pointer-to-member.
1161 @vindex TYPE_CODE_REF
1162 @item gdb.TYPE_CODE_REF
1165 @vindex TYPE_CODE_RVALUE_REF
1166 @item gdb.TYPE_CODE_RVALUE_REF
1167 A C@t{++}11 rvalue reference type.
1169 @vindex TYPE_CODE_CHAR
1170 @item gdb.TYPE_CODE_CHAR
1173 @vindex TYPE_CODE_BOOL
1174 @item gdb.TYPE_CODE_BOOL
1177 @vindex TYPE_CODE_COMPLEX
1178 @item gdb.TYPE_CODE_COMPLEX
1179 A complex float type.
1181 @vindex TYPE_CODE_TYPEDEF
1182 @item gdb.TYPE_CODE_TYPEDEF
1183 A typedef to some other type.
1185 @vindex TYPE_CODE_NAMESPACE
1186 @item gdb.TYPE_CODE_NAMESPACE
1187 A C@t{++} namespace.
1189 @vindex TYPE_CODE_DECFLOAT
1190 @item gdb.TYPE_CODE_DECFLOAT
1191 A decimal floating point type.
1193 @vindex TYPE_CODE_INTERNAL_FUNCTION
1194 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1195 A function internal to @value{GDBN}. This is the type used to represent
1196 convenience functions.
1199 Further support for types is provided in the @code{gdb.types}
1200 Python module (@pxref{gdb.types}).
1202 @node Pretty Printing API
1203 @subsubsection Pretty Printing API
1204 @cindex python pretty printing api
1206 An example output is provided (@pxref{Pretty Printing}).
1208 A pretty-printer is just an object that holds a value and implements a
1209 specific interface, defined here.
1211 @defun pretty_printer.children (self)
1212 @value{GDBN} will call this method on a pretty-printer to compute the
1213 children of the pretty-printer's value.
1215 This method must return an object conforming to the Python iterator
1216 protocol. Each item returned by the iterator must be a tuple holding
1217 two elements. The first element is the ``name'' of the child; the
1218 second element is the child's value. The value can be any Python
1219 object which is convertible to a @value{GDBN} value.
1221 This method is optional. If it does not exist, @value{GDBN} will act
1222 as though the value has no children.
1225 @defun pretty_printer.display_hint (self)
1226 The CLI may call this method and use its result to change the
1227 formatting of a value. The result will also be supplied to an MI
1228 consumer as a @samp{displayhint} attribute of the variable being
1231 This method is optional. If it does exist, this method must return a
1234 Some display hints are predefined by @value{GDBN}:
1238 Indicate that the object being printed is ``array-like''. The CLI
1239 uses this to respect parameters such as @code{set print elements} and
1240 @code{set print array}.
1243 Indicate that the object being printed is ``map-like'', and that the
1244 children of this value can be assumed to alternate between keys and
1248 Indicate that the object being printed is ``string-like''. If the
1249 printer's @code{to_string} method returns a Python string of some
1250 kind, then @value{GDBN} will call its internal language-specific
1251 string-printing function to format the string. For the CLI this means
1252 adding quotation marks, possibly escaping some characters, respecting
1253 @code{set print elements}, and the like.
1257 @defun pretty_printer.to_string (self)
1258 @value{GDBN} will call this method to display the string
1259 representation of the value passed to the object's constructor.
1261 When printing from the CLI, if the @code{to_string} method exists,
1262 then @value{GDBN} will prepend its result to the values returned by
1263 @code{children}. Exactly how this formatting is done is dependent on
1264 the display hint, and may change as more hints are added. Also,
1265 depending on the print settings (@pxref{Print Settings}), the CLI may
1266 print just the result of @code{to_string} in a stack trace, omitting
1267 the result of @code{children}.
1269 If this method returns a string, it is printed verbatim.
1271 Otherwise, if this method returns an instance of @code{gdb.Value},
1272 then @value{GDBN} prints this value. This may result in a call to
1273 another pretty-printer.
1275 If instead the method returns a Python value which is convertible to a
1276 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1277 the resulting value. Again, this may result in a call to another
1278 pretty-printer. Python scalars (integers, floats, and booleans) and
1279 strings are convertible to @code{gdb.Value}; other types are not.
1281 Finally, if this method returns @code{None} then no further operations
1282 are peformed in this method and nothing is printed.
1284 If the result is not one of these types, an exception is raised.
1287 @value{GDBN} provides a function which can be used to look up the
1288 default pretty-printer for a @code{gdb.Value}:
1290 @findex gdb.default_visualizer
1291 @defun gdb.default_visualizer (value)
1292 This function takes a @code{gdb.Value} object as an argument. If a
1293 pretty-printer for this value exists, then it is returned. If no such
1294 printer exists, then this returns @code{None}.
1297 @node Selecting Pretty-Printers
1298 @subsubsection Selecting Pretty-Printers
1299 @cindex selecting python pretty-printers
1301 The Python list @code{gdb.pretty_printers} contains an array of
1302 functions or callable objects that have been registered via addition
1303 as a pretty-printer. Printers in this list are called @code{global}
1304 printers, they're available when debugging all inferiors.
1305 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1306 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1309 Each function on these lists is passed a single @code{gdb.Value}
1310 argument and should return a pretty-printer object conforming to the
1311 interface definition above (@pxref{Pretty Printing API}). If a function
1312 cannot create a pretty-printer for the value, it should return
1315 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1316 @code{gdb.Objfile} in the current program space and iteratively calls
1317 each enabled lookup routine in the list for that @code{gdb.Objfile}
1318 until it receives a pretty-printer object.
1319 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1320 searches the pretty-printer list of the current program space,
1321 calling each enabled function until an object is returned.
1322 After these lists have been exhausted, it tries the global
1323 @code{gdb.pretty_printers} list, again calling each enabled function until an
1326 The order in which the objfiles are searched is not specified. For a
1327 given list, functions are always invoked from the head of the list,
1328 and iterated over sequentially until the end of the list, or a printer
1331 For various reasons a pretty-printer may not work.
1332 For example, the underlying data structure may have changed and
1333 the pretty-printer is out of date.
1335 The consequences of a broken pretty-printer are severe enough that
1336 @value{GDBN} provides support for enabling and disabling individual
1337 printers. For example, if @code{print frame-arguments} is on,
1338 a backtrace can become highly illegible if any argument is printed
1339 with a broken printer.
1341 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1342 attribute to the registered function or callable object. If this attribute
1343 is present and its value is @code{False}, the printer is disabled, otherwise
1344 the printer is enabled.
1346 @node Writing a Pretty-Printer
1347 @subsubsection Writing a Pretty-Printer
1348 @cindex writing a pretty-printer
1350 A pretty-printer consists of two parts: a lookup function to detect
1351 if the type is supported, and the printer itself.
1353 Here is an example showing how a @code{std::string} printer might be
1354 written. @xref{Pretty Printing API}, for details on the API this class
1358 class StdStringPrinter(object):
1359 "Print a std::string"
1361 def __init__(self, val):
1364 def to_string(self):
1365 return self.val['_M_dataplus']['_M_p']
1367 def display_hint(self):
1371 And here is an example showing how a lookup function for the printer
1372 example above might be written.
1375 def str_lookup_function(val):
1376 lookup_tag = val.type.tag
1377 if lookup_tag == None:
1379 regex = re.compile("^std::basic_string<char,.*>$")
1380 if regex.match(lookup_tag):
1381 return StdStringPrinter(val)
1385 The example lookup function extracts the value's type, and attempts to
1386 match it to a type that it can pretty-print. If it is a type the
1387 printer can pretty-print, it will return a printer object. If not, it
1388 returns @code{None}.
1390 We recommend that you put your core pretty-printers into a Python
1391 package. If your pretty-printers are for use with a library, we
1392 further recommend embedding a version number into the package name.
1393 This practice will enable @value{GDBN} to load multiple versions of
1394 your pretty-printers at the same time, because they will have
1397 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1398 can be evaluated multiple times without changing its meaning. An
1399 ideal auto-load file will consist solely of @code{import}s of your
1400 printer modules, followed by a call to a register pretty-printers with
1401 the current objfile.
1403 Taken as a whole, this approach will scale nicely to multiple
1404 inferiors, each potentially using a different library version.
1405 Embedding a version number in the Python package name will ensure that
1406 @value{GDBN} is able to load both sets of printers simultaneously.
1407 Then, because the search for pretty-printers is done by objfile, and
1408 because your auto-loaded code took care to register your library's
1409 printers with a specific objfile, @value{GDBN} will find the correct
1410 printers for the specific version of the library used by each
1413 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1414 this code might appear in @code{gdb.libstdcxx.v6}:
1417 def register_printers(objfile):
1418 objfile.pretty_printers.append(str_lookup_function)
1422 And then the corresponding contents of the auto-load file would be:
1425 import gdb.libstdcxx.v6
1426 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1429 The previous example illustrates a basic pretty-printer.
1430 There are a few things that can be improved on.
1431 The printer doesn't have a name, making it hard to identify in a
1432 list of installed printers. The lookup function has a name, but
1433 lookup functions can have arbitrary, even identical, names.
1435 Second, the printer only handles one type, whereas a library typically has
1436 several types. One could install a lookup function for each desired type
1437 in the library, but one could also have a single lookup function recognize
1438 several types. The latter is the conventional way this is handled.
1439 If a pretty-printer can handle multiple data types, then its
1440 @dfn{subprinters} are the printers for the individual data types.
1442 The @code{gdb.printing} module provides a formal way of solving these
1443 problems (@pxref{gdb.printing}).
1444 Here is another example that handles multiple types.
1446 These are the types we are going to pretty-print:
1449 struct foo @{ int a, b; @};
1450 struct bar @{ struct foo x, y; @};
1453 Here are the printers:
1457 """Print a foo object."""
1459 def __init__(self, val):
1462 def to_string(self):
1463 return ("a=<" + str(self.val["a"]) +
1464 "> b=<" + str(self.val["b"]) + ">")
1467 """Print a bar object."""
1469 def __init__(self, val):
1472 def to_string(self):
1473 return ("x=<" + str(self.val["x"]) +
1474 "> y=<" + str(self.val["y"]) + ">")
1477 This example doesn't need a lookup function, that is handled by the
1478 @code{gdb.printing} module. Instead a function is provided to build up
1479 the object that handles the lookup.
1484 def build_pretty_printer():
1485 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1487 pp.add_printer('foo', '^foo$', fooPrinter)
1488 pp.add_printer('bar', '^bar$', barPrinter)
1492 And here is the autoload support:
1497 gdb.printing.register_pretty_printer(
1498 gdb.current_objfile(),
1499 my_library.build_pretty_printer())
1502 Finally, when this printer is loaded into @value{GDBN}, here is the
1503 corresponding output of @samp{info pretty-printer}:
1506 (gdb) info pretty-printer
1513 @node Type Printing API
1514 @subsubsection Type Printing API
1515 @cindex type printing API for Python
1517 @value{GDBN} provides a way for Python code to customize type display.
1518 This is mainly useful for substituting canonical typedef names for
1521 @cindex type printer
1522 A @dfn{type printer} is just a Python object conforming to a certain
1523 protocol. A simple base class implementing the protocol is provided;
1524 see @ref{gdb.types}. A type printer must supply at least:
1526 @defivar type_printer enabled
1527 A boolean which is True if the printer is enabled, and False
1528 otherwise. This is manipulated by the @code{enable type-printer}
1529 and @code{disable type-printer} commands.
1532 @defivar type_printer name
1533 The name of the type printer. This must be a string. This is used by
1534 the @code{enable type-printer} and @code{disable type-printer}
1538 @defmethod type_printer instantiate (self)
1539 This is called by @value{GDBN} at the start of type-printing. It is
1540 only called if the type printer is enabled. This method must return a
1541 new object that supplies a @code{recognize} method, as described below.
1545 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1546 will compute a list of type recognizers. This is done by iterating
1547 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1548 followed by the per-progspace type printers (@pxref{Progspaces In
1549 Python}), and finally the global type printers.
1551 @value{GDBN} will call the @code{instantiate} method of each enabled
1552 type printer. If this method returns @code{None}, then the result is
1553 ignored; otherwise, it is appended to the list of recognizers.
1555 Then, when @value{GDBN} is going to display a type name, it iterates
1556 over the list of recognizers. For each one, it calls the recognition
1557 function, stopping if the function returns a non-@code{None} value.
1558 The recognition function is defined as:
1560 @defmethod type_recognizer recognize (self, type)
1561 If @var{type} is not recognized, return @code{None}. Otherwise,
1562 return a string which is to be printed as the name of @var{type}.
1563 The @var{type} argument will be an instance of @code{gdb.Type}
1564 (@pxref{Types In Python}).
1567 @value{GDBN} uses this two-pass approach so that type printers can
1568 efficiently cache information without holding on to it too long. For
1569 example, it can be convenient to look up type information in a type
1570 printer and hold it for a recognizer's lifetime; if a single pass were
1571 done then type printers would have to make use of the event system in
1572 order to avoid holding information that could become stale as the
1575 @node Frame Filter API
1576 @subsubsection Filtering Frames.
1577 @cindex frame filters api
1579 Frame filters are Python objects that manipulate the visibility of a
1580 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1583 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1584 commands (@pxref{GDB/MI}), those that return a collection of frames
1585 are affected. The commands that work with frame filters are:
1587 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1588 @code{-stack-list-frames}
1589 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1590 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1591 -stack-list-variables command}), @code{-stack-list-arguments}
1592 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1593 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1594 -stack-list-locals command}).
1596 A frame filter works by taking an iterator as an argument, applying
1597 actions to the contents of that iterator, and returning another
1598 iterator (or, possibly, the same iterator it was provided in the case
1599 where the filter does not perform any operations). Typically, frame
1600 filters utilize tools such as the Python's @code{itertools} module to
1601 work with and create new iterators from the source iterator.
1602 Regardless of how a filter chooses to apply actions, it must not alter
1603 the underlying @value{GDBN} frame or frames, or attempt to alter the
1604 call-stack within @value{GDBN}. This preserves data integrity within
1605 @value{GDBN}. Frame filters are executed on a priority basis and care
1606 should be taken that some frame filters may have been executed before,
1607 and that some frame filters will be executed after.
1609 An important consideration when designing frame filters, and well
1610 worth reflecting upon, is that frame filters should avoid unwinding
1611 the call stack if possible. Some stacks can run very deep, into the
1612 tens of thousands in some cases. To search every frame when a frame
1613 filter executes may be too expensive at that step. The frame filter
1614 cannot know how many frames it has to iterate over, and it may have to
1615 iterate through them all. This ends up duplicating effort as
1616 @value{GDBN} performs this iteration when it prints the frames. If
1617 the filter can defer unwinding frames until frame decorators are
1618 executed, after the last filter has executed, it should. @xref{Frame
1619 Decorator API}, for more information on decorators. Also, there are
1620 examples for both frame decorators and filters in later chapters.
1621 @xref{Writing a Frame Filter}, for more information.
1623 The Python dictionary @code{gdb.frame_filters} contains key/object
1624 pairings that comprise a frame filter. Frame filters in this
1625 dictionary are called @code{global} frame filters, and they are
1626 available when debugging all inferiors. These frame filters must
1627 register with the dictionary directly. In addition to the
1628 @code{global} dictionary, there are other dictionaries that are loaded
1629 with different inferiors via auto-loading (@pxref{Python
1630 Auto-loading}). The two other areas where frame filter dictionaries
1631 can be found are: @code{gdb.Progspace} which contains a
1632 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1633 object which also contains a @code{frame_filters} dictionary
1636 When a command is executed from @value{GDBN} that is compatible with
1637 frame filters, @value{GDBN} combines the @code{global},
1638 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1639 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1640 several frames, and thus several object files, might be in use.
1641 @value{GDBN} then prunes any frame filter whose @code{enabled}
1642 attribute is @code{False}. This pruned list is then sorted according
1643 to the @code{priority} attribute in each filter.
1645 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1646 creates an iterator which wraps each frame in the call stack in a
1647 @code{FrameDecorator} object, and calls each filter in order. The
1648 output from the previous filter will always be the input to the next
1651 Frame filters have a mandatory interface which each frame filter must
1652 implement, defined here:
1654 @defun FrameFilter.filter (iterator)
1655 @value{GDBN} will call this method on a frame filter when it has
1656 reached the order in the priority list for that filter.
1658 For example, if there are four frame filters:
1669 The order that the frame filters will be called is:
1672 Filter3 -> Filter2 -> Filter1 -> Filter4
1675 Note that the output from @code{Filter3} is passed to the input of
1676 @code{Filter2}, and so on.
1678 This @code{filter} method is passed a Python iterator. This iterator
1679 contains a sequence of frame decorators that wrap each
1680 @code{gdb.Frame}, or a frame decorator that wraps another frame
1681 decorator. The first filter that is executed in the sequence of frame
1682 filters will receive an iterator entirely comprised of default
1683 @code{FrameDecorator} objects. However, after each frame filter is
1684 executed, the previous frame filter may have wrapped some or all of
1685 the frame decorators with their own frame decorator. As frame
1686 decorators must also conform to a mandatory interface, these
1687 decorators can be assumed to act in a uniform manner (@pxref{Frame
1690 This method must return an object conforming to the Python iterator
1691 protocol. Each item in the iterator must be an object conforming to
1692 the frame decorator interface. If a frame filter does not wish to
1693 perform any operations on this iterator, it should return that
1696 This method is not optional. If it does not exist, @value{GDBN} will
1697 raise and print an error.
1700 @defvar FrameFilter.name
1701 The @code{name} attribute must be Python string which contains the
1702 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1703 Management}). This attribute may contain any combination of letters
1704 or numbers. Care should be taken to ensure that it is unique. This
1705 attribute is mandatory.
1708 @defvar FrameFilter.enabled
1709 The @code{enabled} attribute must be Python boolean. This attribute
1710 indicates to @value{GDBN} whether the frame filter is enabled, and
1711 should be considered when frame filters are executed. If
1712 @code{enabled} is @code{True}, then the frame filter will be executed
1713 when any of the backtrace commands detailed earlier in this chapter
1714 are executed. If @code{enabled} is @code{False}, then the frame
1715 filter will not be executed. This attribute is mandatory.
1718 @defvar FrameFilter.priority
1719 The @code{priority} attribute must be Python integer. This attribute
1720 controls the order of execution in relation to other frame filters.
1721 There are no imposed limits on the range of @code{priority} other than
1722 it must be a valid integer. The higher the @code{priority} attribute,
1723 the sooner the frame filter will be executed in relation to other
1724 frame filters. Although @code{priority} can be negative, it is
1725 recommended practice to assume zero is the lowest priority that a
1726 frame filter can be assigned. Frame filters that have the same
1727 priority are executed in unsorted order in that priority slot. This
1728 attribute is mandatory.
1731 @node Frame Decorator API
1732 @subsubsection Decorating Frames.
1733 @cindex frame decorator api
1735 Frame decorators are sister objects to frame filters (@pxref{Frame
1736 Filter API}). Frame decorators are applied by a frame filter and can
1737 only be used in conjunction with frame filters.
1739 The purpose of a frame decorator is to customize the printed content
1740 of each @code{gdb.Frame} in commands where frame filters are executed.
1741 This concept is called decorating a frame. Frame decorators decorate
1742 a @code{gdb.Frame} with Python code contained within each API call.
1743 This separates the actual data contained in a @code{gdb.Frame} from
1744 the decorated data produced by a frame decorator. This abstraction is
1745 necessary to maintain integrity of the data contained in each
1748 Frame decorators have a mandatory interface, defined below.
1750 @value{GDBN} already contains a frame decorator called
1751 @code{FrameDecorator}. This contains substantial amounts of
1752 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
1753 recommended that other frame decorators inherit and extend this
1754 object, and only to override the methods needed.
1756 @defun FrameDecorator.elided (self)
1758 The @code{elided} method groups frames together in a hierarchical
1759 system. An example would be an interpreter, where multiple low-level
1760 frames make up a single call in the interpreted language. In this
1761 example, the frame filter would elide the low-level frames and present
1762 a single high-level frame, representing the call in the interpreted
1763 language, to the user.
1765 The @code{elided} function must return an iterable and this iterable
1766 must contain the frames that are being elided wrapped in a suitable
1767 frame decorator. If no frames are being elided this function may
1768 return an empty iterable, or @code{None}. Elided frames are indented
1769 from normal frames in a @code{CLI} backtrace, or in the case of
1770 @code{GDB/MI}, are placed in the @code{children} field of the eliding
1773 It is the frame filter's task to also filter out the elided frames from
1774 the source iterator. This will avoid printing the frame twice.
1777 @defun FrameDecorator.function (self)
1779 This method returns the name of the function in the frame that is to
1782 This method must return a Python string describing the function, or
1785 If this function returns @code{None}, @value{GDBN} will not print any
1786 data for this field.
1789 @defun FrameDecorator.address (self)
1791 This method returns the address of the frame that is to be printed.
1793 This method must return a Python numeric integer type of sufficient
1794 size to describe the address of the frame, or @code{None}.
1796 If this function returns a @code{None}, @value{GDBN} will not print
1797 any data for this field.
1800 @defun FrameDecorator.filename (self)
1802 This method returns the filename and path associated with this frame.
1804 This method must return a Python string containing the filename and
1805 the path to the object file backing the frame, or @code{None}.
1807 If this function returns a @code{None}, @value{GDBN} will not print
1808 any data for this field.
1811 @defun FrameDecorator.line (self):
1813 This method returns the line number associated with the current
1814 position within the function addressed by this frame.
1816 This method must return a Python integer type, or @code{None}.
1818 If this function returns a @code{None}, @value{GDBN} will not print
1819 any data for this field.
1822 @defun FrameDecorator.frame_args (self)
1825 This method must return an iterable, or @code{None}. Returning an
1826 empty iterable, or @code{None} means frame arguments will not be
1827 printed for this frame. This iterable must contain objects that
1828 implement two methods, described here.
1830 This object must implement a @code{argument} method which takes a
1831 single @code{self} parameter and must return a @code{gdb.Symbol}
1832 (@pxref{Symbols In Python}), or a Python string. The object must also
1833 implement a @code{value} method which takes a single @code{self}
1834 parameter and must return a @code{gdb.Value} (@pxref{Values From
1835 Inferior}), a Python value, or @code{None}. If the @code{value}
1836 method returns @code{None}, and the @code{argument} method returns a
1837 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
1838 the @code{gdb.Symbol} automatically.
1843 class SymValueWrapper():
1845 def __init__(self, symbol, value):
1855 class SomeFrameDecorator()
1858 def frame_args(self):
1861 block = self.inferior_frame.block()
1865 # Iterate over all symbols in a block. Only add
1866 # symbols that are arguments.
1868 if not sym.is_argument:
1870 args.append(SymValueWrapper(sym,None))
1872 # Add example synthetic argument.
1873 args.append(SymValueWrapper(``foo'', 42))
1879 @defun FrameDecorator.frame_locals (self)
1881 This method must return an iterable or @code{None}. Returning an
1882 empty iterable, or @code{None} means frame local arguments will not be
1883 printed for this frame.
1885 The object interface, the description of the various strategies for
1886 reading frame locals, and the example are largely similar to those
1887 described in the @code{frame_args} function, (@pxref{frame_args,,The
1888 frame filter frame_args function}). Below is a modified example:
1891 class SomeFrameDecorator()
1894 def frame_locals(self):
1897 block = self.inferior_frame.block()
1901 # Iterate over all symbols in a block. Add all
1902 # symbols, except arguments.
1906 vars.append(SymValueWrapper(sym,None))
1908 # Add an example of a synthetic local variable.
1909 vars.append(SymValueWrapper(``bar'', 99))
1915 @defun FrameDecorator.inferior_frame (self):
1917 This method must return the underlying @code{gdb.Frame} that this
1918 frame decorator is decorating. @value{GDBN} requires the underlying
1919 frame for internal frame information to determine how to print certain
1920 values when printing a frame.
1923 @node Writing a Frame Filter
1924 @subsubsection Writing a Frame Filter
1925 @cindex writing a frame filter
1927 There are three basic elements that a frame filter must implement: it
1928 must correctly implement the documented interface (@pxref{Frame Filter
1929 API}), it must register itself with @value{GDBN}, and finally, it must
1930 decide if it is to work on the data provided by @value{GDBN}. In all
1931 cases, whether it works on the iterator or not, each frame filter must
1932 return an iterator. A bare-bones frame filter follows the pattern in
1933 the following example.
1938 class FrameFilter():
1941 # Frame filter attribute creation.
1943 # 'name' is the name of the filter that GDB will display.
1945 # 'priority' is the priority of the filter relative to other
1948 # 'enabled' is a boolean that indicates whether this filter is
1949 # enabled and should be executed.
1955 # Register this frame filter with the global frame_filters
1957 gdb.frame_filters[self.name] = self
1959 def filter(self, frame_iter):
1960 # Just return the iterator.
1964 The frame filter in the example above implements the three
1965 requirements for all frame filters. It implements the API, self
1966 registers, and makes a decision on the iterator (in this case, it just
1967 returns the iterator untouched).
1969 The first step is attribute creation and assignment, and as shown in
1970 the comments the filter assigns the following attributes: @code{name},
1971 @code{priority} and whether the filter should be enabled with the
1972 @code{enabled} attribute.
1974 The second step is registering the frame filter with the dictionary or
1975 dictionaries that the frame filter has interest in. As shown in the
1976 comments, this filter just registers itself with the global dictionary
1977 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
1978 is a dictionary that is initialized in the @code{gdb} module when
1979 @value{GDBN} starts. What dictionary a filter registers with is an
1980 important consideration. Generally, if a filter is specific to a set
1981 of code, it should be registered either in the @code{objfile} or
1982 @code{progspace} dictionaries as they are specific to the program
1983 currently loaded in @value{GDBN}. The global dictionary is always
1984 present in @value{GDBN} and is never unloaded. Any filters registered
1985 with the global dictionary will exist until @value{GDBN} exits. To
1986 avoid filters that may conflict, it is generally better to register
1987 frame filters against the dictionaries that more closely align with
1988 the usage of the filter currently in question. @xref{Python
1989 Auto-loading}, for further information on auto-loading Python scripts.
1991 @value{GDBN} takes a hands-off approach to frame filter registration,
1992 therefore it is the frame filter's responsibility to ensure
1993 registration has occurred, and that any exceptions are handled
1994 appropriately. In particular, you may wish to handle exceptions
1995 relating to Python dictionary key uniqueness. It is mandatory that
1996 the dictionary key is the same as frame filter's @code{name}
1997 attribute. When a user manages frame filters (@pxref{Frame Filter
1998 Management}), the names @value{GDBN} will display are those contained
1999 in the @code{name} attribute.
2001 The final step of this example is the implementation of the
2002 @code{filter} method. As shown in the example comments, we define the
2003 @code{filter} method and note that the method must take an iterator,
2004 and also must return an iterator. In this bare-bones example, the
2005 frame filter is not very useful as it just returns the iterator
2006 untouched. However this is a valid operation for frame filters that
2007 have the @code{enabled} attribute set, but decide not to operate on
2010 In the next example, the frame filter operates on all frames and
2011 utilizes a frame decorator to perform some work on the frames.
2012 @xref{Frame Decorator API}, for further information on the frame
2013 decorator interface.
2015 This example works on inlined frames. It highlights frames which are
2016 inlined by tagging them with an ``[inlined]'' tag. By applying a
2017 frame decorator to all frames with the Python @code{itertools imap}
2018 method, the example defers actions to the frame decorator. Frame
2019 decorators are only processed when @value{GDBN} prints the backtrace.
2021 This introduces a new decision making topic: whether to perform
2022 decision making operations at the filtering step, or at the printing
2023 step. In this example's approach, it does not perform any filtering
2024 decisions at the filtering step beyond mapping a frame decorator to
2025 each frame. This allows the actual decision making to be performed
2026 when each frame is printed. This is an important consideration, and
2027 well worth reflecting upon when designing a frame filter. An issue
2028 that frame filters should avoid is unwinding the stack if possible.
2029 Some stacks can run very deep, into the tens of thousands in some
2030 cases. To search every frame to determine if it is inlined ahead of
2031 time may be too expensive at the filtering step. The frame filter
2032 cannot know how many frames it has to iterate over, and it would have
2033 to iterate through them all. This ends up duplicating effort as
2034 @value{GDBN} performs this iteration when it prints the frames.
2036 In this example decision making can be deferred to the printing step.
2037 As each frame is printed, the frame decorator can examine each frame
2038 in turn when @value{GDBN} iterates. From a performance viewpoint,
2039 this is the most appropriate decision to make as it avoids duplicating
2040 the effort that the printing step would undertake anyway. Also, if
2041 there are many frame filters unwinding the stack during filtering, it
2042 can substantially delay the printing of the backtrace which will
2043 result in large memory usage, and a poor user experience.
2046 class InlineFilter():
2049 self.name = "InlinedFrameFilter"
2052 gdb.frame_filters[self.name] = self
2054 def filter(self, frame_iter):
2055 frame_iter = itertools.imap(InlinedFrameDecorator,
2060 This frame filter is somewhat similar to the earlier example, except
2061 that the @code{filter} method applies a frame decorator object called
2062 @code{InlinedFrameDecorator} to each element in the iterator. The
2063 @code{imap} Python method is light-weight. It does not proactively
2064 iterate over the iterator, but rather creates a new iterator which
2065 wraps the existing one.
2067 Below is the frame decorator for this example.
2070 class InlinedFrameDecorator(FrameDecorator):
2072 def __init__(self, fobj):
2073 super(InlinedFrameDecorator, self).__init__(fobj)
2076 frame = fobj.inferior_frame()
2077 name = str(frame.name())
2079 if frame.type() == gdb.INLINE_FRAME:
2080 name = name + " [inlined]"
2085 This frame decorator only defines and overrides the @code{function}
2086 method. It lets the supplied @code{FrameDecorator}, which is shipped
2087 with @value{GDBN}, perform the other work associated with printing
2090 The combination of these two objects create this output from a
2094 #0 0x004004e0 in bar () at inline.c:11
2095 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2096 #2 0x00400566 in main () at inline.c:31
2099 So in the case of this example, a frame decorator is applied to all
2100 frames, regardless of whether they may be inlined or not. As
2101 @value{GDBN} iterates over the iterator produced by the frame filters,
2102 @value{GDBN} executes each frame decorator which then makes a decision
2103 on what to print in the @code{function} callback. Using a strategy
2104 like this is a way to defer decisions on the frame content to printing
2107 @subheading Eliding Frames
2109 It might be that the above example is not desirable for representing
2110 inlined frames, and a hierarchical approach may be preferred. If we
2111 want to hierarchically represent frames, the @code{elided} frame
2112 decorator interface might be preferable.
2114 This example approaches the issue with the @code{elided} method. This
2115 example is quite long, but very simplistic. It is out-of-scope for
2116 this section to write a complete example that comprehensively covers
2117 all approaches of finding and printing inlined frames. However, this
2118 example illustrates the approach an author might use.
2120 This example comprises of three sections.
2123 class InlineFrameFilter():
2126 self.name = "InlinedFrameFilter"
2129 gdb.frame_filters[self.name] = self
2131 def filter(self, frame_iter):
2132 return ElidingInlineIterator(frame_iter)
2135 This frame filter is very similar to the other examples. The only
2136 difference is this frame filter is wrapping the iterator provided to
2137 it (@code{frame_iter}) with a custom iterator called
2138 @code{ElidingInlineIterator}. This again defers actions to when
2139 @value{GDBN} prints the backtrace, as the iterator is not traversed
2142 The iterator for this example is as follows. It is in this section of
2143 the example where decisions are made on the content of the backtrace.
2146 class ElidingInlineIterator:
2147 def __init__(self, ii):
2148 self.input_iterator = ii
2154 frame = next(self.input_iterator)
2156 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2160 eliding_frame = next(self.input_iterator)
2161 except StopIteration:
2163 return ElidingFrameDecorator(eliding_frame, [frame])
2166 This iterator implements the Python iterator protocol. When the
2167 @code{next} function is called (when @value{GDBN} prints each frame),
2168 the iterator checks if this frame decorator, @code{frame}, is wrapping
2169 an inlined frame. If it is not, it returns the existing frame decorator
2170 untouched. If it is wrapping an inlined frame, it assumes that the
2171 inlined frame was contained within the next oldest frame,
2172 @code{eliding_frame}, which it fetches. It then creates and returns a
2173 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2174 elided frame, and the eliding frame.
2177 class ElidingInlineDecorator(FrameDecorator):
2179 def __init__(self, frame, elided_frames):
2180 super(ElidingInlineDecorator, self).__init__(frame)
2182 self.elided_frames = elided_frames
2185 return iter(self.elided_frames)
2188 This frame decorator overrides one function and returns the inlined
2189 frame in the @code{elided} method. As before it lets
2190 @code{FrameDecorator} do the rest of the work involved in printing
2191 this frame. This produces the following output.
2194 #0 0x004004e0 in bar () at inline.c:11
2195 #2 0x00400529 in main () at inline.c:25
2196 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2199 In that output, @code{max} which has been inlined into @code{main} is
2200 printed hierarchically. Another approach would be to combine the
2201 @code{function} method, and the @code{elided} method to both print a
2202 marker in the inlined frame, and also show the hierarchical
2205 @node Unwinding Frames in Python
2206 @subsubsection Unwinding Frames in Python
2207 @cindex unwinding frames in Python
2209 In @value{GDBN} terminology ``unwinding'' is the process of finding
2210 the previous frame (that is, caller's) from the current one. An
2211 unwinder has three methods. The first one checks if it can handle
2212 given frame (``sniff'' it). For the frames it can sniff an unwinder
2213 provides two additional methods: it can return frame's ID, and it can
2214 fetch registers from the previous frame. A running @value{GDBN}
2215 mantains a list of the unwinders and calls each unwinder's sniffer in
2216 turn until it finds the one that recognizes the current frame. There
2217 is an API to register an unwinder.
2219 The unwinders that come with @value{GDBN} handle standard frames.
2220 However, mixed language applications (for example, an application
2221 running Java Virtual Machine) sometimes use frame layouts that cannot
2222 be handled by the @value{GDBN} unwinders. You can write Python code
2223 that can handle such custom frames.
2225 You implement a frame unwinder in Python as a class with which has two
2226 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2227 a single method @code{__call__}, which examines a given frame and
2228 returns an object (an instance of @code{gdb.UnwindInfo class)}
2229 describing it. If an unwinder does not recognize a frame, it should
2230 return @code{None}. The code in @value{GDBN} that enables writing
2231 unwinders in Python uses this object to return frame's ID and previous
2232 frame registers when @value{GDBN} core asks for them.
2234 @subheading Unwinder Input
2236 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2237 provides a method to read frame's registers:
2239 @defun PendingFrame.read_register (reg)
2240 This method returns the contents of the register @var{regn} in the
2241 frame as a @code{gdb.Value} object. @var{reg} can be either a
2242 register number or a register name; the values are platform-specific.
2243 They are usually found in the corresponding
2244 @file{@var{platform}-tdep.h} file in the @value{GDBN} source tree.
2247 It also provides a factory method to create a @code{gdb.UnwindInfo}
2248 instance to be returned to @value{GDBN}:
2250 @defun PendingFrame.create_unwind_info (frame_id)
2251 Returns a new @code{gdb.UnwindInfo} instance identified by given
2252 @var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2253 using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2254 determine which function will be used, as follows:
2257 @item sp, pc, special
2258 @code{frame_id_build_special (@var{frame_id}.sp, @var{frame_id}.pc, @var{frame_id}.special)}
2261 @code{frame_id_build (@var{frame_id}.sp, @var{frame_id}.pc)}
2263 This is the most common case.
2266 @code{frame_id_build_wild (@var{frame_id}.sp)}
2268 The attribute values should be @code{gdb.Value}
2272 @subheading Unwinder Output: UnwindInfo
2274 Use @code{PendingFrame.create_unwind_info} method described above to
2275 create a @code{gdb.UnwindInfo} instance. Use the following method to
2276 specify caller registers that have been saved in this frame:
2278 @defun gdb.UnwindInfo.add_saved_register (reg, value)
2279 @var{reg} identifies the register. It can be a number or a name, just
2280 as for the @code{PendingFrame.read_register} method above.
2281 @var{value} is a register value (a @code{gdb.Value} object).
2284 @subheading Unwinder Skeleton Code
2286 @value{GDBN} comes with the module containing the base @code{Unwinder}
2287 class. Derive your unwinder class from it and structure the code as
2291 from gdb.unwinders import Unwinder
2293 class FrameId(object):
2294 def __init__(self, sp, pc):
2299 class MyUnwinder(Unwinder):
2301 supe(MyUnwinder, self).__init___(<expects unwinder name argument>)
2303 def __call__(pending_frame):
2304 if not <we recognize frame>:
2306 # Create UnwindInfo. Usually the frame is identified by the stack
2307 # pointer and the program counter.
2308 sp = pending_frame.read_register(<SP number>)
2309 pc = pending_frame.read_register(<PC number>)
2310 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2312 # Find the values of the registers in the caller's frame and
2313 # save them in the result:
2314 unwind_info.add_saved_register(<register>, <value>)
2317 # Return the result:
2322 @subheading Registering a Unwinder
2324 An object file, a program space, and the @value{GDBN} proper can have
2325 unwinders registered with it.
2327 The @code{gdb.unwinders} module provides the function to register a
2330 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2331 @var{locus} is specifies an object file or a program space to which
2332 @var{unwinder} is added. Passing @code{None} or @code{gdb} adds
2333 @var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
2334 added @var{unwinder} will be called before any other unwinder from the
2335 same locus. Two unwinders in the same locus cannot have the same
2336 name. An attempt to add a unwinder with already existing name raises
2337 an exception unless @var{replace} is @code{True}, in which case the
2338 old unwinder is deleted.
2341 @subheading Unwinder Precedence
2343 @value{GDBN} first calls the unwinders from all the object files in no
2344 particular order, then the unwinders from the current program space,
2345 and finally the unwinders from @value{GDBN}.
2347 @node Xmethods In Python
2348 @subsubsection Xmethods In Python
2349 @cindex xmethods in Python
2351 @dfn{Xmethods} are additional methods or replacements for existing
2352 methods of a C@t{++} class. This feature is useful for those cases
2353 where a method defined in C@t{++} source code could be inlined or
2354 optimized out by the compiler, making it unavailable to @value{GDBN}.
2355 For such cases, one can define an xmethod to serve as a replacement
2356 for the method defined in the C@t{++} source code. @value{GDBN} will
2357 then invoke the xmethod, instead of the C@t{++} method, to
2358 evaluate expressions. One can also use xmethods when debugging
2359 with core files. Moreover, when debugging live programs, invoking an
2360 xmethod need not involve running the inferior (which can potentially
2361 perturb its state). Hence, even if the C@t{++} method is available, it
2362 is better to use its replacement xmethod if one is defined.
2364 The xmethods feature in Python is available via the concepts of an
2365 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2366 implement an xmethod, one has to implement a matcher and a
2367 corresponding worker for it (more than one worker can be
2368 implemented, each catering to a different overloaded instance of the
2369 method). Internally, @value{GDBN} invokes the @code{match} method of a
2370 matcher to match the class type and method name. On a match, the
2371 @code{match} method returns a list of matching @emph{worker} objects.
2372 Each worker object typically corresponds to an overloaded instance of
2373 the xmethod. They implement a @code{get_arg_types} method which
2374 returns a sequence of types corresponding to the arguments the xmethod
2375 requires. @value{GDBN} uses this sequence of types to perform
2376 overload resolution and picks a winning xmethod worker. A winner
2377 is also selected from among the methods @value{GDBN} finds in the
2378 C@t{++} source code. Next, the winning xmethod worker and the
2379 winning C@t{++} method are compared to select an overall winner. In
2380 case of a tie between a xmethod worker and a C@t{++} method, the
2381 xmethod worker is selected as the winner. That is, if a winning
2382 xmethod worker is found to be equivalent to the winning C@t{++}
2383 method, then the xmethod worker is treated as a replacement for
2384 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2385 method. If the winning xmethod worker is the overall winner, then
2386 the corresponding xmethod is invoked via the @code{__call__} method
2387 of the worker object.
2389 If one wants to implement an xmethod as a replacement for an
2390 existing C@t{++} method, then they have to implement an equivalent
2391 xmethod which has exactly the same name and takes arguments of
2392 exactly the same type as the C@t{++} method. If the user wants to
2393 invoke the C@t{++} method even though a replacement xmethod is
2394 available for that method, then they can disable the xmethod.
2396 @xref{Xmethod API}, for API to implement xmethods in Python.
2397 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2400 @subsubsection Xmethod API
2403 The @value{GDBN} Python API provides classes, interfaces and functions
2404 to implement, register and manipulate xmethods.
2405 @xref{Xmethods In Python}.
2407 An xmethod matcher should be an instance of a class derived from
2408 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2409 object with similar interface and attributes. An instance of
2410 @code{XMethodMatcher} has the following attributes:
2413 The name of the matcher.
2417 A boolean value indicating whether the matcher is enabled or disabled.
2421 A list of named methods managed by the matcher. Each object in the list
2422 is an instance of the class @code{XMethod} defined in the module
2423 @code{gdb.xmethod}, or any object with the following attributes:
2428 Name of the xmethod which should be unique for each xmethod
2429 managed by the matcher.
2432 A boolean value indicating whether the xmethod is enabled or
2437 The class @code{XMethod} is a convenience class with same
2438 attributes as above along with the following constructor:
2440 @defun XMethod.__init__ (self, name)
2441 Constructs an enabled xmethod with name @var{name}.
2446 The @code{XMethodMatcher} class has the following methods:
2448 @defun XMethodMatcher.__init__ (self, name)
2449 Constructs an enabled xmethod matcher with name @var{name}. The
2450 @code{methods} attribute is initialized to @code{None}.
2453 @defun XMethodMatcher.match (self, class_type, method_name)
2454 Derived classes should override this method. It should return a
2455 xmethod worker object (or a sequence of xmethod worker
2456 objects) matching the @var{class_type} and @var{method_name}.
2457 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2458 is a string value. If the matcher manages named methods as listed in
2459 its @code{methods} attribute, then only those worker objects whose
2460 corresponding entries in the @code{methods} list are enabled should be
2464 An xmethod worker should be an instance of a class derived from
2465 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
2466 or support the following interface:
2468 @defun XMethodWorker.get_arg_types (self)
2469 This method returns a sequence of @code{gdb.Type} objects corresponding
2470 to the arguments that the xmethod takes. It can return an empty
2471 sequence or @code{None} if the xmethod does not take any arguments.
2472 If the xmethod takes a single argument, then a single
2473 @code{gdb.Type} object corresponding to it can be returned.
2476 @defun XMethodWorker.get_result_type (self, *args)
2477 This method returns a @code{gdb.Type} object representing the type
2478 of the result of invoking this xmethod.
2479 The @var{args} argument is the same tuple of arguments that would be
2480 passed to the @code{__call__} method of this worker.
2483 @defun XMethodWorker.__call__ (self, *args)
2484 This is the method which does the @emph{work} of the xmethod. The
2485 @var{args} arguments is the tuple of arguments to the xmethod. Each
2486 element in this tuple is a gdb.Value object. The first element is
2487 always the @code{this} pointer value.
2490 For @value{GDBN} to lookup xmethods, the xmethod matchers
2491 should be registered using the following function defined in the module
2494 @defun register_xmethod_matcher (locus, matcher, replace=False)
2495 The @code{matcher} is registered with @code{locus}, replacing an
2496 existing matcher with the same name as @code{matcher} if
2497 @code{replace} is @code{True}. @code{locus} can be a
2498 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
2499 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
2500 @code{None}. If it is @code{None}, then @code{matcher} is registered
2504 @node Writing an Xmethod
2505 @subsubsection Writing an Xmethod
2506 @cindex writing xmethods in Python
2508 Implementing xmethods in Python will require implementing xmethod
2509 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2510 the following C@t{++} class:
2516 MyClass (int a) : a_(a) @{ @}
2518 int geta (void) @{ return a_; @}
2519 int operator+ (int b);
2526 MyClass::operator+ (int b)
2533 Let us define two xmethods for the class @code{MyClass}, one
2534 replacing the method @code{geta}, and another adding an overloaded
2535 flavor of @code{operator+} which takes a @code{MyClass} argument (the
2536 C@t{++} code above already has an overloaded @code{operator+}
2537 which takes an @code{int} argument). The xmethod matcher can be
2541 class MyClass_geta(gdb.xmethod.XMethod):
2543 gdb.xmethod.XMethod.__init__(self, 'geta')
2545 def get_worker(self, method_name):
2546 if method_name == 'geta':
2547 return MyClassWorker_geta()
2550 class MyClass_sum(gdb.xmethod.XMethod):
2552 gdb.xmethod.XMethod.__init__(self, 'sum')
2554 def get_worker(self, method_name):
2555 if method_name == 'operator+':
2556 return MyClassWorker_plus()
2559 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2561 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2562 # List of methods 'managed' by this matcher
2563 self.methods = [MyClass_geta(), MyClass_sum()]
2565 def match(self, class_type, method_name):
2566 if class_type.tag != 'MyClass':
2569 for method in self.methods:
2571 worker = method.get_worker(method_name)
2573 workers.append(worker)
2579 Notice that the @code{match} method of @code{MyClassMatcher} returns
2580 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
2581 method, and a worker object of type @code{MyClassWorker_plus} for the
2582 @code{operator+} method. This is done indirectly via helper classes
2583 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
2584 @code{methods} attribute in a matcher as it is optional. However, if a
2585 matcher manages more than one xmethod, it is a good practice to list the
2586 xmethods in the @code{methods} attribute of the matcher. This will then
2587 facilitate enabling and disabling individual xmethods via the
2588 @code{enable/disable} commands. Notice also that a worker object is
2589 returned only if the corresponding entry in the @code{methods} attribute
2590 of the matcher is enabled.
2592 The implementation of the worker classes returned by the matcher setup
2593 above is as follows:
2596 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
2597 def get_arg_types(self):
2600 def get_result_type(self, obj):
2601 return gdb.lookup_type('int')
2603 def __call__(self, obj):
2607 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
2608 def get_arg_types(self):
2609 return gdb.lookup_type('MyClass')
2611 def get_result_type(self, obj):
2612 return gdb.lookup_type('int')
2614 def __call__(self, obj, other):
2615 return obj['a_'] + other['a_']
2618 For @value{GDBN} to actually lookup a xmethod, it has to be
2619 registered with it. The matcher defined above is registered with
2620 @value{GDBN} globally as follows:
2623 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
2626 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
2634 then, after loading the Python script defining the xmethod matchers
2635 and workers into @code{GDBN}, invoking the method @code{geta} or using
2636 the operator @code{+} on @code{obj} will invoke the xmethods
2647 Consider another example with a C++ template class:
2654 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
2655 ~MyTemplate () @{ delete [] data_; @}
2657 int footprint (void)
2659 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
2668 Let us implement an xmethod for the above class which serves as a
2669 replacement for the @code{footprint} method. The full code listing
2670 of the xmethod workers and xmethod matchers is as follows:
2673 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
2674 def __init__(self, class_type):
2675 self.class_type = class_type
2677 def get_arg_types(self):
2680 def get_result_type(self):
2681 return gdb.lookup_type('int')
2683 def __call__(self, obj):
2684 return (self.class_type.sizeof +
2686 self.class_type.template_argument(0).sizeof)
2689 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
2691 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
2693 def match(self, class_type, method_name):
2694 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
2696 method_name == 'footprint'):
2697 return MyTemplateWorker_footprint(class_type)
2700 Notice that, in this example, we have not used the @code{methods}
2701 attribute of the matcher as the matcher manages only one xmethod. The
2702 user can enable/disable this xmethod by enabling/disabling the matcher
2705 @node Inferiors In Python
2706 @subsubsection Inferiors In Python
2707 @cindex inferiors in Python
2709 @findex gdb.Inferior
2710 Programs which are being run under @value{GDBN} are called inferiors
2711 (@pxref{Inferiors and Programs}). Python scripts can access
2712 information about and manipulate inferiors controlled by @value{GDBN}
2713 via objects of the @code{gdb.Inferior} class.
2715 The following inferior-related functions are available in the @code{gdb}
2718 @defun gdb.inferiors ()
2719 Return a tuple containing all inferior objects.
2722 @defun gdb.selected_inferior ()
2723 Return an object representing the current inferior.
2726 A @code{gdb.Inferior} object has the following attributes:
2728 @defvar Inferior.num
2729 ID of inferior, as assigned by GDB.
2732 @defvar Inferior.pid
2733 Process ID of the inferior, as assigned by the underlying operating
2737 @defvar Inferior.was_attached
2738 Boolean signaling whether the inferior was created using `attach', or
2739 started by @value{GDBN} itself.
2742 A @code{gdb.Inferior} object has the following methods:
2744 @defun Inferior.is_valid ()
2745 Returns @code{True} if the @code{gdb.Inferior} object is valid,
2746 @code{False} if not. A @code{gdb.Inferior} object will become invalid
2747 if the inferior no longer exists within @value{GDBN}. All other
2748 @code{gdb.Inferior} methods will throw an exception if it is invalid
2749 at the time the method is called.
2752 @defun Inferior.threads ()
2753 This method returns a tuple holding all the threads which are valid
2754 when it is called. If there are no valid threads, the method will
2755 return an empty tuple.
2758 @findex Inferior.read_memory
2759 @defun Inferior.read_memory (address, length)
2760 Read @var{length} addressable memory units from the inferior, starting at
2761 @var{address}. Returns a buffer object, which behaves much like an array
2762 or a string. It can be modified and given to the
2763 @code{Inferior.write_memory} function. In Python 3, the return
2764 value is a @code{memoryview} object.
2767 @findex Inferior.write_memory
2768 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
2769 Write the contents of @var{buffer} to the inferior, starting at
2770 @var{address}. The @var{buffer} parameter must be a Python object
2771 which supports the buffer protocol, i.e., a string, an array or the
2772 object returned from @code{Inferior.read_memory}. If given, @var{length}
2773 determines the number of addressable memory units from @var{buffer} to be
2777 @findex gdb.search_memory
2778 @defun Inferior.search_memory (address, length, pattern)
2779 Search a region of the inferior memory starting at @var{address} with
2780 the given @var{length} using the search pattern supplied in
2781 @var{pattern}. The @var{pattern} parameter must be a Python object
2782 which supports the buffer protocol, i.e., a string, an array or the
2783 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
2784 containing the address where the pattern was found, or @code{None} if
2785 the pattern could not be found.
2788 @node Events In Python
2789 @subsubsection Events In Python
2790 @cindex inferior events in Python
2792 @value{GDBN} provides a general event facility so that Python code can be
2793 notified of various state changes, particularly changes that occur in
2796 An @dfn{event} is just an object that describes some state change. The
2797 type of the object and its attributes will vary depending on the details
2798 of the change. All the existing events are described below.
2800 In order to be notified of an event, you must register an event handler
2801 with an @dfn{event registry}. An event registry is an object in the
2802 @code{gdb.events} module which dispatches particular events. A registry
2803 provides methods to register and unregister event handlers:
2805 @defun EventRegistry.connect (object)
2806 Add the given callable @var{object} to the registry. This object will be
2807 called when an event corresponding to this registry occurs.
2810 @defun EventRegistry.disconnect (object)
2811 Remove the given @var{object} from the registry. Once removed, the object
2812 will no longer receive notifications of events.
2818 def exit_handler (event):
2819 print "event type: exit"
2820 print "exit code: %d" % (event.exit_code)
2822 gdb.events.exited.connect (exit_handler)
2825 In the above example we connect our handler @code{exit_handler} to the
2826 registry @code{events.exited}. Once connected, @code{exit_handler} gets
2827 called when the inferior exits. The argument @dfn{event} in this example is
2828 of type @code{gdb.ExitedEvent}. As you can see in the example the
2829 @code{ExitedEvent} object has an attribute which indicates the exit code of
2832 The following is a listing of the event registries that are available and
2833 details of the events they emit:
2838 Emits @code{gdb.ThreadEvent}.
2840 Some events can be thread specific when @value{GDBN} is running in non-stop
2841 mode. When represented in Python, these events all extend
2842 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
2843 events which are emitted by this or other modules might extend this event.
2844 Examples of these events are @code{gdb.BreakpointEvent} and
2845 @code{gdb.ContinueEvent}.
2847 @defvar ThreadEvent.inferior_thread
2848 In non-stop mode this attribute will be set to the specific thread which was
2849 involved in the emitted event. Otherwise, it will be set to @code{None}.
2852 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
2854 This event indicates that the inferior has been continued after a stop. For
2855 inherited attribute refer to @code{gdb.ThreadEvent} above.
2858 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
2859 @code{events.ExitedEvent} has two attributes:
2860 @defvar ExitedEvent.exit_code
2861 An integer representing the exit code, if available, which the inferior
2862 has returned. (The exit code could be unavailable if, for example,
2863 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
2864 the attribute does not exist.
2866 @defvar ExitedEvent.inferior
2867 A reference to the inferior which triggered the @code{exited} event.
2871 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
2873 Indicates that the inferior has stopped. All events emitted by this registry
2874 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
2875 will indicate the stopped thread when @value{GDBN} is running in non-stop
2876 mode. Refer to @code{gdb.ThreadEvent} above for more details.
2878 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
2880 This event indicates that the inferior or one of its threads has received as
2881 signal. @code{gdb.SignalEvent} has the following attributes:
2883 @defvar SignalEvent.stop_signal
2884 A string representing the signal received by the inferior. A list of possible
2885 signal values can be obtained by running the command @code{info signals} in
2886 the @value{GDBN} command prompt.
2889 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
2891 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
2892 been hit, and has the following attributes:
2894 @defvar BreakpointEvent.breakpoints
2895 A sequence containing references to all the breakpoints (type
2896 @code{gdb.Breakpoint}) that were hit.
2897 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
2899 @defvar BreakpointEvent.breakpoint
2900 A reference to the first breakpoint that was hit.
2901 This function is maintained for backward compatibility and is now deprecated
2902 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
2905 @item events.new_objfile
2906 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
2907 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
2909 @defvar NewObjFileEvent.new_objfile
2910 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
2911 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
2914 @item events.clear_objfiles
2915 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
2916 files for a program space has been reset.
2917 @code{gdb.ClearObjFilesEvent} has one attribute:
2919 @defvar ClearObjFilesEvent.progspace
2920 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
2921 been cleared. @xref{Progspaces In Python}.
2924 @item events.inferior_call_pre
2925 Emits @code{gdb.InferiorCallPreEvent} which indicates that a function in
2926 the inferior is about to be called.
2928 @defvar InferiorCallPreEvent.ptid
2929 The thread in which the call will be run.
2932 @defvar InferiorCallPreEvent.address
2933 The location of the function to be called.
2936 @item events.inferior_call_post
2937 Emits @code{gdb.InferiorCallPostEvent} which indicates that a function in
2938 the inferior has returned.
2940 @defvar InferiorCallPostEvent.ptid
2941 The thread in which the call was run.
2944 @defvar InferiorCallPostEvent.address
2945 The location of the function that was called.
2948 @item events.memory_changed
2949 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
2950 inferior has been modified by the @value{GDBN} user, for instance via a
2951 command like @w{@code{set *addr = value}}. The event has the following
2954 @defvar MemoryChangedEvent.address
2955 The start address of the changed region.
2958 @defvar MemoryChangedEvent.length
2959 Length in bytes of the changed region.
2962 @item events.register_changed
2963 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
2964 inferior has been modified by the @value{GDBN} user.
2966 @defvar RegisterChangedEvent.frame
2967 A gdb.Frame object representing the frame in which the register was modified.
2969 @defvar RegisterChangedEvent.regnum
2970 Denotes which register was modified.
2973 @item events.breakpoint_created
2974 This is emitted when a new breakpoint has been created. The argument
2975 that is passed is the new @code{gdb.Breakpoint} object.
2977 @item events.breakpoint_modified
2978 This is emitted when a breakpoint has been modified in some way. The
2979 argument that is passed is the new @code{gdb.Breakpoint} object.
2981 @item events.breakpoint_deleted
2982 This is emitted when a breakpoint has been deleted. The argument that
2983 is passed is the @code{gdb.Breakpoint} object. When this event is
2984 emitted, the @code{gdb.Breakpoint} object will already be in its
2985 invalid state; that is, the @code{is_valid} method will return
2988 @item events.before_prompt
2989 This event carries no payload. It is emitted each time @value{GDBN}
2990 presents a prompt to the user.
2994 @node Threads In Python
2995 @subsubsection Threads In Python
2996 @cindex threads in python
2998 @findex gdb.InferiorThread
2999 Python scripts can access information about, and manipulate inferior threads
3000 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
3002 The following thread-related functions are available in the @code{gdb}
3005 @findex gdb.selected_thread
3006 @defun gdb.selected_thread ()
3007 This function returns the thread object for the selected thread. If there
3008 is no selected thread, this will return @code{None}.
3011 A @code{gdb.InferiorThread} object has the following attributes:
3013 @defvar InferiorThread.name
3014 The name of the thread. If the user specified a name using
3015 @code{thread name}, then this returns that name. Otherwise, if an
3016 OS-supplied name is available, then it is returned. Otherwise, this
3017 returns @code{None}.
3019 This attribute can be assigned to. The new value must be a string
3020 object, which sets the new name, or @code{None}, which removes any
3021 user-specified thread name.
3024 @defvar InferiorThread.num
3025 The per-inferior number of the thread, as assigned by GDB.
3028 @defvar InferiorThread.global_num
3029 The global ID of the thread, as assigned by GDB. You can use this to
3030 make Python breakpoints thread-specific, for example
3031 (@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
3034 @defvar InferiorThread.ptid
3035 ID of the thread, as assigned by the operating system. This attribute is a
3036 tuple containing three integers. The first is the Process ID (PID); the second
3037 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
3038 Either the LWPID or TID may be 0, which indicates that the operating system
3039 does not use that identifier.
3042 @defvar InferiorThread.inferior
3043 The inferior this thread belongs to. This attribute is represented as
3044 a @code{gdb.Inferior} object. This attribute is not writable.
3047 A @code{gdb.InferiorThread} object has the following methods:
3049 @defun InferiorThread.is_valid ()
3050 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
3051 @code{False} if not. A @code{gdb.InferiorThread} object will become
3052 invalid if the thread exits, or the inferior that the thread belongs
3053 is deleted. All other @code{gdb.InferiorThread} methods will throw an
3054 exception if it is invalid at the time the method is called.
3057 @defun InferiorThread.switch ()
3058 This changes @value{GDBN}'s currently selected thread to the one represented
3062 @defun InferiorThread.is_stopped ()
3063 Return a Boolean indicating whether the thread is stopped.
3066 @defun InferiorThread.is_running ()
3067 Return a Boolean indicating whether the thread is running.
3070 @defun InferiorThread.is_exited ()
3071 Return a Boolean indicating whether the thread is exited.
3074 @node Recordings In Python
3075 @subsubsection Recordings In Python
3076 @cindex recordings in python
3078 The following recordings-related functions
3079 (@pxref{Process Record and Replay}) are available in the @code{gdb}
3082 @defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
3083 Start a recording using the given @var{method} and @var{format}. If
3084 no @var{format} is given, the default format for the recording method
3085 is used. If no @var{method} is given, the default method will be used.
3086 Returns a @code{gdb.Record} object on success. Throw an exception on
3089 The following strings can be passed as @var{method}:
3095 @code{"btrace"}: Possible values for @var{format}: @code{"pt"},
3096 @code{"bts"} or leave out for default format.
3100 @defun gdb.current_recording ()
3101 Access a currently running recording. Return a @code{gdb.Record}
3102 object on success. Return @code{None} if no recording is currently
3106 @defun gdb.stop_recording ()
3107 Stop the current recording. Throw an exception if no recording is
3108 currently active. All record objects become invalid after this call.
3111 A @code{gdb.Record} object has the following attributes:
3113 @defvar Record.method
3114 A string with the current recording method, e.g.@: @code{full} or
3118 @defvar Record.format
3119 A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
3123 @defvar Record.begin
3124 A method specific instruction object representing the first instruction
3129 A method specific instruction object representing the current
3130 instruction, that is not actually part of the recording.
3133 @defvar Record.replay_position
3134 The instruction representing the current replay position. If there is
3135 no replay active, this will be @code{None}.
3138 @defvar Record.instruction_history
3139 A list with all recorded instructions.
3142 @defvar Record.function_call_history
3143 A list with all recorded function call segments.
3146 A @code{gdb.Record} object has the following methods:
3148 @defun Record.goto (instruction)
3149 Move the replay position to the given @var{instruction}.
3152 A @code{gdb.RecordInstruction} object has the following attributes:
3154 @defvar RecordInstruction.number
3155 An integer identifying this instruction. @var{number} corresponds to
3156 the numbers seen in @code{record instruction-history}
3157 (@pxref{Process Record and Replay}).
3160 @defvar RecordInstruction.sal
3161 A @code{gdb.Symtab_and_line} object representing the associated symtab
3162 and line of this instruction. May be @code{None} if no debug information is
3166 @defvar RecordInstruction.pc
3167 An integer representing this instruction's address.
3170 @defvar RecordInstruction.data
3171 A buffer with the raw instruction data. In Python 3, the return value is a
3172 @code{memoryview} object.
3175 @defvar RecordInstruction.decoded
3176 A human readable string with the disassembled instruction.
3179 @defvar RecordInstruction.size
3180 The size of the instruction in bytes.
3183 @defvar RecordInstruction.is_speculative
3184 A boolean indicating whether the instruction was executed
3188 If an error occured during recording or decoding a recording, this error is
3189 represented by a @code{gdb.RecordGap} object in the instruction list. It has
3190 the following attributes:
3192 @defvar RecordGap.number
3193 An integer identifying this gap. @code{number} corresponds to the numbers seen
3194 in @code{record instruction-history} (@pxref{Process Record and Replay}).
3197 @defvar RecordGap.error_code
3198 A numerical representation of the reason for the gap. The value is specific to
3199 the current recording method.
3202 @defvar RecordGap.error_string
3203 A human readable string with the reason for the gap.
3206 A @code{gdb.RecordFunctionSegment} object has the following attributes:
3208 @defvar RecordFunctionSegment.number
3209 An integer identifying this function segment. @code{number} corresponds to
3210 the numbers seen in @code{record function-call-history}
3211 (@pxref{Process Record and Replay}).
3214 @defvar RecordFunctionSegment.symbol
3215 A @code{gdb.Symbol} object representing the associated symbol. May be
3216 @code{None} if no debug information is available.
3219 @defvar RecordFunctionSegment.level
3220 An integer representing the function call's stack level. May be
3221 @code{None} if the function call is a gap.
3224 @defvar RecordFunctionSegment.instructions
3225 A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
3226 associated with this function call.
3229 @defvar RecordFunctionSegment.up
3230 A @code{gdb.RecordFunctionSegment} object representing the caller's
3231 function segment. If the call has not been recorded, this will be the
3232 function segment to which control returns. If neither the call nor the
3233 return have been recorded, this will be @code{None}.
3236 @defvar RecordFunctionSegment.prev
3237 A @code{gdb.RecordFunctionSegment} object representing the previous
3238 segment of this function call. May be @code{None}.
3241 @defvar RecordFunctionSegment.next
3242 A @code{gdb.RecordFunctionSegment} object representing the next segment of
3243 this function call. May be @code{None}.
3246 The following example demonstrates the usage of these objects and
3247 functions to create a function that will rewind a record to the last
3248 time a function in a different file was executed. This would typically
3249 be used to track the execution of user provided callback functions in a
3250 library which typically are not visible in a back trace.
3254 rec = gdb.current_recording ()
3258 insn = rec.instruction_history
3263 position = insn.index (rec.replay_position)
3267 filename = insn[position].sal.symtab.fullname ()
3271 for i in reversed (insn[:position]):
3273 current = i.sal.symtab.fullname ()
3277 if filename == current:
3284 Another possible application is to write a function that counts the
3285 number of code executions in a given line range. This line range can
3286 contain parts of functions or span across several functions and is not
3287 limited to be contiguous.
3290 def countrange (filename, linerange):
3293 def filter_only (file_name):
3294 for call in gdb.current_recording ().function_call_history:
3296 if file_name in call.symbol.symtab.fullname ():
3301 for c in filter_only (filename):
3302 for i in c.instructions:
3304 if i.sal.line in linerange:
3313 @node Commands In Python
3314 @subsubsection Commands In Python
3316 @cindex commands in python
3317 @cindex python commands
3318 You can implement new @value{GDBN} CLI commands in Python. A CLI
3319 command is implemented using an instance of the @code{gdb.Command}
3320 class, most commonly using a subclass.
3322 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
3323 The object initializer for @code{Command} registers the new command
3324 with @value{GDBN}. This initializer is normally invoked from the
3325 subclass' own @code{__init__} method.
3327 @var{name} is the name of the command. If @var{name} consists of
3328 multiple words, then the initial words are looked for as prefix
3329 commands. In this case, if one of the prefix commands does not exist,
3330 an exception is raised.
3332 There is no support for multi-line commands.
3334 @var{command_class} should be one of the @samp{COMMAND_} constants
3335 defined below. This argument tells @value{GDBN} how to categorize the
3336 new command in the help system.
3338 @var{completer_class} is an optional argument. If given, it should be
3339 one of the @samp{COMPLETE_} constants defined below. This argument
3340 tells @value{GDBN} how to perform completion for this command. If not
3341 given, @value{GDBN} will attempt to complete using the object's
3342 @code{complete} method (see below); if no such method is found, an
3343 error will occur when completion is attempted.
3345 @var{prefix} is an optional argument. If @code{True}, then the new
3346 command is a prefix command; sub-commands of this command may be
3349 The help text for the new command is taken from the Python
3350 documentation string for the command's class, if there is one. If no
3351 documentation string is provided, the default value ``This command is
3352 not documented.'' is used.
3355 @cindex don't repeat Python command
3356 @defun Command.dont_repeat ()
3357 By default, a @value{GDBN} command is repeated when the user enters a
3358 blank line at the command prompt. A command can suppress this
3359 behavior by invoking the @code{dont_repeat} method. This is similar
3360 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
3363 @defun Command.invoke (argument, from_tty)
3364 This method is called by @value{GDBN} when this command is invoked.
3366 @var{argument} is a string. It is the argument to the command, after
3367 leading and trailing whitespace has been stripped.
3369 @var{from_tty} is a boolean argument. When true, this means that the
3370 command was entered by the user at the terminal; when false it means
3371 that the command came from elsewhere.
3373 If this method throws an exception, it is turned into a @value{GDBN}
3374 @code{error} call. Otherwise, the return value is ignored.
3376 @findex gdb.string_to_argv
3377 To break @var{argument} up into an argv-like string use
3378 @code{gdb.string_to_argv}. This function behaves identically to
3379 @value{GDBN}'s internal argument lexer @code{buildargv}.
3380 It is recommended to use this for consistency.
3381 Arguments are separated by spaces and may be quoted.
3385 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
3386 ['1', '2 "3', '4 "5', "6 '7"]
3391 @cindex completion of Python commands
3392 @defun Command.complete (text, word)
3393 This method is called by @value{GDBN} when the user attempts
3394 completion on this command. All forms of completion are handled by
3395 this method, that is, the @key{TAB} and @key{M-?} key bindings
3396 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
3399 The arguments @var{text} and @var{word} are both strings; @var{text}
3400 holds the complete command line up to the cursor's location, while
3401 @var{word} holds the last word of the command line; this is computed
3402 using a word-breaking heuristic.
3404 The @code{complete} method can return several values:
3407 If the return value is a sequence, the contents of the sequence are
3408 used as the completions. It is up to @code{complete} to ensure that the
3409 contents actually do complete the word. A zero-length sequence is
3410 allowed, it means that there were no completions available. Only
3411 string elements of the sequence are used; other elements in the
3412 sequence are ignored.
3415 If the return value is one of the @samp{COMPLETE_} constants defined
3416 below, then the corresponding @value{GDBN}-internal completion
3417 function is invoked, and its result is used.
3420 All other results are treated as though there were no available
3425 When a new command is registered, it must be declared as a member of
3426 some general class of commands. This is used to classify top-level
3427 commands in the on-line help system; note that prefix commands are not
3428 listed under their own category but rather that of their top-level
3429 command. The available classifications are represented by constants
3430 defined in the @code{gdb} module:
3433 @findex COMMAND_NONE
3434 @findex gdb.COMMAND_NONE
3435 @item gdb.COMMAND_NONE
3436 The command does not belong to any particular class. A command in
3437 this category will not be displayed in any of the help categories.
3439 @findex COMMAND_RUNNING
3440 @findex gdb.COMMAND_RUNNING
3441 @item gdb.COMMAND_RUNNING
3442 The command is related to running the inferior. For example,
3443 @code{start}, @code{step}, and @code{continue} are in this category.
3444 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
3445 commands in this category.
3447 @findex COMMAND_DATA
3448 @findex gdb.COMMAND_DATA
3449 @item gdb.COMMAND_DATA
3450 The command is related to data or variables. For example,
3451 @code{call}, @code{find}, and @code{print} are in this category. Type
3452 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
3455 @findex COMMAND_STACK
3456 @findex gdb.COMMAND_STACK
3457 @item gdb.COMMAND_STACK
3458 The command has to do with manipulation of the stack. For example,
3459 @code{backtrace}, @code{frame}, and @code{return} are in this
3460 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
3461 list of commands in this category.
3463 @findex COMMAND_FILES
3464 @findex gdb.COMMAND_FILES
3465 @item gdb.COMMAND_FILES
3466 This class is used for file-related commands. For example,
3467 @code{file}, @code{list} and @code{section} are in this category.
3468 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
3469 commands in this category.
3471 @findex COMMAND_SUPPORT
3472 @findex gdb.COMMAND_SUPPORT
3473 @item gdb.COMMAND_SUPPORT
3474 This should be used for ``support facilities'', generally meaning
3475 things that are useful to the user when interacting with @value{GDBN},
3476 but not related to the state of the inferior. For example,
3477 @code{help}, @code{make}, and @code{shell} are in this category. Type
3478 @kbd{help support} at the @value{GDBN} prompt to see a list of
3479 commands in this category.
3481 @findex COMMAND_STATUS
3482 @findex gdb.COMMAND_STATUS
3483 @item gdb.COMMAND_STATUS
3484 The command is an @samp{info}-related command, that is, related to the
3485 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
3486 and @code{show} are in this category. Type @kbd{help status} at the
3487 @value{GDBN} prompt to see a list of commands in this category.
3489 @findex COMMAND_BREAKPOINTS
3490 @findex gdb.COMMAND_BREAKPOINTS
3491 @item gdb.COMMAND_BREAKPOINTS
3492 The command has to do with breakpoints. For example, @code{break},
3493 @code{clear}, and @code{delete} are in this category. Type @kbd{help
3494 breakpoints} at the @value{GDBN} prompt to see a list of commands in
3497 @findex COMMAND_TRACEPOINTS
3498 @findex gdb.COMMAND_TRACEPOINTS
3499 @item gdb.COMMAND_TRACEPOINTS
3500 The command has to do with tracepoints. For example, @code{trace},
3501 @code{actions}, and @code{tfind} are in this category. Type
3502 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
3503 commands in this category.
3505 @findex COMMAND_USER
3506 @findex gdb.COMMAND_USER
3507 @item gdb.COMMAND_USER
3508 The command is a general purpose command for the user, and typically
3509 does not fit in one of the other categories.
3510 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
3511 a list of commands in this category, as well as the list of gdb macros
3512 (@pxref{Sequences}).
3514 @findex COMMAND_OBSCURE
3515 @findex gdb.COMMAND_OBSCURE
3516 @item gdb.COMMAND_OBSCURE
3517 The command is only used in unusual circumstances, or is not of
3518 general interest to users. For example, @code{checkpoint},
3519 @code{fork}, and @code{stop} are in this category. Type @kbd{help
3520 obscure} at the @value{GDBN} prompt to see a list of commands in this
3523 @findex COMMAND_MAINTENANCE
3524 @findex gdb.COMMAND_MAINTENANCE
3525 @item gdb.COMMAND_MAINTENANCE
3526 The command is only useful to @value{GDBN} maintainers. The
3527 @code{maintenance} and @code{flushregs} commands are in this category.
3528 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
3529 commands in this category.
3532 A new command can use a predefined completion function, either by
3533 specifying it via an argument at initialization, or by returning it
3534 from the @code{complete} method. These predefined completion
3535 constants are all defined in the @code{gdb} module:
3538 @vindex COMPLETE_NONE
3539 @item gdb.COMPLETE_NONE
3540 This constant means that no completion should be done.
3542 @vindex COMPLETE_FILENAME
3543 @item gdb.COMPLETE_FILENAME
3544 This constant means that filename completion should be performed.
3546 @vindex COMPLETE_LOCATION
3547 @item gdb.COMPLETE_LOCATION
3548 This constant means that location completion should be done.
3549 @xref{Specify Location}.
3551 @vindex COMPLETE_COMMAND
3552 @item gdb.COMPLETE_COMMAND
3553 This constant means that completion should examine @value{GDBN}
3556 @vindex COMPLETE_SYMBOL
3557 @item gdb.COMPLETE_SYMBOL
3558 This constant means that completion should be done using symbol names
3561 @vindex COMPLETE_EXPRESSION
3562 @item gdb.COMPLETE_EXPRESSION
3563 This constant means that completion should be done on expressions.
3564 Often this means completing on symbol names, but some language
3565 parsers also have support for completing on field names.
3568 The following code snippet shows how a trivial CLI command can be
3569 implemented in Python:
3572 class HelloWorld (gdb.Command):
3573 """Greet the whole world."""
3575 def __init__ (self):
3576 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
3578 def invoke (self, arg, from_tty):
3579 print "Hello, World!"
3584 The last line instantiates the class, and is necessary to trigger the
3585 registration of the command with @value{GDBN}. Depending on how the
3586 Python code is read into @value{GDBN}, you may need to import the
3587 @code{gdb} module explicitly.
3589 @node Parameters In Python
3590 @subsubsection Parameters In Python
3592 @cindex parameters in python
3593 @cindex python parameters
3594 @tindex gdb.Parameter
3596 You can implement new @value{GDBN} parameters using Python. A new
3597 parameter is implemented as an instance of the @code{gdb.Parameter}
3600 Parameters are exposed to the user via the @code{set} and
3601 @code{show} commands. @xref{Help}.
3603 There are many parameters that already exist and can be set in
3604 @value{GDBN}. Two examples are: @code{set follow fork} and
3605 @code{set charset}. Setting these parameters influences certain
3606 behavior in @value{GDBN}. Similarly, you can define parameters that
3607 can be used to influence behavior in custom Python scripts and commands.
3609 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
3610 The object initializer for @code{Parameter} registers the new
3611 parameter with @value{GDBN}. This initializer is normally invoked
3612 from the subclass' own @code{__init__} method.
3614 @var{name} is the name of the new parameter. If @var{name} consists
3615 of multiple words, then the initial words are looked for as prefix
3616 parameters. An example of this can be illustrated with the
3617 @code{set print} set of parameters. If @var{name} is
3618 @code{print foo}, then @code{print} will be searched as the prefix
3619 parameter. In this case the parameter can subsequently be accessed in
3620 @value{GDBN} as @code{set print foo}.
3622 If @var{name} consists of multiple words, and no prefix parameter group
3623 can be found, an exception is raised.
3625 @var{command-class} should be one of the @samp{COMMAND_} constants
3626 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
3627 categorize the new parameter in the help system.
3629 @var{parameter-class} should be one of the @samp{PARAM_} constants
3630 defined below. This argument tells @value{GDBN} the type of the new
3631 parameter; this information is used for input validation and
3634 If @var{parameter-class} is @code{PARAM_ENUM}, then
3635 @var{enum-sequence} must be a sequence of strings. These strings
3636 represent the possible values for the parameter.
3638 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
3639 of a fourth argument will cause an exception to be thrown.
3641 The help text for the new parameter is taken from the Python
3642 documentation string for the parameter's class, if there is one. If
3643 there is no documentation string, a default value is used.
3646 @defvar Parameter.set_doc
3647 If this attribute exists, and is a string, then its value is used as
3648 the help text for this parameter's @code{set} command. The value is
3649 examined when @code{Parameter.__init__} is invoked; subsequent changes
3653 @defvar Parameter.show_doc
3654 If this attribute exists, and is a string, then its value is used as
3655 the help text for this parameter's @code{show} command. The value is
3656 examined when @code{Parameter.__init__} is invoked; subsequent changes
3660 @defvar Parameter.value
3661 The @code{value} attribute holds the underlying value of the
3662 parameter. It can be read and assigned to just as any other
3663 attribute. @value{GDBN} does validation when assignments are made.
3666 There are two methods that should be implemented in any
3667 @code{Parameter} class. These are:
3669 @defun Parameter.get_set_string (self)
3670 @value{GDBN} will call this method when a @var{parameter}'s value has
3671 been changed via the @code{set} API (for example, @kbd{set foo off}).
3672 The @code{value} attribute has already been populated with the new
3673 value and may be used in output. This method must return a string.
3676 @defun Parameter.get_show_string (self, svalue)
3677 @value{GDBN} will call this method when a @var{parameter}'s
3678 @code{show} API has been invoked (for example, @kbd{show foo}). The
3679 argument @code{svalue} receives the string representation of the
3680 current value. This method must return a string.
3683 When a new parameter is defined, its type must be specified. The
3684 available types are represented by constants defined in the @code{gdb}
3688 @findex PARAM_BOOLEAN
3689 @findex gdb.PARAM_BOOLEAN
3690 @item gdb.PARAM_BOOLEAN
3691 The value is a plain boolean. The Python boolean values, @code{True}
3692 and @code{False} are the only valid values.
3694 @findex PARAM_AUTO_BOOLEAN
3695 @findex gdb.PARAM_AUTO_BOOLEAN
3696 @item gdb.PARAM_AUTO_BOOLEAN
3697 The value has three possible states: true, false, and @samp{auto}. In
3698 Python, true and false are represented using boolean constants, and
3699 @samp{auto} is represented using @code{None}.
3701 @findex PARAM_UINTEGER
3702 @findex gdb.PARAM_UINTEGER
3703 @item gdb.PARAM_UINTEGER
3704 The value is an unsigned integer. The value of 0 should be
3705 interpreted to mean ``unlimited''.
3707 @findex PARAM_INTEGER
3708 @findex gdb.PARAM_INTEGER
3709 @item gdb.PARAM_INTEGER
3710 The value is a signed integer. The value of 0 should be interpreted
3711 to mean ``unlimited''.
3713 @findex PARAM_STRING
3714 @findex gdb.PARAM_STRING
3715 @item gdb.PARAM_STRING
3716 The value is a string. When the user modifies the string, any escape
3717 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
3718 translated into corresponding characters and encoded into the current
3721 @findex PARAM_STRING_NOESCAPE
3722 @findex gdb.PARAM_STRING_NOESCAPE
3723 @item gdb.PARAM_STRING_NOESCAPE
3724 The value is a string. When the user modifies the string, escapes are
3725 passed through untranslated.
3727 @findex PARAM_OPTIONAL_FILENAME
3728 @findex gdb.PARAM_OPTIONAL_FILENAME
3729 @item gdb.PARAM_OPTIONAL_FILENAME
3730 The value is a either a filename (a string), or @code{None}.
3732 @findex PARAM_FILENAME
3733 @findex gdb.PARAM_FILENAME
3734 @item gdb.PARAM_FILENAME
3735 The value is a filename. This is just like
3736 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
3738 @findex PARAM_ZINTEGER
3739 @findex gdb.PARAM_ZINTEGER
3740 @item gdb.PARAM_ZINTEGER
3741 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
3742 is interpreted as itself.
3745 @findex gdb.PARAM_ENUM
3746 @item gdb.PARAM_ENUM
3747 The value is a string, which must be one of a collection string
3748 constants provided when the parameter is created.
3751 @node Functions In Python
3752 @subsubsection Writing new convenience functions
3754 @cindex writing convenience functions
3755 @cindex convenience functions in python
3756 @cindex python convenience functions
3757 @tindex gdb.Function
3759 You can implement new convenience functions (@pxref{Convenience Vars})
3760 in Python. A convenience function is an instance of a subclass of the
3761 class @code{gdb.Function}.
3763 @defun Function.__init__ (name)
3764 The initializer for @code{Function} registers the new function with
3765 @value{GDBN}. The argument @var{name} is the name of the function,
3766 a string. The function will be visible to the user as a convenience
3767 variable of type @code{internal function}, whose name is the same as
3768 the given @var{name}.
3770 The documentation for the new function is taken from the documentation
3771 string for the new class.
3774 @defun Function.invoke (@var{*args})
3775 When a convenience function is evaluated, its arguments are converted
3776 to instances of @code{gdb.Value}, and then the function's
3777 @code{invoke} method is called. Note that @value{GDBN} does not
3778 predetermine the arity of convenience functions. Instead, all
3779 available arguments are passed to @code{invoke}, following the
3780 standard Python calling convention. In particular, a convenience
3781 function can have default values for parameters without ill effect.
3783 The return value of this method is used as its value in the enclosing
3784 expression. If an ordinary Python value is returned, it is converted
3785 to a @code{gdb.Value} following the usual rules.
3788 The following code snippet shows how a trivial convenience function can
3789 be implemented in Python:
3792 class Greet (gdb.Function):
3793 """Return string to greet someone.
3794 Takes a name as argument."""
3796 def __init__ (self):
3797 super (Greet, self).__init__ ("greet")
3799 def invoke (self, name):
3800 return "Hello, %s!" % name.string ()
3805 The last line instantiates the class, and is necessary to trigger the
3806 registration of the function with @value{GDBN}. Depending on how the
3807 Python code is read into @value{GDBN}, you may need to import the
3808 @code{gdb} module explicitly.
3810 Now you can use the function in an expression:
3813 (gdb) print $greet("Bob")
3817 @node Progspaces In Python
3818 @subsubsection Program Spaces In Python
3820 @cindex progspaces in python
3821 @tindex gdb.Progspace
3823 A program space, or @dfn{progspace}, represents a symbolic view
3824 of an address space.
3825 It consists of all of the objfiles of the program.
3826 @xref{Objfiles In Python}.
3827 @xref{Inferiors and Programs, program spaces}, for more details
3828 about program spaces.
3830 The following progspace-related functions are available in the
3833 @findex gdb.current_progspace
3834 @defun gdb.current_progspace ()
3835 This function returns the program space of the currently selected inferior.
3836 @xref{Inferiors and Programs}.
3839 @findex gdb.progspaces
3840 @defun gdb.progspaces ()
3841 Return a sequence of all the progspaces currently known to @value{GDBN}.
3844 Each progspace is represented by an instance of the @code{gdb.Progspace}
3847 @defvar Progspace.filename
3848 The file name of the progspace as a string.
3851 @defvar Progspace.pretty_printers
3852 The @code{pretty_printers} attribute is a list of functions. It is
3853 used to look up pretty-printers. A @code{Value} is passed to each
3854 function in order; if the function returns @code{None}, then the
3855 search continues. Otherwise, the return value should be an object
3856 which is used to format the value. @xref{Pretty Printing API}, for more
3860 @defvar Progspace.type_printers
3861 The @code{type_printers} attribute is a list of type printer objects.
3862 @xref{Type Printing API}, for more information.
3865 @defvar Progspace.frame_filters
3866 The @code{frame_filters} attribute is a dictionary of frame filter
3867 objects. @xref{Frame Filter API}, for more information.
3870 One may add arbitrary attributes to @code{gdb.Progspace} objects
3871 in the usual Python way.
3872 This is useful if, for example, one needs to do some extra record keeping
3873 associated with the program space.
3875 In this contrived example, we want to perform some processing when
3876 an objfile with a certain symbol is loaded, but we only want to do
3877 this once because it is expensive. To achieve this we record the results
3878 with the program space because we can't predict when the desired objfile
3883 def clear_objfiles_handler(event):
3884 event.progspace.expensive_computation = None
3885 def expensive(symbol):
3886 """A mock routine to perform an "expensive" computation on symbol."""
3887 print "Computing the answer to the ultimate question ..."
3889 def new_objfile_handler(event):
3890 objfile = event.new_objfile
3891 progspace = objfile.progspace
3892 if not hasattr(progspace, 'expensive_computation') or \
3893 progspace.expensive_computation is None:
3894 # We use 'main' for the symbol to keep the example simple.
3895 # Note: There's no current way to constrain the lookup
3897 symbol = gdb.lookup_global_symbol('main')
3898 if symbol is not None:
3899 progspace.expensive_computation = expensive(symbol)
3900 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
3901 gdb.events.new_objfile.connect(new_objfile_handler)
3903 (gdb) file /tmp/hello
3904 Reading symbols from /tmp/hello...done.
3905 Computing the answer to the ultimate question ...
3906 (gdb) python print gdb.current_progspace().expensive_computation
3909 Starting program: /tmp/hello
3911 [Inferior 1 (process 4242) exited normally]
3914 @node Objfiles In Python
3915 @subsubsection Objfiles In Python
3917 @cindex objfiles in python
3920 @value{GDBN} loads symbols for an inferior from various
3921 symbol-containing files (@pxref{Files}). These include the primary
3922 executable file, any shared libraries used by the inferior, and any
3923 separate debug info files (@pxref{Separate Debug Files}).
3924 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
3926 The following objfile-related functions are available in the
3929 @findex gdb.current_objfile
3930 @defun gdb.current_objfile ()
3931 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
3932 sets the ``current objfile'' to the corresponding objfile. This
3933 function returns the current objfile. If there is no current objfile,
3934 this function returns @code{None}.
3937 @findex gdb.objfiles
3938 @defun gdb.objfiles ()
3939 Return a sequence of all the objfiles current known to @value{GDBN}.
3940 @xref{Objfiles In Python}.
3943 @findex gdb.lookup_objfile
3944 @defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
3945 Look up @var{name}, a file name or build ID, in the list of objfiles
3946 for the current program space (@pxref{Progspaces In Python}).
3947 If the objfile is not found throw the Python @code{ValueError} exception.
3949 If @var{name} is a relative file name, then it will match any
3950 source file name with the same trailing components. For example, if
3951 @var{name} is @samp{gcc/expr.c}, then it will match source file
3952 name of @file{/build/trunk/gcc/expr.c}, but not
3953 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
3955 If @var{by_build_id} is provided and is @code{True} then @var{name}
3956 is the build ID of the objfile. Otherwise, @var{name} is a file name.
3957 This is supported only on some operating systems, notably those which use
3958 the ELF format for binary files and the @sc{gnu} Binutils. For more details
3959 about this feature, see the description of the @option{--build-id}
3960 command-line option in @ref{Options, , Command Line Options, ld.info,
3964 Each objfile is represented by an instance of the @code{gdb.Objfile}
3967 @defvar Objfile.filename
3968 The file name of the objfile as a string, with symbolic links resolved.
3970 The value is @code{None} if the objfile is no longer valid.
3971 See the @code{gdb.Objfile.is_valid} method, described below.
3974 @defvar Objfile.username
3975 The file name of the objfile as specified by the user as a string.
3977 The value is @code{None} if the objfile is no longer valid.
3978 See the @code{gdb.Objfile.is_valid} method, described below.
3981 @defvar Objfile.owner
3982 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
3983 object that debug info is being provided for.
3984 Otherwise this is @code{None}.
3985 Separate debug info objfiles are added with the
3986 @code{gdb.Objfile.add_separate_debug_file} method, described below.
3989 @defvar Objfile.build_id
3990 The build ID of the objfile as a string.
3991 If the objfile does not have a build ID then the value is @code{None}.
3993 This is supported only on some operating systems, notably those which use
3994 the ELF format for binary files and the @sc{gnu} Binutils. For more details
3995 about this feature, see the description of the @option{--build-id}
3996 command-line option in @ref{Options, , Command Line Options, ld.info,
4000 @defvar Objfile.progspace
4001 The containing program space of the objfile as a @code{gdb.Progspace}
4002 object. @xref{Progspaces In Python}.
4005 @defvar Objfile.pretty_printers
4006 The @code{pretty_printers} attribute is a list of functions. It is
4007 used to look up pretty-printers. A @code{Value} is passed to each
4008 function in order; if the function returns @code{None}, then the
4009 search continues. Otherwise, the return value should be an object
4010 which is used to format the value. @xref{Pretty Printing API}, for more
4014 @defvar Objfile.type_printers
4015 The @code{type_printers} attribute is a list of type printer objects.
4016 @xref{Type Printing API}, for more information.
4019 @defvar Objfile.frame_filters
4020 The @code{frame_filters} attribute is a dictionary of frame filter
4021 objects. @xref{Frame Filter API}, for more information.
4024 One may add arbitrary attributes to @code{gdb.Objfile} objects
4025 in the usual Python way.
4026 This is useful if, for example, one needs to do some extra record keeping
4027 associated with the objfile.
4029 In this contrived example we record the time when @value{GDBN}
4035 def new_objfile_handler(event):
4036 # Set the time_loaded attribute of the new objfile.
4037 event.new_objfile.time_loaded = datetime.datetime.today()
4038 gdb.events.new_objfile.connect(new_objfile_handler)
4041 Reading symbols from ./hello...done.
4042 (gdb) python print gdb.objfiles()[0].time_loaded
4043 2014-10-09 11:41:36.770345
4046 A @code{gdb.Objfile} object has the following methods:
4048 @defun Objfile.is_valid ()
4049 Returns @code{True} if the @code{gdb.Objfile} object is valid,
4050 @code{False} if not. A @code{gdb.Objfile} object can become invalid
4051 if the object file it refers to is not loaded in @value{GDBN} any
4052 longer. All other @code{gdb.Objfile} methods will throw an exception
4053 if it is invalid at the time the method is called.
4056 @defun Objfile.add_separate_debug_file (file)
4057 Add @var{file} to the list of files that @value{GDBN} will search for
4058 debug information for the objfile.
4059 This is useful when the debug info has been removed from the program
4060 and stored in a separate file. @value{GDBN} has built-in support for
4061 finding separate debug info files (@pxref{Separate Debug Files}), but if
4062 the file doesn't live in one of the standard places that @value{GDBN}
4063 searches then this function can be used to add a debug info file
4064 from a different place.
4067 @node Frames In Python
4068 @subsubsection Accessing inferior stack frames from Python.
4070 @cindex frames in python
4071 When the debugged program stops, @value{GDBN} is able to analyze its call
4072 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
4073 represents a frame in the stack. A @code{gdb.Frame} object is only valid
4074 while its corresponding frame exists in the inferior's stack. If you try
4075 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
4076 exception (@pxref{Exception Handling}).
4078 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
4082 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
4086 The following frame-related functions are available in the @code{gdb} module:
4088 @findex gdb.selected_frame
4089 @defun gdb.selected_frame ()
4090 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
4093 @findex gdb.newest_frame
4094 @defun gdb.newest_frame ()
4095 Return the newest frame object for the selected thread.
4098 @defun gdb.frame_stop_reason_string (reason)
4099 Return a string explaining the reason why @value{GDBN} stopped unwinding
4100 frames, as expressed by the given @var{reason} code (an integer, see the
4101 @code{unwind_stop_reason} method further down in this section).
4104 @findex gdb.invalidate_cached_frames
4105 @defun gdb.invalidate_cached_frames
4106 @value{GDBN} internally keeps a cache of the frames that have been
4107 unwound. This function invalidates this cache.
4109 This function should not generally be called by ordinary Python code.
4110 It is documented for the sake of completeness.
4113 A @code{gdb.Frame} object has the following methods:
4115 @defun Frame.is_valid ()
4116 Returns true if the @code{gdb.Frame} object is valid, false if not.
4117 A frame object can become invalid if the frame it refers to doesn't
4118 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
4119 an exception if it is invalid at the time the method is called.
4122 @defun Frame.name ()
4123 Returns the function name of the frame, or @code{None} if it can't be
4127 @defun Frame.architecture ()
4128 Returns the @code{gdb.Architecture} object corresponding to the frame's
4129 architecture. @xref{Architectures In Python}.
4132 @defun Frame.type ()
4133 Returns the type of the frame. The value can be one of:
4135 @item gdb.NORMAL_FRAME
4136 An ordinary stack frame.
4138 @item gdb.DUMMY_FRAME
4139 A fake stack frame that was created by @value{GDBN} when performing an
4140 inferior function call.
4142 @item gdb.INLINE_FRAME
4143 A frame representing an inlined function. The function was inlined
4144 into a @code{gdb.NORMAL_FRAME} that is older than this one.
4146 @item gdb.TAILCALL_FRAME
4147 A frame representing a tail call. @xref{Tail Call Frames}.
4149 @item gdb.SIGTRAMP_FRAME
4150 A signal trampoline frame. This is the frame created by the OS when
4151 it calls into a signal handler.
4153 @item gdb.ARCH_FRAME
4154 A fake stack frame representing a cross-architecture call.
4156 @item gdb.SENTINEL_FRAME
4157 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
4162 @defun Frame.unwind_stop_reason ()
4163 Return an integer representing the reason why it's not possible to find
4164 more frames toward the outermost frame. Use
4165 @code{gdb.frame_stop_reason_string} to convert the value returned by this
4166 function to a string. The value can be one of:
4169 @item gdb.FRAME_UNWIND_NO_REASON
4170 No particular reason (older frames should be available).
4172 @item gdb.FRAME_UNWIND_NULL_ID
4173 The previous frame's analyzer returns an invalid result. This is no
4174 longer used by @value{GDBN}, and is kept only for backward
4177 @item gdb.FRAME_UNWIND_OUTERMOST
4178 This frame is the outermost.
4180 @item gdb.FRAME_UNWIND_UNAVAILABLE
4181 Cannot unwind further, because that would require knowing the
4182 values of registers or memory that have not been collected.
4184 @item gdb.FRAME_UNWIND_INNER_ID
4185 This frame ID looks like it ought to belong to a NEXT frame,
4186 but we got it for a PREV frame. Normally, this is a sign of
4187 unwinder failure. It could also indicate stack corruption.
4189 @item gdb.FRAME_UNWIND_SAME_ID
4190 This frame has the same ID as the previous one. That means
4191 that unwinding further would almost certainly give us another
4192 frame with exactly the same ID, so break the chain. Normally,
4193 this is a sign of unwinder failure. It could also indicate
4196 @item gdb.FRAME_UNWIND_NO_SAVED_PC
4197 The frame unwinder did not find any saved PC, but we needed
4198 one to unwind further.
4200 @item gdb.FRAME_UNWIND_MEMORY_ERROR
4201 The frame unwinder caused an error while trying to access memory.
4203 @item gdb.FRAME_UNWIND_FIRST_ERROR
4204 Any stop reason greater or equal to this value indicates some kind
4205 of error. This special value facilitates writing code that tests
4206 for errors in unwinding in a way that will work correctly even if
4207 the list of the other values is modified in future @value{GDBN}
4208 versions. Using it, you could write:
4210 reason = gdb.selected_frame().unwind_stop_reason ()
4211 reason_str = gdb.frame_stop_reason_string (reason)
4212 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
4213 print "An error occured: %s" % reason_str
4220 Returns the frame's resume address.
4223 @defun Frame.block ()
4224 Return the frame's code block. @xref{Blocks In Python}.
4227 @defun Frame.function ()
4228 Return the symbol for the function corresponding to this frame.
4229 @xref{Symbols In Python}.
4232 @defun Frame.older ()
4233 Return the frame that called this frame.
4236 @defun Frame.newer ()
4237 Return the frame called by this frame.
4240 @defun Frame.find_sal ()
4241 Return the frame's symtab and line object.
4242 @xref{Symbol Tables In Python}.
4245 @defun Frame.read_register (register)
4246 Return the value of @var{register} in this frame. The @var{register}
4247 argument must be a string (e.g., @code{'sp'} or @code{'rax'}).
4248 Returns a @code{Gdb.Value} object. Throws an exception if @var{register}
4252 @defun Frame.read_var (variable @r{[}, block@r{]})
4253 Return the value of @var{variable} in this frame. If the optional
4254 argument @var{block} is provided, search for the variable from that
4255 block; otherwise start at the frame's current block (which is
4256 determined by the frame's current program counter). The @var{variable}
4257 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
4258 @code{gdb.Block} object.
4261 @defun Frame.select ()
4262 Set this frame to be the selected frame. @xref{Stack, ,Examining the
4266 @node Blocks In Python
4267 @subsubsection Accessing blocks from Python.
4269 @cindex blocks in python
4272 In @value{GDBN}, symbols are stored in blocks. A block corresponds
4273 roughly to a scope in the source code. Blocks are organized
4274 hierarchically, and are represented individually in Python as a
4275 @code{gdb.Block}. Blocks rely on debugging information being
4278 A frame has a block. Please see @ref{Frames In Python}, for a more
4279 in-depth discussion of frames.
4281 The outermost block is known as the @dfn{global block}. The global
4282 block typically holds public global variables and functions.
4284 The block nested just inside the global block is the @dfn{static
4285 block}. The static block typically holds file-scoped variables and
4288 @value{GDBN} provides a method to get a block's superblock, but there
4289 is currently no way to examine the sub-blocks of a block, or to
4290 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
4293 Here is a short example that should help explain blocks:
4296 /* This is in the global block. */
4299 /* This is in the static block. */
4300 static int file_scope;
4302 /* 'function' is in the global block, and 'argument' is
4303 in a block nested inside of 'function'. */
4304 int function (int argument)
4306 /* 'local' is in a block inside 'function'. It may or may
4307 not be in the same block as 'argument'. */
4311 /* 'inner' is in a block whose superblock is the one holding
4315 /* If this call is expanded by the compiler, you may see
4316 a nested block here whose function is 'inline_function'
4317 and whose superblock is the one holding 'inner'. */
4323 A @code{gdb.Block} is iterable. The iterator returns the symbols
4324 (@pxref{Symbols In Python}) local to the block. Python programs
4325 should not assume that a specific block object will always contain a
4326 given symbol, since changes in @value{GDBN} features and
4327 infrastructure may cause symbols move across blocks in a symbol
4330 The following block-related functions are available in the @code{gdb}
4333 @findex gdb.block_for_pc
4334 @defun gdb.block_for_pc (pc)
4335 Return the innermost @code{gdb.Block} containing the given @var{pc}
4336 value. If the block cannot be found for the @var{pc} value specified,
4337 the function will return @code{None}.
4340 A @code{gdb.Block} object has the following methods:
4342 @defun Block.is_valid ()
4343 Returns @code{True} if the @code{gdb.Block} object is valid,
4344 @code{False} if not. A block object can become invalid if the block it
4345 refers to doesn't exist anymore in the inferior. All other
4346 @code{gdb.Block} methods will throw an exception if it is invalid at
4347 the time the method is called. The block's validity is also checked
4348 during iteration over symbols of the block.
4351 A @code{gdb.Block} object has the following attributes:
4354 The start address of the block. This attribute is not writable.
4358 The end address of the block. This attribute is not writable.
4361 @defvar Block.function
4362 The name of the block represented as a @code{gdb.Symbol}. If the
4363 block is not named, then this attribute holds @code{None}. This
4364 attribute is not writable.
4366 For ordinary function blocks, the superblock is the static block.
4367 However, you should note that it is possible for a function block to
4368 have a superblock that is not the static block -- for instance this
4369 happens for an inlined function.
4372 @defvar Block.superblock
4373 The block containing this block. If this parent block does not exist,
4374 this attribute holds @code{None}. This attribute is not writable.
4377 @defvar Block.global_block
4378 The global block associated with this block. This attribute is not
4382 @defvar Block.static_block
4383 The static block associated with this block. This attribute is not
4387 @defvar Block.is_global
4388 @code{True} if the @code{gdb.Block} object is a global block,
4389 @code{False} if not. This attribute is not
4393 @defvar Block.is_static
4394 @code{True} if the @code{gdb.Block} object is a static block,
4395 @code{False} if not. This attribute is not writable.
4398 @node Symbols In Python
4399 @subsubsection Python representation of Symbols.
4401 @cindex symbols in python
4404 @value{GDBN} represents every variable, function and type as an
4405 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
4406 Similarly, Python represents these symbols in @value{GDBN} with the
4407 @code{gdb.Symbol} object.
4409 The following symbol-related functions are available in the @code{gdb}
4412 @findex gdb.lookup_symbol
4413 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
4414 This function searches for a symbol by name. The search scope can be
4415 restricted to the parameters defined in the optional domain and block
4418 @var{name} is the name of the symbol. It must be a string. The
4419 optional @var{block} argument restricts the search to symbols visible
4420 in that @var{block}. The @var{block} argument must be a
4421 @code{gdb.Block} object. If omitted, the block for the current frame
4422 is used. The optional @var{domain} argument restricts
4423 the search to the domain type. The @var{domain} argument must be a
4424 domain constant defined in the @code{gdb} module and described later
4427 The result is a tuple of two elements.
4428 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
4430 If the symbol is found, the second element is @code{True} if the symbol
4431 is a field of a method's object (e.g., @code{this} in C@t{++}),
4432 otherwise it is @code{False}.
4433 If the symbol is not found, the second element is @code{False}.
4436 @findex gdb.lookup_global_symbol
4437 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
4438 This function searches for a global symbol by name.
4439 The search scope can be restricted to by the domain argument.
4441 @var{name} is the name of the symbol. It must be a string.
4442 The optional @var{domain} argument restricts the search to the domain type.
4443 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4444 module and described later in this chapter.
4446 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4450 A @code{gdb.Symbol} object has the following attributes:
4453 The type of the symbol or @code{None} if no type is recorded.
4454 This attribute is represented as a @code{gdb.Type} object.
4455 @xref{Types In Python}. This attribute is not writable.
4458 @defvar Symbol.symtab
4459 The symbol table in which the symbol appears. This attribute is
4460 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
4461 Python}. This attribute is not writable.
4465 The line number in the source code at which the symbol was defined.
4470 The name of the symbol as a string. This attribute is not writable.
4473 @defvar Symbol.linkage_name
4474 The name of the symbol, as used by the linker (i.e., may be mangled).
4475 This attribute is not writable.
4478 @defvar Symbol.print_name
4479 The name of the symbol in a form suitable for output. This is either
4480 @code{name} or @code{linkage_name}, depending on whether the user
4481 asked @value{GDBN} to display demangled or mangled names.
4484 @defvar Symbol.addr_class
4485 The address class of the symbol. This classifies how to find the value
4486 of a symbol. Each address class is a constant defined in the
4487 @code{gdb} module and described later in this chapter.
4490 @defvar Symbol.needs_frame
4491 This is @code{True} if evaluating this symbol's value requires a frame
4492 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
4493 local variables will require a frame, but other symbols will not.
4496 @defvar Symbol.is_argument
4497 @code{True} if the symbol is an argument of a function.
4500 @defvar Symbol.is_constant
4501 @code{True} if the symbol is a constant.
4504 @defvar Symbol.is_function
4505 @code{True} if the symbol is a function or a method.
4508 @defvar Symbol.is_variable
4509 @code{True} if the symbol is a variable.
4512 A @code{gdb.Symbol} object has the following methods:
4514 @defun Symbol.is_valid ()
4515 Returns @code{True} if the @code{gdb.Symbol} object is valid,
4516 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
4517 the symbol it refers to does not exist in @value{GDBN} any longer.
4518 All other @code{gdb.Symbol} methods will throw an exception if it is
4519 invalid at the time the method is called.
4522 @defun Symbol.value (@r{[}frame@r{]})
4523 Compute the value of the symbol, as a @code{gdb.Value}. For
4524 functions, this computes the address of the function, cast to the
4525 appropriate type. If the symbol requires a frame in order to compute
4526 its value, then @var{frame} must be given. If @var{frame} is not
4527 given, or if @var{frame} is invalid, then this method will throw an
4531 The available domain categories in @code{gdb.Symbol} are represented
4532 as constants in the @code{gdb} module:
4535 @vindex SYMBOL_UNDEF_DOMAIN
4536 @item gdb.SYMBOL_UNDEF_DOMAIN
4537 This is used when a domain has not been discovered or none of the
4538 following domains apply. This usually indicates an error either
4539 in the symbol information or in @value{GDBN}'s handling of symbols.
4541 @vindex SYMBOL_VAR_DOMAIN
4542 @item gdb.SYMBOL_VAR_DOMAIN
4543 This domain contains variables, function names, typedef names and enum
4546 @vindex SYMBOL_STRUCT_DOMAIN
4547 @item gdb.SYMBOL_STRUCT_DOMAIN
4548 This domain holds struct, union and enum type names.
4550 @vindex SYMBOL_LABEL_DOMAIN
4551 @item gdb.SYMBOL_LABEL_DOMAIN
4552 This domain contains names of labels (for gotos).
4554 @vindex SYMBOL_VARIABLES_DOMAIN
4555 @item gdb.SYMBOL_VARIABLES_DOMAIN
4556 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
4557 contains everything minus functions and types.
4559 @vindex SYMBOL_FUNCTIONS_DOMAIN
4560 @item gdb.SYMBOL_FUNCTION_DOMAIN
4561 This domain contains all functions.
4563 @vindex SYMBOL_TYPES_DOMAIN
4564 @item gdb.SYMBOL_TYPES_DOMAIN
4565 This domain contains all types.
4568 The available address class categories in @code{gdb.Symbol} are represented
4569 as constants in the @code{gdb} module:
4572 @vindex SYMBOL_LOC_UNDEF
4573 @item gdb.SYMBOL_LOC_UNDEF
4574 If this is returned by address class, it indicates an error either in
4575 the symbol information or in @value{GDBN}'s handling of symbols.
4577 @vindex SYMBOL_LOC_CONST
4578 @item gdb.SYMBOL_LOC_CONST
4579 Value is constant int.
4581 @vindex SYMBOL_LOC_STATIC
4582 @item gdb.SYMBOL_LOC_STATIC
4583 Value is at a fixed address.
4585 @vindex SYMBOL_LOC_REGISTER
4586 @item gdb.SYMBOL_LOC_REGISTER
4587 Value is in a register.
4589 @vindex SYMBOL_LOC_ARG
4590 @item gdb.SYMBOL_LOC_ARG
4591 Value is an argument. This value is at the offset stored within the
4592 symbol inside the frame's argument list.
4594 @vindex SYMBOL_LOC_REF_ARG
4595 @item gdb.SYMBOL_LOC_REF_ARG
4596 Value address is stored in the frame's argument list. Just like
4597 @code{LOC_ARG} except that the value's address is stored at the
4598 offset, not the value itself.
4600 @vindex SYMBOL_LOC_REGPARM_ADDR
4601 @item gdb.SYMBOL_LOC_REGPARM_ADDR
4602 Value is a specified register. Just like @code{LOC_REGISTER} except
4603 the register holds the address of the argument instead of the argument
4606 @vindex SYMBOL_LOC_LOCAL
4607 @item gdb.SYMBOL_LOC_LOCAL
4608 Value is a local variable.
4610 @vindex SYMBOL_LOC_TYPEDEF
4611 @item gdb.SYMBOL_LOC_TYPEDEF
4612 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
4615 @vindex SYMBOL_LOC_BLOCK
4616 @item gdb.SYMBOL_LOC_BLOCK
4619 @vindex SYMBOL_LOC_CONST_BYTES
4620 @item gdb.SYMBOL_LOC_CONST_BYTES
4621 Value is a byte-sequence.
4623 @vindex SYMBOL_LOC_UNRESOLVED
4624 @item gdb.SYMBOL_LOC_UNRESOLVED
4625 Value is at a fixed address, but the address of the variable has to be
4626 determined from the minimal symbol table whenever the variable is
4629 @vindex SYMBOL_LOC_OPTIMIZED_OUT
4630 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
4631 The value does not actually exist in the program.
4633 @vindex SYMBOL_LOC_COMPUTED
4634 @item gdb.SYMBOL_LOC_COMPUTED
4635 The value's address is a computed location.
4638 @node Symbol Tables In Python
4639 @subsubsection Symbol table representation in Python.
4641 @cindex symbol tables in python
4643 @tindex gdb.Symtab_and_line
4645 Access to symbol table data maintained by @value{GDBN} on the inferior
4646 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
4647 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
4648 from the @code{find_sal} method in @code{gdb.Frame} object.
4649 @xref{Frames In Python}.
4651 For more information on @value{GDBN}'s symbol table management, see
4652 @ref{Symbols, ,Examining the Symbol Table}, for more information.
4654 A @code{gdb.Symtab_and_line} object has the following attributes:
4656 @defvar Symtab_and_line.symtab
4657 The symbol table object (@code{gdb.Symtab}) for this frame.
4658 This attribute is not writable.
4661 @defvar Symtab_and_line.pc
4662 Indicates the start of the address range occupied by code for the
4663 current source line. This attribute is not writable.
4666 @defvar Symtab_and_line.last
4667 Indicates the end of the address range occupied by code for the current
4668 source line. This attribute is not writable.
4671 @defvar Symtab_and_line.line
4672 Indicates the current line number for this object. This
4673 attribute is not writable.
4676 A @code{gdb.Symtab_and_line} object has the following methods:
4678 @defun Symtab_and_line.is_valid ()
4679 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
4680 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
4681 invalid if the Symbol table and line object it refers to does not
4682 exist in @value{GDBN} any longer. All other
4683 @code{gdb.Symtab_and_line} methods will throw an exception if it is
4684 invalid at the time the method is called.
4687 A @code{gdb.Symtab} object has the following attributes:
4689 @defvar Symtab.filename
4690 The symbol table's source filename. This attribute is not writable.
4693 @defvar Symtab.objfile
4694 The symbol table's backing object file. @xref{Objfiles In Python}.
4695 This attribute is not writable.
4698 @defvar Symtab.producer
4699 The name and possibly version number of the program that
4700 compiled the code in the symbol table.
4701 The contents of this string is up to the compiler.
4702 If no producer information is available then @code{None} is returned.
4703 This attribute is not writable.
4706 A @code{gdb.Symtab} object has the following methods:
4708 @defun Symtab.is_valid ()
4709 Returns @code{True} if the @code{gdb.Symtab} object is valid,
4710 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
4711 the symbol table it refers to does not exist in @value{GDBN} any
4712 longer. All other @code{gdb.Symtab} methods will throw an exception
4713 if it is invalid at the time the method is called.
4716 @defun Symtab.fullname ()
4717 Return the symbol table's source absolute file name.
4720 @defun Symtab.global_block ()
4721 Return the global block of the underlying symbol table.
4722 @xref{Blocks In Python}.
4725 @defun Symtab.static_block ()
4726 Return the static block of the underlying symbol table.
4727 @xref{Blocks In Python}.
4730 @defun Symtab.linetable ()
4731 Return the line table associated with the symbol table.
4732 @xref{Line Tables In Python}.
4735 @node Line Tables In Python
4736 @subsubsection Manipulating line tables using Python
4738 @cindex line tables in python
4739 @tindex gdb.LineTable
4741 Python code can request and inspect line table information from a
4742 symbol table that is loaded in @value{GDBN}. A line table is a
4743 mapping of source lines to their executable locations in memory. To
4744 acquire the line table information for a particular symbol table, use
4745 the @code{linetable} function (@pxref{Symbol Tables In Python}).
4747 A @code{gdb.LineTable} is iterable. The iterator returns
4748 @code{LineTableEntry} objects that correspond to the source line and
4749 address for each line table entry. @code{LineTableEntry} objects have
4750 the following attributes:
4752 @defvar LineTableEntry.line
4753 The source line number for this line table entry. This number
4754 corresponds to the actual line of source. This attribute is not
4758 @defvar LineTableEntry.pc
4759 The address that is associated with the line table entry where the
4760 executable code for that source line resides in memory. This
4761 attribute is not writable.
4764 As there can be multiple addresses for a single source line, you may
4765 receive multiple @code{LineTableEntry} objects with matching
4766 @code{line} attributes, but with different @code{pc} attributes. The
4767 iterator is sorted in ascending @code{pc} order. Here is a small
4768 example illustrating iterating over a line table.
4771 symtab = gdb.selected_frame().find_sal().symtab
4772 linetable = symtab.linetable()
4773 for line in linetable:
4774 print "Line: "+str(line.line)+" Address: "+hex(line.pc)
4777 This will have the following output:
4780 Line: 33 Address: 0x4005c8L
4781 Line: 37 Address: 0x4005caL
4782 Line: 39 Address: 0x4005d2L
4783 Line: 40 Address: 0x4005f8L
4784 Line: 42 Address: 0x4005ffL
4785 Line: 44 Address: 0x400608L
4786 Line: 42 Address: 0x40060cL
4787 Line: 45 Address: 0x400615L
4790 In addition to being able to iterate over a @code{LineTable}, it also
4791 has the following direct access methods:
4793 @defun LineTable.line (line)
4794 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
4795 entries in the line table for the given @var{line}, which specifies
4796 the source code line. If there are no entries for that source code
4797 @var{line}, the Python @code{None} is returned.
4800 @defun LineTable.has_line (line)
4801 Return a Python @code{Boolean} indicating whether there is an entry in
4802 the line table for this source line. Return @code{True} if an entry
4803 is found, or @code{False} if not.
4806 @defun LineTable.source_lines ()
4807 Return a Python @code{List} of the source line numbers in the symbol
4808 table. Only lines with executable code locations are returned. The
4809 contents of the @code{List} will just be the source line entries
4810 represented as Python @code{Long} values.
4813 @node Breakpoints In Python
4814 @subsubsection Manipulating breakpoints using Python
4816 @cindex breakpoints in python
4817 @tindex gdb.Breakpoint
4819 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
4822 @defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
4823 Create a new breakpoint according to @var{spec}, which is a string
4824 naming the location of the breakpoint, or an expression that defines a
4825 watchpoint. The contents can be any location recognized by the
4826 @code{break} command, or in the case of a watchpoint, by the
4827 @code{watch} command. The optional @var{type} denotes the breakpoint
4828 to create from the types defined later in this chapter. This argument
4829 can be either @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}; it
4830 defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
4831 argument allows the breakpoint to become invisible to the user. The
4832 breakpoint will neither be reported when created, nor will it be
4833 listed in the output from @code{info breakpoints} (but will be listed
4834 with the @code{maint info breakpoints} command). The optional
4835 @var{temporary} argument makes the breakpoint a temporary breakpoint.
4836 Temporary breakpoints are deleted after they have been hit. Any
4837 further access to the Python breakpoint after it has been hit will
4838 result in a runtime error (as that breakpoint has now been
4839 automatically deleted). The optional @var{wp_class} argument defines
4840 the class of watchpoint to create, if @var{type} is
4841 @code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it
4842 is assumed to be a @code{gdb.WP_WRITE} class.
4845 The available types are represented by constants defined in the @code{gdb}
4849 @vindex BP_BREAKPOINT
4850 @item gdb.BP_BREAKPOINT
4851 Normal code breakpoint.
4853 @vindex BP_WATCHPOINT
4854 @item gdb.BP_WATCHPOINT
4855 Watchpoint breakpoint.
4857 @vindex BP_HARDWARE_WATCHPOINT
4858 @item gdb.BP_HARDWARE_WATCHPOINT
4859 Hardware assisted watchpoint.
4861 @vindex BP_READ_WATCHPOINT
4862 @item gdb.BP_READ_WATCHPOINT
4863 Hardware assisted read watchpoint.
4865 @vindex BP_ACCESS_WATCHPOINT
4866 @item gdb.BP_ACCESS_WATCHPOINT
4867 Hardware assisted access watchpoint.
4870 The available watchpoint types represented by constants are defined in the
4876 Read only watchpoint.
4880 Write only watchpoint.
4884 Read/Write watchpoint.
4887 @defun Breakpoint.stop (self)
4888 The @code{gdb.Breakpoint} class can be sub-classed and, in
4889 particular, you may choose to implement the @code{stop} method.
4890 If this method is defined in a sub-class of @code{gdb.Breakpoint},
4891 it will be called when the inferior reaches any location of a
4892 breakpoint which instantiates that sub-class. If the method returns
4893 @code{True}, the inferior will be stopped at the location of the
4894 breakpoint, otherwise the inferior will continue.
4896 If there are multiple breakpoints at the same location with a
4897 @code{stop} method, each one will be called regardless of the
4898 return status of the previous. This ensures that all @code{stop}
4899 methods have a chance to execute at that location. In this scenario
4900 if one of the methods returns @code{True} but the others return
4901 @code{False}, the inferior will still be stopped.
4903 You should not alter the execution state of the inferior (i.e.@:, step,
4904 next, etc.), alter the current frame context (i.e.@:, change the current
4905 active frame), or alter, add or delete any breakpoint. As a general
4906 rule, you should not alter any data within @value{GDBN} or the inferior
4909 Example @code{stop} implementation:
4912 class MyBreakpoint (gdb.Breakpoint):
4914 inf_val = gdb.parse_and_eval("foo")
4921 @defun Breakpoint.is_valid ()
4922 Return @code{True} if this @code{Breakpoint} object is valid,
4923 @code{False} otherwise. A @code{Breakpoint} object can become invalid
4924 if the user deletes the breakpoint. In this case, the object still
4925 exists, but the underlying breakpoint does not. In the cases of
4926 watchpoint scope, the watchpoint remains valid even if execution of the
4927 inferior leaves the scope of that watchpoint.
4930 @defun Breakpoint.delete ()
4931 Permanently deletes the @value{GDBN} breakpoint. This also
4932 invalidates the Python @code{Breakpoint} object. Any further access
4933 to this object's attributes or methods will raise an error.
4936 @defvar Breakpoint.enabled
4937 This attribute is @code{True} if the breakpoint is enabled, and
4938 @code{False} otherwise. This attribute is writable. You can use it to enable
4939 or disable the breakpoint.
4942 @defvar Breakpoint.silent
4943 This attribute is @code{True} if the breakpoint is silent, and
4944 @code{False} otherwise. This attribute is writable.
4946 Note that a breakpoint can also be silent if it has commands and the
4947 first command is @code{silent}. This is not reported by the
4948 @code{silent} attribute.
4951 @defvar Breakpoint.pending
4952 This attribute is @code{True} if the breakpoint is pending, and
4953 @code{False} otherwise. @xref{Set Breaks}. This attribute is
4957 @anchor{python_breakpoint_thread}
4958 @defvar Breakpoint.thread
4959 If the breakpoint is thread-specific, this attribute holds the
4960 thread's global id. If the breakpoint is not thread-specific, this
4961 attribute is @code{None}. This attribute is writable.
4964 @defvar Breakpoint.task
4965 If the breakpoint is Ada task-specific, this attribute holds the Ada task
4966 id. If the breakpoint is not task-specific (or the underlying
4967 language is not Ada), this attribute is @code{None}. This attribute
4971 @defvar Breakpoint.ignore_count
4972 This attribute holds the ignore count for the breakpoint, an integer.
4973 This attribute is writable.
4976 @defvar Breakpoint.number
4977 This attribute holds the breakpoint's number --- the identifier used by
4978 the user to manipulate the breakpoint. This attribute is not writable.
4981 @defvar Breakpoint.type
4982 This attribute holds the breakpoint's type --- the identifier used to
4983 determine the actual breakpoint type or use-case. This attribute is not
4987 @defvar Breakpoint.visible
4988 This attribute tells whether the breakpoint is visible to the user
4989 when set, or when the @samp{info breakpoints} command is run. This
4990 attribute is not writable.
4993 @defvar Breakpoint.temporary
4994 This attribute indicates whether the breakpoint was created as a
4995 temporary breakpoint. Temporary breakpoints are automatically deleted
4996 after that breakpoint has been hit. Access to this attribute, and all
4997 other attributes and functions other than the @code{is_valid}
4998 function, will result in an error after the breakpoint has been hit
4999 (as it has been automatically deleted). This attribute is not
5003 @defvar Breakpoint.hit_count
5004 This attribute holds the hit count for the breakpoint, an integer.
5005 This attribute is writable, but currently it can only be set to zero.
5008 @defvar Breakpoint.location
5009 This attribute holds the location of the breakpoint, as specified by
5010 the user. It is a string. If the breakpoint does not have a location
5011 (that is, it is a watchpoint) the attribute's value is @code{None}. This
5012 attribute is not writable.
5015 @defvar Breakpoint.expression
5016 This attribute holds a breakpoint expression, as specified by
5017 the user. It is a string. If the breakpoint does not have an
5018 expression (the breakpoint is not a watchpoint) the attribute's value
5019 is @code{None}. This attribute is not writable.
5022 @defvar Breakpoint.condition
5023 This attribute holds the condition of the breakpoint, as specified by
5024 the user. It is a string. If there is no condition, this attribute's
5025 value is @code{None}. This attribute is writable.
5028 @defvar Breakpoint.commands
5029 This attribute holds the commands attached to the breakpoint. If
5030 there are commands, this attribute's value is a string holding all the
5031 commands, separated by newlines. If there are no commands, this
5032 attribute is @code{None}. This attribute is not writable.
5035 @node Finish Breakpoints in Python
5036 @subsubsection Finish Breakpoints
5038 @cindex python finish breakpoints
5039 @tindex gdb.FinishBreakpoint
5041 A finish breakpoint is a temporary breakpoint set at the return address of
5042 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
5043 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
5044 and deleted when the execution will run out of the breakpoint scope (i.e.@:
5045 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
5046 Finish breakpoints are thread specific and must be create with the right
5049 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
5050 Create a finish breakpoint at the return address of the @code{gdb.Frame}
5051 object @var{frame}. If @var{frame} is not provided, this defaults to the
5052 newest frame. The optional @var{internal} argument allows the breakpoint to
5053 become invisible to the user. @xref{Breakpoints In Python}, for further
5054 details about this argument.
5057 @defun FinishBreakpoint.out_of_scope (self)
5058 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
5059 @code{return} command, @dots{}), a function may not properly terminate, and
5060 thus never hit the finish breakpoint. When @value{GDBN} notices such a
5061 situation, the @code{out_of_scope} callback will be triggered.
5063 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
5067 class MyFinishBreakpoint (gdb.FinishBreakpoint)
5069 print "normal finish"
5072 def out_of_scope ():
5073 print "abnormal finish"
5077 @defvar FinishBreakpoint.return_value
5078 When @value{GDBN} is stopped at a finish breakpoint and the frame
5079 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
5080 attribute will contain a @code{gdb.Value} object corresponding to the return
5081 value of the function. The value will be @code{None} if the function return
5082 type is @code{void} or if the return value was not computable. This attribute
5086 @node Lazy Strings In Python
5087 @subsubsection Python representation of lazy strings.
5089 @cindex lazy strings in python
5090 @tindex gdb.LazyString
5092 A @dfn{lazy string} is a string whose contents is not retrieved or
5093 encoded until it is needed.
5095 A @code{gdb.LazyString} is represented in @value{GDBN} as an
5096 @code{address} that points to a region of memory, an @code{encoding}
5097 that will be used to encode that region of memory, and a @code{length}
5098 to delimit the region of memory that represents the string. The
5099 difference between a @code{gdb.LazyString} and a string wrapped within
5100 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
5101 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
5102 retrieved and encoded during printing, while a @code{gdb.Value}
5103 wrapping a string is immediately retrieved and encoded on creation.
5105 A @code{gdb.LazyString} object has the following functions:
5107 @defun LazyString.value ()
5108 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
5109 will point to the string in memory, but will lose all the delayed
5110 retrieval, encoding and handling that @value{GDBN} applies to a
5111 @code{gdb.LazyString}.
5114 @defvar LazyString.address
5115 This attribute holds the address of the string. This attribute is not
5119 @defvar LazyString.length
5120 This attribute holds the length of the string in characters. If the
5121 length is -1, then the string will be fetched and encoded up to the
5122 first null of appropriate width. This attribute is not writable.
5125 @defvar LazyString.encoding
5126 This attribute holds the encoding that will be applied to the string
5127 when the string is printed by @value{GDBN}. If the encoding is not
5128 set, or contains an empty string, then @value{GDBN} will select the
5129 most appropriate encoding when the string is printed. This attribute
5133 @defvar LazyString.type
5134 This attribute holds the type that is represented by the lazy string's
5135 type. For a lazy string this is a pointer or array type. To
5136 resolve this to the lazy string's character type, use the type's
5137 @code{target} method. @xref{Types In Python}. This attribute is not
5141 @node Architectures In Python
5142 @subsubsection Python representation of architectures
5143 @cindex Python architectures
5145 @value{GDBN} uses architecture specific parameters and artifacts in a
5146 number of its various computations. An architecture is represented
5147 by an instance of the @code{gdb.Architecture} class.
5149 A @code{gdb.Architecture} class has the following methods:
5151 @defun Architecture.name ()
5152 Return the name (string value) of the architecture.
5155 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
5156 Return a list of disassembled instructions starting from the memory
5157 address @var{start_pc}. The optional arguments @var{end_pc} and
5158 @var{count} determine the number of instructions in the returned list.
5159 If both the optional arguments @var{end_pc} and @var{count} are
5160 specified, then a list of at most @var{count} disassembled instructions
5161 whose start address falls in the closed memory address interval from
5162 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
5163 specified, but @var{count} is specified, then @var{count} number of
5164 instructions starting from the address @var{start_pc} are returned. If
5165 @var{count} is not specified but @var{end_pc} is specified, then all
5166 instructions whose start address falls in the closed memory address
5167 interval from @var{start_pc} to @var{end_pc} are returned. If neither
5168 @var{end_pc} nor @var{count} are specified, then a single instruction at
5169 @var{start_pc} is returned. For all of these cases, each element of the
5170 returned list is a Python @code{dict} with the following string keys:
5175 The value corresponding to this key is a Python long integer capturing
5176 the memory address of the instruction.
5179 The value corresponding to this key is a string value which represents
5180 the instruction with assembly language mnemonics. The assembly
5181 language flavor used is the same as that specified by the current CLI
5182 variable @code{disassembly-flavor}. @xref{Machine Code}.
5185 The value corresponding to this key is the length (integer value) of the
5186 instruction in bytes.
5191 @node Python Auto-loading
5192 @subsection Python Auto-loading
5193 @cindex Python auto-loading
5195 When a new object file is read (for example, due to the @code{file}
5196 command, or because the inferior has loaded a shared library),
5197 @value{GDBN} will look for Python support scripts in several ways:
5198 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
5199 @xref{Auto-loading extensions}.
5201 The auto-loading feature is useful for supplying application-specific
5202 debugging commands and scripts.
5204 Auto-loading can be enabled or disabled,
5205 and the list of auto-loaded scripts can be printed.
5208 @anchor{set auto-load python-scripts}
5209 @kindex set auto-load python-scripts
5210 @item set auto-load python-scripts [on|off]
5211 Enable or disable the auto-loading of Python scripts.
5213 @anchor{show auto-load python-scripts}
5214 @kindex show auto-load python-scripts
5215 @item show auto-load python-scripts
5216 Show whether auto-loading of Python scripts is enabled or disabled.
5218 @anchor{info auto-load python-scripts}
5219 @kindex info auto-load python-scripts
5220 @cindex print list of auto-loaded Python scripts
5221 @item info auto-load python-scripts [@var{regexp}]
5222 Print the list of all Python scripts that @value{GDBN} auto-loaded.
5224 Also printed is the list of Python scripts that were mentioned in
5225 the @code{.debug_gdb_scripts} section and were either not found
5226 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
5227 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
5228 This is useful because their names are not printed when @value{GDBN}
5229 tries to load them and fails. There may be many of them, and printing
5230 an error message for each one is problematic.
5232 If @var{regexp} is supplied only Python scripts with matching names are printed.
5237 (gdb) info auto-load python-scripts
5239 Yes py-section-script.py
5240 full name: /tmp/py-section-script.py
5241 No my-foo-pretty-printers.py
5245 When reading an auto-loaded file or script, @value{GDBN} sets the
5246 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
5247 function (@pxref{Objfiles In Python}). This can be useful for
5248 registering objfile-specific pretty-printers and frame-filters.
5250 @node Python modules
5251 @subsection Python modules
5252 @cindex python modules
5254 @value{GDBN} comes with several modules to assist writing Python code.
5257 * gdb.printing:: Building and registering pretty-printers.
5258 * gdb.types:: Utilities for working with types.
5259 * gdb.prompt:: Utilities for prompt value substitution.
5263 @subsubsection gdb.printing
5264 @cindex gdb.printing
5266 This module provides a collection of utilities for working with
5270 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
5271 This class specifies the API that makes @samp{info pretty-printer},
5272 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
5273 Pretty-printers should generally inherit from this class.
5275 @item SubPrettyPrinter (@var{name})
5276 For printers that handle multiple types, this class specifies the
5277 corresponding API for the subprinters.
5279 @item RegexpCollectionPrettyPrinter (@var{name})
5280 Utility class for handling multiple printers, all recognized via
5281 regular expressions.
5282 @xref{Writing a Pretty-Printer}, for an example.
5284 @item FlagEnumerationPrinter (@var{name})
5285 A pretty-printer which handles printing of @code{enum} values. Unlike
5286 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
5287 work properly when there is some overlap between the enumeration
5288 constants. The argument @var{name} is the name of the printer and
5289 also the name of the @code{enum} type to look up.
5291 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
5292 Register @var{printer} with the pretty-printer list of @var{obj}.
5293 If @var{replace} is @code{True} then any existing copy of the printer
5294 is replaced. Otherwise a @code{RuntimeError} exception is raised
5295 if a printer with the same name already exists.
5299 @subsubsection gdb.types
5302 This module provides a collection of utilities for working with
5303 @code{gdb.Type} objects.
5306 @item get_basic_type (@var{type})
5307 Return @var{type} with const and volatile qualifiers stripped,
5308 and with typedefs and C@t{++} references converted to the underlying type.
5313 typedef const int const_int;
5315 const_int& foo_ref (foo);
5316 int main () @{ return 0; @}
5323 (gdb) python import gdb.types
5324 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
5325 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
5329 @item has_field (@var{type}, @var{field})
5330 Return @code{True} if @var{type}, assumed to be a type with fields
5331 (e.g., a structure or union), has field @var{field}.
5333 @item make_enum_dict (@var{enum_type})
5334 Return a Python @code{dictionary} type produced from @var{enum_type}.
5336 @item deep_items (@var{type})
5337 Returns a Python iterator similar to the standard
5338 @code{gdb.Type.iteritems} method, except that the iterator returned
5339 by @code{deep_items} will recursively traverse anonymous struct or
5340 union fields. For example:
5354 Then in @value{GDBN}:
5356 (@value{GDBP}) python import gdb.types
5357 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
5358 (@value{GDBP}) python print struct_a.keys ()
5360 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
5361 @{['a', 'b0', 'b1']@}
5364 @item get_type_recognizers ()
5365 Return a list of the enabled type recognizers for the current context.
5366 This is called by @value{GDBN} during the type-printing process
5367 (@pxref{Type Printing API}).
5369 @item apply_type_recognizers (recognizers, type_obj)
5370 Apply the type recognizers, @var{recognizers}, to the type object
5371 @var{type_obj}. If any recognizer returns a string, return that
5372 string. Otherwise, return @code{None}. This is called by
5373 @value{GDBN} during the type-printing process (@pxref{Type Printing
5376 @item register_type_printer (locus, printer)
5377 This is a convenience function to register a type printer
5378 @var{printer}. The printer must implement the type printer protocol.
5379 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
5380 the printer is registered with that objfile; a @code{gdb.Progspace},
5381 in which case the printer is registered with that progspace; or
5382 @code{None}, in which case the printer is registered globally.
5385 This is a base class that implements the type printer protocol. Type
5386 printers are encouraged, but not required, to derive from this class.
5387 It defines a constructor:
5389 @defmethod TypePrinter __init__ (self, name)
5390 Initialize the type printer with the given name. The new printer
5391 starts in the enabled state.
5397 @subsubsection gdb.prompt
5400 This module provides a method for prompt value-substitution.
5403 @item substitute_prompt (@var{string})
5404 Return @var{string} with escape sequences substituted by values. Some
5405 escape sequences take arguments. You can specify arguments inside
5406 ``@{@}'' immediately following the escape sequence.
5408 The escape sequences you can pass to this function are:
5412 Substitute a backslash.
5414 Substitute an ESC character.
5416 Substitute the selected frame; an argument names a frame parameter.
5418 Substitute a newline.
5420 Substitute a parameter's value; the argument names the parameter.
5422 Substitute a carriage return.
5424 Substitute the selected thread; an argument names a thread parameter.
5426 Substitute the version of GDB.
5428 Substitute the current working directory.
5430 Begin a sequence of non-printing characters. These sequences are
5431 typically used with the ESC character, and are not counted in the string
5432 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
5433 blue-colored ``(gdb)'' prompt where the length is five.
5435 End a sequence of non-printing characters.
5441 substitute_prompt (``frame: \f,
5442 print arguments: \p@{print frame-arguments@}'')
5445 @exdent will return the string:
5448 "frame: main, print arguments: scalars"