1 @c Copyright (C) 2008-2016 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 * Commands In Python:: Implementing new commands in Python.
155 * Parameters In Python:: Adding new @value{GDBN} parameters.
156 * Functions In Python:: Writing new convenience functions.
157 * Progspaces In Python:: Program spaces.
158 * Objfiles In Python:: Object files.
159 * Frames In Python:: Accessing inferior stack frames from Python.
160 * Blocks In Python:: Accessing blocks from Python.
161 * Symbols In Python:: Python representation of symbols.
162 * Symbol Tables In Python:: Python representation of symbol tables.
163 * Line Tables In Python:: Python representation of line tables.
164 * Breakpoints In Python:: Manipulating breakpoints using Python.
165 * Finish Breakpoints in Python:: Setting Breakpoints on function return
167 * Lazy Strings In Python:: Python representation of lazy strings.
168 * Architectures In Python:: Python representation of architectures.
172 @subsubsection Basic Python
174 @cindex python stdout
175 @cindex python pagination
176 At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
177 @code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
178 A Python program which outputs to one of these streams may have its
179 output interrupted by the user (@pxref{Screen Size}). In this
180 situation, a Python @code{KeyboardInterrupt} exception is thrown.
182 Some care must be taken when writing Python code to run in
183 @value{GDBN}. Two things worth noting in particular:
187 @value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
188 Python code must not override these, or even change the options using
189 @code{sigaction}. If your program changes the handling of these
190 signals, @value{GDBN} will most likely stop working correctly. Note
191 that it is unfortunately common for GUI toolkits to install a
192 @code{SIGCHLD} handler.
195 @value{GDBN} takes care to mark its internal file descriptors as
196 close-on-exec. However, this cannot be done in a thread-safe way on
197 all platforms. Your Python programs should be aware of this and
198 should both create new file descriptors with the close-on-exec flag
199 set and arrange to close unneeded file descriptors before starting a
203 @cindex python functions
204 @cindex python module
206 @value{GDBN} introduces a new Python module, named @code{gdb}. All
207 methods and classes added by @value{GDBN} are placed in this module.
208 @value{GDBN} automatically @code{import}s the @code{gdb} module for
209 use in all scripts evaluated by the @code{python} command.
211 @findex gdb.PYTHONDIR
212 @defvar gdb.PYTHONDIR
213 A string containing the python directory (@pxref{Python}).
217 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
218 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
219 If a GDB exception happens while @var{command} runs, it is
220 translated as described in @ref{Exception Handling,,Exception Handling}.
222 The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
223 command as having originated from the user invoking it interactively.
224 It must be a boolean value. If omitted, it defaults to @code{False}.
226 By default, any output produced by @var{command} is sent to
227 @value{GDBN}'s standard output (and to the log output if logging is
228 turned on). If the @var{to_string} parameter is
229 @code{True}, then output will be collected by @code{gdb.execute} and
230 returned as a string. The default is @code{False}, in which case the
231 return value is @code{None}. If @var{to_string} is @code{True}, the
232 @value{GDBN} virtual terminal will be temporarily set to unlimited width
233 and height, and its pagination will be disabled; @pxref{Screen Size}.
236 @findex gdb.breakpoints
237 @defun gdb.breakpoints ()
238 Return a sequence holding all of @value{GDBN}'s breakpoints.
239 @xref{Breakpoints In Python}, for more information. In @value{GDBN}
240 version 7.11 and earlier, this function returned @code{None} if there
241 were no breakpoints. This peculiarity was subsequently fixed, and now
242 @code{gdb.breakpoints} returns an empty sequence in this case.
245 @findex gdb.parameter
246 @defun gdb.parameter (parameter)
247 Return the value of a @value{GDBN} @var{parameter} given by its name,
248 a string; the parameter name string may contain spaces if the parameter has a
249 multi-part name. For example, @samp{print object} is a valid
252 If the named parameter does not exist, this function throws a
253 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
254 parameter's value is converted to a Python value of the appropriate
259 @defun gdb.history (number)
260 Return a value from @value{GDBN}'s value history (@pxref{Value
261 History}). The @var{number} argument indicates which history element to return.
262 If @var{number} is negative, then @value{GDBN} will take its absolute value
263 and count backward from the last element (i.e., the most recent element) to
264 find the value to return. If @var{number} is zero, then @value{GDBN} will
265 return the most recent element. If the element specified by @var{number}
266 doesn't exist in the value history, a @code{gdb.error} exception will be
269 If no exception is raised, the return value is always an instance of
270 @code{gdb.Value} (@pxref{Values From Inferior}).
273 @findex gdb.parse_and_eval
274 @defun gdb.parse_and_eval (expression)
275 Parse @var{expression}, which must be a string, as an expression in
276 the current language, evaluate it, and return the result as a
279 This function can be useful when implementing a new command
280 (@pxref{Commands In Python}), as it provides a way to parse the
281 command's argument as an expression. It is also useful simply to
282 compute values, for example, it is the only way to get the value of a
283 convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
286 @findex gdb.find_pc_line
287 @defun gdb.find_pc_line (pc)
288 Return the @code{gdb.Symtab_and_line} object corresponding to the
289 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
290 value of @var{pc} is passed as an argument, then the @code{symtab} and
291 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
292 will be @code{None} and 0 respectively.
295 @findex gdb.post_event
296 @defun gdb.post_event (event)
297 Put @var{event}, a callable object taking no arguments, into
298 @value{GDBN}'s internal event queue. This callable will be invoked at
299 some later point, during @value{GDBN}'s event processing. Events
300 posted using @code{post_event} will be run in the order in which they
301 were posted; however, there is no way to know when they will be
302 processed relative to other events inside @value{GDBN}.
304 @value{GDBN} is not thread-safe. If your Python program uses multiple
305 threads, you must be careful to only call @value{GDBN}-specific
306 functions in the @value{GDBN} thread. @code{post_event} ensures
310 (@value{GDBP}) python
314 > def __init__(self, message):
315 > self.message = message;
316 > def __call__(self):
317 > gdb.write(self.message)
319 >class MyThread1 (threading.Thread):
321 > gdb.post_event(Writer("Hello "))
323 >class MyThread2 (threading.Thread):
325 > gdb.post_event(Writer("World\n"))
330 (@value{GDBP}) Hello World
335 @defun gdb.write (string @r{[}, stream{]})
336 Print a string to @value{GDBN}'s paginated output stream. The
337 optional @var{stream} determines the stream to print to. The default
338 stream is @value{GDBN}'s standard output stream. Possible stream
345 @value{GDBN}'s standard output stream.
350 @value{GDBN}'s standard error stream.
355 @value{GDBN}'s log stream (@pxref{Logging Output}).
358 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
359 call this function and will automatically direct the output to the
365 Flush the buffer of a @value{GDBN} paginated stream so that the
366 contents are displayed immediately. @value{GDBN} will flush the
367 contents of a stream automatically when it encounters a newline in the
368 buffer. The optional @var{stream} determines the stream to flush. The
369 default stream is @value{GDBN}'s standard output stream. Possible
376 @value{GDBN}'s standard output stream.
381 @value{GDBN}'s standard error stream.
386 @value{GDBN}'s log stream (@pxref{Logging Output}).
390 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
391 call this function for the relevant stream.
394 @findex gdb.target_charset
395 @defun gdb.target_charset ()
396 Return the name of the current target character set (@pxref{Character
397 Sets}). This differs from @code{gdb.parameter('target-charset')} in
398 that @samp{auto} is never returned.
401 @findex gdb.target_wide_charset
402 @defun gdb.target_wide_charset ()
403 Return the name of the current target wide character set
404 (@pxref{Character Sets}). This differs from
405 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
409 @findex gdb.solib_name
410 @defun gdb.solib_name (address)
411 Return the name of the shared library holding the given @var{address}
412 as a string, or @code{None}.
415 @findex gdb.decode_line
416 @defun gdb.decode_line @r{[}expression@r{]}
417 Return locations of the line specified by @var{expression}, or of the
418 current line if no argument was given. This function returns a Python
419 tuple containing two elements. The first element contains a string
420 holding any unparsed section of @var{expression} (or @code{None} if
421 the expression has been fully parsed). The second element contains
422 either @code{None} or another tuple that contains all the locations
423 that match the expression represented as @code{gdb.Symtab_and_line}
424 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
425 provided, it is decoded the way that @value{GDBN}'s inbuilt
426 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
429 @defun gdb.prompt_hook (current_prompt)
432 If @var{prompt_hook} is callable, @value{GDBN} will call the method
433 assigned to this operation before a prompt is displayed by
436 The parameter @code{current_prompt} contains the current @value{GDBN}
437 prompt. This method must return a Python string, or @code{None}. If
438 a string is returned, the @value{GDBN} prompt will be set to that
439 string. If @code{None} is returned, @value{GDBN} will continue to use
442 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
443 such as those used by readline for command input, and annotation
444 related prompts are prohibited from being changed.
447 @node Exception Handling
448 @subsubsection Exception Handling
449 @cindex python exceptions
450 @cindex exceptions, python
452 When executing the @code{python} command, Python exceptions
453 uncaught within the Python code are translated to calls to
454 @value{GDBN} error-reporting mechanism. If the command that called
455 @code{python} does not handle the error, @value{GDBN} will
456 terminate it and print an error message containing the Python
457 exception name, the associated value, and the Python call stack
458 backtrace at the point where the exception was raised. Example:
461 (@value{GDBP}) python print foo
462 Traceback (most recent call last):
463 File "<string>", line 1, in <module>
464 NameError: name 'foo' is not defined
467 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
468 Python code are converted to Python exceptions. The type of the
469 Python exception depends on the error.
473 This is the base class for most exceptions generated by @value{GDBN}.
474 It is derived from @code{RuntimeError}, for compatibility with earlier
475 versions of @value{GDBN}.
477 If an error occurring in @value{GDBN} does not fit into some more
478 specific category, then the generated exception will have this type.
480 @item gdb.MemoryError
481 This is a subclass of @code{gdb.error} which is thrown when an
482 operation tried to access invalid memory in the inferior.
484 @item KeyboardInterrupt
485 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
486 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
489 In all cases, your exception handler will see the @value{GDBN} error
490 message as its value and the Python call stack backtrace at the Python
491 statement closest to where the @value{GDBN} error occured as the
495 When implementing @value{GDBN} commands in Python via @code{gdb.Command},
496 it is useful to be able to throw an exception that doesn't cause a
497 traceback to be printed. For example, the user may have invoked the
498 command incorrectly. Use the @code{gdb.GdbError} exception
499 to handle this case. Example:
503 >class HelloWorld (gdb.Command):
504 > """Greet the whole world."""
505 > def __init__ (self):
506 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
507 > def invoke (self, args, from_tty):
508 > argv = gdb.string_to_argv (args)
509 > if len (argv) != 0:
510 > raise gdb.GdbError ("hello-world takes no arguments")
511 > print "Hello, World!"
515 hello-world takes no arguments
518 @node Values From Inferior
519 @subsubsection Values From Inferior
520 @cindex values from inferior, with Python
521 @cindex python, working with values from inferior
523 @cindex @code{gdb.Value}
524 @value{GDBN} provides values it obtains from the inferior program in
525 an object of type @code{gdb.Value}. @value{GDBN} uses this object
526 for its internal bookkeeping of the inferior's values, and for
527 fetching values when necessary.
529 Inferior values that are simple scalars can be used directly in
530 Python expressions that are valid for the value's data type. Here's
531 an example for an integer or floating-point value @code{some_val}:
538 As result of this, @code{bar} will also be a @code{gdb.Value} object
539 whose values are of the same type as those of @code{some_val}. Valid
540 Python operations can also be performed on @code{gdb.Value} objects
541 representing a @code{struct} or @code{class} object. For such cases,
542 the overloaded operator (if present), is used to perform the operation.
543 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
544 representing instances of a @code{class} which overloads the @code{+}
545 operator, then one can use the @code{+} operator in their Python script
553 The result of the operation @code{val3} is also a @code{gdb.Value}
554 object corresponding to the value returned by the overloaded @code{+}
555 operator. In general, overloaded operators are invoked for the
556 following operations: @code{+} (binary addition), @code{-} (binary
557 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
558 @code{>>}, @code{|}, @code{&}, @code{^}.
560 Inferior values that are structures or instances of some class can
561 be accessed using the Python @dfn{dictionary syntax}. For example, if
562 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
563 can access its @code{foo} element with:
566 bar = some_val['foo']
569 @cindex getting structure elements using gdb.Field objects as subscripts
570 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
571 elements can also be accessed by using @code{gdb.Field} objects as
572 subscripts (@pxref{Types In Python}, for more information on
573 @code{gdb.Field} objects). For example, if @code{foo_field} is a
574 @code{gdb.Field} object corresponding to element @code{foo} of the above
575 structure, then @code{bar} can also be accessed as follows:
578 bar = some_val[foo_field]
581 A @code{gdb.Value} that represents a function can be executed via
582 inferior function call. Any arguments provided to the call must match
583 the function's prototype, and must be provided in the order specified
586 For example, @code{some_val} is a @code{gdb.Value} instance
587 representing a function that takes two integers as arguments. To
588 execute this function, call it like so:
591 result = some_val (10,20)
594 Any values returned from a function call will be stored as a
597 The following attributes are provided:
599 @defvar Value.address
600 If this object is addressable, this read-only attribute holds a
601 @code{gdb.Value} object representing the address. Otherwise,
602 this attribute holds @code{None}.
605 @cindex optimized out value in Python
606 @defvar Value.is_optimized_out
607 This read-only boolean attribute is true if the compiler optimized out
608 this value, thus it is not available for fetching from the inferior.
612 The type of this @code{gdb.Value}. The value of this attribute is a
613 @code{gdb.Type} object (@pxref{Types In Python}).
616 @defvar Value.dynamic_type
617 The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time
618 type information (@acronym{RTTI}) to determine the dynamic type of the
619 value. If this value is of class type, it will return the class in
620 which the value is embedded, if any. If this value is of pointer or
621 reference to a class type, it will compute the dynamic type of the
622 referenced object, and return a pointer or reference to that type,
623 respectively. In all other cases, it will return the value's static
626 Note that this feature will only work when debugging a C@t{++} program
627 that includes @acronym{RTTI} for the object in question. Otherwise,
628 it will just return the static type of the value as in @kbd{ptype foo}
629 (@pxref{Symbols, ptype}).
632 @defvar Value.is_lazy
633 The value of this read-only boolean attribute is @code{True} if this
634 @code{gdb.Value} has not yet been fetched from the inferior.
635 @value{GDBN} does not fetch values until necessary, for efficiency.
639 myval = gdb.parse_and_eval ('somevar')
642 The value of @code{somevar} is not fetched at this time. It will be
643 fetched when the value is needed, or when the @code{fetch_lazy}
647 The following methods are provided:
649 @defun Value.__init__ (@var{val})
650 Many Python values can be converted directly to a @code{gdb.Value} via
651 this object initializer. Specifically:
655 A Python boolean is converted to the boolean type from the current
659 A Python integer is converted to the C @code{long} type for the
660 current architecture.
663 A Python long is converted to the C @code{long long} type for the
664 current architecture.
667 A Python float is converted to the C @code{double} type for the
668 current architecture.
671 A Python string is converted to a target string in the current target
672 language using the current target encoding.
673 If a character cannot be represented in the current target encoding,
674 then an exception is thrown.
676 @item @code{gdb.Value}
677 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
679 @item @code{gdb.LazyString}
680 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
681 Python}), then the lazy string's @code{value} method is called, and
686 @defun Value.cast (type)
687 Return a new instance of @code{gdb.Value} that is the result of
688 casting this instance to the type described by @var{type}, which must
689 be a @code{gdb.Type} object. If the cast cannot be performed for some
690 reason, this method throws an exception.
693 @defun Value.dereference ()
694 For pointer data types, this method returns a new @code{gdb.Value} object
695 whose contents is the object pointed to by the pointer. For example, if
696 @code{foo} is a C pointer to an @code{int}, declared in your C program as
703 then you can use the corresponding @code{gdb.Value} to access what
704 @code{foo} points to like this:
707 bar = foo.dereference ()
710 The result @code{bar} will be a @code{gdb.Value} object holding the
711 value pointed to by @code{foo}.
713 A similar function @code{Value.referenced_value} exists which also
714 returns @code{gdb.Value} objects corresonding to the values pointed to
715 by pointer values (and additionally, values referenced by reference
716 values). However, the behavior of @code{Value.dereference}
717 differs from @code{Value.referenced_value} by the fact that the
718 behavior of @code{Value.dereference} is identical to applying the C
719 unary operator @code{*} on a given value. For example, consider a
720 reference to a pointer @code{ptrref}, declared in your C@t{++} program
728 intptr &ptrref = ptr;
731 Though @code{ptrref} is a reference value, one can apply the method
732 @code{Value.dereference} to the @code{gdb.Value} object corresponding
733 to it and obtain a @code{gdb.Value} which is identical to that
734 corresponding to @code{val}. However, if you apply the method
735 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
736 object identical to that corresponding to @code{ptr}.
739 py_ptrref = gdb.parse_and_eval ("ptrref")
740 py_val = py_ptrref.dereference ()
741 py_ptr = py_ptrref.referenced_value ()
744 The @code{gdb.Value} object @code{py_val} is identical to that
745 corresponding to @code{val}, and @code{py_ptr} is identical to that
746 corresponding to @code{ptr}. In general, @code{Value.dereference} can
747 be applied whenever the C unary operator @code{*} can be applied
748 to the corresponding C value. For those cases where applying both
749 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
750 the results obtained need not be identical (as we have seen in the above
751 example). The results are however identical when applied on
752 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
753 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
756 @defun Value.referenced_value ()
757 For pointer or reference data types, this method returns a new
758 @code{gdb.Value} object corresponding to the value referenced by the
759 pointer/reference value. For pointer data types,
760 @code{Value.dereference} and @code{Value.referenced_value} produce
761 identical results. The difference between these methods is that
762 @code{Value.dereference} cannot get the values referenced by reference
763 values. For example, consider a reference to an @code{int}, declared
764 in your C@t{++} program as
772 then applying @code{Value.dereference} to the @code{gdb.Value} object
773 corresponding to @code{ref} will result in an error, while applying
774 @code{Value.referenced_value} will result in a @code{gdb.Value} object
775 identical to that corresponding to @code{val}.
778 py_ref = gdb.parse_and_eval ("ref")
779 er_ref = py_ref.dereference () # Results in error
780 py_val = py_ref.referenced_value () # Returns the referenced value
783 The @code{gdb.Value} object @code{py_val} is identical to that
784 corresponding to @code{val}.
787 @defun Value.reference_value ()
788 Return a @code{gdb.Value} object which is a reference to the value
789 encapsulated by this instance.
792 @defun Value.const_value ()
793 Return a @code{gdb.Value} object which is a @code{const} version of the
794 value encapsulated by this instance.
797 @defun Value.dynamic_cast (type)
798 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
799 operator were used. Consult a C@t{++} reference for details.
802 @defun Value.reinterpret_cast (type)
803 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
804 operator were used. Consult a C@t{++} reference for details.
807 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
808 If this @code{gdb.Value} represents a string, then this method
809 converts the contents to a Python string. Otherwise, this method will
812 Values are interpreted as strings according to the rules of the
813 current language. If the optional length argument is given, the
814 string will be converted to that length, and will include any embedded
815 zeroes that the string may contain. Otherwise, for languages
816 where the string is zero-terminated, the entire string will be
819 For example, in C-like languages, a value is a string if it is a pointer
820 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
823 If the optional @var{encoding} argument is given, it must be a string
824 naming the encoding of the string in the @code{gdb.Value}, such as
825 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
826 the same encodings as the corresponding argument to Python's
827 @code{string.decode} method, and the Python codec machinery will be used
828 to convert the string. If @var{encoding} is not given, or if
829 @var{encoding} is the empty string, then either the @code{target-charset}
830 (@pxref{Character Sets}) will be used, or a language-specific encoding
831 will be used, if the current language is able to supply one.
833 The optional @var{errors} argument is the same as the corresponding
834 argument to Python's @code{string.decode} method.
836 If the optional @var{length} argument is given, the string will be
837 fetched and converted to the given length.
840 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
841 If this @code{gdb.Value} represents a string, then this method
842 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
843 In Python}). Otherwise, this method will throw an exception.
845 If the optional @var{encoding} argument is given, it must be a string
846 naming the encoding of the @code{gdb.LazyString}. Some examples are:
847 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
848 @var{encoding} argument is an encoding that @value{GDBN} does
849 recognize, @value{GDBN} will raise an error.
851 When a lazy string is printed, the @value{GDBN} encoding machinery is
852 used to convert the string during printing. If the optional
853 @var{encoding} argument is not provided, or is an empty string,
854 @value{GDBN} will automatically select the encoding most suitable for
855 the string type. For further information on encoding in @value{GDBN}
856 please see @ref{Character Sets}.
858 If the optional @var{length} argument is given, the string will be
859 fetched and encoded to the length of characters specified. If
860 the @var{length} argument is not provided, the string will be fetched
861 and encoded until a null of appropriate width is found.
864 @defun Value.fetch_lazy ()
865 If the @code{gdb.Value} object is currently a lazy value
866 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
867 fetched from the inferior. Any errors that occur in the process
868 will produce a Python exception.
870 If the @code{gdb.Value} object is not a lazy value, this method
873 This method does not return a value.
877 @node Types In Python
878 @subsubsection Types In Python
879 @cindex types in Python
880 @cindex Python, working with types
883 @value{GDBN} represents types from the inferior using the class
886 The following type-related functions are available in the @code{gdb}
889 @findex gdb.lookup_type
890 @defun gdb.lookup_type (name @r{[}, block@r{]})
891 This function looks up a type by its @var{name}, which must be a string.
893 If @var{block} is given, then @var{name} is looked up in that scope.
894 Otherwise, it is searched for globally.
896 Ordinarily, this function will return an instance of @code{gdb.Type}.
897 If the named type cannot be found, it will throw an exception.
900 If the type is a structure or class type, or an enum type, the fields
901 of that type can be accessed using the Python @dfn{dictionary syntax}.
902 For example, if @code{some_type} is a @code{gdb.Type} instance holding
903 a structure type, you can access its @code{foo} field with:
906 bar = some_type['foo']
909 @code{bar} will be a @code{gdb.Field} object; see below under the
910 description of the @code{Type.fields} method for a description of the
911 @code{gdb.Field} class.
913 An instance of @code{Type} has the following attributes:
916 The type code for this type. The type code will be one of the
917 @code{TYPE_CODE_} constants defined below.
921 The name of this type. If this type has no name, then @code{None}
926 The size of this type, in target @code{char} units. Usually, a
927 target's @code{char} type will be an 8-bit byte. However, on some
928 unusual platforms, this type may have a different size.
932 The tag name for this type. The tag name is the name after
933 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
934 languages have this concept. If this type has no tag name, then
935 @code{None} is returned.
938 The following methods are provided:
940 @defun Type.fields ()
941 For structure and union types, this method returns the fields. Range
942 types have two fields, the minimum and maximum values. Enum types
943 have one field per enum constant. Function and method types have one
944 field per parameter. The base types of C@t{++} classes are also
945 represented as fields. If the type has no fields, or does not fit
946 into one of these categories, an empty sequence will be returned.
948 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
951 This attribute is not available for @code{enum} or @code{static}
952 (as in C@t{++}) fields. The value is the position, counting
953 in bits, from the start of the containing type.
956 This attribute is only available for @code{enum} fields, and its value
957 is the enumeration member's integer representation.
960 The name of the field, or @code{None} for anonymous fields.
963 This is @code{True} if the field is artificial, usually meaning that
964 it was provided by the compiler and not the user. This attribute is
965 always provided, and is @code{False} if the field is not artificial.
968 This is @code{True} if the field represents a base class of a C@t{++}
969 structure. This attribute is always provided, and is @code{False}
970 if the field is not a base class of the type that is the argument of
971 @code{fields}, or if that type was not a C@t{++} class.
974 If the field is packed, or is a bitfield, then this will have a
975 non-zero value, which is the size of the field in bits. Otherwise,
976 this will be zero; in this case the field's size is given by its type.
979 The type of the field. This is usually an instance of @code{Type},
980 but it can be @code{None} in some situations.
983 The type which contains this field. This is an instance of
988 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
989 Return a new @code{gdb.Type} object which represents an array of this
990 type. If one argument is given, it is the inclusive upper bound of
991 the array; in this case the lower bound is zero. If two arguments are
992 given, the first argument is the lower bound of the array, and the
993 second argument is the upper bound of the array. An array's length
994 must not be negative, but the bounds can be.
997 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
998 Return a new @code{gdb.Type} object which represents a vector of this
999 type. If one argument is given, it is the inclusive upper bound of
1000 the vector; in this case the lower bound is zero. If two arguments are
1001 given, the first argument is the lower bound of the vector, and the
1002 second argument is the upper bound of the vector. A vector's length
1003 must not be negative, but the bounds can be.
1005 The difference between an @code{array} and a @code{vector} is that
1006 arrays behave like in C: when used in expressions they decay to a pointer
1007 to the first element whereas vectors are treated as first class values.
1010 @defun Type.const ()
1011 Return a new @code{gdb.Type} object which represents a
1012 @code{const}-qualified variant of this type.
1015 @defun Type.volatile ()
1016 Return a new @code{gdb.Type} object which represents a
1017 @code{volatile}-qualified variant of this type.
1020 @defun Type.unqualified ()
1021 Return a new @code{gdb.Type} object which represents an unqualified
1022 variant of this type. That is, the result is neither @code{const} nor
1026 @defun Type.range ()
1027 Return a Python @code{Tuple} object that contains two elements: the
1028 low bound of the argument type and the high bound of that type. If
1029 the type does not have a range, @value{GDBN} will raise a
1030 @code{gdb.error} exception (@pxref{Exception Handling}).
1033 @defun Type.reference ()
1034 Return a new @code{gdb.Type} object which represents a reference to this
1038 @defun Type.pointer ()
1039 Return a new @code{gdb.Type} object which represents a pointer to this
1043 @defun Type.strip_typedefs ()
1044 Return a new @code{gdb.Type} that represents the real type,
1045 after removing all layers of typedefs.
1048 @defun Type.target ()
1049 Return a new @code{gdb.Type} object which represents the target type
1052 For a pointer type, the target type is the type of the pointed-to
1053 object. For an array type (meaning C-like arrays), the target type is
1054 the type of the elements of the array. For a function or method type,
1055 the target type is the type of the return value. For a complex type,
1056 the target type is the type of the elements. For a typedef, the
1057 target type is the aliased type.
1059 If the type does not have a target, this method will throw an
1063 @defun Type.template_argument (n @r{[}, block@r{]})
1064 If this @code{gdb.Type} is an instantiation of a template, this will
1065 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1066 value of the @var{n}th template argument (indexed starting at 0).
1068 If this @code{gdb.Type} is not a template type, or if the type has fewer
1069 than @var{n} template arguments, this will throw an exception.
1070 Ordinarily, only C@t{++} code will have template types.
1072 If @var{block} is given, then @var{name} is looked up in that scope.
1073 Otherwise, it is searched for globally.
1076 @defun Type.optimized_out ()
1077 Return @code{gdb.Value} instance of this type whose value is optimized
1078 out. This allows a frame decorator to indicate that the value of an
1079 argument or a local variable is not known.
1082 Each type has a code, which indicates what category this type falls
1083 into. The available type categories are represented by constants
1084 defined in the @code{gdb} module:
1087 @vindex TYPE_CODE_PTR
1088 @item gdb.TYPE_CODE_PTR
1089 The type is a pointer.
1091 @vindex TYPE_CODE_ARRAY
1092 @item gdb.TYPE_CODE_ARRAY
1093 The type is an array.
1095 @vindex TYPE_CODE_STRUCT
1096 @item gdb.TYPE_CODE_STRUCT
1097 The type is a structure.
1099 @vindex TYPE_CODE_UNION
1100 @item gdb.TYPE_CODE_UNION
1101 The type is a union.
1103 @vindex TYPE_CODE_ENUM
1104 @item gdb.TYPE_CODE_ENUM
1105 The type is an enum.
1107 @vindex TYPE_CODE_FLAGS
1108 @item gdb.TYPE_CODE_FLAGS
1109 A bit flags type, used for things such as status registers.
1111 @vindex TYPE_CODE_FUNC
1112 @item gdb.TYPE_CODE_FUNC
1113 The type is a function.
1115 @vindex TYPE_CODE_INT
1116 @item gdb.TYPE_CODE_INT
1117 The type is an integer type.
1119 @vindex TYPE_CODE_FLT
1120 @item gdb.TYPE_CODE_FLT
1121 A floating point type.
1123 @vindex TYPE_CODE_VOID
1124 @item gdb.TYPE_CODE_VOID
1125 The special type @code{void}.
1127 @vindex TYPE_CODE_SET
1128 @item gdb.TYPE_CODE_SET
1131 @vindex TYPE_CODE_RANGE
1132 @item gdb.TYPE_CODE_RANGE
1133 A range type, that is, an integer type with bounds.
1135 @vindex TYPE_CODE_STRING
1136 @item gdb.TYPE_CODE_STRING
1137 A string type. Note that this is only used for certain languages with
1138 language-defined string types; C strings are not represented this way.
1140 @vindex TYPE_CODE_BITSTRING
1141 @item gdb.TYPE_CODE_BITSTRING
1142 A string of bits. It is deprecated.
1144 @vindex TYPE_CODE_ERROR
1145 @item gdb.TYPE_CODE_ERROR
1146 An unknown or erroneous type.
1148 @vindex TYPE_CODE_METHOD
1149 @item gdb.TYPE_CODE_METHOD
1150 A method type, as found in C@t{++}.
1152 @vindex TYPE_CODE_METHODPTR
1153 @item gdb.TYPE_CODE_METHODPTR
1154 A pointer-to-member-function.
1156 @vindex TYPE_CODE_MEMBERPTR
1157 @item gdb.TYPE_CODE_MEMBERPTR
1158 A pointer-to-member.
1160 @vindex TYPE_CODE_REF
1161 @item gdb.TYPE_CODE_REF
1164 @vindex TYPE_CODE_CHAR
1165 @item gdb.TYPE_CODE_CHAR
1168 @vindex TYPE_CODE_BOOL
1169 @item gdb.TYPE_CODE_BOOL
1172 @vindex TYPE_CODE_COMPLEX
1173 @item gdb.TYPE_CODE_COMPLEX
1174 A complex float type.
1176 @vindex TYPE_CODE_TYPEDEF
1177 @item gdb.TYPE_CODE_TYPEDEF
1178 A typedef to some other type.
1180 @vindex TYPE_CODE_NAMESPACE
1181 @item gdb.TYPE_CODE_NAMESPACE
1182 A C@t{++} namespace.
1184 @vindex TYPE_CODE_DECFLOAT
1185 @item gdb.TYPE_CODE_DECFLOAT
1186 A decimal floating point type.
1188 @vindex TYPE_CODE_INTERNAL_FUNCTION
1189 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1190 A function internal to @value{GDBN}. This is the type used to represent
1191 convenience functions.
1194 Further support for types is provided in the @code{gdb.types}
1195 Python module (@pxref{gdb.types}).
1197 @node Pretty Printing API
1198 @subsubsection Pretty Printing API
1199 @cindex python pretty printing api
1201 An example output is provided (@pxref{Pretty Printing}).
1203 A pretty-printer is just an object that holds a value and implements a
1204 specific interface, defined here.
1206 @defun pretty_printer.children (self)
1207 @value{GDBN} will call this method on a pretty-printer to compute the
1208 children of the pretty-printer's value.
1210 This method must return an object conforming to the Python iterator
1211 protocol. Each item returned by the iterator must be a tuple holding
1212 two elements. The first element is the ``name'' of the child; the
1213 second element is the child's value. The value can be any Python
1214 object which is convertible to a @value{GDBN} value.
1216 This method is optional. If it does not exist, @value{GDBN} will act
1217 as though the value has no children.
1220 @defun pretty_printer.display_hint (self)
1221 The CLI may call this method and use its result to change the
1222 formatting of a value. The result will also be supplied to an MI
1223 consumer as a @samp{displayhint} attribute of the variable being
1226 This method is optional. If it does exist, this method must return a
1229 Some display hints are predefined by @value{GDBN}:
1233 Indicate that the object being printed is ``array-like''. The CLI
1234 uses this to respect parameters such as @code{set print elements} and
1235 @code{set print array}.
1238 Indicate that the object being printed is ``map-like'', and that the
1239 children of this value can be assumed to alternate between keys and
1243 Indicate that the object being printed is ``string-like''. If the
1244 printer's @code{to_string} method returns a Python string of some
1245 kind, then @value{GDBN} will call its internal language-specific
1246 string-printing function to format the string. For the CLI this means
1247 adding quotation marks, possibly escaping some characters, respecting
1248 @code{set print elements}, and the like.
1252 @defun pretty_printer.to_string (self)
1253 @value{GDBN} will call this method to display the string
1254 representation of the value passed to the object's constructor.
1256 When printing from the CLI, if the @code{to_string} method exists,
1257 then @value{GDBN} will prepend its result to the values returned by
1258 @code{children}. Exactly how this formatting is done is dependent on
1259 the display hint, and may change as more hints are added. Also,
1260 depending on the print settings (@pxref{Print Settings}), the CLI may
1261 print just the result of @code{to_string} in a stack trace, omitting
1262 the result of @code{children}.
1264 If this method returns a string, it is printed verbatim.
1266 Otherwise, if this method returns an instance of @code{gdb.Value},
1267 then @value{GDBN} prints this value. This may result in a call to
1268 another pretty-printer.
1270 If instead the method returns a Python value which is convertible to a
1271 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1272 the resulting value. Again, this may result in a call to another
1273 pretty-printer. Python scalars (integers, floats, and booleans) and
1274 strings are convertible to @code{gdb.Value}; other types are not.
1276 Finally, if this method returns @code{None} then no further operations
1277 are peformed in this method and nothing is printed.
1279 If the result is not one of these types, an exception is raised.
1282 @value{GDBN} provides a function which can be used to look up the
1283 default pretty-printer for a @code{gdb.Value}:
1285 @findex gdb.default_visualizer
1286 @defun gdb.default_visualizer (value)
1287 This function takes a @code{gdb.Value} object as an argument. If a
1288 pretty-printer for this value exists, then it is returned. If no such
1289 printer exists, then this returns @code{None}.
1292 @node Selecting Pretty-Printers
1293 @subsubsection Selecting Pretty-Printers
1294 @cindex selecting python pretty-printers
1296 The Python list @code{gdb.pretty_printers} contains an array of
1297 functions or callable objects that have been registered via addition
1298 as a pretty-printer. Printers in this list are called @code{global}
1299 printers, they're available when debugging all inferiors.
1300 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1301 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1304 Each function on these lists is passed a single @code{gdb.Value}
1305 argument and should return a pretty-printer object conforming to the
1306 interface definition above (@pxref{Pretty Printing API}). If a function
1307 cannot create a pretty-printer for the value, it should return
1310 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1311 @code{gdb.Objfile} in the current program space and iteratively calls
1312 each enabled lookup routine in the list for that @code{gdb.Objfile}
1313 until it receives a pretty-printer object.
1314 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1315 searches the pretty-printer list of the current program space,
1316 calling each enabled function until an object is returned.
1317 After these lists have been exhausted, it tries the global
1318 @code{gdb.pretty_printers} list, again calling each enabled function until an
1321 The order in which the objfiles are searched is not specified. For a
1322 given list, functions are always invoked from the head of the list,
1323 and iterated over sequentially until the end of the list, or a printer
1326 For various reasons a pretty-printer may not work.
1327 For example, the underlying data structure may have changed and
1328 the pretty-printer is out of date.
1330 The consequences of a broken pretty-printer are severe enough that
1331 @value{GDBN} provides support for enabling and disabling individual
1332 printers. For example, if @code{print frame-arguments} is on,
1333 a backtrace can become highly illegible if any argument is printed
1334 with a broken printer.
1336 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1337 attribute to the registered function or callable object. If this attribute
1338 is present and its value is @code{False}, the printer is disabled, otherwise
1339 the printer is enabled.
1341 @node Writing a Pretty-Printer
1342 @subsubsection Writing a Pretty-Printer
1343 @cindex writing a pretty-printer
1345 A pretty-printer consists of two parts: a lookup function to detect
1346 if the type is supported, and the printer itself.
1348 Here is an example showing how a @code{std::string} printer might be
1349 written. @xref{Pretty Printing API}, for details on the API this class
1353 class StdStringPrinter(object):
1354 "Print a std::string"
1356 def __init__(self, val):
1359 def to_string(self):
1360 return self.val['_M_dataplus']['_M_p']
1362 def display_hint(self):
1366 And here is an example showing how a lookup function for the printer
1367 example above might be written.
1370 def str_lookup_function(val):
1371 lookup_tag = val.type.tag
1372 if lookup_tag == None:
1374 regex = re.compile("^std::basic_string<char,.*>$")
1375 if regex.match(lookup_tag):
1376 return StdStringPrinter(val)
1380 The example lookup function extracts the value's type, and attempts to
1381 match it to a type that it can pretty-print. If it is a type the
1382 printer can pretty-print, it will return a printer object. If not, it
1383 returns @code{None}.
1385 We recommend that you put your core pretty-printers into a Python
1386 package. If your pretty-printers are for use with a library, we
1387 further recommend embedding a version number into the package name.
1388 This practice will enable @value{GDBN} to load multiple versions of
1389 your pretty-printers at the same time, because they will have
1392 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1393 can be evaluated multiple times without changing its meaning. An
1394 ideal auto-load file will consist solely of @code{import}s of your
1395 printer modules, followed by a call to a register pretty-printers with
1396 the current objfile.
1398 Taken as a whole, this approach will scale nicely to multiple
1399 inferiors, each potentially using a different library version.
1400 Embedding a version number in the Python package name will ensure that
1401 @value{GDBN} is able to load both sets of printers simultaneously.
1402 Then, because the search for pretty-printers is done by objfile, and
1403 because your auto-loaded code took care to register your library's
1404 printers with a specific objfile, @value{GDBN} will find the correct
1405 printers for the specific version of the library used by each
1408 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1409 this code might appear in @code{gdb.libstdcxx.v6}:
1412 def register_printers(objfile):
1413 objfile.pretty_printers.append(str_lookup_function)
1417 And then the corresponding contents of the auto-load file would be:
1420 import gdb.libstdcxx.v6
1421 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1424 The previous example illustrates a basic pretty-printer.
1425 There are a few things that can be improved on.
1426 The printer doesn't have a name, making it hard to identify in a
1427 list of installed printers. The lookup function has a name, but
1428 lookup functions can have arbitrary, even identical, names.
1430 Second, the printer only handles one type, whereas a library typically has
1431 several types. One could install a lookup function for each desired type
1432 in the library, but one could also have a single lookup function recognize
1433 several types. The latter is the conventional way this is handled.
1434 If a pretty-printer can handle multiple data types, then its
1435 @dfn{subprinters} are the printers for the individual data types.
1437 The @code{gdb.printing} module provides a formal way of solving these
1438 problems (@pxref{gdb.printing}).
1439 Here is another example that handles multiple types.
1441 These are the types we are going to pretty-print:
1444 struct foo @{ int a, b; @};
1445 struct bar @{ struct foo x, y; @};
1448 Here are the printers:
1452 """Print a foo object."""
1454 def __init__(self, val):
1457 def to_string(self):
1458 return ("a=<" + str(self.val["a"]) +
1459 "> b=<" + str(self.val["b"]) + ">")
1462 """Print a bar object."""
1464 def __init__(self, val):
1467 def to_string(self):
1468 return ("x=<" + str(self.val["x"]) +
1469 "> y=<" + str(self.val["y"]) + ">")
1472 This example doesn't need a lookup function, that is handled by the
1473 @code{gdb.printing} module. Instead a function is provided to build up
1474 the object that handles the lookup.
1479 def build_pretty_printer():
1480 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1482 pp.add_printer('foo', '^foo$', fooPrinter)
1483 pp.add_printer('bar', '^bar$', barPrinter)
1487 And here is the autoload support:
1492 gdb.printing.register_pretty_printer(
1493 gdb.current_objfile(),
1494 my_library.build_pretty_printer())
1497 Finally, when this printer is loaded into @value{GDBN}, here is the
1498 corresponding output of @samp{info pretty-printer}:
1501 (gdb) info pretty-printer
1508 @node Type Printing API
1509 @subsubsection Type Printing API
1510 @cindex type printing API for Python
1512 @value{GDBN} provides a way for Python code to customize type display.
1513 This is mainly useful for substituting canonical typedef names for
1516 @cindex type printer
1517 A @dfn{type printer} is just a Python object conforming to a certain
1518 protocol. A simple base class implementing the protocol is provided;
1519 see @ref{gdb.types}. A type printer must supply at least:
1521 @defivar type_printer enabled
1522 A boolean which is True if the printer is enabled, and False
1523 otherwise. This is manipulated by the @code{enable type-printer}
1524 and @code{disable type-printer} commands.
1527 @defivar type_printer name
1528 The name of the type printer. This must be a string. This is used by
1529 the @code{enable type-printer} and @code{disable type-printer}
1533 @defmethod type_printer instantiate (self)
1534 This is called by @value{GDBN} at the start of type-printing. It is
1535 only called if the type printer is enabled. This method must return a
1536 new object that supplies a @code{recognize} method, as described below.
1540 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1541 will compute a list of type recognizers. This is done by iterating
1542 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1543 followed by the per-progspace type printers (@pxref{Progspaces In
1544 Python}), and finally the global type printers.
1546 @value{GDBN} will call the @code{instantiate} method of each enabled
1547 type printer. If this method returns @code{None}, then the result is
1548 ignored; otherwise, it is appended to the list of recognizers.
1550 Then, when @value{GDBN} is going to display a type name, it iterates
1551 over the list of recognizers. For each one, it calls the recognition
1552 function, stopping if the function returns a non-@code{None} value.
1553 The recognition function is defined as:
1555 @defmethod type_recognizer recognize (self, type)
1556 If @var{type} is not recognized, return @code{None}. Otherwise,
1557 return a string which is to be printed as the name of @var{type}.
1558 The @var{type} argument will be an instance of @code{gdb.Type}
1559 (@pxref{Types In Python}).
1562 @value{GDBN} uses this two-pass approach so that type printers can
1563 efficiently cache information without holding on to it too long. For
1564 example, it can be convenient to look up type information in a type
1565 printer and hold it for a recognizer's lifetime; if a single pass were
1566 done then type printers would have to make use of the event system in
1567 order to avoid holding information that could become stale as the
1570 @node Frame Filter API
1571 @subsubsection Filtering Frames.
1572 @cindex frame filters api
1574 Frame filters are Python objects that manipulate the visibility of a
1575 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1578 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1579 commands (@pxref{GDB/MI}), those that return a collection of frames
1580 are affected. The commands that work with frame filters are:
1582 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1583 @code{-stack-list-frames}
1584 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1585 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1586 -stack-list-variables command}), @code{-stack-list-arguments}
1587 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1588 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1589 -stack-list-locals command}).
1591 A frame filter works by taking an iterator as an argument, applying
1592 actions to the contents of that iterator, and returning another
1593 iterator (or, possibly, the same iterator it was provided in the case
1594 where the filter does not perform any operations). Typically, frame
1595 filters utilize tools such as the Python's @code{itertools} module to
1596 work with and create new iterators from the source iterator.
1597 Regardless of how a filter chooses to apply actions, it must not alter
1598 the underlying @value{GDBN} frame or frames, or attempt to alter the
1599 call-stack within @value{GDBN}. This preserves data integrity within
1600 @value{GDBN}. Frame filters are executed on a priority basis and care
1601 should be taken that some frame filters may have been executed before,
1602 and that some frame filters will be executed after.
1604 An important consideration when designing frame filters, and well
1605 worth reflecting upon, is that frame filters should avoid unwinding
1606 the call stack if possible. Some stacks can run very deep, into the
1607 tens of thousands in some cases. To search every frame when a frame
1608 filter executes may be too expensive at that step. The frame filter
1609 cannot know how many frames it has to iterate over, and it may have to
1610 iterate through them all. This ends up duplicating effort as
1611 @value{GDBN} performs this iteration when it prints the frames. If
1612 the filter can defer unwinding frames until frame decorators are
1613 executed, after the last filter has executed, it should. @xref{Frame
1614 Decorator API}, for more information on decorators. Also, there are
1615 examples for both frame decorators and filters in later chapters.
1616 @xref{Writing a Frame Filter}, for more information.
1618 The Python dictionary @code{gdb.frame_filters} contains key/object
1619 pairings that comprise a frame filter. Frame filters in this
1620 dictionary are called @code{global} frame filters, and they are
1621 available when debugging all inferiors. These frame filters must
1622 register with the dictionary directly. In addition to the
1623 @code{global} dictionary, there are other dictionaries that are loaded
1624 with different inferiors via auto-loading (@pxref{Python
1625 Auto-loading}). The two other areas where frame filter dictionaries
1626 can be found are: @code{gdb.Progspace} which contains a
1627 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1628 object which also contains a @code{frame_filters} dictionary
1631 When a command is executed from @value{GDBN} that is compatible with
1632 frame filters, @value{GDBN} combines the @code{global},
1633 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1634 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1635 several frames, and thus several object files, might be in use.
1636 @value{GDBN} then prunes any frame filter whose @code{enabled}
1637 attribute is @code{False}. This pruned list is then sorted according
1638 to the @code{priority} attribute in each filter.
1640 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1641 creates an iterator which wraps each frame in the call stack in a
1642 @code{FrameDecorator} object, and calls each filter in order. The
1643 output from the previous filter will always be the input to the next
1646 Frame filters have a mandatory interface which each frame filter must
1647 implement, defined here:
1649 @defun FrameFilter.filter (iterator)
1650 @value{GDBN} will call this method on a frame filter when it has
1651 reached the order in the priority list for that filter.
1653 For example, if there are four frame filters:
1664 The order that the frame filters will be called is:
1667 Filter3 -> Filter2 -> Filter1 -> Filter4
1670 Note that the output from @code{Filter3} is passed to the input of
1671 @code{Filter2}, and so on.
1673 This @code{filter} method is passed a Python iterator. This iterator
1674 contains a sequence of frame decorators that wrap each
1675 @code{gdb.Frame}, or a frame decorator that wraps another frame
1676 decorator. The first filter that is executed in the sequence of frame
1677 filters will receive an iterator entirely comprised of default
1678 @code{FrameDecorator} objects. However, after each frame filter is
1679 executed, the previous frame filter may have wrapped some or all of
1680 the frame decorators with their own frame decorator. As frame
1681 decorators must also conform to a mandatory interface, these
1682 decorators can be assumed to act in a uniform manner (@pxref{Frame
1685 This method must return an object conforming to the Python iterator
1686 protocol. Each item in the iterator must be an object conforming to
1687 the frame decorator interface. If a frame filter does not wish to
1688 perform any operations on this iterator, it should return that
1691 This method is not optional. If it does not exist, @value{GDBN} will
1692 raise and print an error.
1695 @defvar FrameFilter.name
1696 The @code{name} attribute must be Python string which contains the
1697 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1698 Management}). This attribute may contain any combination of letters
1699 or numbers. Care should be taken to ensure that it is unique. This
1700 attribute is mandatory.
1703 @defvar FrameFilter.enabled
1704 The @code{enabled} attribute must be Python boolean. This attribute
1705 indicates to @value{GDBN} whether the frame filter is enabled, and
1706 should be considered when frame filters are executed. If
1707 @code{enabled} is @code{True}, then the frame filter will be executed
1708 when any of the backtrace commands detailed earlier in this chapter
1709 are executed. If @code{enabled} is @code{False}, then the frame
1710 filter will not be executed. This attribute is mandatory.
1713 @defvar FrameFilter.priority
1714 The @code{priority} attribute must be Python integer. This attribute
1715 controls the order of execution in relation to other frame filters.
1716 There are no imposed limits on the range of @code{priority} other than
1717 it must be a valid integer. The higher the @code{priority} attribute,
1718 the sooner the frame filter will be executed in relation to other
1719 frame filters. Although @code{priority} can be negative, it is
1720 recommended practice to assume zero is the lowest priority that a
1721 frame filter can be assigned. Frame filters that have the same
1722 priority are executed in unsorted order in that priority slot. This
1723 attribute is mandatory.
1726 @node Frame Decorator API
1727 @subsubsection Decorating Frames.
1728 @cindex frame decorator api
1730 Frame decorators are sister objects to frame filters (@pxref{Frame
1731 Filter API}). Frame decorators are applied by a frame filter and can
1732 only be used in conjunction with frame filters.
1734 The purpose of a frame decorator is to customize the printed content
1735 of each @code{gdb.Frame} in commands where frame filters are executed.
1736 This concept is called decorating a frame. Frame decorators decorate
1737 a @code{gdb.Frame} with Python code contained within each API call.
1738 This separates the actual data contained in a @code{gdb.Frame} from
1739 the decorated data produced by a frame decorator. This abstraction is
1740 necessary to maintain integrity of the data contained in each
1743 Frame decorators have a mandatory interface, defined below.
1745 @value{GDBN} already contains a frame decorator called
1746 @code{FrameDecorator}. This contains substantial amounts of
1747 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
1748 recommended that other frame decorators inherit and extend this
1749 object, and only to override the methods needed.
1751 @defun FrameDecorator.elided (self)
1753 The @code{elided} method groups frames together in a hierarchical
1754 system. An example would be an interpreter, where multiple low-level
1755 frames make up a single call in the interpreted language. In this
1756 example, the frame filter would elide the low-level frames and present
1757 a single high-level frame, representing the call in the interpreted
1758 language, to the user.
1760 The @code{elided} function must return an iterable and this iterable
1761 must contain the frames that are being elided wrapped in a suitable
1762 frame decorator. If no frames are being elided this function may
1763 return an empty iterable, or @code{None}. Elided frames are indented
1764 from normal frames in a @code{CLI} backtrace, or in the case of
1765 @code{GDB/MI}, are placed in the @code{children} field of the eliding
1768 It is the frame filter's task to also filter out the elided frames from
1769 the source iterator. This will avoid printing the frame twice.
1772 @defun FrameDecorator.function (self)
1774 This method returns the name of the function in the frame that is to
1777 This method must return a Python string describing the function, or
1780 If this function returns @code{None}, @value{GDBN} will not print any
1781 data for this field.
1784 @defun FrameDecorator.address (self)
1786 This method returns the address of the frame that is to be printed.
1788 This method must return a Python numeric integer type of sufficient
1789 size to describe the address of the frame, or @code{None}.
1791 If this function returns a @code{None}, @value{GDBN} will not print
1792 any data for this field.
1795 @defun FrameDecorator.filename (self)
1797 This method returns the filename and path associated with this frame.
1799 This method must return a Python string containing the filename and
1800 the path to the object file backing the frame, or @code{None}.
1802 If this function returns a @code{None}, @value{GDBN} will not print
1803 any data for this field.
1806 @defun FrameDecorator.line (self):
1808 This method returns the line number associated with the current
1809 position within the function addressed by this frame.
1811 This method must return a Python integer type, or @code{None}.
1813 If this function returns a @code{None}, @value{GDBN} will not print
1814 any data for this field.
1817 @defun FrameDecorator.frame_args (self)
1820 This method must return an iterable, or @code{None}. Returning an
1821 empty iterable, or @code{None} means frame arguments will not be
1822 printed for this frame. This iterable must contain objects that
1823 implement two methods, described here.
1825 This object must implement a @code{argument} method which takes a
1826 single @code{self} parameter and must return a @code{gdb.Symbol}
1827 (@pxref{Symbols In Python}), or a Python string. The object must also
1828 implement a @code{value} method which takes a single @code{self}
1829 parameter and must return a @code{gdb.Value} (@pxref{Values From
1830 Inferior}), a Python value, or @code{None}. If the @code{value}
1831 method returns @code{None}, and the @code{argument} method returns a
1832 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
1833 the @code{gdb.Symbol} automatically.
1838 class SymValueWrapper():
1840 def __init__(self, symbol, value):
1850 class SomeFrameDecorator()
1853 def frame_args(self):
1856 block = self.inferior_frame.block()
1860 # Iterate over all symbols in a block. Only add
1861 # symbols that are arguments.
1863 if not sym.is_argument:
1865 args.append(SymValueWrapper(sym,None))
1867 # Add example synthetic argument.
1868 args.append(SymValueWrapper(``foo'', 42))
1874 @defun FrameDecorator.frame_locals (self)
1876 This method must return an iterable or @code{None}. Returning an
1877 empty iterable, or @code{None} means frame local arguments will not be
1878 printed for this frame.
1880 The object interface, the description of the various strategies for
1881 reading frame locals, and the example are largely similar to those
1882 described in the @code{frame_args} function, (@pxref{frame_args,,The
1883 frame filter frame_args function}). Below is a modified example:
1886 class SomeFrameDecorator()
1889 def frame_locals(self):
1892 block = self.inferior_frame.block()
1896 # Iterate over all symbols in a block. Add all
1897 # symbols, except arguments.
1901 vars.append(SymValueWrapper(sym,None))
1903 # Add an example of a synthetic local variable.
1904 vars.append(SymValueWrapper(``bar'', 99))
1910 @defun FrameDecorator.inferior_frame (self):
1912 This method must return the underlying @code{gdb.Frame} that this
1913 frame decorator is decorating. @value{GDBN} requires the underlying
1914 frame for internal frame information to determine how to print certain
1915 values when printing a frame.
1918 @node Writing a Frame Filter
1919 @subsubsection Writing a Frame Filter
1920 @cindex writing a frame filter
1922 There are three basic elements that a frame filter must implement: it
1923 must correctly implement the documented interface (@pxref{Frame Filter
1924 API}), it must register itself with @value{GDBN}, and finally, it must
1925 decide if it is to work on the data provided by @value{GDBN}. In all
1926 cases, whether it works on the iterator or not, each frame filter must
1927 return an iterator. A bare-bones frame filter follows the pattern in
1928 the following example.
1933 class FrameFilter():
1936 # Frame filter attribute creation.
1938 # 'name' is the name of the filter that GDB will display.
1940 # 'priority' is the priority of the filter relative to other
1943 # 'enabled' is a boolean that indicates whether this filter is
1944 # enabled and should be executed.
1950 # Register this frame filter with the global frame_filters
1952 gdb.frame_filters[self.name] = self
1954 def filter(self, frame_iter):
1955 # Just return the iterator.
1959 The frame filter in the example above implements the three
1960 requirements for all frame filters. It implements the API, self
1961 registers, and makes a decision on the iterator (in this case, it just
1962 returns the iterator untouched).
1964 The first step is attribute creation and assignment, and as shown in
1965 the comments the filter assigns the following attributes: @code{name},
1966 @code{priority} and whether the filter should be enabled with the
1967 @code{enabled} attribute.
1969 The second step is registering the frame filter with the dictionary or
1970 dictionaries that the frame filter has interest in. As shown in the
1971 comments, this filter just registers itself with the global dictionary
1972 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
1973 is a dictionary that is initialized in the @code{gdb} module when
1974 @value{GDBN} starts. What dictionary a filter registers with is an
1975 important consideration. Generally, if a filter is specific to a set
1976 of code, it should be registered either in the @code{objfile} or
1977 @code{progspace} dictionaries as they are specific to the program
1978 currently loaded in @value{GDBN}. The global dictionary is always
1979 present in @value{GDBN} and is never unloaded. Any filters registered
1980 with the global dictionary will exist until @value{GDBN} exits. To
1981 avoid filters that may conflict, it is generally better to register
1982 frame filters against the dictionaries that more closely align with
1983 the usage of the filter currently in question. @xref{Python
1984 Auto-loading}, for further information on auto-loading Python scripts.
1986 @value{GDBN} takes a hands-off approach to frame filter registration,
1987 therefore it is the frame filter's responsibility to ensure
1988 registration has occurred, and that any exceptions are handled
1989 appropriately. In particular, you may wish to handle exceptions
1990 relating to Python dictionary key uniqueness. It is mandatory that
1991 the dictionary key is the same as frame filter's @code{name}
1992 attribute. When a user manages frame filters (@pxref{Frame Filter
1993 Management}), the names @value{GDBN} will display are those contained
1994 in the @code{name} attribute.
1996 The final step of this example is the implementation of the
1997 @code{filter} method. As shown in the example comments, we define the
1998 @code{filter} method and note that the method must take an iterator,
1999 and also must return an iterator. In this bare-bones example, the
2000 frame filter is not very useful as it just returns the iterator
2001 untouched. However this is a valid operation for frame filters that
2002 have the @code{enabled} attribute set, but decide not to operate on
2005 In the next example, the frame filter operates on all frames and
2006 utilizes a frame decorator to perform some work on the frames.
2007 @xref{Frame Decorator API}, for further information on the frame
2008 decorator interface.
2010 This example works on inlined frames. It highlights frames which are
2011 inlined by tagging them with an ``[inlined]'' tag. By applying a
2012 frame decorator to all frames with the Python @code{itertools imap}
2013 method, the example defers actions to the frame decorator. Frame
2014 decorators are only processed when @value{GDBN} prints the backtrace.
2016 This introduces a new decision making topic: whether to perform
2017 decision making operations at the filtering step, or at the printing
2018 step. In this example's approach, it does not perform any filtering
2019 decisions at the filtering step beyond mapping a frame decorator to
2020 each frame. This allows the actual decision making to be performed
2021 when each frame is printed. This is an important consideration, and
2022 well worth reflecting upon when designing a frame filter. An issue
2023 that frame filters should avoid is unwinding the stack if possible.
2024 Some stacks can run very deep, into the tens of thousands in some
2025 cases. To search every frame to determine if it is inlined ahead of
2026 time may be too expensive at the filtering step. The frame filter
2027 cannot know how many frames it has to iterate over, and it would have
2028 to iterate through them all. This ends up duplicating effort as
2029 @value{GDBN} performs this iteration when it prints the frames.
2031 In this example decision making can be deferred to the printing step.
2032 As each frame is printed, the frame decorator can examine each frame
2033 in turn when @value{GDBN} iterates. From a performance viewpoint,
2034 this is the most appropriate decision to make as it avoids duplicating
2035 the effort that the printing step would undertake anyway. Also, if
2036 there are many frame filters unwinding the stack during filtering, it
2037 can substantially delay the printing of the backtrace which will
2038 result in large memory usage, and a poor user experience.
2041 class InlineFilter():
2044 self.name = "InlinedFrameFilter"
2047 gdb.frame_filters[self.name] = self
2049 def filter(self, frame_iter):
2050 frame_iter = itertools.imap(InlinedFrameDecorator,
2055 This frame filter is somewhat similar to the earlier example, except
2056 that the @code{filter} method applies a frame decorator object called
2057 @code{InlinedFrameDecorator} to each element in the iterator. The
2058 @code{imap} Python method is light-weight. It does not proactively
2059 iterate over the iterator, but rather creates a new iterator which
2060 wraps the existing one.
2062 Below is the frame decorator for this example.
2065 class InlinedFrameDecorator(FrameDecorator):
2067 def __init__(self, fobj):
2068 super(InlinedFrameDecorator, self).__init__(fobj)
2071 frame = fobj.inferior_frame()
2072 name = str(frame.name())
2074 if frame.type() == gdb.INLINE_FRAME:
2075 name = name + " [inlined]"
2080 This frame decorator only defines and overrides the @code{function}
2081 method. It lets the supplied @code{FrameDecorator}, which is shipped
2082 with @value{GDBN}, perform the other work associated with printing
2085 The combination of these two objects create this output from a
2089 #0 0x004004e0 in bar () at inline.c:11
2090 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2091 #2 0x00400566 in main () at inline.c:31
2094 So in the case of this example, a frame decorator is applied to all
2095 frames, regardless of whether they may be inlined or not. As
2096 @value{GDBN} iterates over the iterator produced by the frame filters,
2097 @value{GDBN} executes each frame decorator which then makes a decision
2098 on what to print in the @code{function} callback. Using a strategy
2099 like this is a way to defer decisions on the frame content to printing
2102 @subheading Eliding Frames
2104 It might be that the above example is not desirable for representing
2105 inlined frames, and a hierarchical approach may be preferred. If we
2106 want to hierarchically represent frames, the @code{elided} frame
2107 decorator interface might be preferable.
2109 This example approaches the issue with the @code{elided} method. This
2110 example is quite long, but very simplistic. It is out-of-scope for
2111 this section to write a complete example that comprehensively covers
2112 all approaches of finding and printing inlined frames. However, this
2113 example illustrates the approach an author might use.
2115 This example comprises of three sections.
2118 class InlineFrameFilter():
2121 self.name = "InlinedFrameFilter"
2124 gdb.frame_filters[self.name] = self
2126 def filter(self, frame_iter):
2127 return ElidingInlineIterator(frame_iter)
2130 This frame filter is very similar to the other examples. The only
2131 difference is this frame filter is wrapping the iterator provided to
2132 it (@code{frame_iter}) with a custom iterator called
2133 @code{ElidingInlineIterator}. This again defers actions to when
2134 @value{GDBN} prints the backtrace, as the iterator is not traversed
2137 The iterator for this example is as follows. It is in this section of
2138 the example where decisions are made on the content of the backtrace.
2141 class ElidingInlineIterator:
2142 def __init__(self, ii):
2143 self.input_iterator = ii
2149 frame = next(self.input_iterator)
2151 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2155 eliding_frame = next(self.input_iterator)
2156 except StopIteration:
2158 return ElidingFrameDecorator(eliding_frame, [frame])
2161 This iterator implements the Python iterator protocol. When the
2162 @code{next} function is called (when @value{GDBN} prints each frame),
2163 the iterator checks if this frame decorator, @code{frame}, is wrapping
2164 an inlined frame. If it is not, it returns the existing frame decorator
2165 untouched. If it is wrapping an inlined frame, it assumes that the
2166 inlined frame was contained within the next oldest frame,
2167 @code{eliding_frame}, which it fetches. It then creates and returns a
2168 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2169 elided frame, and the eliding frame.
2172 class ElidingInlineDecorator(FrameDecorator):
2174 def __init__(self, frame, elided_frames):
2175 super(ElidingInlineDecorator, self).__init__(frame)
2177 self.elided_frames = elided_frames
2180 return iter(self.elided_frames)
2183 This frame decorator overrides one function and returns the inlined
2184 frame in the @code{elided} method. As before it lets
2185 @code{FrameDecorator} do the rest of the work involved in printing
2186 this frame. This produces the following output.
2189 #0 0x004004e0 in bar () at inline.c:11
2190 #2 0x00400529 in main () at inline.c:25
2191 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2194 In that output, @code{max} which has been inlined into @code{main} is
2195 printed hierarchically. Another approach would be to combine the
2196 @code{function} method, and the @code{elided} method to both print a
2197 marker in the inlined frame, and also show the hierarchical
2200 @node Unwinding Frames in Python
2201 @subsubsection Unwinding Frames in Python
2202 @cindex unwinding frames in Python
2204 In @value{GDBN} terminology ``unwinding'' is the process of finding
2205 the previous frame (that is, caller's) from the current one. An
2206 unwinder has three methods. The first one checks if it can handle
2207 given frame (``sniff'' it). For the frames it can sniff an unwinder
2208 provides two additional methods: it can return frame's ID, and it can
2209 fetch registers from the previous frame. A running @value{GDBN}
2210 mantains a list of the unwinders and calls each unwinder's sniffer in
2211 turn until it finds the one that recognizes the current frame. There
2212 is an API to register an unwinder.
2214 The unwinders that come with @value{GDBN} handle standard frames.
2215 However, mixed language applications (for example, an application
2216 running Java Virtual Machine) sometimes use frame layouts that cannot
2217 be handled by the @value{GDBN} unwinders. You can write Python code
2218 that can handle such custom frames.
2220 You implement a frame unwinder in Python as a class with which has two
2221 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2222 a single method @code{__call__}, which examines a given frame and
2223 returns an object (an instance of @code{gdb.UnwindInfo class)}
2224 describing it. If an unwinder does not recognize a frame, it should
2225 return @code{None}. The code in @value{GDBN} that enables writing
2226 unwinders in Python uses this object to return frame's ID and previous
2227 frame registers when @value{GDBN} core asks for them.
2229 @subheading Unwinder Input
2231 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2232 provides a method to read frame's registers:
2234 @defun PendingFrame.read_register (reg)
2235 This method returns the contents of the register @var{regn} in the
2236 frame as a @code{gdb.Value} object. @var{reg} can be either a
2237 register number or a register name; the values are platform-specific.
2238 They are usually found in the corresponding
2239 @file{@var{platform}-tdep.h} file in the @value{GDBN} source tree.
2242 It also provides a factory method to create a @code{gdb.UnwindInfo}
2243 instance to be returned to @value{GDBN}:
2245 @defun PendingFrame.create_unwind_info (frame_id)
2246 Returns a new @code{gdb.UnwindInfo} instance identified by given
2247 @var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2248 using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2249 determine which function will be used, as follows:
2252 @item sp, pc, special
2253 @code{frame_id_build_special (@var{frame_id}.sp, @var{frame_id}.pc, @var{frame_id}.special)}
2256 @code{frame_id_build (@var{frame_id}.sp, @var{frame_id}.pc)}
2258 This is the most common case.
2261 @code{frame_id_build_wild (@var{frame_id}.sp)}
2263 The attribute values should be @code{gdb.Value}
2267 @subheading Unwinder Output: UnwindInfo
2269 Use @code{PendingFrame.create_unwind_info} method described above to
2270 create a @code{gdb.UnwindInfo} instance. Use the following method to
2271 specify caller registers that have been saved in this frame:
2273 @defun gdb.UnwindInfo.add_saved_register (reg, value)
2274 @var{reg} identifies the register. It can be a number or a name, just
2275 as for the @code{PendingFrame.read_register} method above.
2276 @var{value} is a register value (a @code{gdb.Value} object).
2279 @subheading Unwinder Skeleton Code
2281 @value{GDBN} comes with the module containing the base @code{Unwinder}
2282 class. Derive your unwinder class from it and structure the code as
2286 from gdb.unwinders import Unwinder
2288 class FrameId(object):
2289 def __init__(self, sp, pc):
2294 class MyUnwinder(Unwinder):
2296 supe(MyUnwinder, self).__init___(<expects unwinder name argument>)
2298 def __call__(pending_frame):
2299 if not <we recognize frame>:
2301 # Create UnwindInfo. Usually the frame is identified by the stack
2302 # pointer and the program counter.
2303 sp = pending_frame.read_register(<SP number>)
2304 pc = pending_frame.read_register(<PC number>)
2305 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2307 # Find the values of the registers in the caller's frame and
2308 # save them in the result:
2309 unwind_info.add_saved_register(<register>, <value>)
2312 # Return the result:
2317 @subheading Registering a Unwinder
2319 An object file, a program space, and the @value{GDBN} proper can have
2320 unwinders registered with it.
2322 The @code{gdb.unwinders} module provides the function to register a
2325 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2326 @var{locus} is specifies an object file or a program space to which
2327 @var{unwinder} is added. Passing @code{None} or @code{gdb} adds
2328 @var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
2329 added @var{unwinder} will be called before any other unwinder from the
2330 same locus. Two unwinders in the same locus cannot have the same
2331 name. An attempt to add a unwinder with already existing name raises
2332 an exception unless @var{replace} is @code{True}, in which case the
2333 old unwinder is deleted.
2336 @subheading Unwinder Precedence
2338 @value{GDBN} first calls the unwinders from all the object files in no
2339 particular order, then the unwinders from the current program space,
2340 and finally the unwinders from @value{GDBN}.
2342 @node Xmethods In Python
2343 @subsubsection Xmethods In Python
2344 @cindex xmethods in Python
2346 @dfn{Xmethods} are additional methods or replacements for existing
2347 methods of a C@t{++} class. This feature is useful for those cases
2348 where a method defined in C@t{++} source code could be inlined or
2349 optimized out by the compiler, making it unavailable to @value{GDBN}.
2350 For such cases, one can define an xmethod to serve as a replacement
2351 for the method defined in the C@t{++} source code. @value{GDBN} will
2352 then invoke the xmethod, instead of the C@t{++} method, to
2353 evaluate expressions. One can also use xmethods when debugging
2354 with core files. Moreover, when debugging live programs, invoking an
2355 xmethod need not involve running the inferior (which can potentially
2356 perturb its state). Hence, even if the C@t{++} method is available, it
2357 is better to use its replacement xmethod if one is defined.
2359 The xmethods feature in Python is available via the concepts of an
2360 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2361 implement an xmethod, one has to implement a matcher and a
2362 corresponding worker for it (more than one worker can be
2363 implemented, each catering to a different overloaded instance of the
2364 method). Internally, @value{GDBN} invokes the @code{match} method of a
2365 matcher to match the class type and method name. On a match, the
2366 @code{match} method returns a list of matching @emph{worker} objects.
2367 Each worker object typically corresponds to an overloaded instance of
2368 the xmethod. They implement a @code{get_arg_types} method which
2369 returns a sequence of types corresponding to the arguments the xmethod
2370 requires. @value{GDBN} uses this sequence of types to perform
2371 overload resolution and picks a winning xmethod worker. A winner
2372 is also selected from among the methods @value{GDBN} finds in the
2373 C@t{++} source code. Next, the winning xmethod worker and the
2374 winning C@t{++} method are compared to select an overall winner. In
2375 case of a tie between a xmethod worker and a C@t{++} method, the
2376 xmethod worker is selected as the winner. That is, if a winning
2377 xmethod worker is found to be equivalent to the winning C@t{++}
2378 method, then the xmethod worker is treated as a replacement for
2379 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2380 method. If the winning xmethod worker is the overall winner, then
2381 the corresponding xmethod is invoked via the @code{__call__} method
2382 of the worker object.
2384 If one wants to implement an xmethod as a replacement for an
2385 existing C@t{++} method, then they have to implement an equivalent
2386 xmethod which has exactly the same name and takes arguments of
2387 exactly the same type as the C@t{++} method. If the user wants to
2388 invoke the C@t{++} method even though a replacement xmethod is
2389 available for that method, then they can disable the xmethod.
2391 @xref{Xmethod API}, for API to implement xmethods in Python.
2392 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2395 @subsubsection Xmethod API
2398 The @value{GDBN} Python API provides classes, interfaces and functions
2399 to implement, register and manipulate xmethods.
2400 @xref{Xmethods In Python}.
2402 An xmethod matcher should be an instance of a class derived from
2403 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2404 object with similar interface and attributes. An instance of
2405 @code{XMethodMatcher} has the following attributes:
2408 The name of the matcher.
2412 A boolean value indicating whether the matcher is enabled or disabled.
2416 A list of named methods managed by the matcher. Each object in the list
2417 is an instance of the class @code{XMethod} defined in the module
2418 @code{gdb.xmethod}, or any object with the following attributes:
2423 Name of the xmethod which should be unique for each xmethod
2424 managed by the matcher.
2427 A boolean value indicating whether the xmethod is enabled or
2432 The class @code{XMethod} is a convenience class with same
2433 attributes as above along with the following constructor:
2435 @defun XMethod.__init__ (self, name)
2436 Constructs an enabled xmethod with name @var{name}.
2441 The @code{XMethodMatcher} class has the following methods:
2443 @defun XMethodMatcher.__init__ (self, name)
2444 Constructs an enabled xmethod matcher with name @var{name}. The
2445 @code{methods} attribute is initialized to @code{None}.
2448 @defun XMethodMatcher.match (self, class_type, method_name)
2449 Derived classes should override this method. It should return a
2450 xmethod worker object (or a sequence of xmethod worker
2451 objects) matching the @var{class_type} and @var{method_name}.
2452 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2453 is a string value. If the matcher manages named methods as listed in
2454 its @code{methods} attribute, then only those worker objects whose
2455 corresponding entries in the @code{methods} list are enabled should be
2459 An xmethod worker should be an instance of a class derived from
2460 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
2461 or support the following interface:
2463 @defun XMethodWorker.get_arg_types (self)
2464 This method returns a sequence of @code{gdb.Type} objects corresponding
2465 to the arguments that the xmethod takes. It can return an empty
2466 sequence or @code{None} if the xmethod does not take any arguments.
2467 If the xmethod takes a single argument, then a single
2468 @code{gdb.Type} object corresponding to it can be returned.
2471 @defun XMethodWorker.get_result_type (self, *args)
2472 This method returns a @code{gdb.Type} object representing the type
2473 of the result of invoking this xmethod.
2474 The @var{args} argument is the same tuple of arguments that would be
2475 passed to the @code{__call__} method of this worker.
2478 @defun XMethodWorker.__call__ (self, *args)
2479 This is the method which does the @emph{work} of the xmethod. The
2480 @var{args} arguments is the tuple of arguments to the xmethod. Each
2481 element in this tuple is a gdb.Value object. The first element is
2482 always the @code{this} pointer value.
2485 For @value{GDBN} to lookup xmethods, the xmethod matchers
2486 should be registered using the following function defined in the module
2489 @defun register_xmethod_matcher (locus, matcher, replace=False)
2490 The @code{matcher} is registered with @code{locus}, replacing an
2491 existing matcher with the same name as @code{matcher} if
2492 @code{replace} is @code{True}. @code{locus} can be a
2493 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
2494 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
2495 @code{None}. If it is @code{None}, then @code{matcher} is registered
2499 @node Writing an Xmethod
2500 @subsubsection Writing an Xmethod
2501 @cindex writing xmethods in Python
2503 Implementing xmethods in Python will require implementing xmethod
2504 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2505 the following C@t{++} class:
2511 MyClass (int a) : a_(a) @{ @}
2513 int geta (void) @{ return a_; @}
2514 int operator+ (int b);
2521 MyClass::operator+ (int b)
2528 Let us define two xmethods for the class @code{MyClass}, one
2529 replacing the method @code{geta}, and another adding an overloaded
2530 flavor of @code{operator+} which takes a @code{MyClass} argument (the
2531 C@t{++} code above already has an overloaded @code{operator+}
2532 which takes an @code{int} argument). The xmethod matcher can be
2536 class MyClass_geta(gdb.xmethod.XMethod):
2538 gdb.xmethod.XMethod.__init__(self, 'geta')
2540 def get_worker(self, method_name):
2541 if method_name == 'geta':
2542 return MyClassWorker_geta()
2545 class MyClass_sum(gdb.xmethod.XMethod):
2547 gdb.xmethod.XMethod.__init__(self, 'sum')
2549 def get_worker(self, method_name):
2550 if method_name == 'operator+':
2551 return MyClassWorker_plus()
2554 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2556 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2557 # List of methods 'managed' by this matcher
2558 self.methods = [MyClass_geta(), MyClass_sum()]
2560 def match(self, class_type, method_name):
2561 if class_type.tag != 'MyClass':
2564 for method in self.methods:
2566 worker = method.get_worker(method_name)
2568 workers.append(worker)
2574 Notice that the @code{match} method of @code{MyClassMatcher} returns
2575 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
2576 method, and a worker object of type @code{MyClassWorker_plus} for the
2577 @code{operator+} method. This is done indirectly via helper classes
2578 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
2579 @code{methods} attribute in a matcher as it is optional. However, if a
2580 matcher manages more than one xmethod, it is a good practice to list the
2581 xmethods in the @code{methods} attribute of the matcher. This will then
2582 facilitate enabling and disabling individual xmethods via the
2583 @code{enable/disable} commands. Notice also that a worker object is
2584 returned only if the corresponding entry in the @code{methods} attribute
2585 of the matcher is enabled.
2587 The implementation of the worker classes returned by the matcher setup
2588 above is as follows:
2591 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
2592 def get_arg_types(self):
2595 def get_result_type(self, obj):
2596 return gdb.lookup_type('int')
2598 def __call__(self, obj):
2602 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
2603 def get_arg_types(self):
2604 return gdb.lookup_type('MyClass')
2606 def get_result_type(self, obj):
2607 return gdb.lookup_type('int')
2609 def __call__(self, obj, other):
2610 return obj['a_'] + other['a_']
2613 For @value{GDBN} to actually lookup a xmethod, it has to be
2614 registered with it. The matcher defined above is registered with
2615 @value{GDBN} globally as follows:
2618 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
2621 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
2629 then, after loading the Python script defining the xmethod matchers
2630 and workers into @code{GDBN}, invoking the method @code{geta} or using
2631 the operator @code{+} on @code{obj} will invoke the xmethods
2642 Consider another example with a C++ template class:
2649 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
2650 ~MyTemplate () @{ delete [] data_; @}
2652 int footprint (void)
2654 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
2663 Let us implement an xmethod for the above class which serves as a
2664 replacement for the @code{footprint} method. The full code listing
2665 of the xmethod workers and xmethod matchers is as follows:
2668 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
2669 def __init__(self, class_type):
2670 self.class_type = class_type
2672 def get_arg_types(self):
2675 def get_result_type(self):
2676 return gdb.lookup_type('int')
2678 def __call__(self, obj):
2679 return (self.class_type.sizeof +
2681 self.class_type.template_argument(0).sizeof)
2684 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
2686 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
2688 def match(self, class_type, method_name):
2689 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
2691 method_name == 'footprint'):
2692 return MyTemplateWorker_footprint(class_type)
2695 Notice that, in this example, we have not used the @code{methods}
2696 attribute of the matcher as the matcher manages only one xmethod. The
2697 user can enable/disable this xmethod by enabling/disabling the matcher
2700 @node Inferiors In Python
2701 @subsubsection Inferiors In Python
2702 @cindex inferiors in Python
2704 @findex gdb.Inferior
2705 Programs which are being run under @value{GDBN} are called inferiors
2706 (@pxref{Inferiors and Programs}). Python scripts can access
2707 information about and manipulate inferiors controlled by @value{GDBN}
2708 via objects of the @code{gdb.Inferior} class.
2710 The following inferior-related functions are available in the @code{gdb}
2713 @defun gdb.inferiors ()
2714 Return a tuple containing all inferior objects.
2717 @defun gdb.selected_inferior ()
2718 Return an object representing the current inferior.
2721 A @code{gdb.Inferior} object has the following attributes:
2723 @defvar Inferior.num
2724 ID of inferior, as assigned by GDB.
2727 @defvar Inferior.pid
2728 Process ID of the inferior, as assigned by the underlying operating
2732 @defvar Inferior.was_attached
2733 Boolean signaling whether the inferior was created using `attach', or
2734 started by @value{GDBN} itself.
2737 A @code{gdb.Inferior} object has the following methods:
2739 @defun Inferior.is_valid ()
2740 Returns @code{True} if the @code{gdb.Inferior} object is valid,
2741 @code{False} if not. A @code{gdb.Inferior} object will become invalid
2742 if the inferior no longer exists within @value{GDBN}. All other
2743 @code{gdb.Inferior} methods will throw an exception if it is invalid
2744 at the time the method is called.
2747 @defun Inferior.threads ()
2748 This method returns a tuple holding all the threads which are valid
2749 when it is called. If there are no valid threads, the method will
2750 return an empty tuple.
2753 @findex Inferior.read_memory
2754 @defun Inferior.read_memory (address, length)
2755 Read @var{length} addressable memory units from the inferior, starting at
2756 @var{address}. Returns a buffer object, which behaves much like an array
2757 or a string. It can be modified and given to the
2758 @code{Inferior.write_memory} function. In @code{Python} 3, the return
2759 value is a @code{memoryview} object.
2762 @findex Inferior.write_memory
2763 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
2764 Write the contents of @var{buffer} to the inferior, starting at
2765 @var{address}. The @var{buffer} parameter must be a Python object
2766 which supports the buffer protocol, i.e., a string, an array or the
2767 object returned from @code{Inferior.read_memory}. If given, @var{length}
2768 determines the number of addressable memory units from @var{buffer} to be
2772 @findex gdb.search_memory
2773 @defun Inferior.search_memory (address, length, pattern)
2774 Search a region of the inferior memory starting at @var{address} with
2775 the given @var{length} using the search pattern supplied in
2776 @var{pattern}. The @var{pattern} parameter must be a Python object
2777 which supports the buffer protocol, i.e., a string, an array or the
2778 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
2779 containing the address where the pattern was found, or @code{None} if
2780 the pattern could not be found.
2783 @node Events In Python
2784 @subsubsection Events In Python
2785 @cindex inferior events in Python
2787 @value{GDBN} provides a general event facility so that Python code can be
2788 notified of various state changes, particularly changes that occur in
2791 An @dfn{event} is just an object that describes some state change. The
2792 type of the object and its attributes will vary depending on the details
2793 of the change. All the existing events are described below.
2795 In order to be notified of an event, you must register an event handler
2796 with an @dfn{event registry}. An event registry is an object in the
2797 @code{gdb.events} module which dispatches particular events. A registry
2798 provides methods to register and unregister event handlers:
2800 @defun EventRegistry.connect (object)
2801 Add the given callable @var{object} to the registry. This object will be
2802 called when an event corresponding to this registry occurs.
2805 @defun EventRegistry.disconnect (object)
2806 Remove the given @var{object} from the registry. Once removed, the object
2807 will no longer receive notifications of events.
2813 def exit_handler (event):
2814 print "event type: exit"
2815 print "exit code: %d" % (event.exit_code)
2817 gdb.events.exited.connect (exit_handler)
2820 In the above example we connect our handler @code{exit_handler} to the
2821 registry @code{events.exited}. Once connected, @code{exit_handler} gets
2822 called when the inferior exits. The argument @dfn{event} in this example is
2823 of type @code{gdb.ExitedEvent}. As you can see in the example the
2824 @code{ExitedEvent} object has an attribute which indicates the exit code of
2827 The following is a listing of the event registries that are available and
2828 details of the events they emit:
2833 Emits @code{gdb.ThreadEvent}.
2835 Some events can be thread specific when @value{GDBN} is running in non-stop
2836 mode. When represented in Python, these events all extend
2837 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
2838 events which are emitted by this or other modules might extend this event.
2839 Examples of these events are @code{gdb.BreakpointEvent} and
2840 @code{gdb.ContinueEvent}.
2842 @defvar ThreadEvent.inferior_thread
2843 In non-stop mode this attribute will be set to the specific thread which was
2844 involved in the emitted event. Otherwise, it will be set to @code{None}.
2847 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
2849 This event indicates that the inferior has been continued after a stop. For
2850 inherited attribute refer to @code{gdb.ThreadEvent} above.
2853 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
2854 @code{events.ExitedEvent} has two attributes:
2855 @defvar ExitedEvent.exit_code
2856 An integer representing the exit code, if available, which the inferior
2857 has returned. (The exit code could be unavailable if, for example,
2858 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
2859 the attribute does not exist.
2861 @defvar ExitedEvent inferior
2862 A reference to the inferior which triggered the @code{exited} event.
2866 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
2868 Indicates that the inferior has stopped. All events emitted by this registry
2869 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
2870 will indicate the stopped thread when @value{GDBN} is running in non-stop
2871 mode. Refer to @code{gdb.ThreadEvent} above for more details.
2873 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
2875 This event indicates that the inferior or one of its threads has received as
2876 signal. @code{gdb.SignalEvent} has the following attributes:
2878 @defvar SignalEvent.stop_signal
2879 A string representing the signal received by the inferior. A list of possible
2880 signal values can be obtained by running the command @code{info signals} in
2881 the @value{GDBN} command prompt.
2884 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
2886 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
2887 been hit, and has the following attributes:
2889 @defvar BreakpointEvent.breakpoints
2890 A sequence containing references to all the breakpoints (type
2891 @code{gdb.Breakpoint}) that were hit.
2892 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
2894 @defvar BreakpointEvent.breakpoint
2895 A reference to the first breakpoint that was hit.
2896 This function is maintained for backward compatibility and is now deprecated
2897 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
2900 @item events.new_objfile
2901 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
2902 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
2904 @defvar NewObjFileEvent.new_objfile
2905 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
2906 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
2909 @item events.clear_objfiles
2910 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
2911 files for a program space has been reset.
2912 @code{gdb.ClearObjFilesEvent} has one attribute:
2914 @defvar ClearObjFilesEvent.progspace
2915 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
2916 been cleared. @xref{Progspaces In Python}.
2919 @item events.inferior_call_pre
2920 Emits @code{gdb.InferiorCallPreEvent} which indicates that a function in
2921 the inferior is about to be called.
2923 @defvar InferiorCallPreEvent.ptid
2924 The thread in which the call will be run.
2927 @defvar InferiorCallPreEvent.address
2928 The location of the function to be called.
2931 @item events.inferior_call_post
2932 Emits @code{gdb.InferiorCallPostEvent} which indicates that a function in
2933 the inferior has returned.
2935 @defvar InferiorCallPostEvent.ptid
2936 The thread in which the call was run.
2939 @defvar InferiorCallPostEvent.address
2940 The location of the function that was called.
2943 @item events.memory_changed
2944 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
2945 inferior has been modified by the @value{GDBN} user, for instance via a
2946 command like @w{@code{set *addr = value}}. The event has the following
2949 @defvar MemoryChangedEvent.address
2950 The start address of the changed region.
2953 @defvar MemoryChangedEvent.length
2954 Length in bytes of the changed region.
2957 @item events.register_changed
2958 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
2959 inferior has been modified by the @value{GDBN} user.
2961 @defvar RegisterChangedEvent.frame
2962 A gdb.Frame object representing the frame in which the register was modified.
2964 @defvar RegisterChangedEvent.regnum
2965 Denotes which register was modified.
2968 @item events.breakpoint_created
2969 This is emitted when a new breakpoint has been created. The argument
2970 that is passed is the new @code{gdb.Breakpoint} object.
2972 @item events.breakpoint_modified
2973 This is emitted when a breakpoint has been modified in some way. The
2974 argument that is passed is the new @code{gdb.Breakpoint} object.
2976 @item events.breakpoint_deleted
2977 This is emitted when a breakpoint has been deleted. The argument that
2978 is passed is the @code{gdb.Breakpoint} object. When this event is
2979 emitted, the @code{gdb.Breakpoint} object will already be in its
2980 invalid state; that is, the @code{is_valid} method will return
2985 @node Threads In Python
2986 @subsubsection Threads In Python
2987 @cindex threads in python
2989 @findex gdb.InferiorThread
2990 Python scripts can access information about, and manipulate inferior threads
2991 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
2993 The following thread-related functions are available in the @code{gdb}
2996 @findex gdb.selected_thread
2997 @defun gdb.selected_thread ()
2998 This function returns the thread object for the selected thread. If there
2999 is no selected thread, this will return @code{None}.
3002 A @code{gdb.InferiorThread} object has the following attributes:
3004 @defvar InferiorThread.name
3005 The name of the thread. If the user specified a name using
3006 @code{thread name}, then this returns that name. Otherwise, if an
3007 OS-supplied name is available, then it is returned. Otherwise, this
3008 returns @code{None}.
3010 This attribute can be assigned to. The new value must be a string
3011 object, which sets the new name, or @code{None}, which removes any
3012 user-specified thread name.
3015 @defvar InferiorThread.num
3016 The per-inferior number of the thread, as assigned by GDB.
3019 @defvar InferiorThread.global_num
3020 The global ID of the thread, as assigned by GDB. You can use this to
3021 make Python breakpoints thread-specific, for example
3022 (@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
3025 @defvar InferiorThread.ptid
3026 ID of the thread, as assigned by the operating system. This attribute is a
3027 tuple containing three integers. The first is the Process ID (PID); the second
3028 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
3029 Either the LWPID or TID may be 0, which indicates that the operating system
3030 does not use that identifier.
3033 @defvar InferiorThread.inferior
3034 The inferior this thread belongs to. This attribute is represented as
3035 a @code{gdb.Inferior} object. This attribute is not writable.
3038 A @code{gdb.InferiorThread} object has the following methods:
3040 @defun InferiorThread.is_valid ()
3041 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
3042 @code{False} if not. A @code{gdb.InferiorThread} object will become
3043 invalid if the thread exits, or the inferior that the thread belongs
3044 is deleted. All other @code{gdb.InferiorThread} methods will throw an
3045 exception if it is invalid at the time the method is called.
3048 @defun InferiorThread.switch ()
3049 This changes @value{GDBN}'s currently selected thread to the one represented
3053 @defun InferiorThread.is_stopped ()
3054 Return a Boolean indicating whether the thread is stopped.
3057 @defun InferiorThread.is_running ()
3058 Return a Boolean indicating whether the thread is running.
3061 @defun InferiorThread.is_exited ()
3062 Return a Boolean indicating whether the thread is exited.
3065 @node Commands In Python
3066 @subsubsection Commands In Python
3068 @cindex commands in python
3069 @cindex python commands
3070 You can implement new @value{GDBN} CLI commands in Python. A CLI
3071 command is implemented using an instance of the @code{gdb.Command}
3072 class, most commonly using a subclass.
3074 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
3075 The object initializer for @code{Command} registers the new command
3076 with @value{GDBN}. This initializer is normally invoked from the
3077 subclass' own @code{__init__} method.
3079 @var{name} is the name of the command. If @var{name} consists of
3080 multiple words, then the initial words are looked for as prefix
3081 commands. In this case, if one of the prefix commands does not exist,
3082 an exception is raised.
3084 There is no support for multi-line commands.
3086 @var{command_class} should be one of the @samp{COMMAND_} constants
3087 defined below. This argument tells @value{GDBN} how to categorize the
3088 new command in the help system.
3090 @var{completer_class} is an optional argument. If given, it should be
3091 one of the @samp{COMPLETE_} constants defined below. This argument
3092 tells @value{GDBN} how to perform completion for this command. If not
3093 given, @value{GDBN} will attempt to complete using the object's
3094 @code{complete} method (see below); if no such method is found, an
3095 error will occur when completion is attempted.
3097 @var{prefix} is an optional argument. If @code{True}, then the new
3098 command is a prefix command; sub-commands of this command may be
3101 The help text for the new command is taken from the Python
3102 documentation string for the command's class, if there is one. If no
3103 documentation string is provided, the default value ``This command is
3104 not documented.'' is used.
3107 @cindex don't repeat Python command
3108 @defun Command.dont_repeat ()
3109 By default, a @value{GDBN} command is repeated when the user enters a
3110 blank line at the command prompt. A command can suppress this
3111 behavior by invoking the @code{dont_repeat} method. This is similar
3112 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
3115 @defun Command.invoke (argument, from_tty)
3116 This method is called by @value{GDBN} when this command is invoked.
3118 @var{argument} is a string. It is the argument to the command, after
3119 leading and trailing whitespace has been stripped.
3121 @var{from_tty} is a boolean argument. When true, this means that the
3122 command was entered by the user at the terminal; when false it means
3123 that the command came from elsewhere.
3125 If this method throws an exception, it is turned into a @value{GDBN}
3126 @code{error} call. Otherwise, the return value is ignored.
3128 @findex gdb.string_to_argv
3129 To break @var{argument} up into an argv-like string use
3130 @code{gdb.string_to_argv}. This function behaves identically to
3131 @value{GDBN}'s internal argument lexer @code{buildargv}.
3132 It is recommended to use this for consistency.
3133 Arguments are separated by spaces and may be quoted.
3137 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
3138 ['1', '2 "3', '4 "5', "6 '7"]
3143 @cindex completion of Python commands
3144 @defun Command.complete (text, word)
3145 This method is called by @value{GDBN} when the user attempts
3146 completion on this command. All forms of completion are handled by
3147 this method, that is, the @key{TAB} and @key{M-?} key bindings
3148 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
3151 The arguments @var{text} and @var{word} are both strings; @var{text}
3152 holds the complete command line up to the cursor's location, while
3153 @var{word} holds the last word of the command line; this is computed
3154 using a word-breaking heuristic.
3156 The @code{complete} method can return several values:
3159 If the return value is a sequence, the contents of the sequence are
3160 used as the completions. It is up to @code{complete} to ensure that the
3161 contents actually do complete the word. A zero-length sequence is
3162 allowed, it means that there were no completions available. Only
3163 string elements of the sequence are used; other elements in the
3164 sequence are ignored.
3167 If the return value is one of the @samp{COMPLETE_} constants defined
3168 below, then the corresponding @value{GDBN}-internal completion
3169 function is invoked, and its result is used.
3172 All other results are treated as though there were no available
3177 When a new command is registered, it must be declared as a member of
3178 some general class of commands. This is used to classify top-level
3179 commands in the on-line help system; note that prefix commands are not
3180 listed under their own category but rather that of their top-level
3181 command. The available classifications are represented by constants
3182 defined in the @code{gdb} module:
3185 @findex COMMAND_NONE
3186 @findex gdb.COMMAND_NONE
3187 @item gdb.COMMAND_NONE
3188 The command does not belong to any particular class. A command in
3189 this category will not be displayed in any of the help categories.
3191 @findex COMMAND_RUNNING
3192 @findex gdb.COMMAND_RUNNING
3193 @item gdb.COMMAND_RUNNING
3194 The command is related to running the inferior. For example,
3195 @code{start}, @code{step}, and @code{continue} are in this category.
3196 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
3197 commands in this category.
3199 @findex COMMAND_DATA
3200 @findex gdb.COMMAND_DATA
3201 @item gdb.COMMAND_DATA
3202 The command is related to data or variables. For example,
3203 @code{call}, @code{find}, and @code{print} are in this category. Type
3204 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
3207 @findex COMMAND_STACK
3208 @findex gdb.COMMAND_STACK
3209 @item gdb.COMMAND_STACK
3210 The command has to do with manipulation of the stack. For example,
3211 @code{backtrace}, @code{frame}, and @code{return} are in this
3212 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
3213 list of commands in this category.
3215 @findex COMMAND_FILES
3216 @findex gdb.COMMAND_FILES
3217 @item gdb.COMMAND_FILES
3218 This class is used for file-related commands. For example,
3219 @code{file}, @code{list} and @code{section} are in this category.
3220 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
3221 commands in this category.
3223 @findex COMMAND_SUPPORT
3224 @findex gdb.COMMAND_SUPPORT
3225 @item gdb.COMMAND_SUPPORT
3226 This should be used for ``support facilities'', generally meaning
3227 things that are useful to the user when interacting with @value{GDBN},
3228 but not related to the state of the inferior. For example,
3229 @code{help}, @code{make}, and @code{shell} are in this category. Type
3230 @kbd{help support} at the @value{GDBN} prompt to see a list of
3231 commands in this category.
3233 @findex COMMAND_STATUS
3234 @findex gdb.COMMAND_STATUS
3235 @item gdb.COMMAND_STATUS
3236 The command is an @samp{info}-related command, that is, related to the
3237 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
3238 and @code{show} are in this category. Type @kbd{help status} at the
3239 @value{GDBN} prompt to see a list of commands in this category.
3241 @findex COMMAND_BREAKPOINTS
3242 @findex gdb.COMMAND_BREAKPOINTS
3243 @item gdb.COMMAND_BREAKPOINTS
3244 The command has to do with breakpoints. For example, @code{break},
3245 @code{clear}, and @code{delete} are in this category. Type @kbd{help
3246 breakpoints} at the @value{GDBN} prompt to see a list of commands in
3249 @findex COMMAND_TRACEPOINTS
3250 @findex gdb.COMMAND_TRACEPOINTS
3251 @item gdb.COMMAND_TRACEPOINTS
3252 The command has to do with tracepoints. For example, @code{trace},
3253 @code{actions}, and @code{tfind} are in this category. Type
3254 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
3255 commands in this category.
3257 @findex COMMAND_USER
3258 @findex gdb.COMMAND_USER
3259 @item gdb.COMMAND_USER
3260 The command is a general purpose command for the user, and typically
3261 does not fit in one of the other categories.
3262 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
3263 a list of commands in this category, as well as the list of gdb macros
3264 (@pxref{Sequences}).
3266 @findex COMMAND_OBSCURE
3267 @findex gdb.COMMAND_OBSCURE
3268 @item gdb.COMMAND_OBSCURE
3269 The command is only used in unusual circumstances, or is not of
3270 general interest to users. For example, @code{checkpoint},
3271 @code{fork}, and @code{stop} are in this category. Type @kbd{help
3272 obscure} at the @value{GDBN} prompt to see a list of commands in this
3275 @findex COMMAND_MAINTENANCE
3276 @findex gdb.COMMAND_MAINTENANCE
3277 @item gdb.COMMAND_MAINTENANCE
3278 The command is only useful to @value{GDBN} maintainers. The
3279 @code{maintenance} and @code{flushregs} commands are in this category.
3280 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
3281 commands in this category.
3284 A new command can use a predefined completion function, either by
3285 specifying it via an argument at initialization, or by returning it
3286 from the @code{complete} method. These predefined completion
3287 constants are all defined in the @code{gdb} module:
3290 @vindex COMPLETE_NONE
3291 @item gdb.COMPLETE_NONE
3292 This constant means that no completion should be done.
3294 @vindex COMPLETE_FILENAME
3295 @item gdb.COMPLETE_FILENAME
3296 This constant means that filename completion should be performed.
3298 @vindex COMPLETE_LOCATION
3299 @item gdb.COMPLETE_LOCATION
3300 This constant means that location completion should be done.
3301 @xref{Specify Location}.
3303 @vindex COMPLETE_COMMAND
3304 @item gdb.COMPLETE_COMMAND
3305 This constant means that completion should examine @value{GDBN}
3308 @vindex COMPLETE_SYMBOL
3309 @item gdb.COMPLETE_SYMBOL
3310 This constant means that completion should be done using symbol names
3313 @vindex COMPLETE_EXPRESSION
3314 @item gdb.COMPLETE_EXPRESSION
3315 This constant means that completion should be done on expressions.
3316 Often this means completing on symbol names, but some language
3317 parsers also have support for completing on field names.
3320 The following code snippet shows how a trivial CLI command can be
3321 implemented in Python:
3324 class HelloWorld (gdb.Command):
3325 """Greet the whole world."""
3327 def __init__ (self):
3328 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
3330 def invoke (self, arg, from_tty):
3331 print "Hello, World!"
3336 The last line instantiates the class, and is necessary to trigger the
3337 registration of the command with @value{GDBN}. Depending on how the
3338 Python code is read into @value{GDBN}, you may need to import the
3339 @code{gdb} module explicitly.
3341 @node Parameters In Python
3342 @subsubsection Parameters In Python
3344 @cindex parameters in python
3345 @cindex python parameters
3346 @tindex gdb.Parameter
3348 You can implement new @value{GDBN} parameters using Python. A new
3349 parameter is implemented as an instance of the @code{gdb.Parameter}
3352 Parameters are exposed to the user via the @code{set} and
3353 @code{show} commands. @xref{Help}.
3355 There are many parameters that already exist and can be set in
3356 @value{GDBN}. Two examples are: @code{set follow fork} and
3357 @code{set charset}. Setting these parameters influences certain
3358 behavior in @value{GDBN}. Similarly, you can define parameters that
3359 can be used to influence behavior in custom Python scripts and commands.
3361 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
3362 The object initializer for @code{Parameter} registers the new
3363 parameter with @value{GDBN}. This initializer is normally invoked
3364 from the subclass' own @code{__init__} method.
3366 @var{name} is the name of the new parameter. If @var{name} consists
3367 of multiple words, then the initial words are looked for as prefix
3368 parameters. An example of this can be illustrated with the
3369 @code{set print} set of parameters. If @var{name} is
3370 @code{print foo}, then @code{print} will be searched as the prefix
3371 parameter. In this case the parameter can subsequently be accessed in
3372 @value{GDBN} as @code{set print foo}.
3374 If @var{name} consists of multiple words, and no prefix parameter group
3375 can be found, an exception is raised.
3377 @var{command-class} should be one of the @samp{COMMAND_} constants
3378 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
3379 categorize the new parameter in the help system.
3381 @var{parameter-class} should be one of the @samp{PARAM_} constants
3382 defined below. This argument tells @value{GDBN} the type of the new
3383 parameter; this information is used for input validation and
3386 If @var{parameter-class} is @code{PARAM_ENUM}, then
3387 @var{enum-sequence} must be a sequence of strings. These strings
3388 represent the possible values for the parameter.
3390 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
3391 of a fourth argument will cause an exception to be thrown.
3393 The help text for the new parameter is taken from the Python
3394 documentation string for the parameter's class, if there is one. If
3395 there is no documentation string, a default value is used.
3398 @defvar Parameter.set_doc
3399 If this attribute exists, and is a string, then its value is used as
3400 the help text for this parameter's @code{set} command. The value is
3401 examined when @code{Parameter.__init__} is invoked; subsequent changes
3405 @defvar Parameter.show_doc
3406 If this attribute exists, and is a string, then its value is used as
3407 the help text for this parameter's @code{show} command. The value is
3408 examined when @code{Parameter.__init__} is invoked; subsequent changes
3412 @defvar Parameter.value
3413 The @code{value} attribute holds the underlying value of the
3414 parameter. It can be read and assigned to just as any other
3415 attribute. @value{GDBN} does validation when assignments are made.
3418 There are two methods that should be implemented in any
3419 @code{Parameter} class. These are:
3421 @defun Parameter.get_set_string (self)
3422 @value{GDBN} will call this method when a @var{parameter}'s value has
3423 been changed via the @code{set} API (for example, @kbd{set foo off}).
3424 The @code{value} attribute has already been populated with the new
3425 value and may be used in output. This method must return a string.
3428 @defun Parameter.get_show_string (self, svalue)
3429 @value{GDBN} will call this method when a @var{parameter}'s
3430 @code{show} API has been invoked (for example, @kbd{show foo}). The
3431 argument @code{svalue} receives the string representation of the
3432 current value. This method must return a string.
3435 When a new parameter is defined, its type must be specified. The
3436 available types are represented by constants defined in the @code{gdb}
3440 @findex PARAM_BOOLEAN
3441 @findex gdb.PARAM_BOOLEAN
3442 @item gdb.PARAM_BOOLEAN
3443 The value is a plain boolean. The Python boolean values, @code{True}
3444 and @code{False} are the only valid values.
3446 @findex PARAM_AUTO_BOOLEAN
3447 @findex gdb.PARAM_AUTO_BOOLEAN
3448 @item gdb.PARAM_AUTO_BOOLEAN
3449 The value has three possible states: true, false, and @samp{auto}. In
3450 Python, true and false are represented using boolean constants, and
3451 @samp{auto} is represented using @code{None}.
3453 @findex PARAM_UINTEGER
3454 @findex gdb.PARAM_UINTEGER
3455 @item gdb.PARAM_UINTEGER
3456 The value is an unsigned integer. The value of 0 should be
3457 interpreted to mean ``unlimited''.
3459 @findex PARAM_INTEGER
3460 @findex gdb.PARAM_INTEGER
3461 @item gdb.PARAM_INTEGER
3462 The value is a signed integer. The value of 0 should be interpreted
3463 to mean ``unlimited''.
3465 @findex PARAM_STRING
3466 @findex gdb.PARAM_STRING
3467 @item gdb.PARAM_STRING
3468 The value is a string. When the user modifies the string, any escape
3469 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
3470 translated into corresponding characters and encoded into the current
3473 @findex PARAM_STRING_NOESCAPE
3474 @findex gdb.PARAM_STRING_NOESCAPE
3475 @item gdb.PARAM_STRING_NOESCAPE
3476 The value is a string. When the user modifies the string, escapes are
3477 passed through untranslated.
3479 @findex PARAM_OPTIONAL_FILENAME
3480 @findex gdb.PARAM_OPTIONAL_FILENAME
3481 @item gdb.PARAM_OPTIONAL_FILENAME
3482 The value is a either a filename (a string), or @code{None}.
3484 @findex PARAM_FILENAME
3485 @findex gdb.PARAM_FILENAME
3486 @item gdb.PARAM_FILENAME
3487 The value is a filename. This is just like
3488 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
3490 @findex PARAM_ZINTEGER
3491 @findex gdb.PARAM_ZINTEGER
3492 @item gdb.PARAM_ZINTEGER
3493 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
3494 is interpreted as itself.
3497 @findex gdb.PARAM_ENUM
3498 @item gdb.PARAM_ENUM
3499 The value is a string, which must be one of a collection string
3500 constants provided when the parameter is created.
3503 @node Functions In Python
3504 @subsubsection Writing new convenience functions
3506 @cindex writing convenience functions
3507 @cindex convenience functions in python
3508 @cindex python convenience functions
3509 @tindex gdb.Function
3511 You can implement new convenience functions (@pxref{Convenience Vars})
3512 in Python. A convenience function is an instance of a subclass of the
3513 class @code{gdb.Function}.
3515 @defun Function.__init__ (name)
3516 The initializer for @code{Function} registers the new function with
3517 @value{GDBN}. The argument @var{name} is the name of the function,
3518 a string. The function will be visible to the user as a convenience
3519 variable of type @code{internal function}, whose name is the same as
3520 the given @var{name}.
3522 The documentation for the new function is taken from the documentation
3523 string for the new class.
3526 @defun Function.invoke (@var{*args})
3527 When a convenience function is evaluated, its arguments are converted
3528 to instances of @code{gdb.Value}, and then the function's
3529 @code{invoke} method is called. Note that @value{GDBN} does not
3530 predetermine the arity of convenience functions. Instead, all
3531 available arguments are passed to @code{invoke}, following the
3532 standard Python calling convention. In particular, a convenience
3533 function can have default values for parameters without ill effect.
3535 The return value of this method is used as its value in the enclosing
3536 expression. If an ordinary Python value is returned, it is converted
3537 to a @code{gdb.Value} following the usual rules.
3540 The following code snippet shows how a trivial convenience function can
3541 be implemented in Python:
3544 class Greet (gdb.Function):
3545 """Return string to greet someone.
3546 Takes a name as argument."""
3548 def __init__ (self):
3549 super (Greet, self).__init__ ("greet")
3551 def invoke (self, name):
3552 return "Hello, %s!" % name.string ()
3557 The last line instantiates the class, and is necessary to trigger the
3558 registration of the function with @value{GDBN}. Depending on how the
3559 Python code is read into @value{GDBN}, you may need to import the
3560 @code{gdb} module explicitly.
3562 Now you can use the function in an expression:
3565 (gdb) print $greet("Bob")
3569 @node Progspaces In Python
3570 @subsubsection Program Spaces In Python
3572 @cindex progspaces in python
3573 @tindex gdb.Progspace
3575 A program space, or @dfn{progspace}, represents a symbolic view
3576 of an address space.
3577 It consists of all of the objfiles of the program.
3578 @xref{Objfiles In Python}.
3579 @xref{Inferiors and Programs, program spaces}, for more details
3580 about program spaces.
3582 The following progspace-related functions are available in the
3585 @findex gdb.current_progspace
3586 @defun gdb.current_progspace ()
3587 This function returns the program space of the currently selected inferior.
3588 @xref{Inferiors and Programs}.
3591 @findex gdb.progspaces
3592 @defun gdb.progspaces ()
3593 Return a sequence of all the progspaces currently known to @value{GDBN}.
3596 Each progspace is represented by an instance of the @code{gdb.Progspace}
3599 @defvar Progspace.filename
3600 The file name of the progspace as a string.
3603 @defvar Progspace.pretty_printers
3604 The @code{pretty_printers} attribute is a list of functions. It is
3605 used to look up pretty-printers. A @code{Value} is passed to each
3606 function in order; if the function returns @code{None}, then the
3607 search continues. Otherwise, the return value should be an object
3608 which is used to format the value. @xref{Pretty Printing API}, for more
3612 @defvar Progspace.type_printers
3613 The @code{type_printers} attribute is a list of type printer objects.
3614 @xref{Type Printing API}, for more information.
3617 @defvar Progspace.frame_filters
3618 The @code{frame_filters} attribute is a dictionary of frame filter
3619 objects. @xref{Frame Filter API}, for more information.
3622 One may add arbitrary attributes to @code{gdb.Progspace} objects
3623 in the usual Python way.
3624 This is useful if, for example, one needs to do some extra record keeping
3625 associated with the program space.
3627 In this contrived example, we want to perform some processing when
3628 an objfile with a certain symbol is loaded, but we only want to do
3629 this once because it is expensive. To achieve this we record the results
3630 with the program space because we can't predict when the desired objfile
3635 def clear_objfiles_handler(event):
3636 event.progspace.expensive_computation = None
3637 def expensive(symbol):
3638 """A mock routine to perform an "expensive" computation on symbol."""
3639 print "Computing the answer to the ultimate question ..."
3641 def new_objfile_handler(event):
3642 objfile = event.new_objfile
3643 progspace = objfile.progspace
3644 if not hasattr(progspace, 'expensive_computation') or \
3645 progspace.expensive_computation is None:
3646 # We use 'main' for the symbol to keep the example simple.
3647 # Note: There's no current way to constrain the lookup
3649 symbol = gdb.lookup_global_symbol('main')
3650 if symbol is not None:
3651 progspace.expensive_computation = expensive(symbol)
3652 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
3653 gdb.events.new_objfile.connect(new_objfile_handler)
3655 (gdb) file /tmp/hello
3656 Reading symbols from /tmp/hello...done.
3657 Computing the answer to the ultimate question ...
3658 (gdb) python print gdb.current_progspace().expensive_computation
3661 Starting program: /tmp/hello
3663 [Inferior 1 (process 4242) exited normally]
3666 @node Objfiles In Python
3667 @subsubsection Objfiles In Python
3669 @cindex objfiles in python
3672 @value{GDBN} loads symbols for an inferior from various
3673 symbol-containing files (@pxref{Files}). These include the primary
3674 executable file, any shared libraries used by the inferior, and any
3675 separate debug info files (@pxref{Separate Debug Files}).
3676 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
3678 The following objfile-related functions are available in the
3681 @findex gdb.current_objfile
3682 @defun gdb.current_objfile ()
3683 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
3684 sets the ``current objfile'' to the corresponding objfile. This
3685 function returns the current objfile. If there is no current objfile,
3686 this function returns @code{None}.
3689 @findex gdb.objfiles
3690 @defun gdb.objfiles ()
3691 Return a sequence of all the objfiles current known to @value{GDBN}.
3692 @xref{Objfiles In Python}.
3695 @findex gdb.lookup_objfile
3696 @defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
3697 Look up @var{name}, a file name or build ID, in the list of objfiles
3698 for the current program space (@pxref{Progspaces In Python}).
3699 If the objfile is not found throw the Python @code{ValueError} exception.
3701 If @var{name} is a relative file name, then it will match any
3702 source file name with the same trailing components. For example, if
3703 @var{name} is @samp{gcc/expr.c}, then it will match source file
3704 name of @file{/build/trunk/gcc/expr.c}, but not
3705 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
3707 If @var{by_build_id} is provided and is @code{True} then @var{name}
3708 is the build ID of the objfile. Otherwise, @var{name} is a file name.
3709 This is supported only on some operating systems, notably those which use
3710 the ELF format for binary files and the @sc{gnu} Binutils. For more details
3711 about this feature, see the description of the @option{--build-id}
3712 command-line option in @ref{Options, , Command Line Options, ld.info,
3716 Each objfile is represented by an instance of the @code{gdb.Objfile}
3719 @defvar Objfile.filename
3720 The file name of the objfile as a string, with symbolic links resolved.
3722 The value is @code{None} if the objfile is no longer valid.
3723 See the @code{gdb.Objfile.is_valid} method, described below.
3726 @defvar Objfile.username
3727 The file name of the objfile as specified by the user as a string.
3729 The value is @code{None} if the objfile is no longer valid.
3730 See the @code{gdb.Objfile.is_valid} method, described below.
3733 @defvar Objfile.owner
3734 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
3735 object that debug info is being provided for.
3736 Otherwise this is @code{None}.
3737 Separate debug info objfiles are added with the
3738 @code{gdb.Objfile.add_separate_debug_file} method, described below.
3741 @defvar Objfile.build_id
3742 The build ID of the objfile as a string.
3743 If the objfile does not have a build ID then the value is @code{None}.
3745 This is supported only on some operating systems, notably those which use
3746 the ELF format for binary files and the @sc{gnu} Binutils. For more details
3747 about this feature, see the description of the @option{--build-id}
3748 command-line option in @ref{Options, , Command Line Options, ld.info,
3752 @defvar Objfile.progspace
3753 The containing program space of the objfile as a @code{gdb.Progspace}
3754 object. @xref{Progspaces In Python}.
3757 @defvar Objfile.pretty_printers
3758 The @code{pretty_printers} attribute is a list of functions. It is
3759 used to look up pretty-printers. A @code{Value} is passed to each
3760 function in order; if the function returns @code{None}, then the
3761 search continues. Otherwise, the return value should be an object
3762 which is used to format the value. @xref{Pretty Printing API}, for more
3766 @defvar Objfile.type_printers
3767 The @code{type_printers} attribute is a list of type printer objects.
3768 @xref{Type Printing API}, for more information.
3771 @defvar Objfile.frame_filters
3772 The @code{frame_filters} attribute is a dictionary of frame filter
3773 objects. @xref{Frame Filter API}, for more information.
3776 One may add arbitrary attributes to @code{gdb.Objfile} objects
3777 in the usual Python way.
3778 This is useful if, for example, one needs to do some extra record keeping
3779 associated with the objfile.
3781 In this contrived example we record the time when @value{GDBN}
3787 def new_objfile_handler(event):
3788 # Set the time_loaded attribute of the new objfile.
3789 event.new_objfile.time_loaded = datetime.datetime.today()
3790 gdb.events.new_objfile.connect(new_objfile_handler)
3793 Reading symbols from ./hello...done.
3794 (gdb) python print gdb.objfiles()[0].time_loaded
3795 2014-10-09 11:41:36.770345
3798 A @code{gdb.Objfile} object has the following methods:
3800 @defun Objfile.is_valid ()
3801 Returns @code{True} if the @code{gdb.Objfile} object is valid,
3802 @code{False} if not. A @code{gdb.Objfile} object can become invalid
3803 if the object file it refers to is not loaded in @value{GDBN} any
3804 longer. All other @code{gdb.Objfile} methods will throw an exception
3805 if it is invalid at the time the method is called.
3808 @defun Objfile.add_separate_debug_file (file)
3809 Add @var{file} to the list of files that @value{GDBN} will search for
3810 debug information for the objfile.
3811 This is useful when the debug info has been removed from the program
3812 and stored in a separate file. @value{GDBN} has built-in support for
3813 finding separate debug info files (@pxref{Separate Debug Files}), but if
3814 the file doesn't live in one of the standard places that @value{GDBN}
3815 searches then this function can be used to add a debug info file
3816 from a different place.
3819 @node Frames In Python
3820 @subsubsection Accessing inferior stack frames from Python.
3822 @cindex frames in python
3823 When the debugged program stops, @value{GDBN} is able to analyze its call
3824 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
3825 represents a frame in the stack. A @code{gdb.Frame} object is only valid
3826 while its corresponding frame exists in the inferior's stack. If you try
3827 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
3828 exception (@pxref{Exception Handling}).
3830 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
3834 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
3838 The following frame-related functions are available in the @code{gdb} module:
3840 @findex gdb.selected_frame
3841 @defun gdb.selected_frame ()
3842 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
3845 @findex gdb.newest_frame
3846 @defun gdb.newest_frame ()
3847 Return the newest frame object for the selected thread.
3850 @defun gdb.frame_stop_reason_string (reason)
3851 Return a string explaining the reason why @value{GDBN} stopped unwinding
3852 frames, as expressed by the given @var{reason} code (an integer, see the
3853 @code{unwind_stop_reason} method further down in this section).
3856 @findex gdb.invalidate_cached_frames
3857 @defun gdb.invalidate_cached_frames
3858 @value{GDBN} internally keeps a cache of the frames that have been
3859 unwound. This function invalidates this cache.
3861 This function should not generally be called by ordinary Python code.
3862 It is documented for the sake of completeness.
3865 A @code{gdb.Frame} object has the following methods:
3867 @defun Frame.is_valid ()
3868 Returns true if the @code{gdb.Frame} object is valid, false if not.
3869 A frame object can become invalid if the frame it refers to doesn't
3870 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
3871 an exception if it is invalid at the time the method is called.
3874 @defun Frame.name ()
3875 Returns the function name of the frame, or @code{None} if it can't be
3879 @defun Frame.architecture ()
3880 Returns the @code{gdb.Architecture} object corresponding to the frame's
3881 architecture. @xref{Architectures In Python}.
3884 @defun Frame.type ()
3885 Returns the type of the frame. The value can be one of:
3887 @item gdb.NORMAL_FRAME
3888 An ordinary stack frame.
3890 @item gdb.DUMMY_FRAME
3891 A fake stack frame that was created by @value{GDBN} when performing an
3892 inferior function call.
3894 @item gdb.INLINE_FRAME
3895 A frame representing an inlined function. The function was inlined
3896 into a @code{gdb.NORMAL_FRAME} that is older than this one.
3898 @item gdb.TAILCALL_FRAME
3899 A frame representing a tail call. @xref{Tail Call Frames}.
3901 @item gdb.SIGTRAMP_FRAME
3902 A signal trampoline frame. This is the frame created by the OS when
3903 it calls into a signal handler.
3905 @item gdb.ARCH_FRAME
3906 A fake stack frame representing a cross-architecture call.
3908 @item gdb.SENTINEL_FRAME
3909 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
3914 @defun Frame.unwind_stop_reason ()
3915 Return an integer representing the reason why it's not possible to find
3916 more frames toward the outermost frame. Use
3917 @code{gdb.frame_stop_reason_string} to convert the value returned by this
3918 function to a string. The value can be one of:
3921 @item gdb.FRAME_UNWIND_NO_REASON
3922 No particular reason (older frames should be available).
3924 @item gdb.FRAME_UNWIND_NULL_ID
3925 The previous frame's analyzer returns an invalid result. This is no
3926 longer used by @value{GDBN}, and is kept only for backward
3929 @item gdb.FRAME_UNWIND_OUTERMOST
3930 This frame is the outermost.
3932 @item gdb.FRAME_UNWIND_UNAVAILABLE
3933 Cannot unwind further, because that would require knowing the
3934 values of registers or memory that have not been collected.
3936 @item gdb.FRAME_UNWIND_INNER_ID
3937 This frame ID looks like it ought to belong to a NEXT frame,
3938 but we got it for a PREV frame. Normally, this is a sign of
3939 unwinder failure. It could also indicate stack corruption.
3941 @item gdb.FRAME_UNWIND_SAME_ID
3942 This frame has the same ID as the previous one. That means
3943 that unwinding further would almost certainly give us another
3944 frame with exactly the same ID, so break the chain. Normally,
3945 this is a sign of unwinder failure. It could also indicate
3948 @item gdb.FRAME_UNWIND_NO_SAVED_PC
3949 The frame unwinder did not find any saved PC, but we needed
3950 one to unwind further.
3952 @item gdb.FRAME_UNWIND_MEMORY_ERROR
3953 The frame unwinder caused an error while trying to access memory.
3955 @item gdb.FRAME_UNWIND_FIRST_ERROR
3956 Any stop reason greater or equal to this value indicates some kind
3957 of error. This special value facilitates writing code that tests
3958 for errors in unwinding in a way that will work correctly even if
3959 the list of the other values is modified in future @value{GDBN}
3960 versions. Using it, you could write:
3962 reason = gdb.selected_frame().unwind_stop_reason ()
3963 reason_str = gdb.frame_stop_reason_string (reason)
3964 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
3965 print "An error occured: %s" % reason_str
3972 Returns the frame's resume address.
3975 @defun Frame.block ()
3976 Return the frame's code block. @xref{Blocks In Python}.
3979 @defun Frame.function ()
3980 Return the symbol for the function corresponding to this frame.
3981 @xref{Symbols In Python}.
3984 @defun Frame.older ()
3985 Return the frame that called this frame.
3988 @defun Frame.newer ()
3989 Return the frame called by this frame.
3992 @defun Frame.find_sal ()
3993 Return the frame's symtab and line object.
3994 @xref{Symbol Tables In Python}.
3997 @defun Frame.read_register (register)
3998 Return the value of @var{register} in this frame. The @var{register}
3999 argument must be a string (e.g., @code{'sp'} or @code{'rax'}).
4000 Returns a @code{Gdb.Value} object. Throws an exception if @var{register}
4004 @defun Frame.read_var (variable @r{[}, block@r{]})
4005 Return the value of @var{variable} in this frame. If the optional
4006 argument @var{block} is provided, search for the variable from that
4007 block; otherwise start at the frame's current block (which is
4008 determined by the frame's current program counter). The @var{variable}
4009 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
4010 @code{gdb.Block} object.
4013 @defun Frame.select ()
4014 Set this frame to be the selected frame. @xref{Stack, ,Examining the
4018 @node Blocks In Python
4019 @subsubsection Accessing blocks from Python.
4021 @cindex blocks in python
4024 In @value{GDBN}, symbols are stored in blocks. A block corresponds
4025 roughly to a scope in the source code. Blocks are organized
4026 hierarchically, and are represented individually in Python as a
4027 @code{gdb.Block}. Blocks rely on debugging information being
4030 A frame has a block. Please see @ref{Frames In Python}, for a more
4031 in-depth discussion of frames.
4033 The outermost block is known as the @dfn{global block}. The global
4034 block typically holds public global variables and functions.
4036 The block nested just inside the global block is the @dfn{static
4037 block}. The static block typically holds file-scoped variables and
4040 @value{GDBN} provides a method to get a block's superblock, but there
4041 is currently no way to examine the sub-blocks of a block, or to
4042 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
4045 Here is a short example that should help explain blocks:
4048 /* This is in the global block. */
4051 /* This is in the static block. */
4052 static int file_scope;
4054 /* 'function' is in the global block, and 'argument' is
4055 in a block nested inside of 'function'. */
4056 int function (int argument)
4058 /* 'local' is in a block inside 'function'. It may or may
4059 not be in the same block as 'argument'. */
4063 /* 'inner' is in a block whose superblock is the one holding
4067 /* If this call is expanded by the compiler, you may see
4068 a nested block here whose function is 'inline_function'
4069 and whose superblock is the one holding 'inner'. */
4075 A @code{gdb.Block} is iterable. The iterator returns the symbols
4076 (@pxref{Symbols In Python}) local to the block. Python programs
4077 should not assume that a specific block object will always contain a
4078 given symbol, since changes in @value{GDBN} features and
4079 infrastructure may cause symbols move across blocks in a symbol
4082 The following block-related functions are available in the @code{gdb}
4085 @findex gdb.block_for_pc
4086 @defun gdb.block_for_pc (pc)
4087 Return the innermost @code{gdb.Block} containing the given @var{pc}
4088 value. If the block cannot be found for the @var{pc} value specified,
4089 the function will return @code{None}.
4092 A @code{gdb.Block} object has the following methods:
4094 @defun Block.is_valid ()
4095 Returns @code{True} if the @code{gdb.Block} object is valid,
4096 @code{False} if not. A block object can become invalid if the block it
4097 refers to doesn't exist anymore in the inferior. All other
4098 @code{gdb.Block} methods will throw an exception if it is invalid at
4099 the time the method is called. The block's validity is also checked
4100 during iteration over symbols of the block.
4103 A @code{gdb.Block} object has the following attributes:
4106 The start address of the block. This attribute is not writable.
4110 The end address of the block. This attribute is not writable.
4113 @defvar Block.function
4114 The name of the block represented as a @code{gdb.Symbol}. If the
4115 block is not named, then this attribute holds @code{None}. This
4116 attribute is not writable.
4118 For ordinary function blocks, the superblock is the static block.
4119 However, you should note that it is possible for a function block to
4120 have a superblock that is not the static block -- for instance this
4121 happens for an inlined function.
4124 @defvar Block.superblock
4125 The block containing this block. If this parent block does not exist,
4126 this attribute holds @code{None}. This attribute is not writable.
4129 @defvar Block.global_block
4130 The global block associated with this block. This attribute is not
4134 @defvar Block.static_block
4135 The static block associated with this block. This attribute is not
4139 @defvar Block.is_global
4140 @code{True} if the @code{gdb.Block} object is a global block,
4141 @code{False} if not. This attribute is not
4145 @defvar Block.is_static
4146 @code{True} if the @code{gdb.Block} object is a static block,
4147 @code{False} if not. This attribute is not writable.
4150 @node Symbols In Python
4151 @subsubsection Python representation of Symbols.
4153 @cindex symbols in python
4156 @value{GDBN} represents every variable, function and type as an
4157 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
4158 Similarly, Python represents these symbols in @value{GDBN} with the
4159 @code{gdb.Symbol} object.
4161 The following symbol-related functions are available in the @code{gdb}
4164 @findex gdb.lookup_symbol
4165 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
4166 This function searches for a symbol by name. The search scope can be
4167 restricted to the parameters defined in the optional domain and block
4170 @var{name} is the name of the symbol. It must be a string. The
4171 optional @var{block} argument restricts the search to symbols visible
4172 in that @var{block}. The @var{block} argument must be a
4173 @code{gdb.Block} object. If omitted, the block for the current frame
4174 is used. The optional @var{domain} argument restricts
4175 the search to the domain type. The @var{domain} argument must be a
4176 domain constant defined in the @code{gdb} module and described later
4179 The result is a tuple of two elements.
4180 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
4182 If the symbol is found, the second element is @code{True} if the symbol
4183 is a field of a method's object (e.g., @code{this} in C@t{++}),
4184 otherwise it is @code{False}.
4185 If the symbol is not found, the second element is @code{False}.
4188 @findex gdb.lookup_global_symbol
4189 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
4190 This function searches for a global symbol by name.
4191 The search scope can be restricted to by the domain argument.
4193 @var{name} is the name of the symbol. It must be a string.
4194 The optional @var{domain} argument restricts the search to the domain type.
4195 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4196 module and described later in this chapter.
4198 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4202 A @code{gdb.Symbol} object has the following attributes:
4205 The type of the symbol or @code{None} if no type is recorded.
4206 This attribute is represented as a @code{gdb.Type} object.
4207 @xref{Types In Python}. This attribute is not writable.
4210 @defvar Symbol.symtab
4211 The symbol table in which the symbol appears. This attribute is
4212 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
4213 Python}. This attribute is not writable.
4217 The line number in the source code at which the symbol was defined.
4222 The name of the symbol as a string. This attribute is not writable.
4225 @defvar Symbol.linkage_name
4226 The name of the symbol, as used by the linker (i.e., may be mangled).
4227 This attribute is not writable.
4230 @defvar Symbol.print_name
4231 The name of the symbol in a form suitable for output. This is either
4232 @code{name} or @code{linkage_name}, depending on whether the user
4233 asked @value{GDBN} to display demangled or mangled names.
4236 @defvar Symbol.addr_class
4237 The address class of the symbol. This classifies how to find the value
4238 of a symbol. Each address class is a constant defined in the
4239 @code{gdb} module and described later in this chapter.
4242 @defvar Symbol.needs_frame
4243 This is @code{True} if evaluating this symbol's value requires a frame
4244 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
4245 local variables will require a frame, but other symbols will not.
4248 @defvar Symbol.is_argument
4249 @code{True} if the symbol is an argument of a function.
4252 @defvar Symbol.is_constant
4253 @code{True} if the symbol is a constant.
4256 @defvar Symbol.is_function
4257 @code{True} if the symbol is a function or a method.
4260 @defvar Symbol.is_variable
4261 @code{True} if the symbol is a variable.
4264 A @code{gdb.Symbol} object has the following methods:
4266 @defun Symbol.is_valid ()
4267 Returns @code{True} if the @code{gdb.Symbol} object is valid,
4268 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
4269 the symbol it refers to does not exist in @value{GDBN} any longer.
4270 All other @code{gdb.Symbol} methods will throw an exception if it is
4271 invalid at the time the method is called.
4274 @defun Symbol.value (@r{[}frame@r{]})
4275 Compute the value of the symbol, as a @code{gdb.Value}. For
4276 functions, this computes the address of the function, cast to the
4277 appropriate type. If the symbol requires a frame in order to compute
4278 its value, then @var{frame} must be given. If @var{frame} is not
4279 given, or if @var{frame} is invalid, then this method will throw an
4283 The available domain categories in @code{gdb.Symbol} are represented
4284 as constants in the @code{gdb} module:
4287 @vindex SYMBOL_UNDEF_DOMAIN
4288 @item gdb.SYMBOL_UNDEF_DOMAIN
4289 This is used when a domain has not been discovered or none of the
4290 following domains apply. This usually indicates an error either
4291 in the symbol information or in @value{GDBN}'s handling of symbols.
4293 @vindex SYMBOL_VAR_DOMAIN
4294 @item gdb.SYMBOL_VAR_DOMAIN
4295 This domain contains variables, function names, typedef names and enum
4298 @vindex SYMBOL_STRUCT_DOMAIN
4299 @item gdb.SYMBOL_STRUCT_DOMAIN
4300 This domain holds struct, union and enum type names.
4302 @vindex SYMBOL_LABEL_DOMAIN
4303 @item gdb.SYMBOL_LABEL_DOMAIN
4304 This domain contains names of labels (for gotos).
4306 @vindex SYMBOL_VARIABLES_DOMAIN
4307 @item gdb.SYMBOL_VARIABLES_DOMAIN
4308 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
4309 contains everything minus functions and types.
4311 @vindex SYMBOL_FUNCTIONS_DOMAIN
4312 @item gdb.SYMBOL_FUNCTION_DOMAIN
4313 This domain contains all functions.
4315 @vindex SYMBOL_TYPES_DOMAIN
4316 @item gdb.SYMBOL_TYPES_DOMAIN
4317 This domain contains all types.
4320 The available address class categories in @code{gdb.Symbol} are represented
4321 as constants in the @code{gdb} module:
4324 @vindex SYMBOL_LOC_UNDEF
4325 @item gdb.SYMBOL_LOC_UNDEF
4326 If this is returned by address class, it indicates an error either in
4327 the symbol information or in @value{GDBN}'s handling of symbols.
4329 @vindex SYMBOL_LOC_CONST
4330 @item gdb.SYMBOL_LOC_CONST
4331 Value is constant int.
4333 @vindex SYMBOL_LOC_STATIC
4334 @item gdb.SYMBOL_LOC_STATIC
4335 Value is at a fixed address.
4337 @vindex SYMBOL_LOC_REGISTER
4338 @item gdb.SYMBOL_LOC_REGISTER
4339 Value is in a register.
4341 @vindex SYMBOL_LOC_ARG
4342 @item gdb.SYMBOL_LOC_ARG
4343 Value is an argument. This value is at the offset stored within the
4344 symbol inside the frame's argument list.
4346 @vindex SYMBOL_LOC_REF_ARG
4347 @item gdb.SYMBOL_LOC_REF_ARG
4348 Value address is stored in the frame's argument list. Just like
4349 @code{LOC_ARG} except that the value's address is stored at the
4350 offset, not the value itself.
4352 @vindex SYMBOL_LOC_REGPARM_ADDR
4353 @item gdb.SYMBOL_LOC_REGPARM_ADDR
4354 Value is a specified register. Just like @code{LOC_REGISTER} except
4355 the register holds the address of the argument instead of the argument
4358 @vindex SYMBOL_LOC_LOCAL
4359 @item gdb.SYMBOL_LOC_LOCAL
4360 Value is a local variable.
4362 @vindex SYMBOL_LOC_TYPEDEF
4363 @item gdb.SYMBOL_LOC_TYPEDEF
4364 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
4367 @vindex SYMBOL_LOC_BLOCK
4368 @item gdb.SYMBOL_LOC_BLOCK
4371 @vindex SYMBOL_LOC_CONST_BYTES
4372 @item gdb.SYMBOL_LOC_CONST_BYTES
4373 Value is a byte-sequence.
4375 @vindex SYMBOL_LOC_UNRESOLVED
4376 @item gdb.SYMBOL_LOC_UNRESOLVED
4377 Value is at a fixed address, but the address of the variable has to be
4378 determined from the minimal symbol table whenever the variable is
4381 @vindex SYMBOL_LOC_OPTIMIZED_OUT
4382 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
4383 The value does not actually exist in the program.
4385 @vindex SYMBOL_LOC_COMPUTED
4386 @item gdb.SYMBOL_LOC_COMPUTED
4387 The value's address is a computed location.
4390 @node Symbol Tables In Python
4391 @subsubsection Symbol table representation in Python.
4393 @cindex symbol tables in python
4395 @tindex gdb.Symtab_and_line
4397 Access to symbol table data maintained by @value{GDBN} on the inferior
4398 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
4399 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
4400 from the @code{find_sal} method in @code{gdb.Frame} object.
4401 @xref{Frames In Python}.
4403 For more information on @value{GDBN}'s symbol table management, see
4404 @ref{Symbols, ,Examining the Symbol Table}, for more information.
4406 A @code{gdb.Symtab_and_line} object has the following attributes:
4408 @defvar Symtab_and_line.symtab
4409 The symbol table object (@code{gdb.Symtab}) for this frame.
4410 This attribute is not writable.
4413 @defvar Symtab_and_line.pc
4414 Indicates the start of the address range occupied by code for the
4415 current source line. This attribute is not writable.
4418 @defvar Symtab_and_line.last
4419 Indicates the end of the address range occupied by code for the current
4420 source line. This attribute is not writable.
4423 @defvar Symtab_and_line.line
4424 Indicates the current line number for this object. This
4425 attribute is not writable.
4428 A @code{gdb.Symtab_and_line} object has the following methods:
4430 @defun Symtab_and_line.is_valid ()
4431 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
4432 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
4433 invalid if the Symbol table and line object it refers to does not
4434 exist in @value{GDBN} any longer. All other
4435 @code{gdb.Symtab_and_line} methods will throw an exception if it is
4436 invalid at the time the method is called.
4439 A @code{gdb.Symtab} object has the following attributes:
4441 @defvar Symtab.filename
4442 The symbol table's source filename. This attribute is not writable.
4445 @defvar Symtab.objfile
4446 The symbol table's backing object file. @xref{Objfiles In Python}.
4447 This attribute is not writable.
4450 @defvar Symtab.producer
4451 The name and possibly version number of the program that
4452 compiled the code in the symbol table.
4453 The contents of this string is up to the compiler.
4454 If no producer information is available then @code{None} is returned.
4455 This attribute is not writable.
4458 A @code{gdb.Symtab} object has the following methods:
4460 @defun Symtab.is_valid ()
4461 Returns @code{True} if the @code{gdb.Symtab} object is valid,
4462 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
4463 the symbol table it refers to does not exist in @value{GDBN} any
4464 longer. All other @code{gdb.Symtab} methods will throw an exception
4465 if it is invalid at the time the method is called.
4468 @defun Symtab.fullname ()
4469 Return the symbol table's source absolute file name.
4472 @defun Symtab.global_block ()
4473 Return the global block of the underlying symbol table.
4474 @xref{Blocks In Python}.
4477 @defun Symtab.static_block ()
4478 Return the static block of the underlying symbol table.
4479 @xref{Blocks In Python}.
4482 @defun Symtab.linetable ()
4483 Return the line table associated with the symbol table.
4484 @xref{Line Tables In Python}.
4487 @node Line Tables In Python
4488 @subsubsection Manipulating line tables using Python
4490 @cindex line tables in python
4491 @tindex gdb.LineTable
4493 Python code can request and inspect line table information from a
4494 symbol table that is loaded in @value{GDBN}. A line table is a
4495 mapping of source lines to their executable locations in memory. To
4496 acquire the line table information for a particular symbol table, use
4497 the @code{linetable} function (@pxref{Symbol Tables In Python}).
4499 A @code{gdb.LineTable} is iterable. The iterator returns
4500 @code{LineTableEntry} objects that correspond to the source line and
4501 address for each line table entry. @code{LineTableEntry} objects have
4502 the following attributes:
4504 @defvar LineTableEntry.line
4505 The source line number for this line table entry. This number
4506 corresponds to the actual line of source. This attribute is not
4510 @defvar LineTableEntry.pc
4511 The address that is associated with the line table entry where the
4512 executable code for that source line resides in memory. This
4513 attribute is not writable.
4516 As there can be multiple addresses for a single source line, you may
4517 receive multiple @code{LineTableEntry} objects with matching
4518 @code{line} attributes, but with different @code{pc} attributes. The
4519 iterator is sorted in ascending @code{pc} order. Here is a small
4520 example illustrating iterating over a line table.
4523 symtab = gdb.selected_frame().find_sal().symtab
4524 linetable = symtab.linetable()
4525 for line in linetable:
4526 print "Line: "+str(line.line)+" Address: "+hex(line.pc)
4529 This will have the following output:
4532 Line: 33 Address: 0x4005c8L
4533 Line: 37 Address: 0x4005caL
4534 Line: 39 Address: 0x4005d2L
4535 Line: 40 Address: 0x4005f8L
4536 Line: 42 Address: 0x4005ffL
4537 Line: 44 Address: 0x400608L
4538 Line: 42 Address: 0x40060cL
4539 Line: 45 Address: 0x400615L
4542 In addition to being able to iterate over a @code{LineTable}, it also
4543 has the following direct access methods:
4545 @defun LineTable.line (line)
4546 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
4547 entries in the line table for the given @var{line}, which specifies
4548 the source code line. If there are no entries for that source code
4549 @var{line}, the Python @code{None} is returned.
4552 @defun LineTable.has_line (line)
4553 Return a Python @code{Boolean} indicating whether there is an entry in
4554 the line table for this source line. Return @code{True} if an entry
4555 is found, or @code{False} if not.
4558 @defun LineTable.source_lines ()
4559 Return a Python @code{List} of the source line numbers in the symbol
4560 table. Only lines with executable code locations are returned. The
4561 contents of the @code{List} will just be the source line entries
4562 represented as Python @code{Long} values.
4565 @node Breakpoints In Python
4566 @subsubsection Manipulating breakpoints using Python
4568 @cindex breakpoints in python
4569 @tindex gdb.Breakpoint
4571 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
4574 @defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
4575 Create a new breakpoint according to @var{spec}, which is a string
4576 naming the location of the breakpoint, or an expression that defines a
4577 watchpoint. The contents can be any location recognized by the
4578 @code{break} command, or in the case of a watchpoint, by the
4579 @code{watch} command. The optional @var{type} denotes the breakpoint
4580 to create from the types defined later in this chapter. This argument
4581 can be either @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}; it
4582 defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
4583 argument allows the breakpoint to become invisible to the user. The
4584 breakpoint will neither be reported when created, nor will it be
4585 listed in the output from @code{info breakpoints} (but will be listed
4586 with the @code{maint info breakpoints} command). The optional
4587 @var{temporary} argument makes the breakpoint a temporary breakpoint.
4588 Temporary breakpoints are deleted after they have been hit. Any
4589 further access to the Python breakpoint after it has been hit will
4590 result in a runtime error (as that breakpoint has now been
4591 automatically deleted). The optional @var{wp_class} argument defines
4592 the class of watchpoint to create, if @var{type} is
4593 @code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it
4594 is assumed to be a @code{gdb.WP_WRITE} class.
4597 The available types are represented by constants defined in the @code{gdb}
4601 @vindex BP_BREAKPOINT
4602 @item gdb.BP_BREAKPOINT
4603 Normal code breakpoint.
4605 @vindex BP_WATCHPOINT
4606 @item gdb.BP_WATCHPOINT
4607 Watchpoint breakpoint.
4609 @vindex BP_HARDWARE_WATCHPOINT
4610 @item gdb.BP_HARDWARE_WATCHPOINT
4611 Hardware assisted watchpoint.
4613 @vindex BP_READ_WATCHPOINT
4614 @item gdb.BP_READ_WATCHPOINT
4615 Hardware assisted read watchpoint.
4617 @vindex BP_ACCESS_WATCHPOINT
4618 @item gdb.BP_ACCESS_WATCHPOINT
4619 Hardware assisted access watchpoint.
4622 The available watchpoint types represented by constants are defined in the
4628 Read only watchpoint.
4632 Write only watchpoint.
4636 Read/Write watchpoint.
4639 @defun Breakpoint.stop (self)
4640 The @code{gdb.Breakpoint} class can be sub-classed and, in
4641 particular, you may choose to implement the @code{stop} method.
4642 If this method is defined in a sub-class of @code{gdb.Breakpoint},
4643 it will be called when the inferior reaches any location of a
4644 breakpoint which instantiates that sub-class. If the method returns
4645 @code{True}, the inferior will be stopped at the location of the
4646 breakpoint, otherwise the inferior will continue.
4648 If there are multiple breakpoints at the same location with a
4649 @code{stop} method, each one will be called regardless of the
4650 return status of the previous. This ensures that all @code{stop}
4651 methods have a chance to execute at that location. In this scenario
4652 if one of the methods returns @code{True} but the others return
4653 @code{False}, the inferior will still be stopped.
4655 You should not alter the execution state of the inferior (i.e.@:, step,
4656 next, etc.), alter the current frame context (i.e.@:, change the current
4657 active frame), or alter, add or delete any breakpoint. As a general
4658 rule, you should not alter any data within @value{GDBN} or the inferior
4661 Example @code{stop} implementation:
4664 class MyBreakpoint (gdb.Breakpoint):
4666 inf_val = gdb.parse_and_eval("foo")
4673 @defun Breakpoint.is_valid ()
4674 Return @code{True} if this @code{Breakpoint} object is valid,
4675 @code{False} otherwise. A @code{Breakpoint} object can become invalid
4676 if the user deletes the breakpoint. In this case, the object still
4677 exists, but the underlying breakpoint does not. In the cases of
4678 watchpoint scope, the watchpoint remains valid even if execution of the
4679 inferior leaves the scope of that watchpoint.
4682 @defun Breakpoint.delete ()
4683 Permanently deletes the @value{GDBN} breakpoint. This also
4684 invalidates the Python @code{Breakpoint} object. Any further access
4685 to this object's attributes or methods will raise an error.
4688 @defvar Breakpoint.enabled
4689 This attribute is @code{True} if the breakpoint is enabled, and
4690 @code{False} otherwise. This attribute is writable. You can use it to enable
4691 or disable the breakpoint.
4694 @defvar Breakpoint.silent
4695 This attribute is @code{True} if the breakpoint is silent, and
4696 @code{False} otherwise. This attribute is writable.
4698 Note that a breakpoint can also be silent if it has commands and the
4699 first command is @code{silent}. This is not reported by the
4700 @code{silent} attribute.
4703 @defvar Breakpoint.pending
4704 This attribute is @code{True} if the breakpoint is pending, and
4705 @code{False} otherwise. @xref{Set Breaks}. This attribute is
4709 @anchor{python_breakpoint_thread}
4710 @defvar Breakpoint.thread
4711 If the breakpoint is thread-specific, this attribute holds the
4712 thread's global id. If the breakpoint is not thread-specific, this
4713 attribute is @code{None}. This attribute is writable.
4716 @defvar Breakpoint.task
4717 If the breakpoint is Ada task-specific, this attribute holds the Ada task
4718 id. If the breakpoint is not task-specific (or the underlying
4719 language is not Ada), this attribute is @code{None}. This attribute
4723 @defvar Breakpoint.ignore_count
4724 This attribute holds the ignore count for the breakpoint, an integer.
4725 This attribute is writable.
4728 @defvar Breakpoint.number
4729 This attribute holds the breakpoint's number --- the identifier used by
4730 the user to manipulate the breakpoint. This attribute is not writable.
4733 @defvar Breakpoint.type
4734 This attribute holds the breakpoint's type --- the identifier used to
4735 determine the actual breakpoint type or use-case. This attribute is not
4739 @defvar Breakpoint.visible
4740 This attribute tells whether the breakpoint is visible to the user
4741 when set, or when the @samp{info breakpoints} command is run. This
4742 attribute is not writable.
4745 @defvar Breakpoint.temporary
4746 This attribute indicates whether the breakpoint was created as a
4747 temporary breakpoint. Temporary breakpoints are automatically deleted
4748 after that breakpoint has been hit. Access to this attribute, and all
4749 other attributes and functions other than the @code{is_valid}
4750 function, will result in an error after the breakpoint has been hit
4751 (as it has been automatically deleted). This attribute is not
4755 @defvar Breakpoint.hit_count
4756 This attribute holds the hit count for the breakpoint, an integer.
4757 This attribute is writable, but currently it can only be set to zero.
4760 @defvar Breakpoint.location
4761 This attribute holds the location of the breakpoint, as specified by
4762 the user. It is a string. If the breakpoint does not have a location
4763 (that is, it is a watchpoint) the attribute's value is @code{None}. This
4764 attribute is not writable.
4767 @defvar Breakpoint.expression
4768 This attribute holds a breakpoint expression, as specified by
4769 the user. It is a string. If the breakpoint does not have an
4770 expression (the breakpoint is not a watchpoint) the attribute's value
4771 is @code{None}. This attribute is not writable.
4774 @defvar Breakpoint.condition
4775 This attribute holds the condition of the breakpoint, as specified by
4776 the user. It is a string. If there is no condition, this attribute's
4777 value is @code{None}. This attribute is writable.
4780 @defvar Breakpoint.commands
4781 This attribute holds the commands attached to the breakpoint. If
4782 there are commands, this attribute's value is a string holding all the
4783 commands, separated by newlines. If there are no commands, this
4784 attribute is @code{None}. This attribute is not writable.
4787 @node Finish Breakpoints in Python
4788 @subsubsection Finish Breakpoints
4790 @cindex python finish breakpoints
4791 @tindex gdb.FinishBreakpoint
4793 A finish breakpoint is a temporary breakpoint set at the return address of
4794 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
4795 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
4796 and deleted when the execution will run out of the breakpoint scope (i.e.@:
4797 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
4798 Finish breakpoints are thread specific and must be create with the right
4801 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
4802 Create a finish breakpoint at the return address of the @code{gdb.Frame}
4803 object @var{frame}. If @var{frame} is not provided, this defaults to the
4804 newest frame. The optional @var{internal} argument allows the breakpoint to
4805 become invisible to the user. @xref{Breakpoints In Python}, for further
4806 details about this argument.
4809 @defun FinishBreakpoint.out_of_scope (self)
4810 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
4811 @code{return} command, @dots{}), a function may not properly terminate, and
4812 thus never hit the finish breakpoint. When @value{GDBN} notices such a
4813 situation, the @code{out_of_scope} callback will be triggered.
4815 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
4819 class MyFinishBreakpoint (gdb.FinishBreakpoint)
4821 print "normal finish"
4824 def out_of_scope ():
4825 print "abnormal finish"
4829 @defvar FinishBreakpoint.return_value
4830 When @value{GDBN} is stopped at a finish breakpoint and the frame
4831 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
4832 attribute will contain a @code{gdb.Value} object corresponding to the return
4833 value of the function. The value will be @code{None} if the function return
4834 type is @code{void} or if the return value was not computable. This attribute
4838 @node Lazy Strings In Python
4839 @subsubsection Python representation of lazy strings.
4841 @cindex lazy strings in python
4842 @tindex gdb.LazyString
4844 A @dfn{lazy string} is a string whose contents is not retrieved or
4845 encoded until it is needed.
4847 A @code{gdb.LazyString} is represented in @value{GDBN} as an
4848 @code{address} that points to a region of memory, an @code{encoding}
4849 that will be used to encode that region of memory, and a @code{length}
4850 to delimit the region of memory that represents the string. The
4851 difference between a @code{gdb.LazyString} and a string wrapped within
4852 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
4853 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
4854 retrieved and encoded during printing, while a @code{gdb.Value}
4855 wrapping a string is immediately retrieved and encoded on creation.
4857 A @code{gdb.LazyString} object has the following functions:
4859 @defun LazyString.value ()
4860 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
4861 will point to the string in memory, but will lose all the delayed
4862 retrieval, encoding and handling that @value{GDBN} applies to a
4863 @code{gdb.LazyString}.
4866 @defvar LazyString.address
4867 This attribute holds the address of the string. This attribute is not
4871 @defvar LazyString.length
4872 This attribute holds the length of the string in characters. If the
4873 length is -1, then the string will be fetched and encoded up to the
4874 first null of appropriate width. This attribute is not writable.
4877 @defvar LazyString.encoding
4878 This attribute holds the encoding that will be applied to the string
4879 when the string is printed by @value{GDBN}. If the encoding is not
4880 set, or contains an empty string, then @value{GDBN} will select the
4881 most appropriate encoding when the string is printed. This attribute
4885 @defvar LazyString.type
4886 This attribute holds the type that is represented by the lazy string's
4887 type. For a lazy string this will always be a pointer type. To
4888 resolve this to the lazy string's character type, use the type's
4889 @code{target} method. @xref{Types In Python}. This attribute is not
4893 @node Architectures In Python
4894 @subsubsection Python representation of architectures
4895 @cindex Python architectures
4897 @value{GDBN} uses architecture specific parameters and artifacts in a
4898 number of its various computations. An architecture is represented
4899 by an instance of the @code{gdb.Architecture} class.
4901 A @code{gdb.Architecture} class has the following methods:
4903 @defun Architecture.name ()
4904 Return the name (string value) of the architecture.
4907 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
4908 Return a list of disassembled instructions starting from the memory
4909 address @var{start_pc}. The optional arguments @var{end_pc} and
4910 @var{count} determine the number of instructions in the returned list.
4911 If both the optional arguments @var{end_pc} and @var{count} are
4912 specified, then a list of at most @var{count} disassembled instructions
4913 whose start address falls in the closed memory address interval from
4914 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
4915 specified, but @var{count} is specified, then @var{count} number of
4916 instructions starting from the address @var{start_pc} are returned. If
4917 @var{count} is not specified but @var{end_pc} is specified, then all
4918 instructions whose start address falls in the closed memory address
4919 interval from @var{start_pc} to @var{end_pc} are returned. If neither
4920 @var{end_pc} nor @var{count} are specified, then a single instruction at
4921 @var{start_pc} is returned. For all of these cases, each element of the
4922 returned list is a Python @code{dict} with the following string keys:
4927 The value corresponding to this key is a Python long integer capturing
4928 the memory address of the instruction.
4931 The value corresponding to this key is a string value which represents
4932 the instruction with assembly language mnemonics. The assembly
4933 language flavor used is the same as that specified by the current CLI
4934 variable @code{disassembly-flavor}. @xref{Machine Code}.
4937 The value corresponding to this key is the length (integer value) of the
4938 instruction in bytes.
4943 @node Python Auto-loading
4944 @subsection Python Auto-loading
4945 @cindex Python auto-loading
4947 When a new object file is read (for example, due to the @code{file}
4948 command, or because the inferior has loaded a shared library),
4949 @value{GDBN} will look for Python support scripts in several ways:
4950 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
4951 @xref{Auto-loading extensions}.
4953 The auto-loading feature is useful for supplying application-specific
4954 debugging commands and scripts.
4956 Auto-loading can be enabled or disabled,
4957 and the list of auto-loaded scripts can be printed.
4960 @anchor{set auto-load python-scripts}
4961 @kindex set auto-load python-scripts
4962 @item set auto-load python-scripts [on|off]
4963 Enable or disable the auto-loading of Python scripts.
4965 @anchor{show auto-load python-scripts}
4966 @kindex show auto-load python-scripts
4967 @item show auto-load python-scripts
4968 Show whether auto-loading of Python scripts is enabled or disabled.
4970 @anchor{info auto-load python-scripts}
4971 @kindex info auto-load python-scripts
4972 @cindex print list of auto-loaded Python scripts
4973 @item info auto-load python-scripts [@var{regexp}]
4974 Print the list of all Python scripts that @value{GDBN} auto-loaded.
4976 Also printed is the list of Python scripts that were mentioned in
4977 the @code{.debug_gdb_scripts} section and were either not found
4978 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
4979 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
4980 This is useful because their names are not printed when @value{GDBN}
4981 tries to load them and fails. There may be many of them, and printing
4982 an error message for each one is problematic.
4984 If @var{regexp} is supplied only Python scripts with matching names are printed.
4989 (gdb) info auto-load python-scripts
4991 Yes py-section-script.py
4992 full name: /tmp/py-section-script.py
4993 No my-foo-pretty-printers.py
4997 When reading an auto-loaded file or script, @value{GDBN} sets the
4998 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
4999 function (@pxref{Objfiles In Python}). This can be useful for
5000 registering objfile-specific pretty-printers and frame-filters.
5002 @node Python modules
5003 @subsection Python modules
5004 @cindex python modules
5006 @value{GDBN} comes with several modules to assist writing Python code.
5009 * gdb.printing:: Building and registering pretty-printers.
5010 * gdb.types:: Utilities for working with types.
5011 * gdb.prompt:: Utilities for prompt value substitution.
5015 @subsubsection gdb.printing
5016 @cindex gdb.printing
5018 This module provides a collection of utilities for working with
5022 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
5023 This class specifies the API that makes @samp{info pretty-printer},
5024 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
5025 Pretty-printers should generally inherit from this class.
5027 @item SubPrettyPrinter (@var{name})
5028 For printers that handle multiple types, this class specifies the
5029 corresponding API for the subprinters.
5031 @item RegexpCollectionPrettyPrinter (@var{name})
5032 Utility class for handling multiple printers, all recognized via
5033 regular expressions.
5034 @xref{Writing a Pretty-Printer}, for an example.
5036 @item FlagEnumerationPrinter (@var{name})
5037 A pretty-printer which handles printing of @code{enum} values. Unlike
5038 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
5039 work properly when there is some overlap between the enumeration
5040 constants. The argument @var{name} is the name of the printer and
5041 also the name of the @code{enum} type to look up.
5043 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
5044 Register @var{printer} with the pretty-printer list of @var{obj}.
5045 If @var{replace} is @code{True} then any existing copy of the printer
5046 is replaced. Otherwise a @code{RuntimeError} exception is raised
5047 if a printer with the same name already exists.
5051 @subsubsection gdb.types
5054 This module provides a collection of utilities for working with
5055 @code{gdb.Type} objects.
5058 @item get_basic_type (@var{type})
5059 Return @var{type} with const and volatile qualifiers stripped,
5060 and with typedefs and C@t{++} references converted to the underlying type.
5065 typedef const int const_int;
5067 const_int& foo_ref (foo);
5068 int main () @{ return 0; @}
5075 (gdb) python import gdb.types
5076 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
5077 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
5081 @item has_field (@var{type}, @var{field})
5082 Return @code{True} if @var{type}, assumed to be a type with fields
5083 (e.g., a structure or union), has field @var{field}.
5085 @item make_enum_dict (@var{enum_type})
5086 Return a Python @code{dictionary} type produced from @var{enum_type}.
5088 @item deep_items (@var{type})
5089 Returns a Python iterator similar to the standard
5090 @code{gdb.Type.iteritems} method, except that the iterator returned
5091 by @code{deep_items} will recursively traverse anonymous struct or
5092 union fields. For example:
5106 Then in @value{GDBN}:
5108 (@value{GDBP}) python import gdb.types
5109 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
5110 (@value{GDBP}) python print struct_a.keys ()
5112 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
5113 @{['a', 'b0', 'b1']@}
5116 @item get_type_recognizers ()
5117 Return a list of the enabled type recognizers for the current context.
5118 This is called by @value{GDBN} during the type-printing process
5119 (@pxref{Type Printing API}).
5121 @item apply_type_recognizers (recognizers, type_obj)
5122 Apply the type recognizers, @var{recognizers}, to the type object
5123 @var{type_obj}. If any recognizer returns a string, return that
5124 string. Otherwise, return @code{None}. This is called by
5125 @value{GDBN} during the type-printing process (@pxref{Type Printing
5128 @item register_type_printer (locus, printer)
5129 This is a convenience function to register a type printer
5130 @var{printer}. The printer must implement the type printer protocol.
5131 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
5132 the printer is registered with that objfile; a @code{gdb.Progspace},
5133 in which case the printer is registered with that progspace; or
5134 @code{None}, in which case the printer is registered globally.
5137 This is a base class that implements the type printer protocol. Type
5138 printers are encouraged, but not required, to derive from this class.
5139 It defines a constructor:
5141 @defmethod TypePrinter __init__ (self, name)
5142 Initialize the type printer with the given name. The new printer
5143 starts in the enabled state.
5149 @subsubsection gdb.prompt
5152 This module provides a method for prompt value-substitution.
5155 @item substitute_prompt (@var{string})
5156 Return @var{string} with escape sequences substituted by values. Some
5157 escape sequences take arguments. You can specify arguments inside
5158 ``@{@}'' immediately following the escape sequence.
5160 The escape sequences you can pass to this function are:
5164 Substitute a backslash.
5166 Substitute an ESC character.
5168 Substitute the selected frame; an argument names a frame parameter.
5170 Substitute a newline.
5172 Substitute a parameter's value; the argument names the parameter.
5174 Substitute a carriage return.
5176 Substitute the selected thread; an argument names a thread parameter.
5178 Substitute the version of GDB.
5180 Substitute the current working directory.
5182 Begin a sequence of non-printing characters. These sequences are
5183 typically used with the ESC character, and are not counted in the string
5184 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
5185 blue-colored ``(gdb)'' prompt where the length is five.
5187 End a sequence of non-printing characters.
5193 substitute_prompt (``frame: \f,
5194 print arguments: \p@{print frame-arguments@}'')
5197 @exdent will return the string:
5200 "frame: main, print arguments: scalars"