1 @c Copyright (C) 2008-2015 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.
242 @findex gdb.parameter
243 @defun gdb.parameter (parameter)
244 Return the value of a @value{GDBN} @var{parameter} given by its name,
245 a string; the parameter name string may contain spaces if the parameter has a
246 multi-part name. For example, @samp{print object} is a valid
249 If the named parameter does not exist, this function throws a
250 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
251 parameter's value is converted to a Python value of the appropriate
256 @defun gdb.history (number)
257 Return a value from @value{GDBN}'s value history (@pxref{Value
258 History}). The @var{number} argument indicates which history element to return.
259 If @var{number} is negative, then @value{GDBN} will take its absolute value
260 and count backward from the last element (i.e., the most recent element) to
261 find the value to return. If @var{number} is zero, then @value{GDBN} will
262 return the most recent element. If the element specified by @var{number}
263 doesn't exist in the value history, a @code{gdb.error} exception will be
266 If no exception is raised, the return value is always an instance of
267 @code{gdb.Value} (@pxref{Values From Inferior}).
270 @findex gdb.parse_and_eval
271 @defun gdb.parse_and_eval (expression)
272 Parse @var{expression}, which must be a string, as an expression in
273 the current language, evaluate it, and return the result as a
276 This function can be useful when implementing a new command
277 (@pxref{Commands In Python}), as it provides a way to parse the
278 command's argument as an expression. It is also useful simply to
279 compute values, for example, it is the only way to get the value of a
280 convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
283 @findex gdb.find_pc_line
284 @defun gdb.find_pc_line (pc)
285 Return the @code{gdb.Symtab_and_line} object corresponding to the
286 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
287 value of @var{pc} is passed as an argument, then the @code{symtab} and
288 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
289 will be @code{None} and 0 respectively.
292 @findex gdb.post_event
293 @defun gdb.post_event (event)
294 Put @var{event}, a callable object taking no arguments, into
295 @value{GDBN}'s internal event queue. This callable will be invoked at
296 some later point, during @value{GDBN}'s event processing. Events
297 posted using @code{post_event} will be run in the order in which they
298 were posted; however, there is no way to know when they will be
299 processed relative to other events inside @value{GDBN}.
301 @value{GDBN} is not thread-safe. If your Python program uses multiple
302 threads, you must be careful to only call @value{GDBN}-specific
303 functions in the @value{GDBN} thread. @code{post_event} ensures
307 (@value{GDBP}) python
311 > def __init__(self, message):
312 > self.message = message;
313 > def __call__(self):
314 > gdb.write(self.message)
316 >class MyThread1 (threading.Thread):
318 > gdb.post_event(Writer("Hello "))
320 >class MyThread2 (threading.Thread):
322 > gdb.post_event(Writer("World\n"))
327 (@value{GDBP}) Hello World
332 @defun gdb.write (string @r{[}, stream{]})
333 Print a string to @value{GDBN}'s paginated output stream. The
334 optional @var{stream} determines the stream to print to. The default
335 stream is @value{GDBN}'s standard output stream. Possible stream
342 @value{GDBN}'s standard output stream.
347 @value{GDBN}'s standard error stream.
352 @value{GDBN}'s log stream (@pxref{Logging Output}).
355 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
356 call this function and will automatically direct the output to the
362 Flush the buffer of a @value{GDBN} paginated stream so that the
363 contents are displayed immediately. @value{GDBN} will flush the
364 contents of a stream automatically when it encounters a newline in the
365 buffer. The optional @var{stream} determines the stream to flush. The
366 default stream is @value{GDBN}'s standard output stream. Possible
373 @value{GDBN}'s standard output stream.
378 @value{GDBN}'s standard error stream.
383 @value{GDBN}'s log stream (@pxref{Logging Output}).
387 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
388 call this function for the relevant stream.
391 @findex gdb.target_charset
392 @defun gdb.target_charset ()
393 Return the name of the current target character set (@pxref{Character
394 Sets}). This differs from @code{gdb.parameter('target-charset')} in
395 that @samp{auto} is never returned.
398 @findex gdb.target_wide_charset
399 @defun gdb.target_wide_charset ()
400 Return the name of the current target wide character set
401 (@pxref{Character Sets}). This differs from
402 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
406 @findex gdb.solib_name
407 @defun gdb.solib_name (address)
408 Return the name of the shared library holding the given @var{address}
409 as a string, or @code{None}.
412 @findex gdb.decode_line
413 @defun gdb.decode_line @r{[}expression@r{]}
414 Return locations of the line specified by @var{expression}, or of the
415 current line if no argument was given. This function returns a Python
416 tuple containing two elements. The first element contains a string
417 holding any unparsed section of @var{expression} (or @code{None} if
418 the expression has been fully parsed). The second element contains
419 either @code{None} or another tuple that contains all the locations
420 that match the expression represented as @code{gdb.Symtab_and_line}
421 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
422 provided, it is decoded the way that @value{GDBN}'s inbuilt
423 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
426 @defun gdb.prompt_hook (current_prompt)
429 If @var{prompt_hook} is callable, @value{GDBN} will call the method
430 assigned to this operation before a prompt is displayed by
433 The parameter @code{current_prompt} contains the current @value{GDBN}
434 prompt. This method must return a Python string, or @code{None}. If
435 a string is returned, the @value{GDBN} prompt will be set to that
436 string. If @code{None} is returned, @value{GDBN} will continue to use
439 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
440 such as those used by readline for command input, and annotation
441 related prompts are prohibited from being changed.
444 @node Exception Handling
445 @subsubsection Exception Handling
446 @cindex python exceptions
447 @cindex exceptions, python
449 When executing the @code{python} command, Python exceptions
450 uncaught within the Python code are translated to calls to
451 @value{GDBN} error-reporting mechanism. If the command that called
452 @code{python} does not handle the error, @value{GDBN} will
453 terminate it and print an error message containing the Python
454 exception name, the associated value, and the Python call stack
455 backtrace at the point where the exception was raised. Example:
458 (@value{GDBP}) python print foo
459 Traceback (most recent call last):
460 File "<string>", line 1, in <module>
461 NameError: name 'foo' is not defined
464 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
465 Python code are converted to Python exceptions. The type of the
466 Python exception depends on the error.
470 This is the base class for most exceptions generated by @value{GDBN}.
471 It is derived from @code{RuntimeError}, for compatibility with earlier
472 versions of @value{GDBN}.
474 If an error occurring in @value{GDBN} does not fit into some more
475 specific category, then the generated exception will have this type.
477 @item gdb.MemoryError
478 This is a subclass of @code{gdb.error} which is thrown when an
479 operation tried to access invalid memory in the inferior.
481 @item KeyboardInterrupt
482 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
483 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
486 In all cases, your exception handler will see the @value{GDBN} error
487 message as its value and the Python call stack backtrace at the Python
488 statement closest to where the @value{GDBN} error occured as the
492 When implementing @value{GDBN} commands in Python via @code{gdb.Command},
493 it is useful to be able to throw an exception that doesn't cause a
494 traceback to be printed. For example, the user may have invoked the
495 command incorrectly. Use the @code{gdb.GdbError} exception
496 to handle this case. Example:
500 >class HelloWorld (gdb.Command):
501 > """Greet the whole world."""
502 > def __init__ (self):
503 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
504 > def invoke (self, args, from_tty):
505 > argv = gdb.string_to_argv (args)
506 > if len (argv) != 0:
507 > raise gdb.GdbError ("hello-world takes no arguments")
508 > print "Hello, World!"
512 hello-world takes no arguments
515 @node Values From Inferior
516 @subsubsection Values From Inferior
517 @cindex values from inferior, with Python
518 @cindex python, working with values from inferior
520 @cindex @code{gdb.Value}
521 @value{GDBN} provides values it obtains from the inferior program in
522 an object of type @code{gdb.Value}. @value{GDBN} uses this object
523 for its internal bookkeeping of the inferior's values, and for
524 fetching values when necessary.
526 Inferior values that are simple scalars can be used directly in
527 Python expressions that are valid for the value's data type. Here's
528 an example for an integer or floating-point value @code{some_val}:
535 As result of this, @code{bar} will also be a @code{gdb.Value} object
536 whose values are of the same type as those of @code{some_val}. Valid
537 Python operations can also be performed on @code{gdb.Value} objects
538 representing a @code{struct} or @code{class} object. For such cases,
539 the overloaded operator (if present), is used to perform the operation.
540 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
541 representing instances of a @code{class} which overloads the @code{+}
542 operator, then one can use the @code{+} operator in their Python script
550 The result of the operation @code{val3} is also a @code{gdb.Value}
551 object corresponding to the value returned by the overloaded @code{+}
552 operator. In general, overloaded operators are invoked for the
553 following operations: @code{+} (binary addition), @code{-} (binary
554 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
555 @code{>>}, @code{|}, @code{&}, @code{^}.
557 Inferior values that are structures or instances of some class can
558 be accessed using the Python @dfn{dictionary syntax}. For example, if
559 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
560 can access its @code{foo} element with:
563 bar = some_val['foo']
566 @cindex getting structure elements using gdb.Field objects as subscripts
567 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
568 elements can also be accessed by using @code{gdb.Field} objects as
569 subscripts (@pxref{Types In Python}, for more information on
570 @code{gdb.Field} objects). For example, if @code{foo_field} is a
571 @code{gdb.Field} object corresponding to element @code{foo} of the above
572 structure, then @code{bar} can also be accessed as follows:
575 bar = some_val[foo_field]
578 A @code{gdb.Value} that represents a function can be executed via
579 inferior function call. Any arguments provided to the call must match
580 the function's prototype, and must be provided in the order specified
583 For example, @code{some_val} is a @code{gdb.Value} instance
584 representing a function that takes two integers as arguments. To
585 execute this function, call it like so:
588 result = some_val (10,20)
591 Any values returned from a function call will be stored as a
594 The following attributes are provided:
596 @defvar Value.address
597 If this object is addressable, this read-only attribute holds a
598 @code{gdb.Value} object representing the address. Otherwise,
599 this attribute holds @code{None}.
602 @cindex optimized out value in Python
603 @defvar Value.is_optimized_out
604 This read-only boolean attribute is true if the compiler optimized out
605 this value, thus it is not available for fetching from the inferior.
609 The type of this @code{gdb.Value}. The value of this attribute is a
610 @code{gdb.Type} object (@pxref{Types In Python}).
613 @defvar Value.dynamic_type
614 The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time
615 type information (@acronym{RTTI}) to determine the dynamic type of the
616 value. If this value is of class type, it will return the class in
617 which the value is embedded, if any. If this value is of pointer or
618 reference to a class type, it will compute the dynamic type of the
619 referenced object, and return a pointer or reference to that type,
620 respectively. In all other cases, it will return the value's static
623 Note that this feature will only work when debugging a C@t{++} program
624 that includes @acronym{RTTI} for the object in question. Otherwise,
625 it will just return the static type of the value as in @kbd{ptype foo}
626 (@pxref{Symbols, ptype}).
629 @defvar Value.is_lazy
630 The value of this read-only boolean attribute is @code{True} if this
631 @code{gdb.Value} has not yet been fetched from the inferior.
632 @value{GDBN} does not fetch values until necessary, for efficiency.
636 myval = gdb.parse_and_eval ('somevar')
639 The value of @code{somevar} is not fetched at this time. It will be
640 fetched when the value is needed, or when the @code{fetch_lazy}
644 The following methods are provided:
646 @defun Value.__init__ (@var{val})
647 Many Python values can be converted directly to a @code{gdb.Value} via
648 this object initializer. Specifically:
652 A Python boolean is converted to the boolean type from the current
656 A Python integer is converted to the C @code{long} type for the
657 current architecture.
660 A Python long is converted to the C @code{long long} type for the
661 current architecture.
664 A Python float is converted to the C @code{double} type for the
665 current architecture.
668 A Python string is converted to a target string in the current target
669 language using the current target encoding.
670 If a character cannot be represented in the current target encoding,
671 then an exception is thrown.
673 @item @code{gdb.Value}
674 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
676 @item @code{gdb.LazyString}
677 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
678 Python}), then the lazy string's @code{value} method is called, and
683 @defun Value.cast (type)
684 Return a new instance of @code{gdb.Value} that is the result of
685 casting this instance to the type described by @var{type}, which must
686 be a @code{gdb.Type} object. If the cast cannot be performed for some
687 reason, this method throws an exception.
690 @defun Value.dereference ()
691 For pointer data types, this method returns a new @code{gdb.Value} object
692 whose contents is the object pointed to by the pointer. For example, if
693 @code{foo} is a C pointer to an @code{int}, declared in your C program as
700 then you can use the corresponding @code{gdb.Value} to access what
701 @code{foo} points to like this:
704 bar = foo.dereference ()
707 The result @code{bar} will be a @code{gdb.Value} object holding the
708 value pointed to by @code{foo}.
710 A similar function @code{Value.referenced_value} exists which also
711 returns @code{gdb.Value} objects corresonding to the values pointed to
712 by pointer values (and additionally, values referenced by reference
713 values). However, the behavior of @code{Value.dereference}
714 differs from @code{Value.referenced_value} by the fact that the
715 behavior of @code{Value.dereference} is identical to applying the C
716 unary operator @code{*} on a given value. For example, consider a
717 reference to a pointer @code{ptrref}, declared in your C@t{++} program
725 intptr &ptrref = ptr;
728 Though @code{ptrref} is a reference value, one can apply the method
729 @code{Value.dereference} to the @code{gdb.Value} object corresponding
730 to it and obtain a @code{gdb.Value} which is identical to that
731 corresponding to @code{val}. However, if you apply the method
732 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
733 object identical to that corresponding to @code{ptr}.
736 py_ptrref = gdb.parse_and_eval ("ptrref")
737 py_val = py_ptrref.dereference ()
738 py_ptr = py_ptrref.referenced_value ()
741 The @code{gdb.Value} object @code{py_val} is identical to that
742 corresponding to @code{val}, and @code{py_ptr} is identical to that
743 corresponding to @code{ptr}. In general, @code{Value.dereference} can
744 be applied whenever the C unary operator @code{*} can be applied
745 to the corresponding C value. For those cases where applying both
746 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
747 the results obtained need not be identical (as we have seen in the above
748 example). The results are however identical when applied on
749 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
750 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
753 @defun Value.referenced_value ()
754 For pointer or reference data types, this method returns a new
755 @code{gdb.Value} object corresponding to the value referenced by the
756 pointer/reference value. For pointer data types,
757 @code{Value.dereference} and @code{Value.referenced_value} produce
758 identical results. The difference between these methods is that
759 @code{Value.dereference} cannot get the values referenced by reference
760 values. For example, consider a reference to an @code{int}, declared
761 in your C@t{++} program as
769 then applying @code{Value.dereference} to the @code{gdb.Value} object
770 corresponding to @code{ref} will result in an error, while applying
771 @code{Value.referenced_value} will result in a @code{gdb.Value} object
772 identical to that corresponding to @code{val}.
775 py_ref = gdb.parse_and_eval ("ref")
776 er_ref = py_ref.dereference () # Results in error
777 py_val = py_ref.referenced_value () # Returns the referenced value
780 The @code{gdb.Value} object @code{py_val} is identical to that
781 corresponding to @code{val}.
784 @defun Value.dynamic_cast (type)
785 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
786 operator were used. Consult a C@t{++} reference for details.
789 @defun Value.reinterpret_cast (type)
790 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
791 operator were used. Consult a C@t{++} reference for details.
794 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
795 If this @code{gdb.Value} represents a string, then this method
796 converts the contents to a Python string. Otherwise, this method will
799 Values are interpreted as strings according to the rules of the
800 current language. If the optional length argument is given, the
801 string will be converted to that length, and will include any embedded
802 zeroes that the string may contain. Otherwise, for languages
803 where the string is zero-terminated, the entire string will be
806 For example, in C-like languages, a value is a string if it is a pointer
807 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
810 If the optional @var{encoding} argument is given, it must be a string
811 naming the encoding of the string in the @code{gdb.Value}, such as
812 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
813 the same encodings as the corresponding argument to Python's
814 @code{string.decode} method, and the Python codec machinery will be used
815 to convert the string. If @var{encoding} is not given, or if
816 @var{encoding} is the empty string, then either the @code{target-charset}
817 (@pxref{Character Sets}) will be used, or a language-specific encoding
818 will be used, if the current language is able to supply one.
820 The optional @var{errors} argument is the same as the corresponding
821 argument to Python's @code{string.decode} method.
823 If the optional @var{length} argument is given, the string will be
824 fetched and converted to the given length.
827 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
828 If this @code{gdb.Value} represents a string, then this method
829 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
830 In Python}). Otherwise, this method will throw an exception.
832 If the optional @var{encoding} argument is given, it must be a string
833 naming the encoding of the @code{gdb.LazyString}. Some examples are:
834 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
835 @var{encoding} argument is an encoding that @value{GDBN} does
836 recognize, @value{GDBN} will raise an error.
838 When a lazy string is printed, the @value{GDBN} encoding machinery is
839 used to convert the string during printing. If the optional
840 @var{encoding} argument is not provided, or is an empty string,
841 @value{GDBN} will automatically select the encoding most suitable for
842 the string type. For further information on encoding in @value{GDBN}
843 please see @ref{Character Sets}.
845 If the optional @var{length} argument is given, the string will be
846 fetched and encoded to the length of characters specified. If
847 the @var{length} argument is not provided, the string will be fetched
848 and encoded until a null of appropriate width is found.
851 @defun Value.fetch_lazy ()
852 If the @code{gdb.Value} object is currently a lazy value
853 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
854 fetched from the inferior. Any errors that occur in the process
855 will produce a Python exception.
857 If the @code{gdb.Value} object is not a lazy value, this method
860 This method does not return a value.
864 @node Types In Python
865 @subsubsection Types In Python
866 @cindex types in Python
867 @cindex Python, working with types
870 @value{GDBN} represents types from the inferior using the class
873 The following type-related functions are available in the @code{gdb}
876 @findex gdb.lookup_type
877 @defun gdb.lookup_type (name @r{[}, block@r{]})
878 This function looks up a type by its @var{name}, which must be a string.
880 If @var{block} is given, then @var{name} is looked up in that scope.
881 Otherwise, it is searched for globally.
883 Ordinarily, this function will return an instance of @code{gdb.Type}.
884 If the named type cannot be found, it will throw an exception.
887 If the type is a structure or class type, or an enum type, the fields
888 of that type can be accessed using the Python @dfn{dictionary syntax}.
889 For example, if @code{some_type} is a @code{gdb.Type} instance holding
890 a structure type, you can access its @code{foo} field with:
893 bar = some_type['foo']
896 @code{bar} will be a @code{gdb.Field} object; see below under the
897 description of the @code{Type.fields} method for a description of the
898 @code{gdb.Field} class.
900 An instance of @code{Type} has the following attributes:
903 The type code for this type. The type code will be one of the
904 @code{TYPE_CODE_} constants defined below.
908 The name of this type. If this type has no name, then @code{None}
913 The size of this type, in target @code{char} units. Usually, a
914 target's @code{char} type will be an 8-bit byte. However, on some
915 unusual platforms, this type may have a different size.
919 The tag name for this type. The tag name is the name after
920 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
921 languages have this concept. If this type has no tag name, then
922 @code{None} is returned.
925 The following methods are provided:
927 @defun Type.fields ()
928 For structure and union types, this method returns the fields. Range
929 types have two fields, the minimum and maximum values. Enum types
930 have one field per enum constant. Function and method types have one
931 field per parameter. The base types of C@t{++} classes are also
932 represented as fields. If the type has no fields, or does not fit
933 into one of these categories, an empty sequence will be returned.
935 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
938 This attribute is not available for @code{enum} or @code{static}
939 (as in C@t{++} or Java) fields. The value is the position, counting
940 in bits, from the start of the containing type.
943 This attribute is only available for @code{enum} fields, and its value
944 is the enumeration member's integer representation.
947 The name of the field, or @code{None} for anonymous fields.
950 This is @code{True} if the field is artificial, usually meaning that
951 it was provided by the compiler and not the user. This attribute is
952 always provided, and is @code{False} if the field is not artificial.
955 This is @code{True} if the field represents a base class of a C@t{++}
956 structure. This attribute is always provided, and is @code{False}
957 if the field is not a base class of the type that is the argument of
958 @code{fields}, or if that type was not a C@t{++} class.
961 If the field is packed, or is a bitfield, then this will have a
962 non-zero value, which is the size of the field in bits. Otherwise,
963 this will be zero; in this case the field's size is given by its type.
966 The type of the field. This is usually an instance of @code{Type},
967 but it can be @code{None} in some situations.
970 The type which contains this field. This is an instance of
975 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
976 Return a new @code{gdb.Type} object which represents an array of this
977 type. If one argument is given, it is the inclusive upper bound of
978 the array; in this case the lower bound is zero. If two arguments are
979 given, the first argument is the lower bound of the array, and the
980 second argument is the upper bound of the array. An array's length
981 must not be negative, but the bounds can be.
984 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
985 Return a new @code{gdb.Type} object which represents a vector of this
986 type. If one argument is given, it is the inclusive upper bound of
987 the vector; in this case the lower bound is zero. If two arguments are
988 given, the first argument is the lower bound of the vector, and the
989 second argument is the upper bound of the vector. A vector's length
990 must not be negative, but the bounds can be.
992 The difference between an @code{array} and a @code{vector} is that
993 arrays behave like in C: when used in expressions they decay to a pointer
994 to the first element whereas vectors are treated as first class values.
998 Return a new @code{gdb.Type} object which represents a
999 @code{const}-qualified variant of this type.
1002 @defun Type.volatile ()
1003 Return a new @code{gdb.Type} object which represents a
1004 @code{volatile}-qualified variant of this type.
1007 @defun Type.unqualified ()
1008 Return a new @code{gdb.Type} object which represents an unqualified
1009 variant of this type. That is, the result is neither @code{const} nor
1013 @defun Type.range ()
1014 Return a Python @code{Tuple} object that contains two elements: the
1015 low bound of the argument type and the high bound of that type. If
1016 the type does not have a range, @value{GDBN} will raise a
1017 @code{gdb.error} exception (@pxref{Exception Handling}).
1020 @defun Type.reference ()
1021 Return a new @code{gdb.Type} object which represents a reference to this
1025 @defun Type.pointer ()
1026 Return a new @code{gdb.Type} object which represents a pointer to this
1030 @defun Type.strip_typedefs ()
1031 Return a new @code{gdb.Type} that represents the real type,
1032 after removing all layers of typedefs.
1035 @defun Type.target ()
1036 Return a new @code{gdb.Type} object which represents the target type
1039 For a pointer type, the target type is the type of the pointed-to
1040 object. For an array type (meaning C-like arrays), the target type is
1041 the type of the elements of the array. For a function or method type,
1042 the target type is the type of the return value. For a complex type,
1043 the target type is the type of the elements. For a typedef, the
1044 target type is the aliased type.
1046 If the type does not have a target, this method will throw an
1050 @defun Type.template_argument (n @r{[}, block@r{]})
1051 If this @code{gdb.Type} is an instantiation of a template, this will
1052 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1053 value of the @var{n}th template argument (indexed starting at 0).
1055 If this @code{gdb.Type} is not a template type, or if the type has fewer
1056 than @var{n} template arguments, this will throw an exception.
1057 Ordinarily, only C@t{++} code will have template types.
1059 If @var{block} is given, then @var{name} is looked up in that scope.
1060 Otherwise, it is searched for globally.
1063 @defun Type.optimized_out ()
1064 Return @code{gdb.Value} instance of this type whose value is optimized
1065 out. This allows a frame decorator to indicate that the value of an
1066 argument or a local variable is not known.
1069 Each type has a code, which indicates what category this type falls
1070 into. The available type categories are represented by constants
1071 defined in the @code{gdb} module:
1074 @vindex TYPE_CODE_PTR
1075 @item gdb.TYPE_CODE_PTR
1076 The type is a pointer.
1078 @vindex TYPE_CODE_ARRAY
1079 @item gdb.TYPE_CODE_ARRAY
1080 The type is an array.
1082 @vindex TYPE_CODE_STRUCT
1083 @item gdb.TYPE_CODE_STRUCT
1084 The type is a structure.
1086 @vindex TYPE_CODE_UNION
1087 @item gdb.TYPE_CODE_UNION
1088 The type is a union.
1090 @vindex TYPE_CODE_ENUM
1091 @item gdb.TYPE_CODE_ENUM
1092 The type is an enum.
1094 @vindex TYPE_CODE_FLAGS
1095 @item gdb.TYPE_CODE_FLAGS
1096 A bit flags type, used for things such as status registers.
1098 @vindex TYPE_CODE_FUNC
1099 @item gdb.TYPE_CODE_FUNC
1100 The type is a function.
1102 @vindex TYPE_CODE_INT
1103 @item gdb.TYPE_CODE_INT
1104 The type is an integer type.
1106 @vindex TYPE_CODE_FLT
1107 @item gdb.TYPE_CODE_FLT
1108 A floating point type.
1110 @vindex TYPE_CODE_VOID
1111 @item gdb.TYPE_CODE_VOID
1112 The special type @code{void}.
1114 @vindex TYPE_CODE_SET
1115 @item gdb.TYPE_CODE_SET
1118 @vindex TYPE_CODE_RANGE
1119 @item gdb.TYPE_CODE_RANGE
1120 A range type, that is, an integer type with bounds.
1122 @vindex TYPE_CODE_STRING
1123 @item gdb.TYPE_CODE_STRING
1124 A string type. Note that this is only used for certain languages with
1125 language-defined string types; C strings are not represented this way.
1127 @vindex TYPE_CODE_BITSTRING
1128 @item gdb.TYPE_CODE_BITSTRING
1129 A string of bits. It is deprecated.
1131 @vindex TYPE_CODE_ERROR
1132 @item gdb.TYPE_CODE_ERROR
1133 An unknown or erroneous type.
1135 @vindex TYPE_CODE_METHOD
1136 @item gdb.TYPE_CODE_METHOD
1137 A method type, as found in C@t{++} or Java.
1139 @vindex TYPE_CODE_METHODPTR
1140 @item gdb.TYPE_CODE_METHODPTR
1141 A pointer-to-member-function.
1143 @vindex TYPE_CODE_MEMBERPTR
1144 @item gdb.TYPE_CODE_MEMBERPTR
1145 A pointer-to-member.
1147 @vindex TYPE_CODE_REF
1148 @item gdb.TYPE_CODE_REF
1151 @vindex TYPE_CODE_CHAR
1152 @item gdb.TYPE_CODE_CHAR
1155 @vindex TYPE_CODE_BOOL
1156 @item gdb.TYPE_CODE_BOOL
1159 @vindex TYPE_CODE_COMPLEX
1160 @item gdb.TYPE_CODE_COMPLEX
1161 A complex float type.
1163 @vindex TYPE_CODE_TYPEDEF
1164 @item gdb.TYPE_CODE_TYPEDEF
1165 A typedef to some other type.
1167 @vindex TYPE_CODE_NAMESPACE
1168 @item gdb.TYPE_CODE_NAMESPACE
1169 A C@t{++} namespace.
1171 @vindex TYPE_CODE_DECFLOAT
1172 @item gdb.TYPE_CODE_DECFLOAT
1173 A decimal floating point type.
1175 @vindex TYPE_CODE_INTERNAL_FUNCTION
1176 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1177 A function internal to @value{GDBN}. This is the type used to represent
1178 convenience functions.
1181 Further support for types is provided in the @code{gdb.types}
1182 Python module (@pxref{gdb.types}).
1184 @node Pretty Printing API
1185 @subsubsection Pretty Printing API
1186 @cindex python pretty printing api
1188 An example output is provided (@pxref{Pretty Printing}).
1190 A pretty-printer is just an object that holds a value and implements a
1191 specific interface, defined here.
1193 @defun pretty_printer.children (self)
1194 @value{GDBN} will call this method on a pretty-printer to compute the
1195 children of the pretty-printer's value.
1197 This method must return an object conforming to the Python iterator
1198 protocol. Each item returned by the iterator must be a tuple holding
1199 two elements. The first element is the ``name'' of the child; the
1200 second element is the child's value. The value can be any Python
1201 object which is convertible to a @value{GDBN} value.
1203 This method is optional. If it does not exist, @value{GDBN} will act
1204 as though the value has no children.
1207 @defun pretty_printer.display_hint (self)
1208 The CLI may call this method and use its result to change the
1209 formatting of a value. The result will also be supplied to an MI
1210 consumer as a @samp{displayhint} attribute of the variable being
1213 This method is optional. If it does exist, this method must return a
1216 Some display hints are predefined by @value{GDBN}:
1220 Indicate that the object being printed is ``array-like''. The CLI
1221 uses this to respect parameters such as @code{set print elements} and
1222 @code{set print array}.
1225 Indicate that the object being printed is ``map-like'', and that the
1226 children of this value can be assumed to alternate between keys and
1230 Indicate that the object being printed is ``string-like''. If the
1231 printer's @code{to_string} method returns a Python string of some
1232 kind, then @value{GDBN} will call its internal language-specific
1233 string-printing function to format the string. For the CLI this means
1234 adding quotation marks, possibly escaping some characters, respecting
1235 @code{set print elements}, and the like.
1239 @defun pretty_printer.to_string (self)
1240 @value{GDBN} will call this method to display the string
1241 representation of the value passed to the object's constructor.
1243 When printing from the CLI, if the @code{to_string} method exists,
1244 then @value{GDBN} will prepend its result to the values returned by
1245 @code{children}. Exactly how this formatting is done is dependent on
1246 the display hint, and may change as more hints are added. Also,
1247 depending on the print settings (@pxref{Print Settings}), the CLI may
1248 print just the result of @code{to_string} in a stack trace, omitting
1249 the result of @code{children}.
1251 If this method returns a string, it is printed verbatim.
1253 Otherwise, if this method returns an instance of @code{gdb.Value},
1254 then @value{GDBN} prints this value. This may result in a call to
1255 another pretty-printer.
1257 If instead the method returns a Python value which is convertible to a
1258 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1259 the resulting value. Again, this may result in a call to another
1260 pretty-printer. Python scalars (integers, floats, and booleans) and
1261 strings are convertible to @code{gdb.Value}; other types are not.
1263 Finally, if this method returns @code{None} then no further operations
1264 are peformed in this method and nothing is printed.
1266 If the result is not one of these types, an exception is raised.
1269 @value{GDBN} provides a function which can be used to look up the
1270 default pretty-printer for a @code{gdb.Value}:
1272 @findex gdb.default_visualizer
1273 @defun gdb.default_visualizer (value)
1274 This function takes a @code{gdb.Value} object as an argument. If a
1275 pretty-printer for this value exists, then it is returned. If no such
1276 printer exists, then this returns @code{None}.
1279 @node Selecting Pretty-Printers
1280 @subsubsection Selecting Pretty-Printers
1281 @cindex selecting python pretty-printers
1283 The Python list @code{gdb.pretty_printers} contains an array of
1284 functions or callable objects that have been registered via addition
1285 as a pretty-printer. Printers in this list are called @code{global}
1286 printers, they're available when debugging all inferiors.
1287 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1288 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1291 Each function on these lists is passed a single @code{gdb.Value}
1292 argument and should return a pretty-printer object conforming to the
1293 interface definition above (@pxref{Pretty Printing API}). If a function
1294 cannot create a pretty-printer for the value, it should return
1297 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1298 @code{gdb.Objfile} in the current program space and iteratively calls
1299 each enabled lookup routine in the list for that @code{gdb.Objfile}
1300 until it receives a pretty-printer object.
1301 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1302 searches the pretty-printer list of the current program space,
1303 calling each enabled function until an object is returned.
1304 After these lists have been exhausted, it tries the global
1305 @code{gdb.pretty_printers} list, again calling each enabled function until an
1308 The order in which the objfiles are searched is not specified. For a
1309 given list, functions are always invoked from the head of the list,
1310 and iterated over sequentially until the end of the list, or a printer
1313 For various reasons a pretty-printer may not work.
1314 For example, the underlying data structure may have changed and
1315 the pretty-printer is out of date.
1317 The consequences of a broken pretty-printer are severe enough that
1318 @value{GDBN} provides support for enabling and disabling individual
1319 printers. For example, if @code{print frame-arguments} is on,
1320 a backtrace can become highly illegible if any argument is printed
1321 with a broken printer.
1323 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1324 attribute to the registered function or callable object. If this attribute
1325 is present and its value is @code{False}, the printer is disabled, otherwise
1326 the printer is enabled.
1328 @node Writing a Pretty-Printer
1329 @subsubsection Writing a Pretty-Printer
1330 @cindex writing a pretty-printer
1332 A pretty-printer consists of two parts: a lookup function to detect
1333 if the type is supported, and the printer itself.
1335 Here is an example showing how a @code{std::string} printer might be
1336 written. @xref{Pretty Printing API}, for details on the API this class
1340 class StdStringPrinter(object):
1341 "Print a std::string"
1343 def __init__(self, val):
1346 def to_string(self):
1347 return self.val['_M_dataplus']['_M_p']
1349 def display_hint(self):
1353 And here is an example showing how a lookup function for the printer
1354 example above might be written.
1357 def str_lookup_function(val):
1358 lookup_tag = val.type.tag
1359 if lookup_tag == None:
1361 regex = re.compile("^std::basic_string<char,.*>$")
1362 if regex.match(lookup_tag):
1363 return StdStringPrinter(val)
1367 The example lookup function extracts the value's type, and attempts to
1368 match it to a type that it can pretty-print. If it is a type the
1369 printer can pretty-print, it will return a printer object. If not, it
1370 returns @code{None}.
1372 We recommend that you put your core pretty-printers into a Python
1373 package. If your pretty-printers are for use with a library, we
1374 further recommend embedding a version number into the package name.
1375 This practice will enable @value{GDBN} to load multiple versions of
1376 your pretty-printers at the same time, because they will have
1379 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1380 can be evaluated multiple times without changing its meaning. An
1381 ideal auto-load file will consist solely of @code{import}s of your
1382 printer modules, followed by a call to a register pretty-printers with
1383 the current objfile.
1385 Taken as a whole, this approach will scale nicely to multiple
1386 inferiors, each potentially using a different library version.
1387 Embedding a version number in the Python package name will ensure that
1388 @value{GDBN} is able to load both sets of printers simultaneously.
1389 Then, because the search for pretty-printers is done by objfile, and
1390 because your auto-loaded code took care to register your library's
1391 printers with a specific objfile, @value{GDBN} will find the correct
1392 printers for the specific version of the library used by each
1395 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1396 this code might appear in @code{gdb.libstdcxx.v6}:
1399 def register_printers(objfile):
1400 objfile.pretty_printers.append(str_lookup_function)
1404 And then the corresponding contents of the auto-load file would be:
1407 import gdb.libstdcxx.v6
1408 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1411 The previous example illustrates a basic pretty-printer.
1412 There are a few things that can be improved on.
1413 The printer doesn't have a name, making it hard to identify in a
1414 list of installed printers. The lookup function has a name, but
1415 lookup functions can have arbitrary, even identical, names.
1417 Second, the printer only handles one type, whereas a library typically has
1418 several types. One could install a lookup function for each desired type
1419 in the library, but one could also have a single lookup function recognize
1420 several types. The latter is the conventional way this is handled.
1421 If a pretty-printer can handle multiple data types, then its
1422 @dfn{subprinters} are the printers for the individual data types.
1424 The @code{gdb.printing} module provides a formal way of solving these
1425 problems (@pxref{gdb.printing}).
1426 Here is another example that handles multiple types.
1428 These are the types we are going to pretty-print:
1431 struct foo @{ int a, b; @};
1432 struct bar @{ struct foo x, y; @};
1435 Here are the printers:
1439 """Print a foo object."""
1441 def __init__(self, val):
1444 def to_string(self):
1445 return ("a=<" + str(self.val["a"]) +
1446 "> b=<" + str(self.val["b"]) + ">")
1449 """Print a bar object."""
1451 def __init__(self, val):
1454 def to_string(self):
1455 return ("x=<" + str(self.val["x"]) +
1456 "> y=<" + str(self.val["y"]) + ">")
1459 This example doesn't need a lookup function, that is handled by the
1460 @code{gdb.printing} module. Instead a function is provided to build up
1461 the object that handles the lookup.
1466 def build_pretty_printer():
1467 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1469 pp.add_printer('foo', '^foo$', fooPrinter)
1470 pp.add_printer('bar', '^bar$', barPrinter)
1474 And here is the autoload support:
1479 gdb.printing.register_pretty_printer(
1480 gdb.current_objfile(),
1481 my_library.build_pretty_printer())
1484 Finally, when this printer is loaded into @value{GDBN}, here is the
1485 corresponding output of @samp{info pretty-printer}:
1488 (gdb) info pretty-printer
1495 @node Type Printing API
1496 @subsubsection Type Printing API
1497 @cindex type printing API for Python
1499 @value{GDBN} provides a way for Python code to customize type display.
1500 This is mainly useful for substituting canonical typedef names for
1503 @cindex type printer
1504 A @dfn{type printer} is just a Python object conforming to a certain
1505 protocol. A simple base class implementing the protocol is provided;
1506 see @ref{gdb.types}. A type printer must supply at least:
1508 @defivar type_printer enabled
1509 A boolean which is True if the printer is enabled, and False
1510 otherwise. This is manipulated by the @code{enable type-printer}
1511 and @code{disable type-printer} commands.
1514 @defivar type_printer name
1515 The name of the type printer. This must be a string. This is used by
1516 the @code{enable type-printer} and @code{disable type-printer}
1520 @defmethod type_printer instantiate (self)
1521 This is called by @value{GDBN} at the start of type-printing. It is
1522 only called if the type printer is enabled. This method must return a
1523 new object that supplies a @code{recognize} method, as described below.
1527 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1528 will compute a list of type recognizers. This is done by iterating
1529 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1530 followed by the per-progspace type printers (@pxref{Progspaces In
1531 Python}), and finally the global type printers.
1533 @value{GDBN} will call the @code{instantiate} method of each enabled
1534 type printer. If this method returns @code{None}, then the result is
1535 ignored; otherwise, it is appended to the list of recognizers.
1537 Then, when @value{GDBN} is going to display a type name, it iterates
1538 over the list of recognizers. For each one, it calls the recognition
1539 function, stopping if the function returns a non-@code{None} value.
1540 The recognition function is defined as:
1542 @defmethod type_recognizer recognize (self, type)
1543 If @var{type} is not recognized, return @code{None}. Otherwise,
1544 return a string which is to be printed as the name of @var{type}.
1545 The @var{type} argument will be an instance of @code{gdb.Type}
1546 (@pxref{Types In Python}).
1549 @value{GDBN} uses this two-pass approach so that type printers can
1550 efficiently cache information without holding on to it too long. For
1551 example, it can be convenient to look up type information in a type
1552 printer and hold it for a recognizer's lifetime; if a single pass were
1553 done then type printers would have to make use of the event system in
1554 order to avoid holding information that could become stale as the
1557 @node Frame Filter API
1558 @subsubsection Filtering Frames.
1559 @cindex frame filters api
1561 Frame filters are Python objects that manipulate the visibility of a
1562 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1565 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1566 commands (@pxref{GDB/MI}), those that return a collection of frames
1567 are affected. The commands that work with frame filters are:
1569 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1570 @code{-stack-list-frames}
1571 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1572 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1573 -stack-list-variables command}), @code{-stack-list-arguments}
1574 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1575 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1576 -stack-list-locals command}).
1578 A frame filter works by taking an iterator as an argument, applying
1579 actions to the contents of that iterator, and returning another
1580 iterator (or, possibly, the same iterator it was provided in the case
1581 where the filter does not perform any operations). Typically, frame
1582 filters utilize tools such as the Python's @code{itertools} module to
1583 work with and create new iterators from the source iterator.
1584 Regardless of how a filter chooses to apply actions, it must not alter
1585 the underlying @value{GDBN} frame or frames, or attempt to alter the
1586 call-stack within @value{GDBN}. This preserves data integrity within
1587 @value{GDBN}. Frame filters are executed on a priority basis and care
1588 should be taken that some frame filters may have been executed before,
1589 and that some frame filters will be executed after.
1591 An important consideration when designing frame filters, and well
1592 worth reflecting upon, is that frame filters should avoid unwinding
1593 the call stack if possible. Some stacks can run very deep, into the
1594 tens of thousands in some cases. To search every frame when a frame
1595 filter executes may be too expensive at that step. The frame filter
1596 cannot know how many frames it has to iterate over, and it may have to
1597 iterate through them all. This ends up duplicating effort as
1598 @value{GDBN} performs this iteration when it prints the frames. If
1599 the filter can defer unwinding frames until frame decorators are
1600 executed, after the last filter has executed, it should. @xref{Frame
1601 Decorator API}, for more information on decorators. Also, there are
1602 examples for both frame decorators and filters in later chapters.
1603 @xref{Writing a Frame Filter}, for more information.
1605 The Python dictionary @code{gdb.frame_filters} contains key/object
1606 pairings that comprise a frame filter. Frame filters in this
1607 dictionary are called @code{global} frame filters, and they are
1608 available when debugging all inferiors. These frame filters must
1609 register with the dictionary directly. In addition to the
1610 @code{global} dictionary, there are other dictionaries that are loaded
1611 with different inferiors via auto-loading (@pxref{Python
1612 Auto-loading}). The two other areas where frame filter dictionaries
1613 can be found are: @code{gdb.Progspace} which contains a
1614 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1615 object which also contains a @code{frame_filters} dictionary
1618 When a command is executed from @value{GDBN} that is compatible with
1619 frame filters, @value{GDBN} combines the @code{global},
1620 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1621 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1622 several frames, and thus several object files, might be in use.
1623 @value{GDBN} then prunes any frame filter whose @code{enabled}
1624 attribute is @code{False}. This pruned list is then sorted according
1625 to the @code{priority} attribute in each filter.
1627 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1628 creates an iterator which wraps each frame in the call stack in a
1629 @code{FrameDecorator} object, and calls each filter in order. The
1630 output from the previous filter will always be the input to the next
1633 Frame filters have a mandatory interface which each frame filter must
1634 implement, defined here:
1636 @defun FrameFilter.filter (iterator)
1637 @value{GDBN} will call this method on a frame filter when it has
1638 reached the order in the priority list for that filter.
1640 For example, if there are four frame filters:
1651 The order that the frame filters will be called is:
1654 Filter3 -> Filter2 -> Filter1 -> Filter4
1657 Note that the output from @code{Filter3} is passed to the input of
1658 @code{Filter2}, and so on.
1660 This @code{filter} method is passed a Python iterator. This iterator
1661 contains a sequence of frame decorators that wrap each
1662 @code{gdb.Frame}, or a frame decorator that wraps another frame
1663 decorator. The first filter that is executed in the sequence of frame
1664 filters will receive an iterator entirely comprised of default
1665 @code{FrameDecorator} objects. However, after each frame filter is
1666 executed, the previous frame filter may have wrapped some or all of
1667 the frame decorators with their own frame decorator. As frame
1668 decorators must also conform to a mandatory interface, these
1669 decorators can be assumed to act in a uniform manner (@pxref{Frame
1672 This method must return an object conforming to the Python iterator
1673 protocol. Each item in the iterator must be an object conforming to
1674 the frame decorator interface. If a frame filter does not wish to
1675 perform any operations on this iterator, it should return that
1678 This method is not optional. If it does not exist, @value{GDBN} will
1679 raise and print an error.
1682 @defvar FrameFilter.name
1683 The @code{name} attribute must be Python string which contains the
1684 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1685 Management}). This attribute may contain any combination of letters
1686 or numbers. Care should be taken to ensure that it is unique. This
1687 attribute is mandatory.
1690 @defvar FrameFilter.enabled
1691 The @code{enabled} attribute must be Python boolean. This attribute
1692 indicates to @value{GDBN} whether the frame filter is enabled, and
1693 should be considered when frame filters are executed. If
1694 @code{enabled} is @code{True}, then the frame filter will be executed
1695 when any of the backtrace commands detailed earlier in this chapter
1696 are executed. If @code{enabled} is @code{False}, then the frame
1697 filter will not be executed. This attribute is mandatory.
1700 @defvar FrameFilter.priority
1701 The @code{priority} attribute must be Python integer. This attribute
1702 controls the order of execution in relation to other frame filters.
1703 There are no imposed limits on the range of @code{priority} other than
1704 it must be a valid integer. The higher the @code{priority} attribute,
1705 the sooner the frame filter will be executed in relation to other
1706 frame filters. Although @code{priority} can be negative, it is
1707 recommended practice to assume zero is the lowest priority that a
1708 frame filter can be assigned. Frame filters that have the same
1709 priority are executed in unsorted order in that priority slot. This
1710 attribute is mandatory.
1713 @node Frame Decorator API
1714 @subsubsection Decorating Frames.
1715 @cindex frame decorator api
1717 Frame decorators are sister objects to frame filters (@pxref{Frame
1718 Filter API}). Frame decorators are applied by a frame filter and can
1719 only be used in conjunction with frame filters.
1721 The purpose of a frame decorator is to customize the printed content
1722 of each @code{gdb.Frame} in commands where frame filters are executed.
1723 This concept is called decorating a frame. Frame decorators decorate
1724 a @code{gdb.Frame} with Python code contained within each API call.
1725 This separates the actual data contained in a @code{gdb.Frame} from
1726 the decorated data produced by a frame decorator. This abstraction is
1727 necessary to maintain integrity of the data contained in each
1730 Frame decorators have a mandatory interface, defined below.
1732 @value{GDBN} already contains a frame decorator called
1733 @code{FrameDecorator}. This contains substantial amounts of
1734 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
1735 recommended that other frame decorators inherit and extend this
1736 object, and only to override the methods needed.
1738 @defun FrameDecorator.elided (self)
1740 The @code{elided} method groups frames together in a hierarchical
1741 system. An example would be an interpreter, where multiple low-level
1742 frames make up a single call in the interpreted language. In this
1743 example, the frame filter would elide the low-level frames and present
1744 a single high-level frame, representing the call in the interpreted
1745 language, to the user.
1747 The @code{elided} function must return an iterable and this iterable
1748 must contain the frames that are being elided wrapped in a suitable
1749 frame decorator. If no frames are being elided this function may
1750 return an empty iterable, or @code{None}. Elided frames are indented
1751 from normal frames in a @code{CLI} backtrace, or in the case of
1752 @code{GDB/MI}, are placed in the @code{children} field of the eliding
1755 It is the frame filter's task to also filter out the elided frames from
1756 the source iterator. This will avoid printing the frame twice.
1759 @defun FrameDecorator.function (self)
1761 This method returns the name of the function in the frame that is to
1764 This method must return a Python string describing the function, or
1767 If this function returns @code{None}, @value{GDBN} will not print any
1768 data for this field.
1771 @defun FrameDecorator.address (self)
1773 This method returns the address of the frame that is to be printed.
1775 This method must return a Python numeric integer type of sufficient
1776 size to describe the address of the frame, or @code{None}.
1778 If this function returns a @code{None}, @value{GDBN} will not print
1779 any data for this field.
1782 @defun FrameDecorator.filename (self)
1784 This method returns the filename and path associated with this frame.
1786 This method must return a Python string containing the filename and
1787 the path to the object file backing the frame, or @code{None}.
1789 If this function returns a @code{None}, @value{GDBN} will not print
1790 any data for this field.
1793 @defun FrameDecorator.line (self):
1795 This method returns the line number associated with the current
1796 position within the function addressed by this frame.
1798 This method must return a Python integer type, or @code{None}.
1800 If this function returns a @code{None}, @value{GDBN} will not print
1801 any data for this field.
1804 @defun FrameDecorator.frame_args (self)
1807 This method must return an iterable, or @code{None}. Returning an
1808 empty iterable, or @code{None} means frame arguments will not be
1809 printed for this frame. This iterable must contain objects that
1810 implement two methods, described here.
1812 This object must implement a @code{argument} method which takes a
1813 single @code{self} parameter and must return a @code{gdb.Symbol}
1814 (@pxref{Symbols In Python}), or a Python string. The object must also
1815 implement a @code{value} method which takes a single @code{self}
1816 parameter and must return a @code{gdb.Value} (@pxref{Values From
1817 Inferior}), a Python value, or @code{None}. If the @code{value}
1818 method returns @code{None}, and the @code{argument} method returns a
1819 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
1820 the @code{gdb.Symbol} automatically.
1825 class SymValueWrapper():
1827 def __init__(self, symbol, value):
1837 class SomeFrameDecorator()
1840 def frame_args(self):
1843 block = self.inferior_frame.block()
1847 # Iterate over all symbols in a block. Only add
1848 # symbols that are arguments.
1850 if not sym.is_argument:
1852 args.append(SymValueWrapper(sym,None))
1854 # Add example synthetic argument.
1855 args.append(SymValueWrapper(``foo'', 42))
1861 @defun FrameDecorator.frame_locals (self)
1863 This method must return an iterable or @code{None}. Returning an
1864 empty iterable, or @code{None} means frame local arguments will not be
1865 printed for this frame.
1867 The object interface, the description of the various strategies for
1868 reading frame locals, and the example are largely similar to those
1869 described in the @code{frame_args} function, (@pxref{frame_args,,The
1870 frame filter frame_args function}). Below is a modified example:
1873 class SomeFrameDecorator()
1876 def frame_locals(self):
1879 block = self.inferior_frame.block()
1883 # Iterate over all symbols in a block. Add all
1884 # symbols, except arguments.
1888 vars.append(SymValueWrapper(sym,None))
1890 # Add an example of a synthetic local variable.
1891 vars.append(SymValueWrapper(``bar'', 99))
1897 @defun FrameDecorator.inferior_frame (self):
1899 This method must return the underlying @code{gdb.Frame} that this
1900 frame decorator is decorating. @value{GDBN} requires the underlying
1901 frame for internal frame information to determine how to print certain
1902 values when printing a frame.
1905 @node Writing a Frame Filter
1906 @subsubsection Writing a Frame Filter
1907 @cindex writing a frame filter
1909 There are three basic elements that a frame filter must implement: it
1910 must correctly implement the documented interface (@pxref{Frame Filter
1911 API}), it must register itself with @value{GDBN}, and finally, it must
1912 decide if it is to work on the data provided by @value{GDBN}. In all
1913 cases, whether it works on the iterator or not, each frame filter must
1914 return an iterator. A bare-bones frame filter follows the pattern in
1915 the following example.
1920 class FrameFilter():
1923 # Frame filter attribute creation.
1925 # 'name' is the name of the filter that GDB will display.
1927 # 'priority' is the priority of the filter relative to other
1930 # 'enabled' is a boolean that indicates whether this filter is
1931 # enabled and should be executed.
1937 # Register this frame filter with the global frame_filters
1939 gdb.frame_filters[self.name] = self
1941 def filter(self, frame_iter):
1942 # Just return the iterator.
1946 The frame filter in the example above implements the three
1947 requirements for all frame filters. It implements the API, self
1948 registers, and makes a decision on the iterator (in this case, it just
1949 returns the iterator untouched).
1951 The first step is attribute creation and assignment, and as shown in
1952 the comments the filter assigns the following attributes: @code{name},
1953 @code{priority} and whether the filter should be enabled with the
1954 @code{enabled} attribute.
1956 The second step is registering the frame filter with the dictionary or
1957 dictionaries that the frame filter has interest in. As shown in the
1958 comments, this filter just registers itself with the global dictionary
1959 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
1960 is a dictionary that is initialized in the @code{gdb} module when
1961 @value{GDBN} starts. What dictionary a filter registers with is an
1962 important consideration. Generally, if a filter is specific to a set
1963 of code, it should be registered either in the @code{objfile} or
1964 @code{progspace} dictionaries as they are specific to the program
1965 currently loaded in @value{GDBN}. The global dictionary is always
1966 present in @value{GDBN} and is never unloaded. Any filters registered
1967 with the global dictionary will exist until @value{GDBN} exits. To
1968 avoid filters that may conflict, it is generally better to register
1969 frame filters against the dictionaries that more closely align with
1970 the usage of the filter currently in question. @xref{Python
1971 Auto-loading}, for further information on auto-loading Python scripts.
1973 @value{GDBN} takes a hands-off approach to frame filter registration,
1974 therefore it is the frame filter's responsibility to ensure
1975 registration has occurred, and that any exceptions are handled
1976 appropriately. In particular, you may wish to handle exceptions
1977 relating to Python dictionary key uniqueness. It is mandatory that
1978 the dictionary key is the same as frame filter's @code{name}
1979 attribute. When a user manages frame filters (@pxref{Frame Filter
1980 Management}), the names @value{GDBN} will display are those contained
1981 in the @code{name} attribute.
1983 The final step of this example is the implementation of the
1984 @code{filter} method. As shown in the example comments, we define the
1985 @code{filter} method and note that the method must take an iterator,
1986 and also must return an iterator. In this bare-bones example, the
1987 frame filter is not very useful as it just returns the iterator
1988 untouched. However this is a valid operation for frame filters that
1989 have the @code{enabled} attribute set, but decide not to operate on
1992 In the next example, the frame filter operates on all frames and
1993 utilizes a frame decorator to perform some work on the frames.
1994 @xref{Frame Decorator API}, for further information on the frame
1995 decorator interface.
1997 This example works on inlined frames. It highlights frames which are
1998 inlined by tagging them with an ``[inlined]'' tag. By applying a
1999 frame decorator to all frames with the Python @code{itertools imap}
2000 method, the example defers actions to the frame decorator. Frame
2001 decorators are only processed when @value{GDBN} prints the backtrace.
2003 This introduces a new decision making topic: whether to perform
2004 decision making operations at the filtering step, or at the printing
2005 step. In this example's approach, it does not perform any filtering
2006 decisions at the filtering step beyond mapping a frame decorator to
2007 each frame. This allows the actual decision making to be performed
2008 when each frame is printed. This is an important consideration, and
2009 well worth reflecting upon when designing a frame filter. An issue
2010 that frame filters should avoid is unwinding the stack if possible.
2011 Some stacks can run very deep, into the tens of thousands in some
2012 cases. To search every frame to determine if it is inlined ahead of
2013 time may be too expensive at the filtering step. The frame filter
2014 cannot know how many frames it has to iterate over, and it would have
2015 to iterate through them all. This ends up duplicating effort as
2016 @value{GDBN} performs this iteration when it prints the frames.
2018 In this example decision making can be deferred to the printing step.
2019 As each frame is printed, the frame decorator can examine each frame
2020 in turn when @value{GDBN} iterates. From a performance viewpoint,
2021 this is the most appropriate decision to make as it avoids duplicating
2022 the effort that the printing step would undertake anyway. Also, if
2023 there are many frame filters unwinding the stack during filtering, it
2024 can substantially delay the printing of the backtrace which will
2025 result in large memory usage, and a poor user experience.
2028 class InlineFilter():
2031 self.name = "InlinedFrameFilter"
2034 gdb.frame_filters[self.name] = self
2036 def filter(self, frame_iter):
2037 frame_iter = itertools.imap(InlinedFrameDecorator,
2042 This frame filter is somewhat similar to the earlier example, except
2043 that the @code{filter} method applies a frame decorator object called
2044 @code{InlinedFrameDecorator} to each element in the iterator. The
2045 @code{imap} Python method is light-weight. It does not proactively
2046 iterate over the iterator, but rather creates a new iterator which
2047 wraps the existing one.
2049 Below is the frame decorator for this example.
2052 class InlinedFrameDecorator(FrameDecorator):
2054 def __init__(self, fobj):
2055 super(InlinedFrameDecorator, self).__init__(fobj)
2058 frame = fobj.inferior_frame()
2059 name = str(frame.name())
2061 if frame.type() == gdb.INLINE_FRAME:
2062 name = name + " [inlined]"
2067 This frame decorator only defines and overrides the @code{function}
2068 method. It lets the supplied @code{FrameDecorator}, which is shipped
2069 with @value{GDBN}, perform the other work associated with printing
2072 The combination of these two objects create this output from a
2076 #0 0x004004e0 in bar () at inline.c:11
2077 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2078 #2 0x00400566 in main () at inline.c:31
2081 So in the case of this example, a frame decorator is applied to all
2082 frames, regardless of whether they may be inlined or not. As
2083 @value{GDBN} iterates over the iterator produced by the frame filters,
2084 @value{GDBN} executes each frame decorator which then makes a decision
2085 on what to print in the @code{function} callback. Using a strategy
2086 like this is a way to defer decisions on the frame content to printing
2089 @subheading Eliding Frames
2091 It might be that the above example is not desirable for representing
2092 inlined frames, and a hierarchical approach may be preferred. If we
2093 want to hierarchically represent frames, the @code{elided} frame
2094 decorator interface might be preferable.
2096 This example approaches the issue with the @code{elided} method. This
2097 example is quite long, but very simplistic. It is out-of-scope for
2098 this section to write a complete example that comprehensively covers
2099 all approaches of finding and printing inlined frames. However, this
2100 example illustrates the approach an author might use.
2102 This example comprises of three sections.
2105 class InlineFrameFilter():
2108 self.name = "InlinedFrameFilter"
2111 gdb.frame_filters[self.name] = self
2113 def filter(self, frame_iter):
2114 return ElidingInlineIterator(frame_iter)
2117 This frame filter is very similar to the other examples. The only
2118 difference is this frame filter is wrapping the iterator provided to
2119 it (@code{frame_iter}) with a custom iterator called
2120 @code{ElidingInlineIterator}. This again defers actions to when
2121 @value{GDBN} prints the backtrace, as the iterator is not traversed
2124 The iterator for this example is as follows. It is in this section of
2125 the example where decisions are made on the content of the backtrace.
2128 class ElidingInlineIterator:
2129 def __init__(self, ii):
2130 self.input_iterator = ii
2136 frame = next(self.input_iterator)
2138 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2142 eliding_frame = next(self.input_iterator)
2143 except StopIteration:
2145 return ElidingFrameDecorator(eliding_frame, [frame])
2148 This iterator implements the Python iterator protocol. When the
2149 @code{next} function is called (when @value{GDBN} prints each frame),
2150 the iterator checks if this frame decorator, @code{frame}, is wrapping
2151 an inlined frame. If it is not, it returns the existing frame decorator
2152 untouched. If it is wrapping an inlined frame, it assumes that the
2153 inlined frame was contained within the next oldest frame,
2154 @code{eliding_frame}, which it fetches. It then creates and returns a
2155 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2156 elided frame, and the eliding frame.
2159 class ElidingInlineDecorator(FrameDecorator):
2161 def __init__(self, frame, elided_frames):
2162 super(ElidingInlineDecorator, self).__init__(frame)
2164 self.elided_frames = elided_frames
2167 return iter(self.elided_frames)
2170 This frame decorator overrides one function and returns the inlined
2171 frame in the @code{elided} method. As before it lets
2172 @code{FrameDecorator} do the rest of the work involved in printing
2173 this frame. This produces the following output.
2176 #0 0x004004e0 in bar () at inline.c:11
2177 #2 0x00400529 in main () at inline.c:25
2178 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2181 In that output, @code{max} which has been inlined into @code{main} is
2182 printed hierarchically. Another approach would be to combine the
2183 @code{function} method, and the @code{elided} method to both print a
2184 marker in the inlined frame, and also show the hierarchical
2187 @node Unwinding Frames in Python
2188 @subsubsection Unwinding Frames in Python
2189 @cindex unwinding frames in Python
2191 In @value{GDBN} terminology ``unwinding'' is the process of finding
2192 the previous frame (that is, caller's) from the current one. An
2193 unwinder has three methods. The first one checks if it can handle
2194 given frame (``sniff'' it). For the frames it can sniff an unwinder
2195 provides two additional methods: it can return frame's ID, and it can
2196 fetch registers from the previous frame. A running @value{GDBN}
2197 mantains a list of the unwinders and calls each unwinder's sniffer in
2198 turn until it finds the one that recognizes the current frame. There
2199 is an API to register an unwinder.
2201 The unwinders that come with @value{GDBN} handle standard frames.
2202 However, mixed language applications (for example, an application
2203 running Java Virtual Machine) sometimes use frame layouts that cannot
2204 be handled by the @value{GDBN} unwinders. You can write Python code
2205 that can handle such custom frames.
2207 You implement a frame unwinder in Python as a class with which has two
2208 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2209 a single method @code{__call__}, which examines a given frame and
2210 returns an object (an instance of @code{gdb.UnwindInfo class)}
2211 describing it. If an unwinder does not recognize a frame, it should
2212 return @code{None}. The code in @value{GDBN} that enables writing
2213 unwinders in Python uses this object to return frame's ID and previous
2214 frame registers when @value{GDBN} core asks for them.
2216 @subheading Unwinder Input
2218 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2219 provides a method to read frame's registers:
2221 @defun PendingFrame.read_register (reg)
2222 This method returns the contents of the register @var{regn} in the
2223 frame as a @code{gdb.Value} object. @var{reg} can be either a
2224 register number or a register name; the values are platform-specific.
2225 They are usually found in the corresponding
2226 @file{@var{platform}-tdep.h} file in the @value{GDBN} source tree.
2229 It also provides a factory method to create a @code{gdb.UnwindInfo}
2230 instance to be returned to @value{GDBN}:
2232 @defun PendingFrame.create_unwind_info (frame_id)
2233 Returns a new @code{gdb.UnwindInfo} instance identified by given
2234 @var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2235 using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2236 determine which function will be used, as follows:
2239 @item sp, pc, special
2240 @code{frame_id_build_special (@var{frame_id}.sp, @var{frame_id}.pc, @var{frame_id}.special)}
2243 @code{frame_id_build (@var{frame_id}.sp, @var{frame_id}.pc)}
2245 This is the most common case.
2248 @code{frame_id_build_wild (@var{frame_id}.sp)}
2250 The attribute values should be @code{gdb.Value}
2254 @subheading Unwinder Output: UnwindInfo
2256 Use @code{PendingFrame.create_unwind_info} method described above to
2257 create a @code{gdb.UnwindInfo} instance. Use the following method to
2258 specify caller registers that have been saved in this frame:
2260 @defun gdb.UnwindInfo.add_saved_register (reg, value)
2261 @var{reg} identifies the register. It can be a number or a name, just
2262 as for the @code{PendingFrame.read_register} method above.
2263 @var{value} is a register value (a @code{gdb.Value} object).
2266 @subheading Unwinder Skeleton Code
2268 @value{GDBN} comes with the module containing the base @code{Unwinder}
2269 class. Derive your unwinder class from it and structure the code as
2273 from gdb.unwinders import Unwinder
2275 class FrameId(object):
2276 def __init__(self, sp, pc):
2281 class MyUnwinder(Unwinder):
2283 supe(MyUnwinder, self).__init___(<expects unwinder name argument>)
2285 def __call__(pending_frame):
2286 if not <we recognize frame>:
2288 # Create UnwindInfo. Usually the frame is identified by the stack
2289 # pointer and the program counter.
2290 sp = pending_frame.read_register(<SP number>)
2291 pc = pending_frame.read_register(<PC number>)
2292 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2294 # Find the values of the registers in the caller's frame and
2295 # save them in the result:
2296 unwind_info.add_saved_register(<register>, <value>)
2299 # Return the result:
2304 @subheading Registering a Unwinder
2306 An object file, a program space, and the @value{GDBN} proper can have
2307 unwinders registered with it.
2309 The @code{gdb.unwinders} module provides the function to register a
2312 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2313 @var{locus} is specifies an object file or a program space to which
2314 @var{unwinder} is added. Passing @code{None} or @code{gdb} adds
2315 @var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
2316 added @var{unwinder} will be called before any other unwinder from the
2317 same locus. Two unwinders in the same locus cannot have the same
2318 name. An attempt to add a unwinder with already existing name raises
2319 an exception unless @var{replace} is @code{True}, in which case the
2320 old unwinder is deleted.
2323 @subheading Unwinder Precedence
2325 @value{GDBN} first calls the unwinders from all the object files in no
2326 particular order, then the unwinders from the current program space,
2327 and finally the unwinders from @value{GDBN}.
2329 @node Xmethods In Python
2330 @subsubsection Xmethods In Python
2331 @cindex xmethods in Python
2333 @dfn{Xmethods} are additional methods or replacements for existing
2334 methods of a C@t{++} class. This feature is useful for those cases
2335 where a method defined in C@t{++} source code could be inlined or
2336 optimized out by the compiler, making it unavailable to @value{GDBN}.
2337 For such cases, one can define an xmethod to serve as a replacement
2338 for the method defined in the C@t{++} source code. @value{GDBN} will
2339 then invoke the xmethod, instead of the C@t{++} method, to
2340 evaluate expressions. One can also use xmethods when debugging
2341 with core files. Moreover, when debugging live programs, invoking an
2342 xmethod need not involve running the inferior (which can potentially
2343 perturb its state). Hence, even if the C@t{++} method is available, it
2344 is better to use its replacement xmethod if one is defined.
2346 The xmethods feature in Python is available via the concepts of an
2347 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2348 implement an xmethod, one has to implement a matcher and a
2349 corresponding worker for it (more than one worker can be
2350 implemented, each catering to a different overloaded instance of the
2351 method). Internally, @value{GDBN} invokes the @code{match} method of a
2352 matcher to match the class type and method name. On a match, the
2353 @code{match} method returns a list of matching @emph{worker} objects.
2354 Each worker object typically corresponds to an overloaded instance of
2355 the xmethod. They implement a @code{get_arg_types} method which
2356 returns a sequence of types corresponding to the arguments the xmethod
2357 requires. @value{GDBN} uses this sequence of types to perform
2358 overload resolution and picks a winning xmethod worker. A winner
2359 is also selected from among the methods @value{GDBN} finds in the
2360 C@t{++} source code. Next, the winning xmethod worker and the
2361 winning C@t{++} method are compared to select an overall winner. In
2362 case of a tie between a xmethod worker and a C@t{++} method, the
2363 xmethod worker is selected as the winner. That is, if a winning
2364 xmethod worker is found to be equivalent to the winning C@t{++}
2365 method, then the xmethod worker is treated as a replacement for
2366 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2367 method. If the winning xmethod worker is the overall winner, then
2368 the corresponding xmethod is invoked via the @code{__call__} method
2369 of the worker object.
2371 If one wants to implement an xmethod as a replacement for an
2372 existing C@t{++} method, then they have to implement an equivalent
2373 xmethod which has exactly the same name and takes arguments of
2374 exactly the same type as the C@t{++} method. If the user wants to
2375 invoke the C@t{++} method even though a replacement xmethod is
2376 available for that method, then they can disable the xmethod.
2378 @xref{Xmethod API}, for API to implement xmethods in Python.
2379 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2382 @subsubsection Xmethod API
2385 The @value{GDBN} Python API provides classes, interfaces and functions
2386 to implement, register and manipulate xmethods.
2387 @xref{Xmethods In Python}.
2389 An xmethod matcher should be an instance of a class derived from
2390 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2391 object with similar interface and attributes. An instance of
2392 @code{XMethodMatcher} has the following attributes:
2395 The name of the matcher.
2399 A boolean value indicating whether the matcher is enabled or disabled.
2403 A list of named methods managed by the matcher. Each object in the list
2404 is an instance of the class @code{XMethod} defined in the module
2405 @code{gdb.xmethod}, or any object with the following attributes:
2410 Name of the xmethod which should be unique for each xmethod
2411 managed by the matcher.
2414 A boolean value indicating whether the xmethod is enabled or
2419 The class @code{XMethod} is a convenience class with same
2420 attributes as above along with the following constructor:
2422 @defun XMethod.__init__ (self, name)
2423 Constructs an enabled xmethod with name @var{name}.
2428 The @code{XMethodMatcher} class has the following methods:
2430 @defun XMethodMatcher.__init__ (self, name)
2431 Constructs an enabled xmethod matcher with name @var{name}. The
2432 @code{methods} attribute is initialized to @code{None}.
2435 @defun XMethodMatcher.match (self, class_type, method_name)
2436 Derived classes should override this method. It should return a
2437 xmethod worker object (or a sequence of xmethod worker
2438 objects) matching the @var{class_type} and @var{method_name}.
2439 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2440 is a string value. If the matcher manages named methods as listed in
2441 its @code{methods} attribute, then only those worker objects whose
2442 corresponding entries in the @code{methods} list are enabled should be
2446 An xmethod worker should be an instance of a class derived from
2447 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
2448 or support the following interface:
2450 @defun XMethodWorker.get_arg_types (self)
2451 This method returns a sequence of @code{gdb.Type} objects corresponding
2452 to the arguments that the xmethod takes. It can return an empty
2453 sequence or @code{None} if the xmethod does not take any arguments.
2454 If the xmethod takes a single argument, then a single
2455 @code{gdb.Type} object corresponding to it can be returned.
2458 @defun XMethodWorker.__call__ (self, *args)
2459 This is the method which does the @emph{work} of the xmethod. The
2460 @var{args} arguments is the tuple of arguments to the xmethod. Each
2461 element in this tuple is a gdb.Value object. The first element is
2462 always the @code{this} pointer value.
2465 For @value{GDBN} to lookup xmethods, the xmethod matchers
2466 should be registered using the following function defined in the module
2469 @defun register_xmethod_matcher (locus, matcher, replace=False)
2470 The @code{matcher} is registered with @code{locus}, replacing an
2471 existing matcher with the same name as @code{matcher} if
2472 @code{replace} is @code{True}. @code{locus} can be a
2473 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
2474 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
2475 @code{None}. If it is @code{None}, then @code{matcher} is registered
2479 @node Writing an Xmethod
2480 @subsubsection Writing an Xmethod
2481 @cindex writing xmethods in Python
2483 Implementing xmethods in Python will require implementing xmethod
2484 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2485 the following C@t{++} class:
2491 MyClass (int a) : a_(a) @{ @}
2493 int geta (void) @{ return a_; @}
2494 int operator+ (int b);
2501 MyClass::operator+ (int b)
2508 Let us define two xmethods for the class @code{MyClass}, one
2509 replacing the method @code{geta}, and another adding an overloaded
2510 flavor of @code{operator+} which takes a @code{MyClass} argument (the
2511 C@t{++} code above already has an overloaded @code{operator+}
2512 which takes an @code{int} argument). The xmethod matcher can be
2516 class MyClass_geta(gdb.xmethod.XMethod):
2518 gdb.xmethod.XMethod.__init__(self, 'geta')
2520 def get_worker(self, method_name):
2521 if method_name == 'geta':
2522 return MyClassWorker_geta()
2525 class MyClass_sum(gdb.xmethod.XMethod):
2527 gdb.xmethod.XMethod.__init__(self, 'sum')
2529 def get_worker(self, method_name):
2530 if method_name == 'operator+':
2531 return MyClassWorker_plus()
2534 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2536 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2537 # List of methods 'managed' by this matcher
2538 self.methods = [MyClass_geta(), MyClass_sum()]
2540 def match(self, class_type, method_name):
2541 if class_type.tag != 'MyClass':
2544 for method in self.methods:
2546 worker = method.get_worker(method_name)
2548 workers.append(worker)
2554 Notice that the @code{match} method of @code{MyClassMatcher} returns
2555 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
2556 method, and a worker object of type @code{MyClassWorker_plus} for the
2557 @code{operator+} method. This is done indirectly via helper classes
2558 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
2559 @code{methods} attribute in a matcher as it is optional. However, if a
2560 matcher manages more than one xmethod, it is a good practice to list the
2561 xmethods in the @code{methods} attribute of the matcher. This will then
2562 facilitate enabling and disabling individual xmethods via the
2563 @code{enable/disable} commands. Notice also that a worker object is
2564 returned only if the corresponding entry in the @code{methods} attribute
2565 of the matcher is enabled.
2567 The implementation of the worker classes returned by the matcher setup
2568 above is as follows:
2571 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
2572 def get_arg_types(self):
2575 def __call__(self, obj):
2579 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
2580 def get_arg_types(self):
2581 return gdb.lookup_type('MyClass')
2583 def __call__(self, obj, other):
2584 return obj['a_'] + other['a_']
2587 For @value{GDBN} to actually lookup a xmethod, it has to be
2588 registered with it. The matcher defined above is registered with
2589 @value{GDBN} globally as follows:
2592 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
2595 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
2603 then, after loading the Python script defining the xmethod matchers
2604 and workers into @code{GDBN}, invoking the method @code{geta} or using
2605 the operator @code{+} on @code{obj} will invoke the xmethods
2616 Consider another example with a C++ template class:
2623 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
2624 ~MyTemplate () @{ delete [] data_; @}
2626 int footprint (void)
2628 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
2637 Let us implement an xmethod for the above class which serves as a
2638 replacement for the @code{footprint} method. The full code listing
2639 of the xmethod workers and xmethod matchers is as follows:
2642 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
2643 def __init__(self, class_type):
2644 self.class_type = class_type
2646 def get_arg_types(self):
2649 def __call__(self, obj):
2650 return (self.class_type.sizeof +
2652 self.class_type.template_argument(0).sizeof)
2655 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
2657 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
2659 def match(self, class_type, method_name):
2660 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
2662 method_name == 'footprint'):
2663 return MyTemplateWorker_footprint(class_type)
2666 Notice that, in this example, we have not used the @code{methods}
2667 attribute of the matcher as the matcher manages only one xmethod. The
2668 user can enable/disable this xmethod by enabling/disabling the matcher
2671 @node Inferiors In Python
2672 @subsubsection Inferiors In Python
2673 @cindex inferiors in Python
2675 @findex gdb.Inferior
2676 Programs which are being run under @value{GDBN} are called inferiors
2677 (@pxref{Inferiors and Programs}). Python scripts can access
2678 information about and manipulate inferiors controlled by @value{GDBN}
2679 via objects of the @code{gdb.Inferior} class.
2681 The following inferior-related functions are available in the @code{gdb}
2684 @defun gdb.inferiors ()
2685 Return a tuple containing all inferior objects.
2688 @defun gdb.selected_inferior ()
2689 Return an object representing the current inferior.
2692 A @code{gdb.Inferior} object has the following attributes:
2694 @defvar Inferior.num
2695 ID of inferior, as assigned by GDB.
2698 @defvar Inferior.pid
2699 Process ID of the inferior, as assigned by the underlying operating
2703 @defvar Inferior.was_attached
2704 Boolean signaling whether the inferior was created using `attach', or
2705 started by @value{GDBN} itself.
2708 A @code{gdb.Inferior} object has the following methods:
2710 @defun Inferior.is_valid ()
2711 Returns @code{True} if the @code{gdb.Inferior} object is valid,
2712 @code{False} if not. A @code{gdb.Inferior} object will become invalid
2713 if the inferior no longer exists within @value{GDBN}. All other
2714 @code{gdb.Inferior} methods will throw an exception if it is invalid
2715 at the time the method is called.
2718 @defun Inferior.threads ()
2719 This method returns a tuple holding all the threads which are valid
2720 when it is called. If there are no valid threads, the method will
2721 return an empty tuple.
2724 @findex Inferior.read_memory
2725 @defun Inferior.read_memory (address, length)
2726 Read @var{length} bytes of memory from the inferior, starting at
2727 @var{address}. Returns a buffer object, which behaves much like an array
2728 or a string. It can be modified and given to the
2729 @code{Inferior.write_memory} function. In @code{Python} 3, the return
2730 value is a @code{memoryview} object.
2733 @findex Inferior.write_memory
2734 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
2735 Write the contents of @var{buffer} to the inferior, starting at
2736 @var{address}. The @var{buffer} parameter must be a Python object
2737 which supports the buffer protocol, i.e., a string, an array or the
2738 object returned from @code{Inferior.read_memory}. If given, @var{length}
2739 determines the number of bytes from @var{buffer} to be written.
2742 @findex gdb.search_memory
2743 @defun Inferior.search_memory (address, length, pattern)
2744 Search a region of the inferior memory starting at @var{address} with
2745 the given @var{length} using the search pattern supplied in
2746 @var{pattern}. The @var{pattern} parameter must be a Python object
2747 which supports the buffer protocol, i.e., a string, an array or the
2748 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
2749 containing the address where the pattern was found, or @code{None} if
2750 the pattern could not be found.
2753 @node Events In Python
2754 @subsubsection Events In Python
2755 @cindex inferior events in Python
2757 @value{GDBN} provides a general event facility so that Python code can be
2758 notified of various state changes, particularly changes that occur in
2761 An @dfn{event} is just an object that describes some state change. The
2762 type of the object and its attributes will vary depending on the details
2763 of the change. All the existing events are described below.
2765 In order to be notified of an event, you must register an event handler
2766 with an @dfn{event registry}. An event registry is an object in the
2767 @code{gdb.events} module which dispatches particular events. A registry
2768 provides methods to register and unregister event handlers:
2770 @defun EventRegistry.connect (object)
2771 Add the given callable @var{object} to the registry. This object will be
2772 called when an event corresponding to this registry occurs.
2775 @defun EventRegistry.disconnect (object)
2776 Remove the given @var{object} from the registry. Once removed, the object
2777 will no longer receive notifications of events.
2783 def exit_handler (event):
2784 print "event type: exit"
2785 print "exit code: %d" % (event.exit_code)
2787 gdb.events.exited.connect (exit_handler)
2790 In the above example we connect our handler @code{exit_handler} to the
2791 registry @code{events.exited}. Once connected, @code{exit_handler} gets
2792 called when the inferior exits. The argument @dfn{event} in this example is
2793 of type @code{gdb.ExitedEvent}. As you can see in the example the
2794 @code{ExitedEvent} object has an attribute which indicates the exit code of
2797 The following is a listing of the event registries that are available and
2798 details of the events they emit:
2803 Emits @code{gdb.ThreadEvent}.
2805 Some events can be thread specific when @value{GDBN} is running in non-stop
2806 mode. When represented in Python, these events all extend
2807 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
2808 events which are emitted by this or other modules might extend this event.
2809 Examples of these events are @code{gdb.BreakpointEvent} and
2810 @code{gdb.ContinueEvent}.
2812 @defvar ThreadEvent.inferior_thread
2813 In non-stop mode this attribute will be set to the specific thread which was
2814 involved in the emitted event. Otherwise, it will be set to @code{None}.
2817 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
2819 This event indicates that the inferior has been continued after a stop. For
2820 inherited attribute refer to @code{gdb.ThreadEvent} above.
2823 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
2824 @code{events.ExitedEvent} has two attributes:
2825 @defvar ExitedEvent.exit_code
2826 An integer representing the exit code, if available, which the inferior
2827 has returned. (The exit code could be unavailable if, for example,
2828 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
2829 the attribute does not exist.
2831 @defvar ExitedEvent inferior
2832 A reference to the inferior which triggered the @code{exited} event.
2836 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
2838 Indicates that the inferior has stopped. All events emitted by this registry
2839 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
2840 will indicate the stopped thread when @value{GDBN} is running in non-stop
2841 mode. Refer to @code{gdb.ThreadEvent} above for more details.
2843 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
2845 This event indicates that the inferior or one of its threads has received as
2846 signal. @code{gdb.SignalEvent} has the following attributes:
2848 @defvar SignalEvent.stop_signal
2849 A string representing the signal received by the inferior. A list of possible
2850 signal values can be obtained by running the command @code{info signals} in
2851 the @value{GDBN} command prompt.
2854 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
2856 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
2857 been hit, and has the following attributes:
2859 @defvar BreakpointEvent.breakpoints
2860 A sequence containing references to all the breakpoints (type
2861 @code{gdb.Breakpoint}) that were hit.
2862 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
2864 @defvar BreakpointEvent.breakpoint
2865 A reference to the first breakpoint that was hit.
2866 This function is maintained for backward compatibility and is now deprecated
2867 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
2870 @item events.new_objfile
2871 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
2872 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
2874 @defvar NewObjFileEvent.new_objfile
2875 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
2876 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
2879 @item events.clear_objfiles
2880 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
2881 files for a program space has been reset.
2882 @code{gdb.ClearObjFilesEvent} has one attribute:
2884 @defvar ClearObjFilesEvent.progspace
2885 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
2886 been cleared. @xref{Progspaces In Python}.
2889 @item events.inferior_call_pre
2890 Emits @code{gdb.InferiorCallPreEvent} which indicates that a function in
2891 the inferior is about to be called.
2893 @defvar InferiorCallPreEvent.ptid
2894 The thread in which the call will be run.
2897 @defvar InferiorCallPreEvent.address
2898 The location of the function to be called.
2901 @item events.inferior_call_post
2902 Emits @code{gdb.InferiorCallPostEvent} which indicates that a function in
2903 the inferior has returned.
2905 @defvar InferiorCallPostEvent.ptid
2906 The thread in which the call was run.
2909 @defvar InferiorCallPostEvent.address
2910 The location of the function that was called.
2913 @item events.memory_changed
2914 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
2915 inferior has been modified by the @value{GDBN} user, for instance via a
2916 command like @w{@code{set *addr = value}}. The event has the following
2919 @defvar MemoryChangedEvent.address
2920 The start address of the changed region.
2923 @defvar MemoryChangedEvent.length
2924 Length in bytes of the changed region.
2927 @item events.register_changed
2928 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
2929 inferior has been modified by the @value{GDBN} user.
2931 @defvar RegisterChangedEvent.frame
2932 A gdb.Frame object representing the frame in which the register was modified.
2934 @defvar RegisterChangedEvent.regnum
2935 Denotes which register was modified.
2940 @node Threads In Python
2941 @subsubsection Threads In Python
2942 @cindex threads in python
2944 @findex gdb.InferiorThread
2945 Python scripts can access information about, and manipulate inferior threads
2946 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
2948 The following thread-related functions are available in the @code{gdb}
2951 @findex gdb.selected_thread
2952 @defun gdb.selected_thread ()
2953 This function returns the thread object for the selected thread. If there
2954 is no selected thread, this will return @code{None}.
2957 A @code{gdb.InferiorThread} object has the following attributes:
2959 @defvar InferiorThread.name
2960 The name of the thread. If the user specified a name using
2961 @code{thread name}, then this returns that name. Otherwise, if an
2962 OS-supplied name is available, then it is returned. Otherwise, this
2963 returns @code{None}.
2965 This attribute can be assigned to. The new value must be a string
2966 object, which sets the new name, or @code{None}, which removes any
2967 user-specified thread name.
2970 @defvar InferiorThread.num
2971 ID of the thread, as assigned by GDB.
2974 @defvar InferiorThread.ptid
2975 ID of the thread, as assigned by the operating system. This attribute is a
2976 tuple containing three integers. The first is the Process ID (PID); the second
2977 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
2978 Either the LWPID or TID may be 0, which indicates that the operating system
2979 does not use that identifier.
2982 A @code{gdb.InferiorThread} object has the following methods:
2984 @defun InferiorThread.is_valid ()
2985 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
2986 @code{False} if not. A @code{gdb.InferiorThread} object will become
2987 invalid if the thread exits, or the inferior that the thread belongs
2988 is deleted. All other @code{gdb.InferiorThread} methods will throw an
2989 exception if it is invalid at the time the method is called.
2992 @defun InferiorThread.switch ()
2993 This changes @value{GDBN}'s currently selected thread to the one represented
2997 @defun InferiorThread.is_stopped ()
2998 Return a Boolean indicating whether the thread is stopped.
3001 @defun InferiorThread.is_running ()
3002 Return a Boolean indicating whether the thread is running.
3005 @defun InferiorThread.is_exited ()
3006 Return a Boolean indicating whether the thread is exited.
3009 @node Commands In Python
3010 @subsubsection Commands In Python
3012 @cindex commands in python
3013 @cindex python commands
3014 You can implement new @value{GDBN} CLI commands in Python. A CLI
3015 command is implemented using an instance of the @code{gdb.Command}
3016 class, most commonly using a subclass.
3018 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
3019 The object initializer for @code{Command} registers the new command
3020 with @value{GDBN}. This initializer is normally invoked from the
3021 subclass' own @code{__init__} method.
3023 @var{name} is the name of the command. If @var{name} consists of
3024 multiple words, then the initial words are looked for as prefix
3025 commands. In this case, if one of the prefix commands does not exist,
3026 an exception is raised.
3028 There is no support for multi-line commands.
3030 @var{command_class} should be one of the @samp{COMMAND_} constants
3031 defined below. This argument tells @value{GDBN} how to categorize the
3032 new command in the help system.
3034 @var{completer_class} is an optional argument. If given, it should be
3035 one of the @samp{COMPLETE_} constants defined below. This argument
3036 tells @value{GDBN} how to perform completion for this command. If not
3037 given, @value{GDBN} will attempt to complete using the object's
3038 @code{complete} method (see below); if no such method is found, an
3039 error will occur when completion is attempted.
3041 @var{prefix} is an optional argument. If @code{True}, then the new
3042 command is a prefix command; sub-commands of this command may be
3045 The help text for the new command is taken from the Python
3046 documentation string for the command's class, if there is one. If no
3047 documentation string is provided, the default value ``This command is
3048 not documented.'' is used.
3051 @cindex don't repeat Python command
3052 @defun Command.dont_repeat ()
3053 By default, a @value{GDBN} command is repeated when the user enters a
3054 blank line at the command prompt. A command can suppress this
3055 behavior by invoking the @code{dont_repeat} method. This is similar
3056 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
3059 @defun Command.invoke (argument, from_tty)
3060 This method is called by @value{GDBN} when this command is invoked.
3062 @var{argument} is a string. It is the argument to the command, after
3063 leading and trailing whitespace has been stripped.
3065 @var{from_tty} is a boolean argument. When true, this means that the
3066 command was entered by the user at the terminal; when false it means
3067 that the command came from elsewhere.
3069 If this method throws an exception, it is turned into a @value{GDBN}
3070 @code{error} call. Otherwise, the return value is ignored.
3072 @findex gdb.string_to_argv
3073 To break @var{argument} up into an argv-like string use
3074 @code{gdb.string_to_argv}. This function behaves identically to
3075 @value{GDBN}'s internal argument lexer @code{buildargv}.
3076 It is recommended to use this for consistency.
3077 Arguments are separated by spaces and may be quoted.
3081 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
3082 ['1', '2 "3', '4 "5', "6 '7"]
3087 @cindex completion of Python commands
3088 @defun Command.complete (text, word)
3089 This method is called by @value{GDBN} when the user attempts
3090 completion on this command. All forms of completion are handled by
3091 this method, that is, the @key{TAB} and @key{M-?} key bindings
3092 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
3095 The arguments @var{text} and @var{word} are both strings; @var{text}
3096 holds the complete command line up to the cursor's location, while
3097 @var{word} holds the last word of the command line; this is computed
3098 using a word-breaking heuristic.
3100 The @code{complete} method can return several values:
3103 If the return value is a sequence, the contents of the sequence are
3104 used as the completions. It is up to @code{complete} to ensure that the
3105 contents actually do complete the word. A zero-length sequence is
3106 allowed, it means that there were no completions available. Only
3107 string elements of the sequence are used; other elements in the
3108 sequence are ignored.
3111 If the return value is one of the @samp{COMPLETE_} constants defined
3112 below, then the corresponding @value{GDBN}-internal completion
3113 function is invoked, and its result is used.
3116 All other results are treated as though there were no available
3121 When a new command is registered, it must be declared as a member of
3122 some general class of commands. This is used to classify top-level
3123 commands in the on-line help system; note that prefix commands are not
3124 listed under their own category but rather that of their top-level
3125 command. The available classifications are represented by constants
3126 defined in the @code{gdb} module:
3129 @findex COMMAND_NONE
3130 @findex gdb.COMMAND_NONE
3131 @item gdb.COMMAND_NONE
3132 The command does not belong to any particular class. A command in
3133 this category will not be displayed in any of the help categories.
3135 @findex COMMAND_RUNNING
3136 @findex gdb.COMMAND_RUNNING
3137 @item gdb.COMMAND_RUNNING
3138 The command is related to running the inferior. For example,
3139 @code{start}, @code{step}, and @code{continue} are in this category.
3140 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
3141 commands in this category.
3143 @findex COMMAND_DATA
3144 @findex gdb.COMMAND_DATA
3145 @item gdb.COMMAND_DATA
3146 The command is related to data or variables. For example,
3147 @code{call}, @code{find}, and @code{print} are in this category. Type
3148 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
3151 @findex COMMAND_STACK
3152 @findex gdb.COMMAND_STACK
3153 @item gdb.COMMAND_STACK
3154 The command has to do with manipulation of the stack. For example,
3155 @code{backtrace}, @code{frame}, and @code{return} are in this
3156 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
3157 list of commands in this category.
3159 @findex COMMAND_FILES
3160 @findex gdb.COMMAND_FILES
3161 @item gdb.COMMAND_FILES
3162 This class is used for file-related commands. For example,
3163 @code{file}, @code{list} and @code{section} are in this category.
3164 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
3165 commands in this category.
3167 @findex COMMAND_SUPPORT
3168 @findex gdb.COMMAND_SUPPORT
3169 @item gdb.COMMAND_SUPPORT
3170 This should be used for ``support facilities'', generally meaning
3171 things that are useful to the user when interacting with @value{GDBN},
3172 but not related to the state of the inferior. For example,
3173 @code{help}, @code{make}, and @code{shell} are in this category. Type
3174 @kbd{help support} at the @value{GDBN} prompt to see a list of
3175 commands in this category.
3177 @findex COMMAND_STATUS
3178 @findex gdb.COMMAND_STATUS
3179 @item gdb.COMMAND_STATUS
3180 The command is an @samp{info}-related command, that is, related to the
3181 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
3182 and @code{show} are in this category. Type @kbd{help status} at the
3183 @value{GDBN} prompt to see a list of commands in this category.
3185 @findex COMMAND_BREAKPOINTS
3186 @findex gdb.COMMAND_BREAKPOINTS
3187 @item gdb.COMMAND_BREAKPOINTS
3188 The command has to do with breakpoints. For example, @code{break},
3189 @code{clear}, and @code{delete} are in this category. Type @kbd{help
3190 breakpoints} at the @value{GDBN} prompt to see a list of commands in
3193 @findex COMMAND_TRACEPOINTS
3194 @findex gdb.COMMAND_TRACEPOINTS
3195 @item gdb.COMMAND_TRACEPOINTS
3196 The command has to do with tracepoints. For example, @code{trace},
3197 @code{actions}, and @code{tfind} are in this category. Type
3198 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
3199 commands in this category.
3201 @findex COMMAND_USER
3202 @findex gdb.COMMAND_USER
3203 @item gdb.COMMAND_USER
3204 The command is a general purpose command for the user, and typically
3205 does not fit in one of the other categories.
3206 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
3207 a list of commands in this category, as well as the list of gdb macros
3208 (@pxref{Sequences}).
3210 @findex COMMAND_OBSCURE
3211 @findex gdb.COMMAND_OBSCURE
3212 @item gdb.COMMAND_OBSCURE
3213 The command is only used in unusual circumstances, or is not of
3214 general interest to users. For example, @code{checkpoint},
3215 @code{fork}, and @code{stop} are in this category. Type @kbd{help
3216 obscure} at the @value{GDBN} prompt to see a list of commands in this
3219 @findex COMMAND_MAINTENANCE
3220 @findex gdb.COMMAND_MAINTENANCE
3221 @item gdb.COMMAND_MAINTENANCE
3222 The command is only useful to @value{GDBN} maintainers. The
3223 @code{maintenance} and @code{flushregs} commands are in this category.
3224 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
3225 commands in this category.
3228 A new command can use a predefined completion function, either by
3229 specifying it via an argument at initialization, or by returning it
3230 from the @code{complete} method. These predefined completion
3231 constants are all defined in the @code{gdb} module:
3234 @vindex COMPLETE_NONE
3235 @item gdb.COMPLETE_NONE
3236 This constant means that no completion should be done.
3238 @vindex COMPLETE_FILENAME
3239 @item gdb.COMPLETE_FILENAME
3240 This constant means that filename completion should be performed.
3242 @vindex COMPLETE_LOCATION
3243 @item gdb.COMPLETE_LOCATION
3244 This constant means that location completion should be done.
3245 @xref{Specify Location}.
3247 @vindex COMPLETE_COMMAND
3248 @item gdb.COMPLETE_COMMAND
3249 This constant means that completion should examine @value{GDBN}
3252 @vindex COMPLETE_SYMBOL
3253 @item gdb.COMPLETE_SYMBOL
3254 This constant means that completion should be done using symbol names
3257 @vindex COMPLETE_EXPRESSION
3258 @item gdb.COMPLETE_EXPRESSION
3259 This constant means that completion should be done on expressions.
3260 Often this means completing on symbol names, but some language
3261 parsers also have support for completing on field names.
3264 The following code snippet shows how a trivial CLI command can be
3265 implemented in Python:
3268 class HelloWorld (gdb.Command):
3269 """Greet the whole world."""
3271 def __init__ (self):
3272 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
3274 def invoke (self, arg, from_tty):
3275 print "Hello, World!"
3280 The last line instantiates the class, and is necessary to trigger the
3281 registration of the command with @value{GDBN}. Depending on how the
3282 Python code is read into @value{GDBN}, you may need to import the
3283 @code{gdb} module explicitly.
3285 @node Parameters In Python
3286 @subsubsection Parameters In Python
3288 @cindex parameters in python
3289 @cindex python parameters
3290 @tindex gdb.Parameter
3292 You can implement new @value{GDBN} parameters using Python. A new
3293 parameter is implemented as an instance of the @code{gdb.Parameter}
3296 Parameters are exposed to the user via the @code{set} and
3297 @code{show} commands. @xref{Help}.
3299 There are many parameters that already exist and can be set in
3300 @value{GDBN}. Two examples are: @code{set follow fork} and
3301 @code{set charset}. Setting these parameters influences certain
3302 behavior in @value{GDBN}. Similarly, you can define parameters that
3303 can be used to influence behavior in custom Python scripts and commands.
3305 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
3306 The object initializer for @code{Parameter} registers the new
3307 parameter with @value{GDBN}. This initializer is normally invoked
3308 from the subclass' own @code{__init__} method.
3310 @var{name} is the name of the new parameter. If @var{name} consists
3311 of multiple words, then the initial words are looked for as prefix
3312 parameters. An example of this can be illustrated with the
3313 @code{set print} set of parameters. If @var{name} is
3314 @code{print foo}, then @code{print} will be searched as the prefix
3315 parameter. In this case the parameter can subsequently be accessed in
3316 @value{GDBN} as @code{set print foo}.
3318 If @var{name} consists of multiple words, and no prefix parameter group
3319 can be found, an exception is raised.
3321 @var{command-class} should be one of the @samp{COMMAND_} constants
3322 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
3323 categorize the new parameter in the help system.
3325 @var{parameter-class} should be one of the @samp{PARAM_} constants
3326 defined below. This argument tells @value{GDBN} the type of the new
3327 parameter; this information is used for input validation and
3330 If @var{parameter-class} is @code{PARAM_ENUM}, then
3331 @var{enum-sequence} must be a sequence of strings. These strings
3332 represent the possible values for the parameter.
3334 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
3335 of a fourth argument will cause an exception to be thrown.
3337 The help text for the new parameter is taken from the Python
3338 documentation string for the parameter's class, if there is one. If
3339 there is no documentation string, a default value is used.
3342 @defvar Parameter.set_doc
3343 If this attribute exists, and is a string, then its value is used as
3344 the help text for this parameter's @code{set} command. The value is
3345 examined when @code{Parameter.__init__} is invoked; subsequent changes
3349 @defvar Parameter.show_doc
3350 If this attribute exists, and is a string, then its value is used as
3351 the help text for this parameter's @code{show} command. The value is
3352 examined when @code{Parameter.__init__} is invoked; subsequent changes
3356 @defvar Parameter.value
3357 The @code{value} attribute holds the underlying value of the
3358 parameter. It can be read and assigned to just as any other
3359 attribute. @value{GDBN} does validation when assignments are made.
3362 There are two methods that should be implemented in any
3363 @code{Parameter} class. These are:
3365 @defun Parameter.get_set_string (self)
3366 @value{GDBN} will call this method when a @var{parameter}'s value has
3367 been changed via the @code{set} API (for example, @kbd{set foo off}).
3368 The @code{value} attribute has already been populated with the new
3369 value and may be used in output. This method must return a string.
3372 @defun Parameter.get_show_string (self, svalue)
3373 @value{GDBN} will call this method when a @var{parameter}'s
3374 @code{show} API has been invoked (for example, @kbd{show foo}). The
3375 argument @code{svalue} receives the string representation of the
3376 current value. This method must return a string.
3379 When a new parameter is defined, its type must be specified. The
3380 available types are represented by constants defined in the @code{gdb}
3384 @findex PARAM_BOOLEAN
3385 @findex gdb.PARAM_BOOLEAN
3386 @item gdb.PARAM_BOOLEAN
3387 The value is a plain boolean. The Python boolean values, @code{True}
3388 and @code{False} are the only valid values.
3390 @findex PARAM_AUTO_BOOLEAN
3391 @findex gdb.PARAM_AUTO_BOOLEAN
3392 @item gdb.PARAM_AUTO_BOOLEAN
3393 The value has three possible states: true, false, and @samp{auto}. In
3394 Python, true and false are represented using boolean constants, and
3395 @samp{auto} is represented using @code{None}.
3397 @findex PARAM_UINTEGER
3398 @findex gdb.PARAM_UINTEGER
3399 @item gdb.PARAM_UINTEGER
3400 The value is an unsigned integer. The value of 0 should be
3401 interpreted to mean ``unlimited''.
3403 @findex PARAM_INTEGER
3404 @findex gdb.PARAM_INTEGER
3405 @item gdb.PARAM_INTEGER
3406 The value is a signed integer. The value of 0 should be interpreted
3407 to mean ``unlimited''.
3409 @findex PARAM_STRING
3410 @findex gdb.PARAM_STRING
3411 @item gdb.PARAM_STRING
3412 The value is a string. When the user modifies the string, any escape
3413 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
3414 translated into corresponding characters and encoded into the current
3417 @findex PARAM_STRING_NOESCAPE
3418 @findex gdb.PARAM_STRING_NOESCAPE
3419 @item gdb.PARAM_STRING_NOESCAPE
3420 The value is a string. When the user modifies the string, escapes are
3421 passed through untranslated.
3423 @findex PARAM_OPTIONAL_FILENAME
3424 @findex gdb.PARAM_OPTIONAL_FILENAME
3425 @item gdb.PARAM_OPTIONAL_FILENAME
3426 The value is a either a filename (a string), or @code{None}.
3428 @findex PARAM_FILENAME
3429 @findex gdb.PARAM_FILENAME
3430 @item gdb.PARAM_FILENAME
3431 The value is a filename. This is just like
3432 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
3434 @findex PARAM_ZINTEGER
3435 @findex gdb.PARAM_ZINTEGER
3436 @item gdb.PARAM_ZINTEGER
3437 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
3438 is interpreted as itself.
3441 @findex gdb.PARAM_ENUM
3442 @item gdb.PARAM_ENUM
3443 The value is a string, which must be one of a collection string
3444 constants provided when the parameter is created.
3447 @node Functions In Python
3448 @subsubsection Writing new convenience functions
3450 @cindex writing convenience functions
3451 @cindex convenience functions in python
3452 @cindex python convenience functions
3453 @tindex gdb.Function
3455 You can implement new convenience functions (@pxref{Convenience Vars})
3456 in Python. A convenience function is an instance of a subclass of the
3457 class @code{gdb.Function}.
3459 @defun Function.__init__ (name)
3460 The initializer for @code{Function} registers the new function with
3461 @value{GDBN}. The argument @var{name} is the name of the function,
3462 a string. The function will be visible to the user as a convenience
3463 variable of type @code{internal function}, whose name is the same as
3464 the given @var{name}.
3466 The documentation for the new function is taken from the documentation
3467 string for the new class.
3470 @defun Function.invoke (@var{*args})
3471 When a convenience function is evaluated, its arguments are converted
3472 to instances of @code{gdb.Value}, and then the function's
3473 @code{invoke} method is called. Note that @value{GDBN} does not
3474 predetermine the arity of convenience functions. Instead, all
3475 available arguments are passed to @code{invoke}, following the
3476 standard Python calling convention. In particular, a convenience
3477 function can have default values for parameters without ill effect.
3479 The return value of this method is used as its value in the enclosing
3480 expression. If an ordinary Python value is returned, it is converted
3481 to a @code{gdb.Value} following the usual rules.
3484 The following code snippet shows how a trivial convenience function can
3485 be implemented in Python:
3488 class Greet (gdb.Function):
3489 """Return string to greet someone.
3490 Takes a name as argument."""
3492 def __init__ (self):
3493 super (Greet, self).__init__ ("greet")
3495 def invoke (self, name):
3496 return "Hello, %s!" % name.string ()
3501 The last line instantiates the class, and is necessary to trigger the
3502 registration of the function with @value{GDBN}. Depending on how the
3503 Python code is read into @value{GDBN}, you may need to import the
3504 @code{gdb} module explicitly.
3506 Now you can use the function in an expression:
3509 (gdb) print $greet("Bob")
3513 @node Progspaces In Python
3514 @subsubsection Program Spaces In Python
3516 @cindex progspaces in python
3517 @tindex gdb.Progspace
3519 A program space, or @dfn{progspace}, represents a symbolic view
3520 of an address space.
3521 It consists of all of the objfiles of the program.
3522 @xref{Objfiles In Python}.
3523 @xref{Inferiors and Programs, program spaces}, for more details
3524 about program spaces.
3526 The following progspace-related functions are available in the
3529 @findex gdb.current_progspace
3530 @defun gdb.current_progspace ()
3531 This function returns the program space of the currently selected inferior.
3532 @xref{Inferiors and Programs}.
3535 @findex gdb.progspaces
3536 @defun gdb.progspaces ()
3537 Return a sequence of all the progspaces currently known to @value{GDBN}.
3540 Each progspace is represented by an instance of the @code{gdb.Progspace}
3543 @defvar Progspace.filename
3544 The file name of the progspace as a string.
3547 @defvar Progspace.pretty_printers
3548 The @code{pretty_printers} attribute is a list of functions. It is
3549 used to look up pretty-printers. A @code{Value} is passed to each
3550 function in order; if the function returns @code{None}, then the
3551 search continues. Otherwise, the return value should be an object
3552 which is used to format the value. @xref{Pretty Printing API}, for more
3556 @defvar Progspace.type_printers
3557 The @code{type_printers} attribute is a list of type printer objects.
3558 @xref{Type Printing API}, for more information.
3561 @defvar Progspace.frame_filters
3562 The @code{frame_filters} attribute is a dictionary of frame filter
3563 objects. @xref{Frame Filter API}, for more information.
3566 One may add arbitrary attributes to @code{gdb.Progspace} objects
3567 in the usual Python way.
3568 This is useful if, for example, one needs to do some extra record keeping
3569 associated with the program space.
3571 In this contrived example, we want to perform some processing when
3572 an objfile with a certain symbol is loaded, but we only want to do
3573 this once because it is expensive. To achieve this we record the results
3574 with the program space because we can't predict when the desired objfile
3579 def clear_objfiles_handler(event):
3580 event.progspace.expensive_computation = None
3581 def expensive(symbol):
3582 """A mock routine to perform an "expensive" computation on symbol."""
3583 print "Computing the answer to the ultimate question ..."
3585 def new_objfile_handler(event):
3586 objfile = event.new_objfile
3587 progspace = objfile.progspace
3588 if not hasattr(progspace, 'expensive_computation') or \
3589 progspace.expensive_computation is None:
3590 # We use 'main' for the symbol to keep the example simple.
3591 # Note: There's no current way to constrain the lookup
3593 symbol = gdb.lookup_global_symbol('main')
3594 if symbol is not None:
3595 progspace.expensive_computation = expensive(symbol)
3596 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
3597 gdb.events.new_objfile.connect(new_objfile_handler)
3599 (gdb) file /tmp/hello
3600 Reading symbols from /tmp/hello...done.
3601 Computing the answer to the ultimate question ...
3602 (gdb) python print gdb.current_progspace().expensive_computation
3605 Starting program: /tmp/hello
3607 [Inferior 1 (process 4242) exited normally]
3610 @node Objfiles In Python
3611 @subsubsection Objfiles In Python
3613 @cindex objfiles in python
3616 @value{GDBN} loads symbols for an inferior from various
3617 symbol-containing files (@pxref{Files}). These include the primary
3618 executable file, any shared libraries used by the inferior, and any
3619 separate debug info files (@pxref{Separate Debug Files}).
3620 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
3622 The following objfile-related functions are available in the
3625 @findex gdb.current_objfile
3626 @defun gdb.current_objfile ()
3627 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
3628 sets the ``current objfile'' to the corresponding objfile. This
3629 function returns the current objfile. If there is no current objfile,
3630 this function returns @code{None}.
3633 @findex gdb.objfiles
3634 @defun gdb.objfiles ()
3635 Return a sequence of all the objfiles current known to @value{GDBN}.
3636 @xref{Objfiles In Python}.
3639 @findex gdb.lookup_objfile
3640 @defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
3641 Look up @var{name}, a file name or build ID, in the list of objfiles
3642 for the current program space (@pxref{Progspaces In Python}).
3643 If the objfile is not found throw the Python @code{ValueError} exception.
3645 If @var{name} is a relative file name, then it will match any
3646 source file name with the same trailing components. For example, if
3647 @var{name} is @samp{gcc/expr.c}, then it will match source file
3648 name of @file{/build/trunk/gcc/expr.c}, but not
3649 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
3651 If @var{by_build_id} is provided and is @code{True} then @var{name}
3652 is the build ID of the objfile. Otherwise, @var{name} is a file name.
3653 This is supported only on some operating systems, notably those which use
3654 the ELF format for binary files and the @sc{gnu} Binutils. For more details
3655 about this feature, see the description of the @option{--build-id}
3656 command-line option in @ref{Options, , Command Line Options, ld.info,
3660 Each objfile is represented by an instance of the @code{gdb.Objfile}
3663 @defvar Objfile.filename
3664 The file name of the objfile as a string, with symbolic links resolved.
3666 The value is @code{None} if the objfile is no longer valid.
3667 See the @code{gdb.Objfile.is_valid} method, described below.
3670 @defvar Objfile.username
3671 The file name of the objfile as specified by the user as a string.
3673 The value is @code{None} if the objfile is no longer valid.
3674 See the @code{gdb.Objfile.is_valid} method, described below.
3677 @defvar Objfile.owner
3678 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
3679 object that debug info is being provided for.
3680 Otherwise this is @code{None}.
3681 Separate debug info objfiles are added with the
3682 @code{gdb.Objfile.add_separate_debug_file} method, described below.
3685 @defvar Objfile.build_id
3686 The build ID of the objfile as a string.
3687 If the objfile does not have a build ID then the value is @code{None}.
3689 This is supported only on some operating systems, notably those which use
3690 the ELF format for binary files and the @sc{gnu} Binutils. For more details
3691 about this feature, see the description of the @option{--build-id}
3692 command-line option in @ref{Options, , Command Line Options, ld.info,
3696 @defvar Objfile.progspace
3697 The containing program space of the objfile as a @code{gdb.Progspace}
3698 object. @xref{Progspaces In Python}.
3701 @defvar Objfile.pretty_printers
3702 The @code{pretty_printers} attribute is a list of functions. It is
3703 used to look up pretty-printers. A @code{Value} is passed to each
3704 function in order; if the function returns @code{None}, then the
3705 search continues. Otherwise, the return value should be an object
3706 which is used to format the value. @xref{Pretty Printing API}, for more
3710 @defvar Objfile.type_printers
3711 The @code{type_printers} attribute is a list of type printer objects.
3712 @xref{Type Printing API}, for more information.
3715 @defvar Objfile.frame_filters
3716 The @code{frame_filters} attribute is a dictionary of frame filter
3717 objects. @xref{Frame Filter API}, for more information.
3720 One may add arbitrary attributes to @code{gdb.Objfile} objects
3721 in the usual Python way.
3722 This is useful if, for example, one needs to do some extra record keeping
3723 associated with the objfile.
3725 In this contrived example we record the time when @value{GDBN}
3731 def new_objfile_handler(event):
3732 # Set the time_loaded attribute of the new objfile.
3733 event.new_objfile.time_loaded = datetime.datetime.today()
3734 gdb.events.new_objfile.connect(new_objfile_handler)
3737 Reading symbols from ./hello...done.
3738 (gdb) python print gdb.objfiles()[0].time_loaded
3739 2014-10-09 11:41:36.770345
3742 A @code{gdb.Objfile} object has the following methods:
3744 @defun Objfile.is_valid ()
3745 Returns @code{True} if the @code{gdb.Objfile} object is valid,
3746 @code{False} if not. A @code{gdb.Objfile} object can become invalid
3747 if the object file it refers to is not loaded in @value{GDBN} any
3748 longer. All other @code{gdb.Objfile} methods will throw an exception
3749 if it is invalid at the time the method is called.
3752 @defun Objfile.add_separate_debug_file (file)
3753 Add @var{file} to the list of files that @value{GDBN} will search for
3754 debug information for the objfile.
3755 This is useful when the debug info has been removed from the program
3756 and stored in a separate file. @value{GDBN} has built-in support for
3757 finding separate debug info files (@pxref{Separate Debug Files}), but if
3758 the file doesn't live in one of the standard places that @value{GDBN}
3759 searches then this function can be used to add a debug info file
3760 from a different place.
3763 @node Frames In Python
3764 @subsubsection Accessing inferior stack frames from Python.
3766 @cindex frames in python
3767 When the debugged program stops, @value{GDBN} is able to analyze its call
3768 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
3769 represents a frame in the stack. A @code{gdb.Frame} object is only valid
3770 while its corresponding frame exists in the inferior's stack. If you try
3771 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
3772 exception (@pxref{Exception Handling}).
3774 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
3778 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
3782 The following frame-related functions are available in the @code{gdb} module:
3784 @findex gdb.selected_frame
3785 @defun gdb.selected_frame ()
3786 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
3789 @findex gdb.newest_frame
3790 @defun gdb.newest_frame ()
3791 Return the newest frame object for the selected thread.
3794 @defun gdb.frame_stop_reason_string (reason)
3795 Return a string explaining the reason why @value{GDBN} stopped unwinding
3796 frames, as expressed by the given @var{reason} code (an integer, see the
3797 @code{unwind_stop_reason} method further down in this section).
3800 A @code{gdb.Frame} object has the following methods:
3802 @defun Frame.is_valid ()
3803 Returns true if the @code{gdb.Frame} object is valid, false if not.
3804 A frame object can become invalid if the frame it refers to doesn't
3805 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
3806 an exception if it is invalid at the time the method is called.
3809 @defun Frame.name ()
3810 Returns the function name of the frame, or @code{None} if it can't be
3814 @defun Frame.architecture ()
3815 Returns the @code{gdb.Architecture} object corresponding to the frame's
3816 architecture. @xref{Architectures In Python}.
3819 @defun Frame.type ()
3820 Returns the type of the frame. The value can be one of:
3822 @item gdb.NORMAL_FRAME
3823 An ordinary stack frame.
3825 @item gdb.DUMMY_FRAME
3826 A fake stack frame that was created by @value{GDBN} when performing an
3827 inferior function call.
3829 @item gdb.INLINE_FRAME
3830 A frame representing an inlined function. The function was inlined
3831 into a @code{gdb.NORMAL_FRAME} that is older than this one.
3833 @item gdb.TAILCALL_FRAME
3834 A frame representing a tail call. @xref{Tail Call Frames}.
3836 @item gdb.SIGTRAMP_FRAME
3837 A signal trampoline frame. This is the frame created by the OS when
3838 it calls into a signal handler.
3840 @item gdb.ARCH_FRAME
3841 A fake stack frame representing a cross-architecture call.
3843 @item gdb.SENTINEL_FRAME
3844 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
3849 @defun Frame.unwind_stop_reason ()
3850 Return an integer representing the reason why it's not possible to find
3851 more frames toward the outermost frame. Use
3852 @code{gdb.frame_stop_reason_string} to convert the value returned by this
3853 function to a string. The value can be one of:
3856 @item gdb.FRAME_UNWIND_NO_REASON
3857 No particular reason (older frames should be available).
3859 @item gdb.FRAME_UNWIND_NULL_ID
3860 The previous frame's analyzer returns an invalid result. This is no
3861 longer used by @value{GDBN}, and is kept only for backward
3864 @item gdb.FRAME_UNWIND_OUTERMOST
3865 This frame is the outermost.
3867 @item gdb.FRAME_UNWIND_UNAVAILABLE
3868 Cannot unwind further, because that would require knowing the
3869 values of registers or memory that have not been collected.
3871 @item gdb.FRAME_UNWIND_INNER_ID
3872 This frame ID looks like it ought to belong to a NEXT frame,
3873 but we got it for a PREV frame. Normally, this is a sign of
3874 unwinder failure. It could also indicate stack corruption.
3876 @item gdb.FRAME_UNWIND_SAME_ID
3877 This frame has the same ID as the previous one. That means
3878 that unwinding further would almost certainly give us another
3879 frame with exactly the same ID, so break the chain. Normally,
3880 this is a sign of unwinder failure. It could also indicate
3883 @item gdb.FRAME_UNWIND_NO_SAVED_PC
3884 The frame unwinder did not find any saved PC, but we needed
3885 one to unwind further.
3887 @item gdb.FRAME_UNWIND_MEMORY_ERROR
3888 The frame unwinder caused an error while trying to access memory.
3890 @item gdb.FRAME_UNWIND_FIRST_ERROR
3891 Any stop reason greater or equal to this value indicates some kind
3892 of error. This special value facilitates writing code that tests
3893 for errors in unwinding in a way that will work correctly even if
3894 the list of the other values is modified in future @value{GDBN}
3895 versions. Using it, you could write:
3897 reason = gdb.selected_frame().unwind_stop_reason ()
3898 reason_str = gdb.frame_stop_reason_string (reason)
3899 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
3900 print "An error occured: %s" % reason_str
3907 Returns the frame's resume address.
3910 @defun Frame.block ()
3911 Return the frame's code block. @xref{Blocks In Python}.
3914 @defun Frame.function ()
3915 Return the symbol for the function corresponding to this frame.
3916 @xref{Symbols In Python}.
3919 @defun Frame.older ()
3920 Return the frame that called this frame.
3923 @defun Frame.newer ()
3924 Return the frame called by this frame.
3927 @defun Frame.find_sal ()
3928 Return the frame's symtab and line object.
3929 @xref{Symbol Tables In Python}.
3932 @defun Frame.read_register (register)
3933 Return the value of @var{register} in this frame. The @var{register}
3934 argument must be a string (e.g., @code{'sp'} or @code{'rax'}).
3935 Returns a @code{Gdb.Value} object. Throws an exception if @var{register}
3939 @defun Frame.read_var (variable @r{[}, block@r{]})
3940 Return the value of @var{variable} in this frame. If the optional
3941 argument @var{block} is provided, search for the variable from that
3942 block; otherwise start at the frame's current block (which is
3943 determined by the frame's current program counter). The @var{variable}
3944 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
3945 @code{gdb.Block} object.
3948 @defun Frame.select ()
3949 Set this frame to be the selected frame. @xref{Stack, ,Examining the
3953 @node Blocks In Python
3954 @subsubsection Accessing blocks from Python.
3956 @cindex blocks in python
3959 In @value{GDBN}, symbols are stored in blocks. A block corresponds
3960 roughly to a scope in the source code. Blocks are organized
3961 hierarchically, and are represented individually in Python as a
3962 @code{gdb.Block}. Blocks rely on debugging information being
3965 A frame has a block. Please see @ref{Frames In Python}, for a more
3966 in-depth discussion of frames.
3968 The outermost block is known as the @dfn{global block}. The global
3969 block typically holds public global variables and functions.
3971 The block nested just inside the global block is the @dfn{static
3972 block}. The static block typically holds file-scoped variables and
3975 @value{GDBN} provides a method to get a block's superblock, but there
3976 is currently no way to examine the sub-blocks of a block, or to
3977 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
3980 Here is a short example that should help explain blocks:
3983 /* This is in the global block. */
3986 /* This is in the static block. */
3987 static int file_scope;
3989 /* 'function' is in the global block, and 'argument' is
3990 in a block nested inside of 'function'. */
3991 int function (int argument)
3993 /* 'local' is in a block inside 'function'. It may or may
3994 not be in the same block as 'argument'. */
3998 /* 'inner' is in a block whose superblock is the one holding
4002 /* If this call is expanded by the compiler, you may see
4003 a nested block here whose function is 'inline_function'
4004 and whose superblock is the one holding 'inner'. */
4010 A @code{gdb.Block} is iterable. The iterator returns the symbols
4011 (@pxref{Symbols In Python}) local to the block. Python programs
4012 should not assume that a specific block object will always contain a
4013 given symbol, since changes in @value{GDBN} features and
4014 infrastructure may cause symbols move across blocks in a symbol
4017 The following block-related functions are available in the @code{gdb}
4020 @findex gdb.block_for_pc
4021 @defun gdb.block_for_pc (pc)
4022 Return the innermost @code{gdb.Block} containing the given @var{pc}
4023 value. If the block cannot be found for the @var{pc} value specified,
4024 the function will return @code{None}.
4027 A @code{gdb.Block} object has the following methods:
4029 @defun Block.is_valid ()
4030 Returns @code{True} if the @code{gdb.Block} object is valid,
4031 @code{False} if not. A block object can become invalid if the block it
4032 refers to doesn't exist anymore in the inferior. All other
4033 @code{gdb.Block} methods will throw an exception if it is invalid at
4034 the time the method is called. The block's validity is also checked
4035 during iteration over symbols of the block.
4038 A @code{gdb.Block} object has the following attributes:
4041 The start address of the block. This attribute is not writable.
4045 The end address of the block. This attribute is not writable.
4048 @defvar Block.function
4049 The name of the block represented as a @code{gdb.Symbol}. If the
4050 block is not named, then this attribute holds @code{None}. This
4051 attribute is not writable.
4053 For ordinary function blocks, the superblock is the static block.
4054 However, you should note that it is possible for a function block to
4055 have a superblock that is not the static block -- for instance this
4056 happens for an inlined function.
4059 @defvar Block.superblock
4060 The block containing this block. If this parent block does not exist,
4061 this attribute holds @code{None}. This attribute is not writable.
4064 @defvar Block.global_block
4065 The global block associated with this block. This attribute is not
4069 @defvar Block.static_block
4070 The static block associated with this block. This attribute is not
4074 @defvar Block.is_global
4075 @code{True} if the @code{gdb.Block} object is a global block,
4076 @code{False} if not. This attribute is not
4080 @defvar Block.is_static
4081 @code{True} if the @code{gdb.Block} object is a static block,
4082 @code{False} if not. This attribute is not writable.
4085 @node Symbols In Python
4086 @subsubsection Python representation of Symbols.
4088 @cindex symbols in python
4091 @value{GDBN} represents every variable, function and type as an
4092 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
4093 Similarly, Python represents these symbols in @value{GDBN} with the
4094 @code{gdb.Symbol} object.
4096 The following symbol-related functions are available in the @code{gdb}
4099 @findex gdb.lookup_symbol
4100 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
4101 This function searches for a symbol by name. The search scope can be
4102 restricted to the parameters defined in the optional domain and block
4105 @var{name} is the name of the symbol. It must be a string. The
4106 optional @var{block} argument restricts the search to symbols visible
4107 in that @var{block}. The @var{block} argument must be a
4108 @code{gdb.Block} object. If omitted, the block for the current frame
4109 is used. The optional @var{domain} argument restricts
4110 the search to the domain type. The @var{domain} argument must be a
4111 domain constant defined in the @code{gdb} module and described later
4114 The result is a tuple of two elements.
4115 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
4117 If the symbol is found, the second element is @code{True} if the symbol
4118 is a field of a method's object (e.g., @code{this} in C@t{++}),
4119 otherwise it is @code{False}.
4120 If the symbol is not found, the second element is @code{False}.
4123 @findex gdb.lookup_global_symbol
4124 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
4125 This function searches for a global symbol by name.
4126 The search scope can be restricted to by the domain argument.
4128 @var{name} is the name of the symbol. It must be a string.
4129 The optional @var{domain} argument restricts the search to the domain type.
4130 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4131 module and described later in this chapter.
4133 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4137 A @code{gdb.Symbol} object has the following attributes:
4140 The type of the symbol or @code{None} if no type is recorded.
4141 This attribute is represented as a @code{gdb.Type} object.
4142 @xref{Types In Python}. This attribute is not writable.
4145 @defvar Symbol.symtab
4146 The symbol table in which the symbol appears. This attribute is
4147 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
4148 Python}. This attribute is not writable.
4152 The line number in the source code at which the symbol was defined.
4157 The name of the symbol as a string. This attribute is not writable.
4160 @defvar Symbol.linkage_name
4161 The name of the symbol, as used by the linker (i.e., may be mangled).
4162 This attribute is not writable.
4165 @defvar Symbol.print_name
4166 The name of the symbol in a form suitable for output. This is either
4167 @code{name} or @code{linkage_name}, depending on whether the user
4168 asked @value{GDBN} to display demangled or mangled names.
4171 @defvar Symbol.addr_class
4172 The address class of the symbol. This classifies how to find the value
4173 of a symbol. Each address class is a constant defined in the
4174 @code{gdb} module and described later in this chapter.
4177 @defvar Symbol.needs_frame
4178 This is @code{True} if evaluating this symbol's value requires a frame
4179 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
4180 local variables will require a frame, but other symbols will not.
4183 @defvar Symbol.is_argument
4184 @code{True} if the symbol is an argument of a function.
4187 @defvar Symbol.is_constant
4188 @code{True} if the symbol is a constant.
4191 @defvar Symbol.is_function
4192 @code{True} if the symbol is a function or a method.
4195 @defvar Symbol.is_variable
4196 @code{True} if the symbol is a variable.
4199 A @code{gdb.Symbol} object has the following methods:
4201 @defun Symbol.is_valid ()
4202 Returns @code{True} if the @code{gdb.Symbol} object is valid,
4203 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
4204 the symbol it refers to does not exist in @value{GDBN} any longer.
4205 All other @code{gdb.Symbol} methods will throw an exception if it is
4206 invalid at the time the method is called.
4209 @defun Symbol.value (@r{[}frame@r{]})
4210 Compute the value of the symbol, as a @code{gdb.Value}. For
4211 functions, this computes the address of the function, cast to the
4212 appropriate type. If the symbol requires a frame in order to compute
4213 its value, then @var{frame} must be given. If @var{frame} is not
4214 given, or if @var{frame} is invalid, then this method will throw an
4218 The available domain categories in @code{gdb.Symbol} are represented
4219 as constants in the @code{gdb} module:
4222 @vindex SYMBOL_UNDEF_DOMAIN
4223 @item gdb.SYMBOL_UNDEF_DOMAIN
4224 This is used when a domain has not been discovered or none of the
4225 following domains apply. This usually indicates an error either
4226 in the symbol information or in @value{GDBN}'s handling of symbols.
4228 @vindex SYMBOL_VAR_DOMAIN
4229 @item gdb.SYMBOL_VAR_DOMAIN
4230 This domain contains variables, function names, typedef names and enum
4233 @vindex SYMBOL_STRUCT_DOMAIN
4234 @item gdb.SYMBOL_STRUCT_DOMAIN
4235 This domain holds struct, union and enum type names.
4237 @vindex SYMBOL_LABEL_DOMAIN
4238 @item gdb.SYMBOL_LABEL_DOMAIN
4239 This domain contains names of labels (for gotos).
4241 @vindex SYMBOL_VARIABLES_DOMAIN
4242 @item gdb.SYMBOL_VARIABLES_DOMAIN
4243 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
4244 contains everything minus functions and types.
4246 @vindex SYMBOL_FUNCTIONS_DOMAIN
4247 @item gdb.SYMBOL_FUNCTION_DOMAIN
4248 This domain contains all functions.
4250 @vindex SYMBOL_TYPES_DOMAIN
4251 @item gdb.SYMBOL_TYPES_DOMAIN
4252 This domain contains all types.
4255 The available address class categories in @code{gdb.Symbol} are represented
4256 as constants in the @code{gdb} module:
4259 @vindex SYMBOL_LOC_UNDEF
4260 @item gdb.SYMBOL_LOC_UNDEF
4261 If this is returned by address class, it indicates an error either in
4262 the symbol information or in @value{GDBN}'s handling of symbols.
4264 @vindex SYMBOL_LOC_CONST
4265 @item gdb.SYMBOL_LOC_CONST
4266 Value is constant int.
4268 @vindex SYMBOL_LOC_STATIC
4269 @item gdb.SYMBOL_LOC_STATIC
4270 Value is at a fixed address.
4272 @vindex SYMBOL_LOC_REGISTER
4273 @item gdb.SYMBOL_LOC_REGISTER
4274 Value is in a register.
4276 @vindex SYMBOL_LOC_ARG
4277 @item gdb.SYMBOL_LOC_ARG
4278 Value is an argument. This value is at the offset stored within the
4279 symbol inside the frame's argument list.
4281 @vindex SYMBOL_LOC_REF_ARG
4282 @item gdb.SYMBOL_LOC_REF_ARG
4283 Value address is stored in the frame's argument list. Just like
4284 @code{LOC_ARG} except that the value's address is stored at the
4285 offset, not the value itself.
4287 @vindex SYMBOL_LOC_REGPARM_ADDR
4288 @item gdb.SYMBOL_LOC_REGPARM_ADDR
4289 Value is a specified register. Just like @code{LOC_REGISTER} except
4290 the register holds the address of the argument instead of the argument
4293 @vindex SYMBOL_LOC_LOCAL
4294 @item gdb.SYMBOL_LOC_LOCAL
4295 Value is a local variable.
4297 @vindex SYMBOL_LOC_TYPEDEF
4298 @item gdb.SYMBOL_LOC_TYPEDEF
4299 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
4302 @vindex SYMBOL_LOC_BLOCK
4303 @item gdb.SYMBOL_LOC_BLOCK
4306 @vindex SYMBOL_LOC_CONST_BYTES
4307 @item gdb.SYMBOL_LOC_CONST_BYTES
4308 Value is a byte-sequence.
4310 @vindex SYMBOL_LOC_UNRESOLVED
4311 @item gdb.SYMBOL_LOC_UNRESOLVED
4312 Value is at a fixed address, but the address of the variable has to be
4313 determined from the minimal symbol table whenever the variable is
4316 @vindex SYMBOL_LOC_OPTIMIZED_OUT
4317 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
4318 The value does not actually exist in the program.
4320 @vindex SYMBOL_LOC_COMPUTED
4321 @item gdb.SYMBOL_LOC_COMPUTED
4322 The value's address is a computed location.
4325 @node Symbol Tables In Python
4326 @subsubsection Symbol table representation in Python.
4328 @cindex symbol tables in python
4330 @tindex gdb.Symtab_and_line
4332 Access to symbol table data maintained by @value{GDBN} on the inferior
4333 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
4334 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
4335 from the @code{find_sal} method in @code{gdb.Frame} object.
4336 @xref{Frames In Python}.
4338 For more information on @value{GDBN}'s symbol table management, see
4339 @ref{Symbols, ,Examining the Symbol Table}, for more information.
4341 A @code{gdb.Symtab_and_line} object has the following attributes:
4343 @defvar Symtab_and_line.symtab
4344 The symbol table object (@code{gdb.Symtab}) for this frame.
4345 This attribute is not writable.
4348 @defvar Symtab_and_line.pc
4349 Indicates the start of the address range occupied by code for the
4350 current source line. This attribute is not writable.
4353 @defvar Symtab_and_line.last
4354 Indicates the end of the address range occupied by code for the current
4355 source line. This attribute is not writable.
4358 @defvar Symtab_and_line.line
4359 Indicates the current line number for this object. This
4360 attribute is not writable.
4363 A @code{gdb.Symtab_and_line} object has the following methods:
4365 @defun Symtab_and_line.is_valid ()
4366 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
4367 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
4368 invalid if the Symbol table and line object it refers to does not
4369 exist in @value{GDBN} any longer. All other
4370 @code{gdb.Symtab_and_line} methods will throw an exception if it is
4371 invalid at the time the method is called.
4374 A @code{gdb.Symtab} object has the following attributes:
4376 @defvar Symtab.filename
4377 The symbol table's source filename. This attribute is not writable.
4380 @defvar Symtab.objfile
4381 The symbol table's backing object file. @xref{Objfiles In Python}.
4382 This attribute is not writable.
4385 @defvar Symtab.producer
4386 The name and possibly version number of the program that
4387 compiled the code in the symbol table.
4388 The contents of this string is up to the compiler.
4389 If no producer information is available then @code{None} is returned.
4390 This attribute is not writable.
4393 A @code{gdb.Symtab} object has the following methods:
4395 @defun Symtab.is_valid ()
4396 Returns @code{True} if the @code{gdb.Symtab} object is valid,
4397 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
4398 the symbol table it refers to does not exist in @value{GDBN} any
4399 longer. All other @code{gdb.Symtab} methods will throw an exception
4400 if it is invalid at the time the method is called.
4403 @defun Symtab.fullname ()
4404 Return the symbol table's source absolute file name.
4407 @defun Symtab.global_block ()
4408 Return the global block of the underlying symbol table.
4409 @xref{Blocks In Python}.
4412 @defun Symtab.static_block ()
4413 Return the static block of the underlying symbol table.
4414 @xref{Blocks In Python}.
4417 @defun Symtab.linetable ()
4418 Return the line table associated with the symbol table.
4419 @xref{Line Tables In Python}.
4422 @node Line Tables In Python
4423 @subsubsection Manipulating line tables using Python
4425 @cindex line tables in python
4426 @tindex gdb.LineTable
4428 Python code can request and inspect line table information from a
4429 symbol table that is loaded in @value{GDBN}. A line table is a
4430 mapping of source lines to their executable locations in memory. To
4431 acquire the line table information for a particular symbol table, use
4432 the @code{linetable} function (@pxref{Symbol Tables In Python}).
4434 A @code{gdb.LineTable} is iterable. The iterator returns
4435 @code{LineTableEntry} objects that correspond to the source line and
4436 address for each line table entry. @code{LineTableEntry} objects have
4437 the following attributes:
4439 @defvar LineTableEntry.line
4440 The source line number for this line table entry. This number
4441 corresponds to the actual line of source. This attribute is not
4445 @defvar LineTableEntry.pc
4446 The address that is associated with the line table entry where the
4447 executable code for that source line resides in memory. This
4448 attribute is not writable.
4451 As there can be multiple addresses for a single source line, you may
4452 receive multiple @code{LineTableEntry} objects with matching
4453 @code{line} attributes, but with different @code{pc} attributes. The
4454 iterator is sorted in ascending @code{pc} order. Here is a small
4455 example illustrating iterating over a line table.
4458 symtab = gdb.selected_frame().find_sal().symtab
4459 linetable = symtab.linetable()
4460 for line in linetable:
4461 print "Line: "+str(line.line)+" Address: "+hex(line.pc)
4464 This will have the following output:
4467 Line: 33 Address: 0x4005c8L
4468 Line: 37 Address: 0x4005caL
4469 Line: 39 Address: 0x4005d2L
4470 Line: 40 Address: 0x4005f8L
4471 Line: 42 Address: 0x4005ffL
4472 Line: 44 Address: 0x400608L
4473 Line: 42 Address: 0x40060cL
4474 Line: 45 Address: 0x400615L
4477 In addition to being able to iterate over a @code{LineTable}, it also
4478 has the following direct access methods:
4480 @defun LineTable.line (line)
4481 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
4482 entries in the line table for the given @var{line}, which specifies
4483 the source code line. If there are no entries for that source code
4484 @var{line}, the Python @code{None} is returned.
4487 @defun LineTable.has_line (line)
4488 Return a Python @code{Boolean} indicating whether there is an entry in
4489 the line table for this source line. Return @code{True} if an entry
4490 is found, or @code{False} if not.
4493 @defun LineTable.source_lines ()
4494 Return a Python @code{List} of the source line numbers in the symbol
4495 table. Only lines with executable code locations are returned. The
4496 contents of the @code{List} will just be the source line entries
4497 represented as Python @code{Long} values.
4500 @node Breakpoints In Python
4501 @subsubsection Manipulating breakpoints using Python
4503 @cindex breakpoints in python
4504 @tindex gdb.Breakpoint
4506 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
4509 @defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
4510 Create a new breakpoint according to @var{spec}, which is a string
4511 naming the location of the breakpoint, or an expression that defines a
4512 watchpoint. The contents can be any location recognized by the
4513 @code{break} command, or in the case of a watchpoint, by the
4514 @code{watch} command. The optional @var{type} denotes the breakpoint
4515 to create from the types defined later in this chapter. This argument
4516 can be either @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}; it
4517 defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
4518 argument allows the breakpoint to become invisible to the user. The
4519 breakpoint will neither be reported when created, nor will it be
4520 listed in the output from @code{info breakpoints} (but will be listed
4521 with the @code{maint info breakpoints} command). The optional
4522 @var{temporary} argument makes the breakpoint a temporary breakpoint.
4523 Temporary breakpoints are deleted after they have been hit. Any
4524 further access to the Python breakpoint after it has been hit will
4525 result in a runtime error (as that breakpoint has now been
4526 automatically deleted). The optional @var{wp_class} argument defines
4527 the class of watchpoint to create, if @var{type} is
4528 @code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it
4529 is assumed to be a @code{gdb.WP_WRITE} class.
4532 @defun Breakpoint.stop (self)
4533 The @code{gdb.Breakpoint} class can be sub-classed and, in
4534 particular, you may choose to implement the @code{stop} method.
4535 If this method is defined in a sub-class of @code{gdb.Breakpoint},
4536 it will be called when the inferior reaches any location of a
4537 breakpoint which instantiates that sub-class. If the method returns
4538 @code{True}, the inferior will be stopped at the location of the
4539 breakpoint, otherwise the inferior will continue.
4541 If there are multiple breakpoints at the same location with a
4542 @code{stop} method, each one will be called regardless of the
4543 return status of the previous. This ensures that all @code{stop}
4544 methods have a chance to execute at that location. In this scenario
4545 if one of the methods returns @code{True} but the others return
4546 @code{False}, the inferior will still be stopped.
4548 You should not alter the execution state of the inferior (i.e.@:, step,
4549 next, etc.), alter the current frame context (i.e.@:, change the current
4550 active frame), or alter, add or delete any breakpoint. As a general
4551 rule, you should not alter any data within @value{GDBN} or the inferior
4554 Example @code{stop} implementation:
4557 class MyBreakpoint (gdb.Breakpoint):
4559 inf_val = gdb.parse_and_eval("foo")
4566 The available watchpoint types represented by constants are defined in the
4572 Read only watchpoint.
4576 Write only watchpoint.
4580 Read/Write watchpoint.
4583 @defun Breakpoint.is_valid ()
4584 Return @code{True} if this @code{Breakpoint} object is valid,
4585 @code{False} otherwise. A @code{Breakpoint} object can become invalid
4586 if the user deletes the breakpoint. In this case, the object still
4587 exists, but the underlying breakpoint does not. In the cases of
4588 watchpoint scope, the watchpoint remains valid even if execution of the
4589 inferior leaves the scope of that watchpoint.
4592 @defun Breakpoint.delete ()
4593 Permanently deletes the @value{GDBN} breakpoint. This also
4594 invalidates the Python @code{Breakpoint} object. Any further access
4595 to this object's attributes or methods will raise an error.
4598 @defvar Breakpoint.enabled
4599 This attribute is @code{True} if the breakpoint is enabled, and
4600 @code{False} otherwise. This attribute is writable. You can use it to enable
4601 or disable the breakpoint.
4604 @defvar Breakpoint.silent
4605 This attribute is @code{True} if the breakpoint is silent, and
4606 @code{False} otherwise. This attribute is writable.
4608 Note that a breakpoint can also be silent if it has commands and the
4609 first command is @code{silent}. This is not reported by the
4610 @code{silent} attribute.
4613 @defvar Breakpoint.thread
4614 If the breakpoint is thread-specific, this attribute holds the thread
4615 id. If the breakpoint is not thread-specific, this attribute is
4616 @code{None}. This attribute is writable.
4619 @defvar Breakpoint.task
4620 If the breakpoint is Ada task-specific, this attribute holds the Ada task
4621 id. If the breakpoint is not task-specific (or the underlying
4622 language is not Ada), this attribute is @code{None}. This attribute
4626 @defvar Breakpoint.ignore_count
4627 This attribute holds the ignore count for the breakpoint, an integer.
4628 This attribute is writable.
4631 @defvar Breakpoint.number
4632 This attribute holds the breakpoint's number --- the identifier used by
4633 the user to manipulate the breakpoint. This attribute is not writable.
4636 @defvar Breakpoint.type
4637 This attribute holds the breakpoint's type --- the identifier used to
4638 determine the actual breakpoint type or use-case. This attribute is not
4642 @defvar Breakpoint.visible
4643 This attribute tells whether the breakpoint is visible to the user
4644 when set, or when the @samp{info breakpoints} command is run. This
4645 attribute is not writable.
4648 @defvar Breakpoint.temporary
4649 This attribute indicates whether the breakpoint was created as a
4650 temporary breakpoint. Temporary breakpoints are automatically deleted
4651 after that breakpoint has been hit. Access to this attribute, and all
4652 other attributes and functions other than the @code{is_valid}
4653 function, will result in an error after the breakpoint has been hit
4654 (as it has been automatically deleted). This attribute is not
4658 The available types are represented by constants defined in the @code{gdb}
4662 @vindex BP_BREAKPOINT
4663 @item gdb.BP_BREAKPOINT
4664 Normal code breakpoint.
4666 @vindex BP_WATCHPOINT
4667 @item gdb.BP_WATCHPOINT
4668 Watchpoint breakpoint.
4670 @vindex BP_HARDWARE_WATCHPOINT
4671 @item gdb.BP_HARDWARE_WATCHPOINT
4672 Hardware assisted watchpoint.
4674 @vindex BP_READ_WATCHPOINT
4675 @item gdb.BP_READ_WATCHPOINT
4676 Hardware assisted read watchpoint.
4678 @vindex BP_ACCESS_WATCHPOINT
4679 @item gdb.BP_ACCESS_WATCHPOINT
4680 Hardware assisted access watchpoint.
4683 @defvar Breakpoint.hit_count
4684 This attribute holds the hit count for the breakpoint, an integer.
4685 This attribute is writable, but currently it can only be set to zero.
4688 @defvar Breakpoint.location
4689 This attribute holds the location of the breakpoint, as specified by
4690 the user. It is a string. If the breakpoint does not have a location
4691 (that is, it is a watchpoint) the attribute's value is @code{None}. This
4692 attribute is not writable.
4695 @defvar Breakpoint.expression
4696 This attribute holds a breakpoint expression, as specified by
4697 the user. It is a string. If the breakpoint does not have an
4698 expression (the breakpoint is not a watchpoint) the attribute's value
4699 is @code{None}. This attribute is not writable.
4702 @defvar Breakpoint.condition
4703 This attribute holds the condition of the breakpoint, as specified by
4704 the user. It is a string. If there is no condition, this attribute's
4705 value is @code{None}. This attribute is writable.
4708 @defvar Breakpoint.commands
4709 This attribute holds the commands attached to the breakpoint. If
4710 there are commands, this attribute's value is a string holding all the
4711 commands, separated by newlines. If there are no commands, this
4712 attribute is @code{None}. This attribute is not writable.
4715 @node Finish Breakpoints in Python
4716 @subsubsection Finish Breakpoints
4718 @cindex python finish breakpoints
4719 @tindex gdb.FinishBreakpoint
4721 A finish breakpoint is a temporary breakpoint set at the return address of
4722 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
4723 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
4724 and deleted when the execution will run out of the breakpoint scope (i.e.@:
4725 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
4726 Finish breakpoints are thread specific and must be create with the right
4729 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
4730 Create a finish breakpoint at the return address of the @code{gdb.Frame}
4731 object @var{frame}. If @var{frame} is not provided, this defaults to the
4732 newest frame. The optional @var{internal} argument allows the breakpoint to
4733 become invisible to the user. @xref{Breakpoints In Python}, for further
4734 details about this argument.
4737 @defun FinishBreakpoint.out_of_scope (self)
4738 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
4739 @code{return} command, @dots{}), a function may not properly terminate, and
4740 thus never hit the finish breakpoint. When @value{GDBN} notices such a
4741 situation, the @code{out_of_scope} callback will be triggered.
4743 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
4747 class MyFinishBreakpoint (gdb.FinishBreakpoint)
4749 print "normal finish"
4752 def out_of_scope ():
4753 print "abnormal finish"
4757 @defvar FinishBreakpoint.return_value
4758 When @value{GDBN} is stopped at a finish breakpoint and the frame
4759 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
4760 attribute will contain a @code{gdb.Value} object corresponding to the return
4761 value of the function. The value will be @code{None} if the function return
4762 type is @code{void} or if the return value was not computable. This attribute
4766 @node Lazy Strings In Python
4767 @subsubsection Python representation of lazy strings.
4769 @cindex lazy strings in python
4770 @tindex gdb.LazyString
4772 A @dfn{lazy string} is a string whose contents is not retrieved or
4773 encoded until it is needed.
4775 A @code{gdb.LazyString} is represented in @value{GDBN} as an
4776 @code{address} that points to a region of memory, an @code{encoding}
4777 that will be used to encode that region of memory, and a @code{length}
4778 to delimit the region of memory that represents the string. The
4779 difference between a @code{gdb.LazyString} and a string wrapped within
4780 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
4781 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
4782 retrieved and encoded during printing, while a @code{gdb.Value}
4783 wrapping a string is immediately retrieved and encoded on creation.
4785 A @code{gdb.LazyString} object has the following functions:
4787 @defun LazyString.value ()
4788 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
4789 will point to the string in memory, but will lose all the delayed
4790 retrieval, encoding and handling that @value{GDBN} applies to a
4791 @code{gdb.LazyString}.
4794 @defvar LazyString.address
4795 This attribute holds the address of the string. This attribute is not
4799 @defvar LazyString.length
4800 This attribute holds the length of the string in characters. If the
4801 length is -1, then the string will be fetched and encoded up to the
4802 first null of appropriate width. This attribute is not writable.
4805 @defvar LazyString.encoding
4806 This attribute holds the encoding that will be applied to the string
4807 when the string is printed by @value{GDBN}. If the encoding is not
4808 set, or contains an empty string, then @value{GDBN} will select the
4809 most appropriate encoding when the string is printed. This attribute
4813 @defvar LazyString.type
4814 This attribute holds the type that is represented by the lazy string's
4815 type. For a lazy string this will always be a pointer type. To
4816 resolve this to the lazy string's character type, use the type's
4817 @code{target} method. @xref{Types In Python}. This attribute is not
4821 @node Architectures In Python
4822 @subsubsection Python representation of architectures
4823 @cindex Python architectures
4825 @value{GDBN} uses architecture specific parameters and artifacts in a
4826 number of its various computations. An architecture is represented
4827 by an instance of the @code{gdb.Architecture} class.
4829 A @code{gdb.Architecture} class has the following methods:
4831 @defun Architecture.name ()
4832 Return the name (string value) of the architecture.
4835 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
4836 Return a list of disassembled instructions starting from the memory
4837 address @var{start_pc}. The optional arguments @var{end_pc} and
4838 @var{count} determine the number of instructions in the returned list.
4839 If both the optional arguments @var{end_pc} and @var{count} are
4840 specified, then a list of at most @var{count} disassembled instructions
4841 whose start address falls in the closed memory address interval from
4842 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
4843 specified, but @var{count} is specified, then @var{count} number of
4844 instructions starting from the address @var{start_pc} are returned. If
4845 @var{count} is not specified but @var{end_pc} is specified, then all
4846 instructions whose start address falls in the closed memory address
4847 interval from @var{start_pc} to @var{end_pc} are returned. If neither
4848 @var{end_pc} nor @var{count} are specified, then a single instruction at
4849 @var{start_pc} is returned. For all of these cases, each element of the
4850 returned list is a Python @code{dict} with the following string keys:
4855 The value corresponding to this key is a Python long integer capturing
4856 the memory address of the instruction.
4859 The value corresponding to this key is a string value which represents
4860 the instruction with assembly language mnemonics. The assembly
4861 language flavor used is the same as that specified by the current CLI
4862 variable @code{disassembly-flavor}. @xref{Machine Code}.
4865 The value corresponding to this key is the length (integer value) of the
4866 instruction in bytes.
4871 @node Python Auto-loading
4872 @subsection Python Auto-loading
4873 @cindex Python auto-loading
4875 When a new object file is read (for example, due to the @code{file}
4876 command, or because the inferior has loaded a shared library),
4877 @value{GDBN} will look for Python support scripts in several ways:
4878 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
4879 @xref{Auto-loading extensions}.
4881 The auto-loading feature is useful for supplying application-specific
4882 debugging commands and scripts.
4884 Auto-loading can be enabled or disabled,
4885 and the list of auto-loaded scripts can be printed.
4888 @anchor{set auto-load python-scripts}
4889 @kindex set auto-load python-scripts
4890 @item set auto-load python-scripts [on|off]
4891 Enable or disable the auto-loading of Python scripts.
4893 @anchor{show auto-load python-scripts}
4894 @kindex show auto-load python-scripts
4895 @item show auto-load python-scripts
4896 Show whether auto-loading of Python scripts is enabled or disabled.
4898 @anchor{info auto-load python-scripts}
4899 @kindex info auto-load python-scripts
4900 @cindex print list of auto-loaded Python scripts
4901 @item info auto-load python-scripts [@var{regexp}]
4902 Print the list of all Python scripts that @value{GDBN} auto-loaded.
4904 Also printed is the list of Python scripts that were mentioned in
4905 the @code{.debug_gdb_scripts} section and were either not found
4906 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
4907 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
4908 This is useful because their names are not printed when @value{GDBN}
4909 tries to load them and fails. There may be many of them, and printing
4910 an error message for each one is problematic.
4912 If @var{regexp} is supplied only Python scripts with matching names are printed.
4917 (gdb) info auto-load python-scripts
4919 Yes py-section-script.py
4920 full name: /tmp/py-section-script.py
4921 No my-foo-pretty-printers.py
4925 When reading an auto-loaded file or script, @value{GDBN} sets the
4926 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
4927 function (@pxref{Objfiles In Python}). This can be useful for
4928 registering objfile-specific pretty-printers and frame-filters.
4930 @node Python modules
4931 @subsection Python modules
4932 @cindex python modules
4934 @value{GDBN} comes with several modules to assist writing Python code.
4937 * gdb.printing:: Building and registering pretty-printers.
4938 * gdb.types:: Utilities for working with types.
4939 * gdb.prompt:: Utilities for prompt value substitution.
4943 @subsubsection gdb.printing
4944 @cindex gdb.printing
4946 This module provides a collection of utilities for working with
4950 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
4951 This class specifies the API that makes @samp{info pretty-printer},
4952 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
4953 Pretty-printers should generally inherit from this class.
4955 @item SubPrettyPrinter (@var{name})
4956 For printers that handle multiple types, this class specifies the
4957 corresponding API for the subprinters.
4959 @item RegexpCollectionPrettyPrinter (@var{name})
4960 Utility class for handling multiple printers, all recognized via
4961 regular expressions.
4962 @xref{Writing a Pretty-Printer}, for an example.
4964 @item FlagEnumerationPrinter (@var{name})
4965 A pretty-printer which handles printing of @code{enum} values. Unlike
4966 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
4967 work properly when there is some overlap between the enumeration
4968 constants. The argument @var{name} is the name of the printer and
4969 also the name of the @code{enum} type to look up.
4971 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
4972 Register @var{printer} with the pretty-printer list of @var{obj}.
4973 If @var{replace} is @code{True} then any existing copy of the printer
4974 is replaced. Otherwise a @code{RuntimeError} exception is raised
4975 if a printer with the same name already exists.
4979 @subsubsection gdb.types
4982 This module provides a collection of utilities for working with
4983 @code{gdb.Type} objects.
4986 @item get_basic_type (@var{type})
4987 Return @var{type} with const and volatile qualifiers stripped,
4988 and with typedefs and C@t{++} references converted to the underlying type.
4993 typedef const int const_int;
4995 const_int& foo_ref (foo);
4996 int main () @{ return 0; @}
5003 (gdb) python import gdb.types
5004 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
5005 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
5009 @item has_field (@var{type}, @var{field})
5010 Return @code{True} if @var{type}, assumed to be a type with fields
5011 (e.g., a structure or union), has field @var{field}.
5013 @item make_enum_dict (@var{enum_type})
5014 Return a Python @code{dictionary} type produced from @var{enum_type}.
5016 @item deep_items (@var{type})
5017 Returns a Python iterator similar to the standard
5018 @code{gdb.Type.iteritems} method, except that the iterator returned
5019 by @code{deep_items} will recursively traverse anonymous struct or
5020 union fields. For example:
5034 Then in @value{GDBN}:
5036 (@value{GDBP}) python import gdb.types
5037 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
5038 (@value{GDBP}) python print struct_a.keys ()
5040 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
5041 @{['a', 'b0', 'b1']@}
5044 @item get_type_recognizers ()
5045 Return a list of the enabled type recognizers for the current context.
5046 This is called by @value{GDBN} during the type-printing process
5047 (@pxref{Type Printing API}).
5049 @item apply_type_recognizers (recognizers, type_obj)
5050 Apply the type recognizers, @var{recognizers}, to the type object
5051 @var{type_obj}. If any recognizer returns a string, return that
5052 string. Otherwise, return @code{None}. This is called by
5053 @value{GDBN} during the type-printing process (@pxref{Type Printing
5056 @item register_type_printer (locus, printer)
5057 This is a convenience function to register a type printer
5058 @var{printer}. The printer must implement the type printer protocol.
5059 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
5060 the printer is registered with that objfile; a @code{gdb.Progspace},
5061 in which case the printer is registered with that progspace; or
5062 @code{None}, in which case the printer is registered globally.
5065 This is a base class that implements the type printer protocol. Type
5066 printers are encouraged, but not required, to derive from this class.
5067 It defines a constructor:
5069 @defmethod TypePrinter __init__ (self, name)
5070 Initialize the type printer with the given name. The new printer
5071 starts in the enabled state.
5077 @subsubsection gdb.prompt
5080 This module provides a method for prompt value-substitution.
5083 @item substitute_prompt (@var{string})
5084 Return @var{string} with escape sequences substituted by values. Some
5085 escape sequences take arguments. You can specify arguments inside
5086 ``@{@}'' immediately following the escape sequence.
5088 The escape sequences you can pass to this function are:
5092 Substitute a backslash.
5094 Substitute an ESC character.
5096 Substitute the selected frame; an argument names a frame parameter.
5098 Substitute a newline.
5100 Substitute a parameter's value; the argument names the parameter.
5102 Substitute a carriage return.
5104 Substitute the selected thread; an argument names a thread parameter.
5106 Substitute the version of GDB.
5108 Substitute the current working directory.
5110 Begin a sequence of non-printing characters. These sequences are
5111 typically used with the ESC character, and are not counted in the string
5112 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
5113 blue-colored ``(gdb)'' prompt where the length is five.
5115 End a sequence of non-printing characters.
5121 substitute_prompt (``frame: \f,
5122 print arguments: \p@{print frame-arguments@}'')
5125 @exdent will return the string:
5128 "frame: main, print arguments: scalars"