1 @c Copyright (C) 2008-2019 Free Software Foundation, Inc.
2 @c Permission is granted to copy, distribute and/or modify this document
3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
4 @c any later version published by the Free Software Foundation; with the
5 @c Invariant Sections being ``Free Software'' and ``Free Software Needs
6 @c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
7 @c and with the Back-Cover Texts as in (a) below.
9 @c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
10 @c this GNU Manual. Buying copies from GNU Press supports the FSF in
11 @c developing GNU and promoting software freedom.''
14 @section Extending @value{GDBN} using Python
15 @cindex python scripting
16 @cindex scripting with python
18 You can extend @value{GDBN} using the @uref{http://www.python.org/,
19 Python programming language}. This feature is available only if
20 @value{GDBN} was configured using @option{--with-python}.
21 @value{GDBN} can be built against either Python 2 or Python 3; which
22 one you have depends on this configure-time option.
24 @cindex python directory
25 Python scripts used by @value{GDBN} should be installed in
26 @file{@var{data-directory}/python}, where @var{data-directory} is
27 the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
28 This directory, known as the @dfn{python directory},
29 is automatically added to the Python Search Path in order to allow
30 the Python interpreter to locate all scripts installed at this location.
32 Additionally, @value{GDBN} commands and convenience functions which
33 are written in Python and are located in the
34 @file{@var{data-directory}/python/gdb/command} or
35 @file{@var{data-directory}/python/gdb/function} directories are
36 automatically imported when @value{GDBN} starts.
39 * Python Commands:: Accessing Python from @value{GDBN}.
40 * Python API:: Accessing @value{GDBN} from Python.
41 * Python Auto-loading:: Automatically loading Python code.
42 * Python modules:: Python modules provided by @value{GDBN}.
46 @subsection Python Commands
47 @cindex python commands
48 @cindex commands to access python
50 @value{GDBN} provides two commands for accessing the Python interpreter,
51 and one related setting:
54 @kindex python-interactive
56 @item python-interactive @r{[}@var{command}@r{]}
57 @itemx pi @r{[}@var{command}@r{]}
58 Without an argument, the @code{python-interactive} command can be used
59 to start an interactive Python prompt. To return to @value{GDBN},
60 type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
62 Alternatively, a single-line Python command can be given as an
63 argument and evaluated. If the command is an expression, the result
64 will be printed; otherwise, nothing will be printed. For example:
67 (@value{GDBP}) python-interactive 2 + 3
73 @item python @r{[}@var{command}@r{]}
74 @itemx py @r{[}@var{command}@r{]}
75 The @code{python} command can be used to evaluate Python code.
77 If given an argument, the @code{python} command will evaluate the
78 argument as a Python command. For example:
81 (@value{GDBP}) python print 23
85 If you do not provide an argument to @code{python}, it will act as a
86 multi-line command, like @code{define}. In this case, the Python
87 script is made up of subsequent command lines, given after the
88 @code{python} command. This command list is terminated using a line
89 containing @code{end}. For example:
94 End with a line saying just "end".
100 @kindex set python print-stack
101 @item set python print-stack
102 By default, @value{GDBN} will print only the message component of a
103 Python exception when an error occurs in a Python script. This can be
104 controlled using @code{set python print-stack}: if @code{full}, then
105 full Python stack printing is enabled; if @code{none}, then Python stack
106 and message printing is disabled; if @code{message}, the default, only
107 the message component of the error is printed.
110 It is also possible to execute a Python script from the @value{GDBN}
114 @item source @file{script-name}
115 The script name must end with @samp{.py} and @value{GDBN} must be configured
116 to recognize the script language based on filename extension using
117 the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
121 @subsection Python API
123 @cindex programming in python
125 You can get quick online help for @value{GDBN}'s Python API by issuing
126 the command @w{@kbd{python help (gdb)}}.
128 Functions and methods which have two or more optional arguments allow
129 them to be specified using keyword syntax. This allows passing some
130 optional arguments while skipping others. Example:
131 @w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
134 * Basic Python:: Basic Python Functions.
135 * Exception Handling:: How Python exceptions are translated.
136 * Values From Inferior:: Python representation of values.
137 * Types In Python:: Python representation of types.
138 * Pretty Printing API:: Pretty-printing values.
139 * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
140 * Writing a Pretty-Printer:: Writing a Pretty-Printer.
141 * Type Printing API:: Pretty-printing types.
142 * Frame Filter API:: Filtering Frames.
143 * Frame Decorator API:: Decorating Frames.
144 * Writing a Frame Filter:: Writing a Frame Filter.
145 * Unwinding Frames in Python:: Writing frame unwinder.
146 * Xmethods In Python:: Adding and replacing methods of C++ classes.
147 * Xmethod API:: Xmethod types.
148 * Writing an Xmethod:: Writing an xmethod.
149 * Inferiors In Python:: Python representation of inferiors (processes)
150 * Events In Python:: Listening for events from @value{GDBN}.
151 * Threads In Python:: Accessing inferior threads from Python.
152 * Recordings In Python:: Accessing recordings from Python.
153 * Commands In Python:: Implementing new commands in Python.
154 * Parameters In Python:: Adding new @value{GDBN} parameters.
155 * Functions In Python:: Writing new convenience functions.
156 * Progspaces In Python:: Program spaces.
157 * Objfiles In Python:: Object files.
158 * Frames In Python:: Accessing inferior stack frames from Python.
159 * Blocks In Python:: Accessing blocks from Python.
160 * Symbols In Python:: Python representation of symbols.
161 * Symbol Tables In Python:: Python representation of symbol tables.
162 * Line Tables In Python:: Python representation of line tables.
163 * Breakpoints In Python:: Manipulating breakpoints using Python.
164 * Finish Breakpoints in Python:: Setting Breakpoints on function return
166 * Lazy Strings In Python:: Python representation of lazy strings.
167 * Architectures In Python:: Python representation of architectures.
171 @subsubsection Basic Python
173 @cindex python stdout
174 @cindex python pagination
175 At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
176 @code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
177 A Python program which outputs to one of these streams may have its
178 output interrupted by the user (@pxref{Screen Size}). In this
179 situation, a Python @code{KeyboardInterrupt} exception is thrown.
181 Some care must be taken when writing Python code to run in
182 @value{GDBN}. Two things worth noting in particular:
186 @value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
187 Python code must not override these, or even change the options using
188 @code{sigaction}. If your program changes the handling of these
189 signals, @value{GDBN} will most likely stop working correctly. Note
190 that it is unfortunately common for GUI toolkits to install a
191 @code{SIGCHLD} handler.
194 @value{GDBN} takes care to mark its internal file descriptors as
195 close-on-exec. However, this cannot be done in a thread-safe way on
196 all platforms. Your Python programs should be aware of this and
197 should both create new file descriptors with the close-on-exec flag
198 set and arrange to close unneeded file descriptors before starting a
202 @cindex python functions
203 @cindex python module
205 @value{GDBN} introduces a new Python module, named @code{gdb}. All
206 methods and classes added by @value{GDBN} are placed in this module.
207 @value{GDBN} automatically @code{import}s the @code{gdb} module for
208 use in all scripts evaluated by the @code{python} command.
210 Some types of the @code{gdb} module come with a textual representation
211 (accessible through the @code{repr} or @code{str} functions). These are
212 offered for debugging purposes only, expect them to change over time.
214 @findex gdb.PYTHONDIR
215 @defvar gdb.PYTHONDIR
216 A string containing the python directory (@pxref{Python}).
220 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
221 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
222 If a GDB exception happens while @var{command} runs, it is
223 translated as described in @ref{Exception Handling,,Exception Handling}.
225 The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
226 command as having originated from the user invoking it interactively.
227 It must be a boolean value. If omitted, it defaults to @code{False}.
229 By default, any output produced by @var{command} is sent to
230 @value{GDBN}'s standard output (and to the log output if logging is
231 turned on). If the @var{to_string} parameter is
232 @code{True}, then output will be collected by @code{gdb.execute} and
233 returned as a string. The default is @code{False}, in which case the
234 return value is @code{None}. If @var{to_string} is @code{True}, the
235 @value{GDBN} virtual terminal will be temporarily set to unlimited width
236 and height, and its pagination will be disabled; @pxref{Screen Size}.
239 @findex gdb.breakpoints
240 @defun gdb.breakpoints ()
241 Return a sequence holding all of @value{GDBN}'s breakpoints.
242 @xref{Breakpoints In Python}, for more information. In @value{GDBN}
243 version 7.11 and earlier, this function returned @code{None} if there
244 were no breakpoints. This peculiarity was subsequently fixed, and now
245 @code{gdb.breakpoints} returns an empty sequence in this case.
248 @defun gdb.rbreak (regex @r{[}, minsyms @r{[}, throttle, @r{[}, symtabs @r{]]]})
249 Return a Python list holding a collection of newly set
250 @code{gdb.Breakpoint} objects matching function names defined by the
251 @var{regex} pattern. If the @var{minsyms} keyword is @code{True}, all
252 system functions (those not explicitly defined in the inferior) will
253 also be included in the match. The @var{throttle} keyword takes an
254 integer that defines the maximum number of pattern matches for
255 functions matched by the @var{regex} pattern. If the number of
256 matches exceeds the integer value of @var{throttle}, a
257 @code{RuntimeError} will be raised and no breakpoints will be created.
258 If @var{throttle} is not defined then there is no imposed limit on the
259 maximum number of matches and breakpoints to be created. The
260 @var{symtabs} keyword takes a Python iterable that yields a collection
261 of @code{gdb.Symtab} objects and will restrict the search to those
262 functions only contained within the @code{gdb.Symtab} objects.
265 @findex gdb.parameter
266 @defun gdb.parameter (parameter)
267 Return the value of a @value{GDBN} @var{parameter} given by its name,
268 a string; the parameter name string may contain spaces if the parameter has a
269 multi-part name. For example, @samp{print object} is a valid
272 If the named parameter does not exist, this function throws a
273 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
274 parameter's value is converted to a Python value of the appropriate
279 @defun gdb.history (number)
280 Return a value from @value{GDBN}'s value history (@pxref{Value
281 History}). The @var{number} argument indicates which history element to return.
282 If @var{number} is negative, then @value{GDBN} will take its absolute value
283 and count backward from the last element (i.e., the most recent element) to
284 find the value to return. If @var{number} is zero, then @value{GDBN} will
285 return the most recent element. If the element specified by @var{number}
286 doesn't exist in the value history, a @code{gdb.error} exception will be
289 If no exception is raised, the return value is always an instance of
290 @code{gdb.Value} (@pxref{Values From Inferior}).
293 @findex gdb.convenience_variable
294 @defun gdb.convenience_variable (name)
295 Return the value of the convenience variable (@pxref{Convenience
296 Vars}) named @var{name}. @var{name} must be a string. The name
297 should not include the @samp{$} that is used to mark a convenience
298 variable in an expression. If the convenience variable does not
299 exist, then @code{None} is returned.
302 @findex gdb.set_convenience_variable
303 @defun gdb.set_convenience_variable (name, value)
304 Set the value of the convenience variable (@pxref{Convenience Vars})
305 named @var{name}. @var{name} must be a string. The name should not
306 include the @samp{$} that is used to mark a convenience variable in an
307 expression. If @var{value} is @code{None}, then the convenience
308 variable is removed. Otherwise, if @var{value} is not a
309 @code{gdb.Value} (@pxref{Values From Inferior}), it is is converted
310 using the @code{gdb.Value} constructor.
313 @findex gdb.parse_and_eval
314 @defun gdb.parse_and_eval (expression)
315 Parse @var{expression}, which must be a string, as an expression in
316 the current language, evaluate it, and return the result as a
319 This function can be useful when implementing a new command
320 (@pxref{Commands In Python}), as it provides a way to parse the
321 command's argument as an expression. It is also useful simply to
325 @findex gdb.find_pc_line
326 @defun gdb.find_pc_line (pc)
327 Return the @code{gdb.Symtab_and_line} object corresponding to the
328 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
329 value of @var{pc} is passed as an argument, then the @code{symtab} and
330 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
331 will be @code{None} and 0 respectively. This is identical to
332 @code{gdb.current_progspace().find_pc_line(pc)} and is included for
333 historical compatibility.
336 @findex gdb.post_event
337 @defun gdb.post_event (event)
338 Put @var{event}, a callable object taking no arguments, into
339 @value{GDBN}'s internal event queue. This callable will be invoked at
340 some later point, during @value{GDBN}'s event processing. Events
341 posted using @code{post_event} will be run in the order in which they
342 were posted; however, there is no way to know when they will be
343 processed relative to other events inside @value{GDBN}.
345 @value{GDBN} is not thread-safe. If your Python program uses multiple
346 threads, you must be careful to only call @value{GDBN}-specific
347 functions in the @value{GDBN} thread. @code{post_event} ensures
351 (@value{GDBP}) python
355 > def __init__(self, message):
356 > self.message = message;
357 > def __call__(self):
358 > gdb.write(self.message)
360 >class MyThread1 (threading.Thread):
362 > gdb.post_event(Writer("Hello "))
364 >class MyThread2 (threading.Thread):
366 > gdb.post_event(Writer("World\n"))
371 (@value{GDBP}) Hello World
376 @defun gdb.write (string @r{[}, stream{]})
377 Print a string to @value{GDBN}'s paginated output stream. The
378 optional @var{stream} determines the stream to print to. The default
379 stream is @value{GDBN}'s standard output stream. Possible stream
386 @value{GDBN}'s standard output stream.
391 @value{GDBN}'s standard error stream.
396 @value{GDBN}'s log stream (@pxref{Logging Output}).
399 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
400 call this function and will automatically direct the output to the
406 Flush the buffer of a @value{GDBN} paginated stream so that the
407 contents are displayed immediately. @value{GDBN} will flush the
408 contents of a stream automatically when it encounters a newline in the
409 buffer. The optional @var{stream} determines the stream to flush. The
410 default stream is @value{GDBN}'s standard output stream. Possible
417 @value{GDBN}'s standard output stream.
422 @value{GDBN}'s standard error stream.
427 @value{GDBN}'s log stream (@pxref{Logging Output}).
431 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
432 call this function for the relevant stream.
435 @findex gdb.target_charset
436 @defun gdb.target_charset ()
437 Return the name of the current target character set (@pxref{Character
438 Sets}). This differs from @code{gdb.parameter('target-charset')} in
439 that @samp{auto} is never returned.
442 @findex gdb.target_wide_charset
443 @defun gdb.target_wide_charset ()
444 Return the name of the current target wide character set
445 (@pxref{Character Sets}). This differs from
446 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
450 @findex gdb.solib_name
451 @defun gdb.solib_name (address)
452 Return the name of the shared library holding the given @var{address}
453 as a string, or @code{None}. This is identical to
454 @code{gdb.current_progspace().solib_name(address)} and is included for
455 historical compatibility.
458 @findex gdb.decode_line
459 @defun gdb.decode_line (@r{[}expression@r{]})
460 Return locations of the line specified by @var{expression}, or of the
461 current line if no argument was given. This function returns a Python
462 tuple containing two elements. The first element contains a string
463 holding any unparsed section of @var{expression} (or @code{None} if
464 the expression has been fully parsed). The second element contains
465 either @code{None} or another tuple that contains all the locations
466 that match the expression represented as @code{gdb.Symtab_and_line}
467 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
468 provided, it is decoded the way that @value{GDBN}'s inbuilt
469 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
472 @defun gdb.prompt_hook (current_prompt)
475 If @var{prompt_hook} is callable, @value{GDBN} will call the method
476 assigned to this operation before a prompt is displayed by
479 The parameter @code{current_prompt} contains the current @value{GDBN}
480 prompt. This method must return a Python string, or @code{None}. If
481 a string is returned, the @value{GDBN} prompt will be set to that
482 string. If @code{None} is returned, @value{GDBN} will continue to use
485 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
486 such as those used by readline for command input, and annotation
487 related prompts are prohibited from being changed.
490 @node Exception Handling
491 @subsubsection Exception Handling
492 @cindex python exceptions
493 @cindex exceptions, python
495 When executing the @code{python} command, Python exceptions
496 uncaught within the Python code are translated to calls to
497 @value{GDBN} error-reporting mechanism. If the command that called
498 @code{python} does not handle the error, @value{GDBN} will
499 terminate it and print an error message containing the Python
500 exception name, the associated value, and the Python call stack
501 backtrace at the point where the exception was raised. Example:
504 (@value{GDBP}) python print foo
505 Traceback (most recent call last):
506 File "<string>", line 1, in <module>
507 NameError: name 'foo' is not defined
510 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
511 Python code are converted to Python exceptions. The type of the
512 Python exception depends on the error.
516 This is the base class for most exceptions generated by @value{GDBN}.
517 It is derived from @code{RuntimeError}, for compatibility with earlier
518 versions of @value{GDBN}.
520 If an error occurring in @value{GDBN} does not fit into some more
521 specific category, then the generated exception will have this type.
523 @item gdb.MemoryError
524 This is a subclass of @code{gdb.error} which is thrown when an
525 operation tried to access invalid memory in the inferior.
527 @item KeyboardInterrupt
528 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
529 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
532 In all cases, your exception handler will see the @value{GDBN} error
533 message as its value and the Python call stack backtrace at the Python
534 statement closest to where the @value{GDBN} error occured as the
538 When implementing @value{GDBN} commands in Python via
539 @code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
540 to be able to throw an exception that doesn't cause a traceback to be
541 printed. For example, the user may have invoked the command
542 incorrectly. @value{GDBN} provides a special exception class that can
543 be used for this purpose.
547 When thrown from a command or function, this exception will cause the
548 command or function to fail, but the Python stack will not be
549 displayed. @value{GDBN} does not throw this exception itself, but
550 rather recognizes it when thrown from user Python code. Example:
554 >class HelloWorld (gdb.Command):
555 > """Greet the whole world."""
556 > def __init__ (self):
557 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
558 > def invoke (self, args, from_tty):
559 > argv = gdb.string_to_argv (args)
560 > if len (argv) != 0:
561 > raise gdb.GdbError ("hello-world takes no arguments")
562 > print "Hello, World!"
566 hello-world takes no arguments
570 @node Values From Inferior
571 @subsubsection Values From Inferior
572 @cindex values from inferior, with Python
573 @cindex python, working with values from inferior
575 @cindex @code{gdb.Value}
576 @value{GDBN} provides values it obtains from the inferior program in
577 an object of type @code{gdb.Value}. @value{GDBN} uses this object
578 for its internal bookkeeping of the inferior's values, and for
579 fetching values when necessary.
581 Inferior values that are simple scalars can be used directly in
582 Python expressions that are valid for the value's data type. Here's
583 an example for an integer or floating-point value @code{some_val}:
590 As result of this, @code{bar} will also be a @code{gdb.Value} object
591 whose values are of the same type as those of @code{some_val}. Valid
592 Python operations can also be performed on @code{gdb.Value} objects
593 representing a @code{struct} or @code{class} object. For such cases,
594 the overloaded operator (if present), is used to perform the operation.
595 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
596 representing instances of a @code{class} which overloads the @code{+}
597 operator, then one can use the @code{+} operator in their Python script
605 The result of the operation @code{val3} is also a @code{gdb.Value}
606 object corresponding to the value returned by the overloaded @code{+}
607 operator. In general, overloaded operators are invoked for the
608 following operations: @code{+} (binary addition), @code{-} (binary
609 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
610 @code{>>}, @code{|}, @code{&}, @code{^}.
612 Inferior values that are structures or instances of some class can
613 be accessed using the Python @dfn{dictionary syntax}. For example, if
614 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
615 can access its @code{foo} element with:
618 bar = some_val['foo']
621 @cindex getting structure elements using gdb.Field objects as subscripts
622 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
623 elements can also be accessed by using @code{gdb.Field} objects as
624 subscripts (@pxref{Types In Python}, for more information on
625 @code{gdb.Field} objects). For example, if @code{foo_field} is a
626 @code{gdb.Field} object corresponding to element @code{foo} of the above
627 structure, then @code{bar} can also be accessed as follows:
630 bar = some_val[foo_field]
633 A @code{gdb.Value} that represents a function can be executed via
634 inferior function call. Any arguments provided to the call must match
635 the function's prototype, and must be provided in the order specified
638 For example, @code{some_val} is a @code{gdb.Value} instance
639 representing a function that takes two integers as arguments. To
640 execute this function, call it like so:
643 result = some_val (10,20)
646 Any values returned from a function call will be stored as a
649 The following attributes are provided:
651 @defvar Value.address
652 If this object is addressable, this read-only attribute holds a
653 @code{gdb.Value} object representing the address. Otherwise,
654 this attribute holds @code{None}.
657 @cindex optimized out value in Python
658 @defvar Value.is_optimized_out
659 This read-only boolean attribute is true if the compiler optimized out
660 this value, thus it is not available for fetching from the inferior.
664 The type of this @code{gdb.Value}. The value of this attribute is a
665 @code{gdb.Type} object (@pxref{Types In Python}).
668 @defvar Value.dynamic_type
669 The dynamic type of this @code{gdb.Value}. This uses the object's
670 virtual table and the C@t{++} run-time type information
671 (@acronym{RTTI}) to determine the dynamic type of the value. If this
672 value is of class type, it will return the class in which the value is
673 embedded, if any. If this value is of pointer or reference to a class
674 type, it will compute the dynamic type of the referenced object, and
675 return a pointer or reference to that type, respectively. In all
676 other cases, it will return the value's static type.
678 Note that this feature will only work when debugging a C@t{++} program
679 that includes @acronym{RTTI} for the object in question. Otherwise,
680 it will just return the static type of the value as in @kbd{ptype foo}
681 (@pxref{Symbols, ptype}).
684 @defvar Value.is_lazy
685 The value of this read-only boolean attribute is @code{True} if this
686 @code{gdb.Value} has not yet been fetched from the inferior.
687 @value{GDBN} does not fetch values until necessary, for efficiency.
691 myval = gdb.parse_and_eval ('somevar')
694 The value of @code{somevar} is not fetched at this time. It will be
695 fetched when the value is needed, or when the @code{fetch_lazy}
699 The following methods are provided:
701 @defun Value.__init__ (@var{val})
702 Many Python values can be converted directly to a @code{gdb.Value} via
703 this object initializer. Specifically:
707 A Python boolean is converted to the boolean type from the current
711 A Python integer is converted to the C @code{long} type for the
712 current architecture.
715 A Python long is converted to the C @code{long long} type for the
716 current architecture.
719 A Python float is converted to the C @code{double} type for the
720 current architecture.
723 A Python string is converted to a target string in the current target
724 language using the current target encoding.
725 If a character cannot be represented in the current target encoding,
726 then an exception is thrown.
728 @item @code{gdb.Value}
729 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
731 @item @code{gdb.LazyString}
732 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
733 Python}), then the lazy string's @code{value} method is called, and
738 @defun Value.__init__ (@var{val}, @var{type})
739 This second form of the @code{gdb.Value} constructor returns a
740 @code{gdb.Value} of type @var{type} where the value contents are taken
741 from the Python buffer object specified by @var{val}. The number of
742 bytes in the Python buffer object must be greater than or equal to the
746 @defun Value.cast (type)
747 Return a new instance of @code{gdb.Value} that is the result of
748 casting this instance to the type described by @var{type}, which must
749 be a @code{gdb.Type} object. If the cast cannot be performed for some
750 reason, this method throws an exception.
753 @defun Value.dereference ()
754 For pointer data types, this method returns a new @code{gdb.Value} object
755 whose contents is the object pointed to by the pointer. For example, if
756 @code{foo} is a C pointer to an @code{int}, declared in your C program as
763 then you can use the corresponding @code{gdb.Value} to access what
764 @code{foo} points to like this:
767 bar = foo.dereference ()
770 The result @code{bar} will be a @code{gdb.Value} object holding the
771 value pointed to by @code{foo}.
773 A similar function @code{Value.referenced_value} exists which also
774 returns @code{gdb.Value} objects corresonding to the values pointed to
775 by pointer values (and additionally, values referenced by reference
776 values). However, the behavior of @code{Value.dereference}
777 differs from @code{Value.referenced_value} by the fact that the
778 behavior of @code{Value.dereference} is identical to applying the C
779 unary operator @code{*} on a given value. For example, consider a
780 reference to a pointer @code{ptrref}, declared in your C@t{++} program
788 intptr &ptrref = ptr;
791 Though @code{ptrref} is a reference value, one can apply the method
792 @code{Value.dereference} to the @code{gdb.Value} object corresponding
793 to it and obtain a @code{gdb.Value} which is identical to that
794 corresponding to @code{val}. However, if you apply the method
795 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
796 object identical to that corresponding to @code{ptr}.
799 py_ptrref = gdb.parse_and_eval ("ptrref")
800 py_val = py_ptrref.dereference ()
801 py_ptr = py_ptrref.referenced_value ()
804 The @code{gdb.Value} object @code{py_val} is identical to that
805 corresponding to @code{val}, and @code{py_ptr} is identical to that
806 corresponding to @code{ptr}. In general, @code{Value.dereference} can
807 be applied whenever the C unary operator @code{*} can be applied
808 to the corresponding C value. For those cases where applying both
809 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
810 the results obtained need not be identical (as we have seen in the above
811 example). The results are however identical when applied on
812 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
813 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
816 @defun Value.referenced_value ()
817 For pointer or reference data types, this method returns a new
818 @code{gdb.Value} object corresponding to the value referenced by the
819 pointer/reference value. For pointer data types,
820 @code{Value.dereference} and @code{Value.referenced_value} produce
821 identical results. The difference between these methods is that
822 @code{Value.dereference} cannot get the values referenced by reference
823 values. For example, consider a reference to an @code{int}, declared
824 in your C@t{++} program as
832 then applying @code{Value.dereference} to the @code{gdb.Value} object
833 corresponding to @code{ref} will result in an error, while applying
834 @code{Value.referenced_value} will result in a @code{gdb.Value} object
835 identical to that corresponding to @code{val}.
838 py_ref = gdb.parse_and_eval ("ref")
839 er_ref = py_ref.dereference () # Results in error
840 py_val = py_ref.referenced_value () # Returns the referenced value
843 The @code{gdb.Value} object @code{py_val} is identical to that
844 corresponding to @code{val}.
847 @defun Value.reference_value ()
848 Return a @code{gdb.Value} object which is a reference to the value
849 encapsulated by this instance.
852 @defun Value.const_value ()
853 Return a @code{gdb.Value} object which is a @code{const} version of the
854 value encapsulated by this instance.
857 @defun Value.dynamic_cast (type)
858 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
859 operator were used. Consult a C@t{++} reference for details.
862 @defun Value.reinterpret_cast (type)
863 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
864 operator were used. Consult a C@t{++} reference for details.
867 @defun Value.format_string (...)
868 Convert a @code{gdb.Value} to a string, similarly to what the @code{print}
869 command does. Invoked with no arguments, this is equivalent to calling
870 the @code{str} function on the @code{gdb.Value}. The representation of
871 the same value may change across different versions of @value{GDBN}, so
872 you shouldn't, for instance, parse the strings returned by this method.
874 All the arguments are keyword only. If an argument is not specified, the
875 current global default setting is used.
879 @code{True} if pretty-printers (@pxref{Pretty Printing}) should not be
880 used to format the value. @code{False} if enabled pretty-printers
881 matching the type represented by the @code{gdb.Value} should be used to
885 @code{True} if arrays should be pretty printed to be more convenient to
886 read, @code{False} if they shouldn't (see @code{set print array} in
887 @ref{Print Settings}).
890 @code{True} if structs should be pretty printed to be more convenient to
891 read, @code{False} if they shouldn't (see @code{set print pretty} in
892 @ref{Print Settings}).
895 @code{True} if array indexes should be included in the string
896 representation of arrays, @code{False} if they shouldn't (see @code{set
897 print array-indexes} in @ref{Print Settings}).
900 @code{True} if the string representation of a pointer should include the
901 corresponding symbol name (if one exists), @code{False} if it shouldn't
902 (see @code{set print symbol} in @ref{Print Settings}).
905 @code{True} if unions which are contained in other structures or unions
906 should be expanded, @code{False} if they shouldn't (see @code{set print
907 union} in @ref{Print Settings}).
910 @code{True} if C@t{++} references should be resolved to the value they
911 refer to, @code{False} (the default) if they shouldn't. Note that, unlike
912 for the @code{print} command, references are not automatically expanded
913 when using the @code{format_string} method or the @code{str}
914 function. There is no global @code{print} setting to change the default
918 @code{True} if the representation of a pointer to an object should
919 identify the @emph{actual} (derived) type of the object rather than the
920 @emph{declared} type, using the virtual function table. @code{False} if
921 the @emph{declared} type should be used. (See @code{set print object} in
922 @ref{Print Settings}).
925 @code{True} if static members should be included in the string
926 representation of a C@t{++} object, @code{False} if they shouldn't (see
927 @code{set print static-members} in @ref{Print Settings}).
930 Number of array elements to print, or @code{0} to print an unlimited
931 number of elements (see @code{set print elements} in @ref{Print
935 The maximum depth to print for nested structs and unions, or @code{-1}
936 to print an unlimited number of elements (see @code{set print
937 max-depth} in @ref{Print Settings}).
939 @item repeat_threshold
940 Set the threshold for suppressing display of repeated array elements, or
941 @code{0} to represent all elements, even if repeated. (See @code{set
942 print repeats} in @ref{Print Settings}).
945 A string containing a single character representing the format to use for
946 the returned string. For instance, @code{'x'} is equivalent to using the
947 @value{GDBN} command @code{print} with the @code{/x} option and formats
948 the value as a hexadecimal number.
952 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
953 If this @code{gdb.Value} represents a string, then this method
954 converts the contents to a Python string. Otherwise, this method will
957 Values are interpreted as strings according to the rules of the
958 current language. If the optional length argument is given, the
959 string will be converted to that length, and will include any embedded
960 zeroes that the string may contain. Otherwise, for languages
961 where the string is zero-terminated, the entire string will be
964 For example, in C-like languages, a value is a string if it is a pointer
965 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
968 If the optional @var{encoding} argument is given, it must be a string
969 naming the encoding of the string in the @code{gdb.Value}, such as
970 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
971 the same encodings as the corresponding argument to Python's
972 @code{string.decode} method, and the Python codec machinery will be used
973 to convert the string. If @var{encoding} is not given, or if
974 @var{encoding} is the empty string, then either the @code{target-charset}
975 (@pxref{Character Sets}) will be used, or a language-specific encoding
976 will be used, if the current language is able to supply one.
978 The optional @var{errors} argument is the same as the corresponding
979 argument to Python's @code{string.decode} method.
981 If the optional @var{length} argument is given, the string will be
982 fetched and converted to the given length.
985 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
986 If this @code{gdb.Value} represents a string, then this method
987 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
988 In Python}). Otherwise, this method will throw an exception.
990 If the optional @var{encoding} argument is given, it must be a string
991 naming the encoding of the @code{gdb.LazyString}. Some examples are:
992 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
993 @var{encoding} argument is an encoding that @value{GDBN} does
994 recognize, @value{GDBN} will raise an error.
996 When a lazy string is printed, the @value{GDBN} encoding machinery is
997 used to convert the string during printing. If the optional
998 @var{encoding} argument is not provided, or is an empty string,
999 @value{GDBN} will automatically select the encoding most suitable for
1000 the string type. For further information on encoding in @value{GDBN}
1001 please see @ref{Character Sets}.
1003 If the optional @var{length} argument is given, the string will be
1004 fetched and encoded to the length of characters specified. If
1005 the @var{length} argument is not provided, the string will be fetched
1006 and encoded until a null of appropriate width is found.
1009 @defun Value.fetch_lazy ()
1010 If the @code{gdb.Value} object is currently a lazy value
1011 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
1012 fetched from the inferior. Any errors that occur in the process
1013 will produce a Python exception.
1015 If the @code{gdb.Value} object is not a lazy value, this method
1018 This method does not return a value.
1022 @node Types In Python
1023 @subsubsection Types In Python
1024 @cindex types in Python
1025 @cindex Python, working with types
1028 @value{GDBN} represents types from the inferior using the class
1031 The following type-related functions are available in the @code{gdb}
1034 @findex gdb.lookup_type
1035 @defun gdb.lookup_type (name @r{[}, block@r{]})
1036 This function looks up a type by its @var{name}, which must be a string.
1038 If @var{block} is given, then @var{name} is looked up in that scope.
1039 Otherwise, it is searched for globally.
1041 Ordinarily, this function will return an instance of @code{gdb.Type}.
1042 If the named type cannot be found, it will throw an exception.
1045 If the type is a structure or class type, or an enum type, the fields
1046 of that type can be accessed using the Python @dfn{dictionary syntax}.
1047 For example, if @code{some_type} is a @code{gdb.Type} instance holding
1048 a structure type, you can access its @code{foo} field with:
1051 bar = some_type['foo']
1054 @code{bar} will be a @code{gdb.Field} object; see below under the
1055 description of the @code{Type.fields} method for a description of the
1056 @code{gdb.Field} class.
1058 An instance of @code{Type} has the following attributes:
1060 @defvar Type.alignof
1061 The alignment of this type, in bytes. Type alignment comes from the
1062 debugging information; if it was not specified, then @value{GDBN} will
1063 use the relevant ABI to try to determine the alignment. In some
1064 cases, even this is not possible, and zero will be returned.
1068 The type code for this type. The type code will be one of the
1069 @code{TYPE_CODE_} constants defined below.
1073 The name of this type. If this type has no name, then @code{None}
1078 The size of this type, in target @code{char} units. Usually, a
1079 target's @code{char} type will be an 8-bit byte. However, on some
1080 unusual platforms, this type may have a different size.
1084 The tag name for this type. The tag name is the name after
1085 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1086 languages have this concept. If this type has no tag name, then
1087 @code{None} is returned.
1090 @defvar Type.objfile
1091 The @code{gdb.Objfile} that this type was defined in, or @code{None} if
1092 there is no associated objfile.
1095 The following methods are provided:
1097 @defun Type.fields ()
1098 For structure and union types, this method returns the fields. Range
1099 types have two fields, the minimum and maximum values. Enum types
1100 have one field per enum constant. Function and method types have one
1101 field per parameter. The base types of C@t{++} classes are also
1102 represented as fields. If the type has no fields, or does not fit
1103 into one of these categories, an empty sequence will be returned.
1105 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
1108 This attribute is not available for @code{enum} or @code{static}
1109 (as in C@t{++}) fields. The value is the position, counting
1110 in bits, from the start of the containing type.
1113 This attribute is only available for @code{enum} fields, and its value
1114 is the enumeration member's integer representation.
1117 The name of the field, or @code{None} for anonymous fields.
1120 This is @code{True} if the field is artificial, usually meaning that
1121 it was provided by the compiler and not the user. This attribute is
1122 always provided, and is @code{False} if the field is not artificial.
1125 This is @code{True} if the field represents a base class of a C@t{++}
1126 structure. This attribute is always provided, and is @code{False}
1127 if the field is not a base class of the type that is the argument of
1128 @code{fields}, or if that type was not a C@t{++} class.
1131 If the field is packed, or is a bitfield, then this will have a
1132 non-zero value, which is the size of the field in bits. Otherwise,
1133 this will be zero; in this case the field's size is given by its type.
1136 The type of the field. This is usually an instance of @code{Type},
1137 but it can be @code{None} in some situations.
1140 The type which contains this field. This is an instance of
1145 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
1146 Return a new @code{gdb.Type} object which represents an array of this
1147 type. If one argument is given, it is the inclusive upper bound of
1148 the array; in this case the lower bound is zero. If two arguments are
1149 given, the first argument is the lower bound of the array, and the
1150 second argument is the upper bound of the array. An array's length
1151 must not be negative, but the bounds can be.
1154 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
1155 Return a new @code{gdb.Type} object which represents a vector of this
1156 type. If one argument is given, it is the inclusive upper bound of
1157 the vector; in this case the lower bound is zero. If two arguments are
1158 given, the first argument is the lower bound of the vector, and the
1159 second argument is the upper bound of the vector. A vector's length
1160 must not be negative, but the bounds can be.
1162 The difference between an @code{array} and a @code{vector} is that
1163 arrays behave like in C: when used in expressions they decay to a pointer
1164 to the first element whereas vectors are treated as first class values.
1167 @defun Type.const ()
1168 Return a new @code{gdb.Type} object which represents a
1169 @code{const}-qualified variant of this type.
1172 @defun Type.volatile ()
1173 Return a new @code{gdb.Type} object which represents a
1174 @code{volatile}-qualified variant of this type.
1177 @defun Type.unqualified ()
1178 Return a new @code{gdb.Type} object which represents an unqualified
1179 variant of this type. That is, the result is neither @code{const} nor
1183 @defun Type.range ()
1184 Return a Python @code{Tuple} object that contains two elements: the
1185 low bound of the argument type and the high bound of that type. If
1186 the type does not have a range, @value{GDBN} will raise a
1187 @code{gdb.error} exception (@pxref{Exception Handling}).
1190 @defun Type.reference ()
1191 Return a new @code{gdb.Type} object which represents a reference to this
1195 @defun Type.pointer ()
1196 Return a new @code{gdb.Type} object which represents a pointer to this
1200 @defun Type.strip_typedefs ()
1201 Return a new @code{gdb.Type} that represents the real type,
1202 after removing all layers of typedefs.
1205 @defun Type.target ()
1206 Return a new @code{gdb.Type} object which represents the target type
1209 For a pointer type, the target type is the type of the pointed-to
1210 object. For an array type (meaning C-like arrays), the target type is
1211 the type of the elements of the array. For a function or method type,
1212 the target type is the type of the return value. For a complex type,
1213 the target type is the type of the elements. For a typedef, the
1214 target type is the aliased type.
1216 If the type does not have a target, this method will throw an
1220 @defun Type.template_argument (n @r{[}, block@r{]})
1221 If this @code{gdb.Type} is an instantiation of a template, this will
1222 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1223 value of the @var{n}th template argument (indexed starting at 0).
1225 If this @code{gdb.Type} is not a template type, or if the type has fewer
1226 than @var{n} template arguments, this will throw an exception.
1227 Ordinarily, only C@t{++} code will have template types.
1229 If @var{block} is given, then @var{name} is looked up in that scope.
1230 Otherwise, it is searched for globally.
1233 @defun Type.optimized_out ()
1234 Return @code{gdb.Value} instance of this type whose value is optimized
1235 out. This allows a frame decorator to indicate that the value of an
1236 argument or a local variable is not known.
1239 Each type has a code, which indicates what category this type falls
1240 into. The available type categories are represented by constants
1241 defined in the @code{gdb} module:
1244 @vindex TYPE_CODE_PTR
1245 @item gdb.TYPE_CODE_PTR
1246 The type is a pointer.
1248 @vindex TYPE_CODE_ARRAY
1249 @item gdb.TYPE_CODE_ARRAY
1250 The type is an array.
1252 @vindex TYPE_CODE_STRUCT
1253 @item gdb.TYPE_CODE_STRUCT
1254 The type is a structure.
1256 @vindex TYPE_CODE_UNION
1257 @item gdb.TYPE_CODE_UNION
1258 The type is a union.
1260 @vindex TYPE_CODE_ENUM
1261 @item gdb.TYPE_CODE_ENUM
1262 The type is an enum.
1264 @vindex TYPE_CODE_FLAGS
1265 @item gdb.TYPE_CODE_FLAGS
1266 A bit flags type, used for things such as status registers.
1268 @vindex TYPE_CODE_FUNC
1269 @item gdb.TYPE_CODE_FUNC
1270 The type is a function.
1272 @vindex TYPE_CODE_INT
1273 @item gdb.TYPE_CODE_INT
1274 The type is an integer type.
1276 @vindex TYPE_CODE_FLT
1277 @item gdb.TYPE_CODE_FLT
1278 A floating point type.
1280 @vindex TYPE_CODE_VOID
1281 @item gdb.TYPE_CODE_VOID
1282 The special type @code{void}.
1284 @vindex TYPE_CODE_SET
1285 @item gdb.TYPE_CODE_SET
1288 @vindex TYPE_CODE_RANGE
1289 @item gdb.TYPE_CODE_RANGE
1290 A range type, that is, an integer type with bounds.
1292 @vindex TYPE_CODE_STRING
1293 @item gdb.TYPE_CODE_STRING
1294 A string type. Note that this is only used for certain languages with
1295 language-defined string types; C strings are not represented this way.
1297 @vindex TYPE_CODE_BITSTRING
1298 @item gdb.TYPE_CODE_BITSTRING
1299 A string of bits. It is deprecated.
1301 @vindex TYPE_CODE_ERROR
1302 @item gdb.TYPE_CODE_ERROR
1303 An unknown or erroneous type.
1305 @vindex TYPE_CODE_METHOD
1306 @item gdb.TYPE_CODE_METHOD
1307 A method type, as found in C@t{++}.
1309 @vindex TYPE_CODE_METHODPTR
1310 @item gdb.TYPE_CODE_METHODPTR
1311 A pointer-to-member-function.
1313 @vindex TYPE_CODE_MEMBERPTR
1314 @item gdb.TYPE_CODE_MEMBERPTR
1315 A pointer-to-member.
1317 @vindex TYPE_CODE_REF
1318 @item gdb.TYPE_CODE_REF
1321 @vindex TYPE_CODE_RVALUE_REF
1322 @item gdb.TYPE_CODE_RVALUE_REF
1323 A C@t{++}11 rvalue reference type.
1325 @vindex TYPE_CODE_CHAR
1326 @item gdb.TYPE_CODE_CHAR
1329 @vindex TYPE_CODE_BOOL
1330 @item gdb.TYPE_CODE_BOOL
1333 @vindex TYPE_CODE_COMPLEX
1334 @item gdb.TYPE_CODE_COMPLEX
1335 A complex float type.
1337 @vindex TYPE_CODE_TYPEDEF
1338 @item gdb.TYPE_CODE_TYPEDEF
1339 A typedef to some other type.
1341 @vindex TYPE_CODE_NAMESPACE
1342 @item gdb.TYPE_CODE_NAMESPACE
1343 A C@t{++} namespace.
1345 @vindex TYPE_CODE_DECFLOAT
1346 @item gdb.TYPE_CODE_DECFLOAT
1347 A decimal floating point type.
1349 @vindex TYPE_CODE_INTERNAL_FUNCTION
1350 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1351 A function internal to @value{GDBN}. This is the type used to represent
1352 convenience functions.
1355 Further support for types is provided in the @code{gdb.types}
1356 Python module (@pxref{gdb.types}).
1358 @node Pretty Printing API
1359 @subsubsection Pretty Printing API
1360 @cindex python pretty printing api
1362 A pretty-printer is just an object that holds a value and implements a
1363 specific interface, defined here. An example output is provided
1364 (@pxref{Pretty Printing}).
1366 @defun pretty_printer.children (self)
1367 @value{GDBN} will call this method on a pretty-printer to compute the
1368 children of the pretty-printer's value.
1370 This method must return an object conforming to the Python iterator
1371 protocol. Each item returned by the iterator must be a tuple holding
1372 two elements. The first element is the ``name'' of the child; the
1373 second element is the child's value. The value can be any Python
1374 object which is convertible to a @value{GDBN} value.
1376 This method is optional. If it does not exist, @value{GDBN} will act
1377 as though the value has no children.
1379 For efficiency, the @code{children} method should lazily compute its
1380 results. This will let @value{GDBN} read as few elements as
1381 necessary, for example when various print settings (@pxref{Print
1382 Settings}) or @code{-var-list-children} (@pxref{GDB/MI Variable
1383 Objects}) limit the number of elements to be displayed.
1385 Children may be hidden from display based on the value of @samp{set
1386 print max-depth} (@pxref{Print Settings}).
1389 @defun pretty_printer.display_hint (self)
1390 The CLI may call this method and use its result to change the
1391 formatting of a value. The result will also be supplied to an MI
1392 consumer as a @samp{displayhint} attribute of the variable being
1395 This method is optional. If it does exist, this method must return a
1396 string or the special value @code{None}.
1398 Some display hints are predefined by @value{GDBN}:
1402 Indicate that the object being printed is ``array-like''. The CLI
1403 uses this to respect parameters such as @code{set print elements} and
1404 @code{set print array}.
1407 Indicate that the object being printed is ``map-like'', and that the
1408 children of this value can be assumed to alternate between keys and
1412 Indicate that the object being printed is ``string-like''. If the
1413 printer's @code{to_string} method returns a Python string of some
1414 kind, then @value{GDBN} will call its internal language-specific
1415 string-printing function to format the string. For the CLI this means
1416 adding quotation marks, possibly escaping some characters, respecting
1417 @code{set print elements}, and the like.
1420 The special value @code{None} causes @value{GDBN} to apply the default
1424 @defun pretty_printer.to_string (self)
1425 @value{GDBN} will call this method to display the string
1426 representation of the value passed to the object's constructor.
1428 When printing from the CLI, if the @code{to_string} method exists,
1429 then @value{GDBN} will prepend its result to the values returned by
1430 @code{children}. Exactly how this formatting is done is dependent on
1431 the display hint, and may change as more hints are added. Also,
1432 depending on the print settings (@pxref{Print Settings}), the CLI may
1433 print just the result of @code{to_string} in a stack trace, omitting
1434 the result of @code{children}.
1436 If this method returns a string, it is printed verbatim.
1438 Otherwise, if this method returns an instance of @code{gdb.Value},
1439 then @value{GDBN} prints this value. This may result in a call to
1440 another pretty-printer.
1442 If instead the method returns a Python value which is convertible to a
1443 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1444 the resulting value. Again, this may result in a call to another
1445 pretty-printer. Python scalars (integers, floats, and booleans) and
1446 strings are convertible to @code{gdb.Value}; other types are not.
1448 Finally, if this method returns @code{None} then no further operations
1449 are peformed in this method and nothing is printed.
1451 If the result is not one of these types, an exception is raised.
1454 @value{GDBN} provides a function which can be used to look up the
1455 default pretty-printer for a @code{gdb.Value}:
1457 @findex gdb.default_visualizer
1458 @defun gdb.default_visualizer (value)
1459 This function takes a @code{gdb.Value} object as an argument. If a
1460 pretty-printer for this value exists, then it is returned. If no such
1461 printer exists, then this returns @code{None}.
1464 @node Selecting Pretty-Printers
1465 @subsubsection Selecting Pretty-Printers
1466 @cindex selecting python pretty-printers
1468 @value{GDBN} provides several ways to register a pretty-printer:
1469 globally, per program space, and per objfile. When choosing how to
1470 register your pretty-printer, a good rule is to register it with the
1471 smallest scope possible: that is prefer a specific objfile first, then
1472 a program space, and only register a printer globally as a last
1475 @findex gdb.pretty_printers
1476 @defvar gdb.pretty_printers
1477 The Python list @code{gdb.pretty_printers} contains an array of
1478 functions or callable objects that have been registered via addition
1479 as a pretty-printer. Printers in this list are called @code{global}
1480 printers, they're available when debugging all inferiors.
1483 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1484 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1487 Each function on these lists is passed a single @code{gdb.Value}
1488 argument and should return a pretty-printer object conforming to the
1489 interface definition above (@pxref{Pretty Printing API}). If a function
1490 cannot create a pretty-printer for the value, it should return
1493 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1494 @code{gdb.Objfile} in the current program space and iteratively calls
1495 each enabled lookup routine in the list for that @code{gdb.Objfile}
1496 until it receives a pretty-printer object.
1497 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1498 searches the pretty-printer list of the current program space,
1499 calling each enabled function until an object is returned.
1500 After these lists have been exhausted, it tries the global
1501 @code{gdb.pretty_printers} list, again calling each enabled function until an
1504 The order in which the objfiles are searched is not specified. For a
1505 given list, functions are always invoked from the head of the list,
1506 and iterated over sequentially until the end of the list, or a printer
1509 For various reasons a pretty-printer may not work.
1510 For example, the underlying data structure may have changed and
1511 the pretty-printer is out of date.
1513 The consequences of a broken pretty-printer are severe enough that
1514 @value{GDBN} provides support for enabling and disabling individual
1515 printers. For example, if @code{print frame-arguments} is on,
1516 a backtrace can become highly illegible if any argument is printed
1517 with a broken printer.
1519 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1520 attribute to the registered function or callable object. If this attribute
1521 is present and its value is @code{False}, the printer is disabled, otherwise
1522 the printer is enabled.
1524 @node Writing a Pretty-Printer
1525 @subsubsection Writing a Pretty-Printer
1526 @cindex writing a pretty-printer
1528 A pretty-printer consists of two parts: a lookup function to detect
1529 if the type is supported, and the printer itself.
1531 Here is an example showing how a @code{std::string} printer might be
1532 written. @xref{Pretty Printing API}, for details on the API this class
1536 class StdStringPrinter(object):
1537 "Print a std::string"
1539 def __init__(self, val):
1542 def to_string(self):
1543 return self.val['_M_dataplus']['_M_p']
1545 def display_hint(self):
1549 And here is an example showing how a lookup function for the printer
1550 example above might be written.
1553 def str_lookup_function(val):
1554 lookup_tag = val.type.tag
1555 if lookup_tag == None:
1557 regex = re.compile("^std::basic_string<char,.*>$")
1558 if regex.match(lookup_tag):
1559 return StdStringPrinter(val)
1563 The example lookup function extracts the value's type, and attempts to
1564 match it to a type that it can pretty-print. If it is a type the
1565 printer can pretty-print, it will return a printer object. If not, it
1566 returns @code{None}.
1568 We recommend that you put your core pretty-printers into a Python
1569 package. If your pretty-printers are for use with a library, we
1570 further recommend embedding a version number into the package name.
1571 This practice will enable @value{GDBN} to load multiple versions of
1572 your pretty-printers at the same time, because they will have
1575 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1576 can be evaluated multiple times without changing its meaning. An
1577 ideal auto-load file will consist solely of @code{import}s of your
1578 printer modules, followed by a call to a register pretty-printers with
1579 the current objfile.
1581 Taken as a whole, this approach will scale nicely to multiple
1582 inferiors, each potentially using a different library version.
1583 Embedding a version number in the Python package name will ensure that
1584 @value{GDBN} is able to load both sets of printers simultaneously.
1585 Then, because the search for pretty-printers is done by objfile, and
1586 because your auto-loaded code took care to register your library's
1587 printers with a specific objfile, @value{GDBN} will find the correct
1588 printers for the specific version of the library used by each
1591 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1592 this code might appear in @code{gdb.libstdcxx.v6}:
1595 def register_printers(objfile):
1596 objfile.pretty_printers.append(str_lookup_function)
1600 And then the corresponding contents of the auto-load file would be:
1603 import gdb.libstdcxx.v6
1604 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1607 The previous example illustrates a basic pretty-printer.
1608 There are a few things that can be improved on.
1609 The printer doesn't have a name, making it hard to identify in a
1610 list of installed printers. The lookup function has a name, but
1611 lookup functions can have arbitrary, even identical, names.
1613 Second, the printer only handles one type, whereas a library typically has
1614 several types. One could install a lookup function for each desired type
1615 in the library, but one could also have a single lookup function recognize
1616 several types. The latter is the conventional way this is handled.
1617 If a pretty-printer can handle multiple data types, then its
1618 @dfn{subprinters} are the printers for the individual data types.
1620 The @code{gdb.printing} module provides a formal way of solving these
1621 problems (@pxref{gdb.printing}).
1622 Here is another example that handles multiple types.
1624 These are the types we are going to pretty-print:
1627 struct foo @{ int a, b; @};
1628 struct bar @{ struct foo x, y; @};
1631 Here are the printers:
1635 """Print a foo object."""
1637 def __init__(self, val):
1640 def to_string(self):
1641 return ("a=<" + str(self.val["a"]) +
1642 "> b=<" + str(self.val["b"]) + ">")
1645 """Print a bar object."""
1647 def __init__(self, val):
1650 def to_string(self):
1651 return ("x=<" + str(self.val["x"]) +
1652 "> y=<" + str(self.val["y"]) + ">")
1655 This example doesn't need a lookup function, that is handled by the
1656 @code{gdb.printing} module. Instead a function is provided to build up
1657 the object that handles the lookup.
1662 def build_pretty_printer():
1663 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1665 pp.add_printer('foo', '^foo$', fooPrinter)
1666 pp.add_printer('bar', '^bar$', barPrinter)
1670 And here is the autoload support:
1675 gdb.printing.register_pretty_printer(
1676 gdb.current_objfile(),
1677 my_library.build_pretty_printer())
1680 Finally, when this printer is loaded into @value{GDBN}, here is the
1681 corresponding output of @samp{info pretty-printer}:
1684 (gdb) info pretty-printer
1691 @node Type Printing API
1692 @subsubsection Type Printing API
1693 @cindex type printing API for Python
1695 @value{GDBN} provides a way for Python code to customize type display.
1696 This is mainly useful for substituting canonical typedef names for
1699 @cindex type printer
1700 A @dfn{type printer} is just a Python object conforming to a certain
1701 protocol. A simple base class implementing the protocol is provided;
1702 see @ref{gdb.types}. A type printer must supply at least:
1704 @defivar type_printer enabled
1705 A boolean which is True if the printer is enabled, and False
1706 otherwise. This is manipulated by the @code{enable type-printer}
1707 and @code{disable type-printer} commands.
1710 @defivar type_printer name
1711 The name of the type printer. This must be a string. This is used by
1712 the @code{enable type-printer} and @code{disable type-printer}
1716 @defmethod type_printer instantiate (self)
1717 This is called by @value{GDBN} at the start of type-printing. It is
1718 only called if the type printer is enabled. This method must return a
1719 new object that supplies a @code{recognize} method, as described below.
1723 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1724 will compute a list of type recognizers. This is done by iterating
1725 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1726 followed by the per-progspace type printers (@pxref{Progspaces In
1727 Python}), and finally the global type printers.
1729 @value{GDBN} will call the @code{instantiate} method of each enabled
1730 type printer. If this method returns @code{None}, then the result is
1731 ignored; otherwise, it is appended to the list of recognizers.
1733 Then, when @value{GDBN} is going to display a type name, it iterates
1734 over the list of recognizers. For each one, it calls the recognition
1735 function, stopping if the function returns a non-@code{None} value.
1736 The recognition function is defined as:
1738 @defmethod type_recognizer recognize (self, type)
1739 If @var{type} is not recognized, return @code{None}. Otherwise,
1740 return a string which is to be printed as the name of @var{type}.
1741 The @var{type} argument will be an instance of @code{gdb.Type}
1742 (@pxref{Types In Python}).
1745 @value{GDBN} uses this two-pass approach so that type printers can
1746 efficiently cache information without holding on to it too long. For
1747 example, it can be convenient to look up type information in a type
1748 printer and hold it for a recognizer's lifetime; if a single pass were
1749 done then type printers would have to make use of the event system in
1750 order to avoid holding information that could become stale as the
1753 @node Frame Filter API
1754 @subsubsection Filtering Frames
1755 @cindex frame filters api
1757 Frame filters are Python objects that manipulate the visibility of a
1758 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1761 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1762 commands (@pxref{GDB/MI}), those that return a collection of frames
1763 are affected. The commands that work with frame filters are:
1765 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1766 @code{-stack-list-frames}
1767 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1768 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1769 -stack-list-variables command}), @code{-stack-list-arguments}
1770 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1771 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1772 -stack-list-locals command}).
1774 A frame filter works by taking an iterator as an argument, applying
1775 actions to the contents of that iterator, and returning another
1776 iterator (or, possibly, the same iterator it was provided in the case
1777 where the filter does not perform any operations). Typically, frame
1778 filters utilize tools such as the Python's @code{itertools} module to
1779 work with and create new iterators from the source iterator.
1780 Regardless of how a filter chooses to apply actions, it must not alter
1781 the underlying @value{GDBN} frame or frames, or attempt to alter the
1782 call-stack within @value{GDBN}. This preserves data integrity within
1783 @value{GDBN}. Frame filters are executed on a priority basis and care
1784 should be taken that some frame filters may have been executed before,
1785 and that some frame filters will be executed after.
1787 An important consideration when designing frame filters, and well
1788 worth reflecting upon, is that frame filters should avoid unwinding
1789 the call stack if possible. Some stacks can run very deep, into the
1790 tens of thousands in some cases. To search every frame when a frame
1791 filter executes may be too expensive at that step. The frame filter
1792 cannot know how many frames it has to iterate over, and it may have to
1793 iterate through them all. This ends up duplicating effort as
1794 @value{GDBN} performs this iteration when it prints the frames. If
1795 the filter can defer unwinding frames until frame decorators are
1796 executed, after the last filter has executed, it should. @xref{Frame
1797 Decorator API}, for more information on decorators. Also, there are
1798 examples for both frame decorators and filters in later chapters.
1799 @xref{Writing a Frame Filter}, for more information.
1801 The Python dictionary @code{gdb.frame_filters} contains key/object
1802 pairings that comprise a frame filter. Frame filters in this
1803 dictionary are called @code{global} frame filters, and they are
1804 available when debugging all inferiors. These frame filters must
1805 register with the dictionary directly. In addition to the
1806 @code{global} dictionary, there are other dictionaries that are loaded
1807 with different inferiors via auto-loading (@pxref{Python
1808 Auto-loading}). The two other areas where frame filter dictionaries
1809 can be found are: @code{gdb.Progspace} which contains a
1810 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1811 object which also contains a @code{frame_filters} dictionary
1814 When a command is executed from @value{GDBN} that is compatible with
1815 frame filters, @value{GDBN} combines the @code{global},
1816 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1817 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1818 several frames, and thus several object files, might be in use.
1819 @value{GDBN} then prunes any frame filter whose @code{enabled}
1820 attribute is @code{False}. This pruned list is then sorted according
1821 to the @code{priority} attribute in each filter.
1823 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1824 creates an iterator which wraps each frame in the call stack in a
1825 @code{FrameDecorator} object, and calls each filter in order. The
1826 output from the previous filter will always be the input to the next
1829 Frame filters have a mandatory interface which each frame filter must
1830 implement, defined here:
1832 @defun FrameFilter.filter (iterator)
1833 @value{GDBN} will call this method on a frame filter when it has
1834 reached the order in the priority list for that filter.
1836 For example, if there are four frame filters:
1847 The order that the frame filters will be called is:
1850 Filter3 -> Filter2 -> Filter1 -> Filter4
1853 Note that the output from @code{Filter3} is passed to the input of
1854 @code{Filter2}, and so on.
1856 This @code{filter} method is passed a Python iterator. This iterator
1857 contains a sequence of frame decorators that wrap each
1858 @code{gdb.Frame}, or a frame decorator that wraps another frame
1859 decorator. The first filter that is executed in the sequence of frame
1860 filters will receive an iterator entirely comprised of default
1861 @code{FrameDecorator} objects. However, after each frame filter is
1862 executed, the previous frame filter may have wrapped some or all of
1863 the frame decorators with their own frame decorator. As frame
1864 decorators must also conform to a mandatory interface, these
1865 decorators can be assumed to act in a uniform manner (@pxref{Frame
1868 This method must return an object conforming to the Python iterator
1869 protocol. Each item in the iterator must be an object conforming to
1870 the frame decorator interface. If a frame filter does not wish to
1871 perform any operations on this iterator, it should return that
1874 This method is not optional. If it does not exist, @value{GDBN} will
1875 raise and print an error.
1878 @defvar FrameFilter.name
1879 The @code{name} attribute must be Python string which contains the
1880 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1881 Management}). This attribute may contain any combination of letters
1882 or numbers. Care should be taken to ensure that it is unique. This
1883 attribute is mandatory.
1886 @defvar FrameFilter.enabled
1887 The @code{enabled} attribute must be Python boolean. This attribute
1888 indicates to @value{GDBN} whether the frame filter is enabled, and
1889 should be considered when frame filters are executed. If
1890 @code{enabled} is @code{True}, then the frame filter will be executed
1891 when any of the backtrace commands detailed earlier in this chapter
1892 are executed. If @code{enabled} is @code{False}, then the frame
1893 filter will not be executed. This attribute is mandatory.
1896 @defvar FrameFilter.priority
1897 The @code{priority} attribute must be Python integer. This attribute
1898 controls the order of execution in relation to other frame filters.
1899 There are no imposed limits on the range of @code{priority} other than
1900 it must be a valid integer. The higher the @code{priority} attribute,
1901 the sooner the frame filter will be executed in relation to other
1902 frame filters. Although @code{priority} can be negative, it is
1903 recommended practice to assume zero is the lowest priority that a
1904 frame filter can be assigned. Frame filters that have the same
1905 priority are executed in unsorted order in that priority slot. This
1906 attribute is mandatory. 100 is a good default priority.
1909 @node Frame Decorator API
1910 @subsubsection Decorating Frames
1911 @cindex frame decorator api
1913 Frame decorators are sister objects to frame filters (@pxref{Frame
1914 Filter API}). Frame decorators are applied by a frame filter and can
1915 only be used in conjunction with frame filters.
1917 The purpose of a frame decorator is to customize the printed content
1918 of each @code{gdb.Frame} in commands where frame filters are executed.
1919 This concept is called decorating a frame. Frame decorators decorate
1920 a @code{gdb.Frame} with Python code contained within each API call.
1921 This separates the actual data contained in a @code{gdb.Frame} from
1922 the decorated data produced by a frame decorator. This abstraction is
1923 necessary to maintain integrity of the data contained in each
1926 Frame decorators have a mandatory interface, defined below.
1928 @value{GDBN} already contains a frame decorator called
1929 @code{FrameDecorator}. This contains substantial amounts of
1930 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
1931 recommended that other frame decorators inherit and extend this
1932 object, and only to override the methods needed.
1934 @tindex gdb.FrameDecorator
1935 @code{FrameDecorator} is defined in the Python module
1936 @code{gdb.FrameDecorator}, so your code can import it like:
1938 from gdb.FrameDecorator import FrameDecorator
1941 @defun FrameDecorator.elided (self)
1943 The @code{elided} method groups frames together in a hierarchical
1944 system. An example would be an interpreter, where multiple low-level
1945 frames make up a single call in the interpreted language. In this
1946 example, the frame filter would elide the low-level frames and present
1947 a single high-level frame, representing the call in the interpreted
1948 language, to the user.
1950 The @code{elided} function must return an iterable and this iterable
1951 must contain the frames that are being elided wrapped in a suitable
1952 frame decorator. If no frames are being elided this function may
1953 return an empty iterable, or @code{None}. Elided frames are indented
1954 from normal frames in a @code{CLI} backtrace, or in the case of
1955 @code{GDB/MI}, are placed in the @code{children} field of the eliding
1958 It is the frame filter's task to also filter out the elided frames from
1959 the source iterator. This will avoid printing the frame twice.
1962 @defun FrameDecorator.function (self)
1964 This method returns the name of the function in the frame that is to
1967 This method must return a Python string describing the function, or
1970 If this function returns @code{None}, @value{GDBN} will not print any
1971 data for this field.
1974 @defun FrameDecorator.address (self)
1976 This method returns the address of the frame that is to be printed.
1978 This method must return a Python numeric integer type of sufficient
1979 size to describe the address of the frame, or @code{None}.
1981 If this function returns a @code{None}, @value{GDBN} will not print
1982 any data for this field.
1985 @defun FrameDecorator.filename (self)
1987 This method returns the filename and path associated with this frame.
1989 This method must return a Python string containing the filename and
1990 the path to the object file backing the frame, or @code{None}.
1992 If this function returns a @code{None}, @value{GDBN} will not print
1993 any data for this field.
1996 @defun FrameDecorator.line (self):
1998 This method returns the line number associated with the current
1999 position within the function addressed by this frame.
2001 This method must return a Python integer type, or @code{None}.
2003 If this function returns a @code{None}, @value{GDBN} will not print
2004 any data for this field.
2007 @defun FrameDecorator.frame_args (self)
2010 This method must return an iterable, or @code{None}. Returning an
2011 empty iterable, or @code{None} means frame arguments will not be
2012 printed for this frame. This iterable must contain objects that
2013 implement two methods, described here.
2015 This object must implement a @code{argument} method which takes a
2016 single @code{self} parameter and must return a @code{gdb.Symbol}
2017 (@pxref{Symbols In Python}), or a Python string. The object must also
2018 implement a @code{value} method which takes a single @code{self}
2019 parameter and must return a @code{gdb.Value} (@pxref{Values From
2020 Inferior}), a Python value, or @code{None}. If the @code{value}
2021 method returns @code{None}, and the @code{argument} method returns a
2022 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
2023 the @code{gdb.Symbol} automatically.
2028 class SymValueWrapper():
2030 def __init__(self, symbol, value):
2040 class SomeFrameDecorator()
2043 def frame_args(self):
2046 block = self.inferior_frame.block()
2050 # Iterate over all symbols in a block. Only add
2051 # symbols that are arguments.
2053 if not sym.is_argument:
2055 args.append(SymValueWrapper(sym,None))
2057 # Add example synthetic argument.
2058 args.append(SymValueWrapper(``foo'', 42))
2064 @defun FrameDecorator.frame_locals (self)
2066 This method must return an iterable or @code{None}. Returning an
2067 empty iterable, or @code{None} means frame local arguments will not be
2068 printed for this frame.
2070 The object interface, the description of the various strategies for
2071 reading frame locals, and the example are largely similar to those
2072 described in the @code{frame_args} function, (@pxref{frame_args,,The
2073 frame filter frame_args function}). Below is a modified example:
2076 class SomeFrameDecorator()
2079 def frame_locals(self):
2082 block = self.inferior_frame.block()
2086 # Iterate over all symbols in a block. Add all
2087 # symbols, except arguments.
2091 vars.append(SymValueWrapper(sym,None))
2093 # Add an example of a synthetic local variable.
2094 vars.append(SymValueWrapper(``bar'', 99))
2100 @defun FrameDecorator.inferior_frame (self):
2102 This method must return the underlying @code{gdb.Frame} that this
2103 frame decorator is decorating. @value{GDBN} requires the underlying
2104 frame for internal frame information to determine how to print certain
2105 values when printing a frame.
2108 @node Writing a Frame Filter
2109 @subsubsection Writing a Frame Filter
2110 @cindex writing a frame filter
2112 There are three basic elements that a frame filter must implement: it
2113 must correctly implement the documented interface (@pxref{Frame Filter
2114 API}), it must register itself with @value{GDBN}, and finally, it must
2115 decide if it is to work on the data provided by @value{GDBN}. In all
2116 cases, whether it works on the iterator or not, each frame filter must
2117 return an iterator. A bare-bones frame filter follows the pattern in
2118 the following example.
2123 class FrameFilter():
2126 # Frame filter attribute creation.
2128 # 'name' is the name of the filter that GDB will display.
2130 # 'priority' is the priority of the filter relative to other
2133 # 'enabled' is a boolean that indicates whether this filter is
2134 # enabled and should be executed.
2140 # Register this frame filter with the global frame_filters
2142 gdb.frame_filters[self.name] = self
2144 def filter(self, frame_iter):
2145 # Just return the iterator.
2149 The frame filter in the example above implements the three
2150 requirements for all frame filters. It implements the API, self
2151 registers, and makes a decision on the iterator (in this case, it just
2152 returns the iterator untouched).
2154 The first step is attribute creation and assignment, and as shown in
2155 the comments the filter assigns the following attributes: @code{name},
2156 @code{priority} and whether the filter should be enabled with the
2157 @code{enabled} attribute.
2159 The second step is registering the frame filter with the dictionary or
2160 dictionaries that the frame filter has interest in. As shown in the
2161 comments, this filter just registers itself with the global dictionary
2162 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
2163 is a dictionary that is initialized in the @code{gdb} module when
2164 @value{GDBN} starts. What dictionary a filter registers with is an
2165 important consideration. Generally, if a filter is specific to a set
2166 of code, it should be registered either in the @code{objfile} or
2167 @code{progspace} dictionaries as they are specific to the program
2168 currently loaded in @value{GDBN}. The global dictionary is always
2169 present in @value{GDBN} and is never unloaded. Any filters registered
2170 with the global dictionary will exist until @value{GDBN} exits. To
2171 avoid filters that may conflict, it is generally better to register
2172 frame filters against the dictionaries that more closely align with
2173 the usage of the filter currently in question. @xref{Python
2174 Auto-loading}, for further information on auto-loading Python scripts.
2176 @value{GDBN} takes a hands-off approach to frame filter registration,
2177 therefore it is the frame filter's responsibility to ensure
2178 registration has occurred, and that any exceptions are handled
2179 appropriately. In particular, you may wish to handle exceptions
2180 relating to Python dictionary key uniqueness. It is mandatory that
2181 the dictionary key is the same as frame filter's @code{name}
2182 attribute. When a user manages frame filters (@pxref{Frame Filter
2183 Management}), the names @value{GDBN} will display are those contained
2184 in the @code{name} attribute.
2186 The final step of this example is the implementation of the
2187 @code{filter} method. As shown in the example comments, we define the
2188 @code{filter} method and note that the method must take an iterator,
2189 and also must return an iterator. In this bare-bones example, the
2190 frame filter is not very useful as it just returns the iterator
2191 untouched. However this is a valid operation for frame filters that
2192 have the @code{enabled} attribute set, but decide not to operate on
2195 In the next example, the frame filter operates on all frames and
2196 utilizes a frame decorator to perform some work on the frames.
2197 @xref{Frame Decorator API}, for further information on the frame
2198 decorator interface.
2200 This example works on inlined frames. It highlights frames which are
2201 inlined by tagging them with an ``[inlined]'' tag. By applying a
2202 frame decorator to all frames with the Python @code{itertools imap}
2203 method, the example defers actions to the frame decorator. Frame
2204 decorators are only processed when @value{GDBN} prints the backtrace.
2206 This introduces a new decision making topic: whether to perform
2207 decision making operations at the filtering step, or at the printing
2208 step. In this example's approach, it does not perform any filtering
2209 decisions at the filtering step beyond mapping a frame decorator to
2210 each frame. This allows the actual decision making to be performed
2211 when each frame is printed. This is an important consideration, and
2212 well worth reflecting upon when designing a frame filter. An issue
2213 that frame filters should avoid is unwinding the stack if possible.
2214 Some stacks can run very deep, into the tens of thousands in some
2215 cases. To search every frame to determine if it is inlined ahead of
2216 time may be too expensive at the filtering step. The frame filter
2217 cannot know how many frames it has to iterate over, and it would have
2218 to iterate through them all. This ends up duplicating effort as
2219 @value{GDBN} performs this iteration when it prints the frames.
2221 In this example decision making can be deferred to the printing step.
2222 As each frame is printed, the frame decorator can examine each frame
2223 in turn when @value{GDBN} iterates. From a performance viewpoint,
2224 this is the most appropriate decision to make as it avoids duplicating
2225 the effort that the printing step would undertake anyway. Also, if
2226 there are many frame filters unwinding the stack during filtering, it
2227 can substantially delay the printing of the backtrace which will
2228 result in large memory usage, and a poor user experience.
2231 class InlineFilter():
2234 self.name = "InlinedFrameFilter"
2237 gdb.frame_filters[self.name] = self
2239 def filter(self, frame_iter):
2240 frame_iter = itertools.imap(InlinedFrameDecorator,
2245 This frame filter is somewhat similar to the earlier example, except
2246 that the @code{filter} method applies a frame decorator object called
2247 @code{InlinedFrameDecorator} to each element in the iterator. The
2248 @code{imap} Python method is light-weight. It does not proactively
2249 iterate over the iterator, but rather creates a new iterator which
2250 wraps the existing one.
2252 Below is the frame decorator for this example.
2255 class InlinedFrameDecorator(FrameDecorator):
2257 def __init__(self, fobj):
2258 super(InlinedFrameDecorator, self).__init__(fobj)
2261 frame = fobj.inferior_frame()
2262 name = str(frame.name())
2264 if frame.type() == gdb.INLINE_FRAME:
2265 name = name + " [inlined]"
2270 This frame decorator only defines and overrides the @code{function}
2271 method. It lets the supplied @code{FrameDecorator}, which is shipped
2272 with @value{GDBN}, perform the other work associated with printing
2275 The combination of these two objects create this output from a
2279 #0 0x004004e0 in bar () at inline.c:11
2280 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2281 #2 0x00400566 in main () at inline.c:31
2284 So in the case of this example, a frame decorator is applied to all
2285 frames, regardless of whether they may be inlined or not. As
2286 @value{GDBN} iterates over the iterator produced by the frame filters,
2287 @value{GDBN} executes each frame decorator which then makes a decision
2288 on what to print in the @code{function} callback. Using a strategy
2289 like this is a way to defer decisions on the frame content to printing
2292 @subheading Eliding Frames
2294 It might be that the above example is not desirable for representing
2295 inlined frames, and a hierarchical approach may be preferred. If we
2296 want to hierarchically represent frames, the @code{elided} frame
2297 decorator interface might be preferable.
2299 This example approaches the issue with the @code{elided} method. This
2300 example is quite long, but very simplistic. It is out-of-scope for
2301 this section to write a complete example that comprehensively covers
2302 all approaches of finding and printing inlined frames. However, this
2303 example illustrates the approach an author might use.
2305 This example comprises of three sections.
2308 class InlineFrameFilter():
2311 self.name = "InlinedFrameFilter"
2314 gdb.frame_filters[self.name] = self
2316 def filter(self, frame_iter):
2317 return ElidingInlineIterator(frame_iter)
2320 This frame filter is very similar to the other examples. The only
2321 difference is this frame filter is wrapping the iterator provided to
2322 it (@code{frame_iter}) with a custom iterator called
2323 @code{ElidingInlineIterator}. This again defers actions to when
2324 @value{GDBN} prints the backtrace, as the iterator is not traversed
2327 The iterator for this example is as follows. It is in this section of
2328 the example where decisions are made on the content of the backtrace.
2331 class ElidingInlineIterator:
2332 def __init__(self, ii):
2333 self.input_iterator = ii
2339 frame = next(self.input_iterator)
2341 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2345 eliding_frame = next(self.input_iterator)
2346 except StopIteration:
2348 return ElidingFrameDecorator(eliding_frame, [frame])
2351 This iterator implements the Python iterator protocol. When the
2352 @code{next} function is called (when @value{GDBN} prints each frame),
2353 the iterator checks if this frame decorator, @code{frame}, is wrapping
2354 an inlined frame. If it is not, it returns the existing frame decorator
2355 untouched. If it is wrapping an inlined frame, it assumes that the
2356 inlined frame was contained within the next oldest frame,
2357 @code{eliding_frame}, which it fetches. It then creates and returns a
2358 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2359 elided frame, and the eliding frame.
2362 class ElidingInlineDecorator(FrameDecorator):
2364 def __init__(self, frame, elided_frames):
2365 super(ElidingInlineDecorator, self).__init__(frame)
2367 self.elided_frames = elided_frames
2370 return iter(self.elided_frames)
2373 This frame decorator overrides one function and returns the inlined
2374 frame in the @code{elided} method. As before it lets
2375 @code{FrameDecorator} do the rest of the work involved in printing
2376 this frame. This produces the following output.
2379 #0 0x004004e0 in bar () at inline.c:11
2380 #2 0x00400529 in main () at inline.c:25
2381 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2384 In that output, @code{max} which has been inlined into @code{main} is
2385 printed hierarchically. Another approach would be to combine the
2386 @code{function} method, and the @code{elided} method to both print a
2387 marker in the inlined frame, and also show the hierarchical
2390 @node Unwinding Frames in Python
2391 @subsubsection Unwinding Frames in Python
2392 @cindex unwinding frames in Python
2394 In @value{GDBN} terminology ``unwinding'' is the process of finding
2395 the previous frame (that is, caller's) from the current one. An
2396 unwinder has three methods. The first one checks if it can handle
2397 given frame (``sniff'' it). For the frames it can sniff an unwinder
2398 provides two additional methods: it can return frame's ID, and it can
2399 fetch registers from the previous frame. A running @value{GDBN}
2400 mantains a list of the unwinders and calls each unwinder's sniffer in
2401 turn until it finds the one that recognizes the current frame. There
2402 is an API to register an unwinder.
2404 The unwinders that come with @value{GDBN} handle standard frames.
2405 However, mixed language applications (for example, an application
2406 running Java Virtual Machine) sometimes use frame layouts that cannot
2407 be handled by the @value{GDBN} unwinders. You can write Python code
2408 that can handle such custom frames.
2410 You implement a frame unwinder in Python as a class with which has two
2411 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2412 a single method @code{__call__}, which examines a given frame and
2413 returns an object (an instance of @code{gdb.UnwindInfo class)}
2414 describing it. If an unwinder does not recognize a frame, it should
2415 return @code{None}. The code in @value{GDBN} that enables writing
2416 unwinders in Python uses this object to return frame's ID and previous
2417 frame registers when @value{GDBN} core asks for them.
2419 An unwinder should do as little work as possible. Some otherwise
2420 innocuous operations can cause problems (even crashes, as this code is
2421 not not well-hardened yet). For example, making an inferior call from
2422 an unwinder is unadvisable, as an inferior call will reset
2423 @value{GDBN}'s stack unwinding process, potentially causing re-entrant
2426 @subheading Unwinder Input
2428 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2429 provides a method to read frame's registers:
2431 @defun PendingFrame.read_register (reg)
2432 This method returns the contents of the register @var{reg} in the
2433 frame as a @code{gdb.Value} object. @var{reg} can be either a
2434 register number or a register name; the values are platform-specific.
2435 They are usually found in the corresponding
2436 @file{@var{platform}-tdep.h} file in the @value{GDBN} source tree. If
2437 @var{reg} does not name a register for the current architecture, this
2438 method will throw an exception.
2440 Note that this method will always return a @code{gdb.Value} for a
2441 valid register name. This does not mean that the value will be valid.
2442 For example, you may request a register that an earlier unwinder could
2443 not unwind---the value will be unavailable. Instead, the
2444 @code{gdb.Value} returned from this method will be lazy; that is, its
2445 underlying bits will not be fetched until it is first used. So,
2446 attempting to use such a value will cause an exception at the point of
2449 The type of the returned @code{gdb.Value} depends on the register and
2450 the architecture. It is common for registers to have a scalar type,
2451 like @code{long long}; but many other types are possible, such as
2452 pointer, pointer-to-function, floating point or vector types.
2455 It also provides a factory method to create a @code{gdb.UnwindInfo}
2456 instance to be returned to @value{GDBN}:
2458 @defun PendingFrame.create_unwind_info (frame_id)
2459 Returns a new @code{gdb.UnwindInfo} instance identified by given
2460 @var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2461 using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2462 determine which function will be used, as follows:
2466 The frame is identified by the given stack address and PC. The stack
2467 address must be chosen so that it is constant throughout the lifetime
2468 of the frame, so a typical choice is the value of the stack pointer at
2469 the start of the function---in the DWARF standard, this would be the
2470 ``Call Frame Address''.
2472 This is the most common case by far. The other cases are documented
2473 for completeness but are only useful in specialized situations.
2475 @item sp, pc, special
2476 The frame is identified by the stack address, the PC, and a
2477 ``special'' address. The special address is used on architectures
2478 that can have frames that do not change the stack, but which are still
2479 distinct, for example the IA-64, which has a second stack for
2480 registers. Both @var{sp} and @var{special} must be constant
2481 throughout the lifetime of the frame.
2484 The frame is identified by the stack address only. Any other stack
2485 frame with a matching @var{sp} will be considered to match this frame.
2486 Inside gdb, this is called a ``wild frame''. You will never need
2490 Each attribute value should be an instance of @code{gdb.Value}.
2494 @subheading Unwinder Output: UnwindInfo
2496 Use @code{PendingFrame.create_unwind_info} method described above to
2497 create a @code{gdb.UnwindInfo} instance. Use the following method to
2498 specify caller registers that have been saved in this frame:
2500 @defun gdb.UnwindInfo.add_saved_register (reg, value)
2501 @var{reg} identifies the register. It can be a number or a name, just
2502 as for the @code{PendingFrame.read_register} method above.
2503 @var{value} is a register value (a @code{gdb.Value} object).
2506 @subheading Unwinder Skeleton Code
2508 @value{GDBN} comes with the module containing the base @code{Unwinder}
2509 class. Derive your unwinder class from it and structure the code as
2513 from gdb.unwinders import Unwinder
2515 class FrameId(object):
2516 def __init__(self, sp, pc):
2521 class MyUnwinder(Unwinder):
2523 supe(MyUnwinder, self).__init___(<expects unwinder name argument>)
2525 def __call__(pending_frame):
2526 if not <we recognize frame>:
2528 # Create UnwindInfo. Usually the frame is identified by the stack
2529 # pointer and the program counter.
2530 sp = pending_frame.read_register(<SP number>)
2531 pc = pending_frame.read_register(<PC number>)
2532 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2534 # Find the values of the registers in the caller's frame and
2535 # save them in the result:
2536 unwind_info.add_saved_register(<register>, <value>)
2539 # Return the result:
2544 @subheading Registering a Unwinder
2546 An object file, a program space, and the @value{GDBN} proper can have
2547 unwinders registered with it.
2549 The @code{gdb.unwinders} module provides the function to register a
2552 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2553 @var{locus} is specifies an object file or a program space to which
2554 @var{unwinder} is added. Passing @code{None} or @code{gdb} adds
2555 @var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
2556 added @var{unwinder} will be called before any other unwinder from the
2557 same locus. Two unwinders in the same locus cannot have the same
2558 name. An attempt to add a unwinder with already existing name raises
2559 an exception unless @var{replace} is @code{True}, in which case the
2560 old unwinder is deleted.
2563 @subheading Unwinder Precedence
2565 @value{GDBN} first calls the unwinders from all the object files in no
2566 particular order, then the unwinders from the current program space,
2567 and finally the unwinders from @value{GDBN}.
2569 @node Xmethods In Python
2570 @subsubsection Xmethods In Python
2571 @cindex xmethods in Python
2573 @dfn{Xmethods} are additional methods or replacements for existing
2574 methods of a C@t{++} class. This feature is useful for those cases
2575 where a method defined in C@t{++} source code could be inlined or
2576 optimized out by the compiler, making it unavailable to @value{GDBN}.
2577 For such cases, one can define an xmethod to serve as a replacement
2578 for the method defined in the C@t{++} source code. @value{GDBN} will
2579 then invoke the xmethod, instead of the C@t{++} method, to
2580 evaluate expressions. One can also use xmethods when debugging
2581 with core files. Moreover, when debugging live programs, invoking an
2582 xmethod need not involve running the inferior (which can potentially
2583 perturb its state). Hence, even if the C@t{++} method is available, it
2584 is better to use its replacement xmethod if one is defined.
2586 The xmethods feature in Python is available via the concepts of an
2587 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2588 implement an xmethod, one has to implement a matcher and a
2589 corresponding worker for it (more than one worker can be
2590 implemented, each catering to a different overloaded instance of the
2591 method). Internally, @value{GDBN} invokes the @code{match} method of a
2592 matcher to match the class type and method name. On a match, the
2593 @code{match} method returns a list of matching @emph{worker} objects.
2594 Each worker object typically corresponds to an overloaded instance of
2595 the xmethod. They implement a @code{get_arg_types} method which
2596 returns a sequence of types corresponding to the arguments the xmethod
2597 requires. @value{GDBN} uses this sequence of types to perform
2598 overload resolution and picks a winning xmethod worker. A winner
2599 is also selected from among the methods @value{GDBN} finds in the
2600 C@t{++} source code. Next, the winning xmethod worker and the
2601 winning C@t{++} method are compared to select an overall winner. In
2602 case of a tie between a xmethod worker and a C@t{++} method, the
2603 xmethod worker is selected as the winner. That is, if a winning
2604 xmethod worker is found to be equivalent to the winning C@t{++}
2605 method, then the xmethod worker is treated as a replacement for
2606 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2607 method. If the winning xmethod worker is the overall winner, then
2608 the corresponding xmethod is invoked via the @code{__call__} method
2609 of the worker object.
2611 If one wants to implement an xmethod as a replacement for an
2612 existing C@t{++} method, then they have to implement an equivalent
2613 xmethod which has exactly the same name and takes arguments of
2614 exactly the same type as the C@t{++} method. If the user wants to
2615 invoke the C@t{++} method even though a replacement xmethod is
2616 available for that method, then they can disable the xmethod.
2618 @xref{Xmethod API}, for API to implement xmethods in Python.
2619 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2622 @subsubsection Xmethod API
2625 The @value{GDBN} Python API provides classes, interfaces and functions
2626 to implement, register and manipulate xmethods.
2627 @xref{Xmethods In Python}.
2629 An xmethod matcher should be an instance of a class derived from
2630 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2631 object with similar interface and attributes. An instance of
2632 @code{XMethodMatcher} has the following attributes:
2635 The name of the matcher.
2639 A boolean value indicating whether the matcher is enabled or disabled.
2643 A list of named methods managed by the matcher. Each object in the list
2644 is an instance of the class @code{XMethod} defined in the module
2645 @code{gdb.xmethod}, or any object with the following attributes:
2650 Name of the xmethod which should be unique for each xmethod
2651 managed by the matcher.
2654 A boolean value indicating whether the xmethod is enabled or
2659 The class @code{XMethod} is a convenience class with same
2660 attributes as above along with the following constructor:
2662 @defun XMethod.__init__ (self, name)
2663 Constructs an enabled xmethod with name @var{name}.
2668 The @code{XMethodMatcher} class has the following methods:
2670 @defun XMethodMatcher.__init__ (self, name)
2671 Constructs an enabled xmethod matcher with name @var{name}. The
2672 @code{methods} attribute is initialized to @code{None}.
2675 @defun XMethodMatcher.match (self, class_type, method_name)
2676 Derived classes should override this method. It should return a
2677 xmethod worker object (or a sequence of xmethod worker
2678 objects) matching the @var{class_type} and @var{method_name}.
2679 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2680 is a string value. If the matcher manages named methods as listed in
2681 its @code{methods} attribute, then only those worker objects whose
2682 corresponding entries in the @code{methods} list are enabled should be
2686 An xmethod worker should be an instance of a class derived from
2687 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
2688 or support the following interface:
2690 @defun XMethodWorker.get_arg_types (self)
2691 This method returns a sequence of @code{gdb.Type} objects corresponding
2692 to the arguments that the xmethod takes. It can return an empty
2693 sequence or @code{None} if the xmethod does not take any arguments.
2694 If the xmethod takes a single argument, then a single
2695 @code{gdb.Type} object corresponding to it can be returned.
2698 @defun XMethodWorker.get_result_type (self, *args)
2699 This method returns a @code{gdb.Type} object representing the type
2700 of the result of invoking this xmethod.
2701 The @var{args} argument is the same tuple of arguments that would be
2702 passed to the @code{__call__} method of this worker.
2705 @defun XMethodWorker.__call__ (self, *args)
2706 This is the method which does the @emph{work} of the xmethod. The
2707 @var{args} arguments is the tuple of arguments to the xmethod. Each
2708 element in this tuple is a gdb.Value object. The first element is
2709 always the @code{this} pointer value.
2712 For @value{GDBN} to lookup xmethods, the xmethod matchers
2713 should be registered using the following function defined in the module
2716 @defun register_xmethod_matcher (locus, matcher, replace=False)
2717 The @code{matcher} is registered with @code{locus}, replacing an
2718 existing matcher with the same name as @code{matcher} if
2719 @code{replace} is @code{True}. @code{locus} can be a
2720 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
2721 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
2722 @code{None}. If it is @code{None}, then @code{matcher} is registered
2726 @node Writing an Xmethod
2727 @subsubsection Writing an Xmethod
2728 @cindex writing xmethods in Python
2730 Implementing xmethods in Python will require implementing xmethod
2731 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2732 the following C@t{++} class:
2738 MyClass (int a) : a_(a) @{ @}
2740 int geta (void) @{ return a_; @}
2741 int operator+ (int b);
2748 MyClass::operator+ (int b)
2755 Let us define two xmethods for the class @code{MyClass}, one
2756 replacing the method @code{geta}, and another adding an overloaded
2757 flavor of @code{operator+} which takes a @code{MyClass} argument (the
2758 C@t{++} code above already has an overloaded @code{operator+}
2759 which takes an @code{int} argument). The xmethod matcher can be
2763 class MyClass_geta(gdb.xmethod.XMethod):
2765 gdb.xmethod.XMethod.__init__(self, 'geta')
2767 def get_worker(self, method_name):
2768 if method_name == 'geta':
2769 return MyClassWorker_geta()
2772 class MyClass_sum(gdb.xmethod.XMethod):
2774 gdb.xmethod.XMethod.__init__(self, 'sum')
2776 def get_worker(self, method_name):
2777 if method_name == 'operator+':
2778 return MyClassWorker_plus()
2781 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2783 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2784 # List of methods 'managed' by this matcher
2785 self.methods = [MyClass_geta(), MyClass_sum()]
2787 def match(self, class_type, method_name):
2788 if class_type.tag != 'MyClass':
2791 for method in self.methods:
2793 worker = method.get_worker(method_name)
2795 workers.append(worker)
2801 Notice that the @code{match} method of @code{MyClassMatcher} returns
2802 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
2803 method, and a worker object of type @code{MyClassWorker_plus} for the
2804 @code{operator+} method. This is done indirectly via helper classes
2805 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
2806 @code{methods} attribute in a matcher as it is optional. However, if a
2807 matcher manages more than one xmethod, it is a good practice to list the
2808 xmethods in the @code{methods} attribute of the matcher. This will then
2809 facilitate enabling and disabling individual xmethods via the
2810 @code{enable/disable} commands. Notice also that a worker object is
2811 returned only if the corresponding entry in the @code{methods} attribute
2812 of the matcher is enabled.
2814 The implementation of the worker classes returned by the matcher setup
2815 above is as follows:
2818 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
2819 def get_arg_types(self):
2822 def get_result_type(self, obj):
2823 return gdb.lookup_type('int')
2825 def __call__(self, obj):
2829 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
2830 def get_arg_types(self):
2831 return gdb.lookup_type('MyClass')
2833 def get_result_type(self, obj):
2834 return gdb.lookup_type('int')
2836 def __call__(self, obj, other):
2837 return obj['a_'] + other['a_']
2840 For @value{GDBN} to actually lookup a xmethod, it has to be
2841 registered with it. The matcher defined above is registered with
2842 @value{GDBN} globally as follows:
2845 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
2848 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
2856 then, after loading the Python script defining the xmethod matchers
2857 and workers into @code{GDBN}, invoking the method @code{geta} or using
2858 the operator @code{+} on @code{obj} will invoke the xmethods
2869 Consider another example with a C++ template class:
2876 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
2877 ~MyTemplate () @{ delete [] data_; @}
2879 int footprint (void)
2881 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
2890 Let us implement an xmethod for the above class which serves as a
2891 replacement for the @code{footprint} method. The full code listing
2892 of the xmethod workers and xmethod matchers is as follows:
2895 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
2896 def __init__(self, class_type):
2897 self.class_type = class_type
2899 def get_arg_types(self):
2902 def get_result_type(self):
2903 return gdb.lookup_type('int')
2905 def __call__(self, obj):
2906 return (self.class_type.sizeof +
2908 self.class_type.template_argument(0).sizeof)
2911 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
2913 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
2915 def match(self, class_type, method_name):
2916 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
2918 method_name == 'footprint'):
2919 return MyTemplateWorker_footprint(class_type)
2922 Notice that, in this example, we have not used the @code{methods}
2923 attribute of the matcher as the matcher manages only one xmethod. The
2924 user can enable/disable this xmethod by enabling/disabling the matcher
2927 @node Inferiors In Python
2928 @subsubsection Inferiors In Python
2929 @cindex inferiors in Python
2931 @findex gdb.Inferior
2932 Programs which are being run under @value{GDBN} are called inferiors
2933 (@pxref{Inferiors and Programs}). Python scripts can access
2934 information about and manipulate inferiors controlled by @value{GDBN}
2935 via objects of the @code{gdb.Inferior} class.
2937 The following inferior-related functions are available in the @code{gdb}
2940 @defun gdb.inferiors ()
2941 Return a tuple containing all inferior objects.
2944 @defun gdb.selected_inferior ()
2945 Return an object representing the current inferior.
2948 A @code{gdb.Inferior} object has the following attributes:
2950 @defvar Inferior.num
2951 ID of inferior, as assigned by GDB.
2954 @defvar Inferior.pid
2955 Process ID of the inferior, as assigned by the underlying operating
2959 @defvar Inferior.was_attached
2960 Boolean signaling whether the inferior was created using `attach', or
2961 started by @value{GDBN} itself.
2964 @defvar Inferior.progspace
2965 The inferior's program space. @xref{Progspaces In Python}.
2968 A @code{gdb.Inferior} object has the following methods:
2970 @defun Inferior.is_valid ()
2971 Returns @code{True} if the @code{gdb.Inferior} object is valid,
2972 @code{False} if not. A @code{gdb.Inferior} object will become invalid
2973 if the inferior no longer exists within @value{GDBN}. All other
2974 @code{gdb.Inferior} methods will throw an exception if it is invalid
2975 at the time the method is called.
2978 @defun Inferior.threads ()
2979 This method returns a tuple holding all the threads which are valid
2980 when it is called. If there are no valid threads, the method will
2981 return an empty tuple.
2984 @defun Inferior.architecture ()
2985 Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
2986 for this inferior. This represents the architecture of the inferior
2987 as a whole. Some platforms can have multiple architectures in a
2988 single address space, so this may not match the architecture of a
2989 particular frame (@pxref{Frames In Python}).
2992 @findex Inferior.read_memory
2993 @defun Inferior.read_memory (address, length)
2994 Read @var{length} addressable memory units from the inferior, starting at
2995 @var{address}. Returns a buffer object, which behaves much like an array
2996 or a string. It can be modified and given to the
2997 @code{Inferior.write_memory} function. In Python 3, the return
2998 value is a @code{memoryview} object.
3001 @findex Inferior.write_memory
3002 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
3003 Write the contents of @var{buffer} to the inferior, starting at
3004 @var{address}. The @var{buffer} parameter must be a Python object
3005 which supports the buffer protocol, i.e., a string, an array or the
3006 object returned from @code{Inferior.read_memory}. If given, @var{length}
3007 determines the number of addressable memory units from @var{buffer} to be
3011 @findex gdb.search_memory
3012 @defun Inferior.search_memory (address, length, pattern)
3013 Search a region of the inferior memory starting at @var{address} with
3014 the given @var{length} using the search pattern supplied in
3015 @var{pattern}. The @var{pattern} parameter must be a Python object
3016 which supports the buffer protocol, i.e., a string, an array or the
3017 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
3018 containing the address where the pattern was found, or @code{None} if
3019 the pattern could not be found.
3022 @findex Inferior.thread_from_handle
3023 @findex Inferior.thread_from_thread_handle
3024 @defun Inferior.thread_from_handle (handle)
3025 Return the thread object corresponding to @var{handle}, a thread
3026 library specific data structure such as @code{pthread_t} for pthreads
3027 library implementations.
3029 The function @code{Inferior.thread_from_thread_handle} provides
3030 the same functionality, but use of @code{Inferior.thread_from_thread_handle}
3034 @node Events In Python
3035 @subsubsection Events In Python
3036 @cindex inferior events in Python
3038 @value{GDBN} provides a general event facility so that Python code can be
3039 notified of various state changes, particularly changes that occur in
3042 An @dfn{event} is just an object that describes some state change. The
3043 type of the object and its attributes will vary depending on the details
3044 of the change. All the existing events are described below.
3046 In order to be notified of an event, you must register an event handler
3047 with an @dfn{event registry}. An event registry is an object in the
3048 @code{gdb.events} module which dispatches particular events. A registry
3049 provides methods to register and unregister event handlers:
3051 @defun EventRegistry.connect (object)
3052 Add the given callable @var{object} to the registry. This object will be
3053 called when an event corresponding to this registry occurs.
3056 @defun EventRegistry.disconnect (object)
3057 Remove the given @var{object} from the registry. Once removed, the object
3058 will no longer receive notifications of events.
3064 def exit_handler (event):
3065 print "event type: exit"
3066 print "exit code: %d" % (event.exit_code)
3068 gdb.events.exited.connect (exit_handler)
3071 In the above example we connect our handler @code{exit_handler} to the
3072 registry @code{events.exited}. Once connected, @code{exit_handler} gets
3073 called when the inferior exits. The argument @dfn{event} in this example is
3074 of type @code{gdb.ExitedEvent}. As you can see in the example the
3075 @code{ExitedEvent} object has an attribute which indicates the exit code of
3078 The following is a listing of the event registries that are available and
3079 details of the events they emit:
3084 Emits @code{gdb.ThreadEvent}.
3086 Some events can be thread specific when @value{GDBN} is running in non-stop
3087 mode. When represented in Python, these events all extend
3088 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
3089 events which are emitted by this or other modules might extend this event.
3090 Examples of these events are @code{gdb.BreakpointEvent} and
3091 @code{gdb.ContinueEvent}.
3093 @defvar ThreadEvent.inferior_thread
3094 In non-stop mode this attribute will be set to the specific thread which was
3095 involved in the emitted event. Otherwise, it will be set to @code{None}.
3098 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
3100 This event indicates that the inferior has been continued after a stop. For
3101 inherited attribute refer to @code{gdb.ThreadEvent} above.
3104 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
3105 @code{events.ExitedEvent} has two attributes:
3106 @defvar ExitedEvent.exit_code
3107 An integer representing the exit code, if available, which the inferior
3108 has returned. (The exit code could be unavailable if, for example,
3109 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
3110 the attribute does not exist.
3112 @defvar ExitedEvent.inferior
3113 A reference to the inferior which triggered the @code{exited} event.
3117 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
3119 Indicates that the inferior has stopped. All events emitted by this registry
3120 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
3121 will indicate the stopped thread when @value{GDBN} is running in non-stop
3122 mode. Refer to @code{gdb.ThreadEvent} above for more details.
3124 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
3126 This event indicates that the inferior or one of its threads has received as
3127 signal. @code{gdb.SignalEvent} has the following attributes:
3129 @defvar SignalEvent.stop_signal
3130 A string representing the signal received by the inferior. A list of possible
3131 signal values can be obtained by running the command @code{info signals} in
3132 the @value{GDBN} command prompt.
3135 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
3137 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
3138 been hit, and has the following attributes:
3140 @defvar BreakpointEvent.breakpoints
3141 A sequence containing references to all the breakpoints (type
3142 @code{gdb.Breakpoint}) that were hit.
3143 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
3145 @defvar BreakpointEvent.breakpoint
3146 A reference to the first breakpoint that was hit.
3147 This function is maintained for backward compatibility and is now deprecated
3148 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
3151 @item events.new_objfile
3152 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
3153 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
3155 @defvar NewObjFileEvent.new_objfile
3156 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
3157 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
3160 @item events.clear_objfiles
3161 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
3162 files for a program space has been reset.
3163 @code{gdb.ClearObjFilesEvent} has one attribute:
3165 @defvar ClearObjFilesEvent.progspace
3166 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
3167 been cleared. @xref{Progspaces In Python}.
3170 @item events.inferior_call
3171 Emits events just before and after a function in the inferior is
3172 called by @value{GDBN}. Before an inferior call, this emits an event
3173 of type @code{gdb.InferiorCallPreEvent}, and after an inferior call,
3174 this emits an event of type @code{gdb.InferiorCallPostEvent}.
3177 @tindex gdb.InferiorCallPreEvent
3178 @item @code{gdb.InferiorCallPreEvent}
3179 Indicates that a function in the inferior is about to be called.
3181 @defvar InferiorCallPreEvent.ptid
3182 The thread in which the call will be run.
3185 @defvar InferiorCallPreEvent.address
3186 The location of the function to be called.
3189 @tindex gdb.InferiorCallPostEvent
3190 @item @code{gdb.InferiorCallPostEvent}
3191 Indicates that a function in the inferior has just been called.
3193 @defvar InferiorCallPostEvent.ptid
3194 The thread in which the call was run.
3197 @defvar InferiorCallPostEvent.address
3198 The location of the function that was called.
3202 @item events.memory_changed
3203 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
3204 inferior has been modified by the @value{GDBN} user, for instance via a
3205 command like @w{@code{set *addr = value}}. The event has the following
3208 @defvar MemoryChangedEvent.address
3209 The start address of the changed region.
3212 @defvar MemoryChangedEvent.length
3213 Length in bytes of the changed region.
3216 @item events.register_changed
3217 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
3218 inferior has been modified by the @value{GDBN} user.
3220 @defvar RegisterChangedEvent.frame
3221 A gdb.Frame object representing the frame in which the register was modified.
3223 @defvar RegisterChangedEvent.regnum
3224 Denotes which register was modified.
3227 @item events.breakpoint_created
3228 This is emitted when a new breakpoint has been created. The argument
3229 that is passed is the new @code{gdb.Breakpoint} object.
3231 @item events.breakpoint_modified
3232 This is emitted when a breakpoint has been modified in some way. The
3233 argument that is passed is the new @code{gdb.Breakpoint} object.
3235 @item events.breakpoint_deleted
3236 This is emitted when a breakpoint has been deleted. The argument that
3237 is passed is the @code{gdb.Breakpoint} object. When this event is
3238 emitted, the @code{gdb.Breakpoint} object will already be in its
3239 invalid state; that is, the @code{is_valid} method will return
3242 @item events.before_prompt
3243 This event carries no payload. It is emitted each time @value{GDBN}
3244 presents a prompt to the user.
3246 @item events.new_inferior
3247 This is emitted when a new inferior is created. Note that the
3248 inferior is not necessarily running; in fact, it may not even have an
3249 associated executable.
3251 The event is of type @code{gdb.NewInferiorEvent}. This has a single
3254 @defvar NewInferiorEvent.inferior
3255 The new inferior, a @code{gdb.Inferior} object.
3258 @item events.inferior_deleted
3259 This is emitted when an inferior has been deleted. Note that this is
3260 not the same as process exit; it is notified when the inferior itself
3261 is removed, say via @code{remove-inferiors}.
3263 The event is of type @code{gdb.InferiorDeletedEvent}. This has a single
3266 @defvar NewInferiorEvent.inferior
3267 The inferior that is being removed, a @code{gdb.Inferior} object.
3270 @item events.new_thread
3271 This is emitted when @value{GDBN} notices a new thread. The event is of
3272 type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}.
3273 This has a single attribute:
3275 @defvar NewThreadEvent.inferior_thread
3281 @node Threads In Python
3282 @subsubsection Threads In Python
3283 @cindex threads in python
3285 @findex gdb.InferiorThread
3286 Python scripts can access information about, and manipulate inferior threads
3287 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
3289 The following thread-related functions are available in the @code{gdb}
3292 @findex gdb.selected_thread
3293 @defun gdb.selected_thread ()
3294 This function returns the thread object for the selected thread. If there
3295 is no selected thread, this will return @code{None}.
3298 A @code{gdb.InferiorThread} object has the following attributes:
3300 @defvar InferiorThread.name
3301 The name of the thread. If the user specified a name using
3302 @code{thread name}, then this returns that name. Otherwise, if an
3303 OS-supplied name is available, then it is returned. Otherwise, this
3304 returns @code{None}.
3306 This attribute can be assigned to. The new value must be a string
3307 object, which sets the new name, or @code{None}, which removes any
3308 user-specified thread name.
3311 @defvar InferiorThread.num
3312 The per-inferior number of the thread, as assigned by GDB.
3315 @defvar InferiorThread.global_num
3316 The global ID of the thread, as assigned by GDB. You can use this to
3317 make Python breakpoints thread-specific, for example
3318 (@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
3321 @defvar InferiorThread.ptid
3322 ID of the thread, as assigned by the operating system. This attribute is a
3323 tuple containing three integers. The first is the Process ID (PID); the second
3324 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
3325 Either the LWPID or TID may be 0, which indicates that the operating system
3326 does not use that identifier.
3329 @defvar InferiorThread.inferior
3330 The inferior this thread belongs to. This attribute is represented as
3331 a @code{gdb.Inferior} object. This attribute is not writable.
3334 A @code{gdb.InferiorThread} object has the following methods:
3336 @defun InferiorThread.is_valid ()
3337 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
3338 @code{False} if not. A @code{gdb.InferiorThread} object will become
3339 invalid if the thread exits, or the inferior that the thread belongs
3340 is deleted. All other @code{gdb.InferiorThread} methods will throw an
3341 exception if it is invalid at the time the method is called.
3344 @defun InferiorThread.switch ()
3345 This changes @value{GDBN}'s currently selected thread to the one represented
3349 @defun InferiorThread.is_stopped ()
3350 Return a Boolean indicating whether the thread is stopped.
3353 @defun InferiorThread.is_running ()
3354 Return a Boolean indicating whether the thread is running.
3357 @defun InferiorThread.is_exited ()
3358 Return a Boolean indicating whether the thread is exited.
3361 @defun InferiorThread.handle ()
3362 Return the thread object's handle, represented as a Python @code{bytes}
3363 object. A @code{gdb.Value} representation of the handle may be
3364 constructed via @code{gdb.Value(bufobj, type)} where @var{bufobj} is
3365 the Python @code{bytes} representation of the handle and @var{type} is
3366 a @code{gdb.Type} for the handle type.
3369 @node Recordings In Python
3370 @subsubsection Recordings In Python
3371 @cindex recordings in python
3373 The following recordings-related functions
3374 (@pxref{Process Record and Replay}) are available in the @code{gdb}
3377 @defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
3378 Start a recording using the given @var{method} and @var{format}. If
3379 no @var{format} is given, the default format for the recording method
3380 is used. If no @var{method} is given, the default method will be used.
3381 Returns a @code{gdb.Record} object on success. Throw an exception on
3384 The following strings can be passed as @var{method}:
3390 @code{"btrace"}: Possible values for @var{format}: @code{"pt"},
3391 @code{"bts"} or leave out for default format.
3395 @defun gdb.current_recording ()
3396 Access a currently running recording. Return a @code{gdb.Record}
3397 object on success. Return @code{None} if no recording is currently
3401 @defun gdb.stop_recording ()
3402 Stop the current recording. Throw an exception if no recording is
3403 currently active. All record objects become invalid after this call.
3406 A @code{gdb.Record} object has the following attributes:
3408 @defvar Record.method
3409 A string with the current recording method, e.g.@: @code{full} or
3413 @defvar Record.format
3414 A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
3418 @defvar Record.begin
3419 A method specific instruction object representing the first instruction
3424 A method specific instruction object representing the current
3425 instruction, that is not actually part of the recording.
3428 @defvar Record.replay_position
3429 The instruction representing the current replay position. If there is
3430 no replay active, this will be @code{None}.
3433 @defvar Record.instruction_history
3434 A list with all recorded instructions.
3437 @defvar Record.function_call_history
3438 A list with all recorded function call segments.
3441 A @code{gdb.Record} object has the following methods:
3443 @defun Record.goto (instruction)
3444 Move the replay position to the given @var{instruction}.
3447 The common @code{gdb.Instruction} class that recording method specific
3448 instruction objects inherit from, has the following attributes:
3450 @defvar Instruction.pc
3451 An integer representing this instruction's address.
3454 @defvar Instruction.data
3455 A buffer with the raw instruction data. In Python 3, the return value is a
3456 @code{memoryview} object.
3459 @defvar Instruction.decoded
3460 A human readable string with the disassembled instruction.
3463 @defvar Instruction.size
3464 The size of the instruction in bytes.
3467 Additionally @code{gdb.RecordInstruction} has the following attributes:
3469 @defvar RecordInstruction.number
3470 An integer identifying this instruction. @code{number} corresponds to
3471 the numbers seen in @code{record instruction-history}
3472 (@pxref{Process Record and Replay}).
3475 @defvar RecordInstruction.sal
3476 A @code{gdb.Symtab_and_line} object representing the associated symtab
3477 and line of this instruction. May be @code{None} if no debug information is
3481 @defvar RecordInstruction.is_speculative
3482 A boolean indicating whether the instruction was executed speculatively.
3485 If an error occured during recording or decoding a recording, this error is
3486 represented by a @code{gdb.RecordGap} object in the instruction list. It has
3487 the following attributes:
3489 @defvar RecordGap.number
3490 An integer identifying this gap. @code{number} corresponds to the numbers seen
3491 in @code{record instruction-history} (@pxref{Process Record and Replay}).
3494 @defvar RecordGap.error_code
3495 A numerical representation of the reason for the gap. The value is specific to
3496 the current recording method.
3499 @defvar RecordGap.error_string
3500 A human readable string with the reason for the gap.
3503 A @code{gdb.RecordFunctionSegment} object has the following attributes:
3505 @defvar RecordFunctionSegment.number
3506 An integer identifying this function segment. @code{number} corresponds to
3507 the numbers seen in @code{record function-call-history}
3508 (@pxref{Process Record and Replay}).
3511 @defvar RecordFunctionSegment.symbol
3512 A @code{gdb.Symbol} object representing the associated symbol. May be
3513 @code{None} if no debug information is available.
3516 @defvar RecordFunctionSegment.level
3517 An integer representing the function call's stack level. May be
3518 @code{None} if the function call is a gap.
3521 @defvar RecordFunctionSegment.instructions
3522 A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
3523 associated with this function call.
3526 @defvar RecordFunctionSegment.up
3527 A @code{gdb.RecordFunctionSegment} object representing the caller's
3528 function segment. If the call has not been recorded, this will be the
3529 function segment to which control returns. If neither the call nor the
3530 return have been recorded, this will be @code{None}.
3533 @defvar RecordFunctionSegment.prev
3534 A @code{gdb.RecordFunctionSegment} object representing the previous
3535 segment of this function call. May be @code{None}.
3538 @defvar RecordFunctionSegment.next
3539 A @code{gdb.RecordFunctionSegment} object representing the next segment of
3540 this function call. May be @code{None}.
3543 The following example demonstrates the usage of these objects and
3544 functions to create a function that will rewind a record to the last
3545 time a function in a different file was executed. This would typically
3546 be used to track the execution of user provided callback functions in a
3547 library which typically are not visible in a back trace.
3551 rec = gdb.current_recording ()
3555 insn = rec.instruction_history
3560 position = insn.index (rec.replay_position)
3564 filename = insn[position].sal.symtab.fullname ()
3568 for i in reversed (insn[:position]):
3570 current = i.sal.symtab.fullname ()
3574 if filename == current:
3581 Another possible application is to write a function that counts the
3582 number of code executions in a given line range. This line range can
3583 contain parts of functions or span across several functions and is not
3584 limited to be contiguous.
3587 def countrange (filename, linerange):
3590 def filter_only (file_name):
3591 for call in gdb.current_recording ().function_call_history:
3593 if file_name in call.symbol.symtab.fullname ():
3598 for c in filter_only (filename):
3599 for i in c.instructions:
3601 if i.sal.line in linerange:
3610 @node Commands In Python
3611 @subsubsection Commands In Python
3613 @cindex commands in python
3614 @cindex python commands
3615 You can implement new @value{GDBN} CLI commands in Python. A CLI
3616 command is implemented using an instance of the @code{gdb.Command}
3617 class, most commonly using a subclass.
3619 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
3620 The object initializer for @code{Command} registers the new command
3621 with @value{GDBN}. This initializer is normally invoked from the
3622 subclass' own @code{__init__} method.
3624 @var{name} is the name of the command. If @var{name} consists of
3625 multiple words, then the initial words are looked for as prefix
3626 commands. In this case, if one of the prefix commands does not exist,
3627 an exception is raised.
3629 There is no support for multi-line commands.
3631 @var{command_class} should be one of the @samp{COMMAND_} constants
3632 defined below. This argument tells @value{GDBN} how to categorize the
3633 new command in the help system.
3635 @var{completer_class} is an optional argument. If given, it should be
3636 one of the @samp{COMPLETE_} constants defined below. This argument
3637 tells @value{GDBN} how to perform completion for this command. If not
3638 given, @value{GDBN} will attempt to complete using the object's
3639 @code{complete} method (see below); if no such method is found, an
3640 error will occur when completion is attempted.
3642 @var{prefix} is an optional argument. If @code{True}, then the new
3643 command is a prefix command; sub-commands of this command may be
3646 The help text for the new command is taken from the Python
3647 documentation string for the command's class, if there is one. If no
3648 documentation string is provided, the default value ``This command is
3649 not documented.'' is used.
3652 @cindex don't repeat Python command
3653 @defun Command.dont_repeat ()
3654 By default, a @value{GDBN} command is repeated when the user enters a
3655 blank line at the command prompt. A command can suppress this
3656 behavior by invoking the @code{dont_repeat} method. This is similar
3657 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
3660 @defun Command.invoke (argument, from_tty)
3661 This method is called by @value{GDBN} when this command is invoked.
3663 @var{argument} is a string. It is the argument to the command, after
3664 leading and trailing whitespace has been stripped.
3666 @var{from_tty} is a boolean argument. When true, this means that the
3667 command was entered by the user at the terminal; when false it means
3668 that the command came from elsewhere.
3670 If this method throws an exception, it is turned into a @value{GDBN}
3671 @code{error} call. Otherwise, the return value is ignored.
3673 @findex gdb.string_to_argv
3674 To break @var{argument} up into an argv-like string use
3675 @code{gdb.string_to_argv}. This function behaves identically to
3676 @value{GDBN}'s internal argument lexer @code{buildargv}.
3677 It is recommended to use this for consistency.
3678 Arguments are separated by spaces and may be quoted.
3682 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
3683 ['1', '2 "3', '4 "5', "6 '7"]
3688 @cindex completion of Python commands
3689 @defun Command.complete (text, word)
3690 This method is called by @value{GDBN} when the user attempts
3691 completion on this command. All forms of completion are handled by
3692 this method, that is, the @key{TAB} and @key{M-?} key bindings
3693 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
3696 The arguments @var{text} and @var{word} are both strings; @var{text}
3697 holds the complete command line up to the cursor's location, while
3698 @var{word} holds the last word of the command line; this is computed
3699 using a word-breaking heuristic.
3701 The @code{complete} method can return several values:
3704 If the return value is a sequence, the contents of the sequence are
3705 used as the completions. It is up to @code{complete} to ensure that the
3706 contents actually do complete the word. A zero-length sequence is
3707 allowed, it means that there were no completions available. Only
3708 string elements of the sequence are used; other elements in the
3709 sequence are ignored.
3712 If the return value is one of the @samp{COMPLETE_} constants defined
3713 below, then the corresponding @value{GDBN}-internal completion
3714 function is invoked, and its result is used.
3717 All other results are treated as though there were no available
3722 When a new command is registered, it must be declared as a member of
3723 some general class of commands. This is used to classify top-level
3724 commands in the on-line help system; note that prefix commands are not
3725 listed under their own category but rather that of their top-level
3726 command. The available classifications are represented by constants
3727 defined in the @code{gdb} module:
3730 @findex COMMAND_NONE
3731 @findex gdb.COMMAND_NONE
3732 @item gdb.COMMAND_NONE
3733 The command does not belong to any particular class. A command in
3734 this category will not be displayed in any of the help categories.
3736 @findex COMMAND_RUNNING
3737 @findex gdb.COMMAND_RUNNING
3738 @item gdb.COMMAND_RUNNING
3739 The command is related to running the inferior. For example,
3740 @code{start}, @code{step}, and @code{continue} are in this category.
3741 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
3742 commands in this category.
3744 @findex COMMAND_DATA
3745 @findex gdb.COMMAND_DATA
3746 @item gdb.COMMAND_DATA
3747 The command is related to data or variables. For example,
3748 @code{call}, @code{find}, and @code{print} are in this category. Type
3749 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
3752 @findex COMMAND_STACK
3753 @findex gdb.COMMAND_STACK
3754 @item gdb.COMMAND_STACK
3755 The command has to do with manipulation of the stack. For example,
3756 @code{backtrace}, @code{frame}, and @code{return} are in this
3757 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
3758 list of commands in this category.
3760 @findex COMMAND_FILES
3761 @findex gdb.COMMAND_FILES
3762 @item gdb.COMMAND_FILES
3763 This class is used for file-related commands. For example,
3764 @code{file}, @code{list} and @code{section} are in this category.
3765 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
3766 commands in this category.
3768 @findex COMMAND_SUPPORT
3769 @findex gdb.COMMAND_SUPPORT
3770 @item gdb.COMMAND_SUPPORT
3771 This should be used for ``support facilities'', generally meaning
3772 things that are useful to the user when interacting with @value{GDBN},
3773 but not related to the state of the inferior. For example,
3774 @code{help}, @code{make}, and @code{shell} are in this category. Type
3775 @kbd{help support} at the @value{GDBN} prompt to see a list of
3776 commands in this category.
3778 @findex COMMAND_STATUS
3779 @findex gdb.COMMAND_STATUS
3780 @item gdb.COMMAND_STATUS
3781 The command is an @samp{info}-related command, that is, related to the
3782 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
3783 and @code{show} are in this category. Type @kbd{help status} at the
3784 @value{GDBN} prompt to see a list of commands in this category.
3786 @findex COMMAND_BREAKPOINTS
3787 @findex gdb.COMMAND_BREAKPOINTS
3788 @item gdb.COMMAND_BREAKPOINTS
3789 The command has to do with breakpoints. For example, @code{break},
3790 @code{clear}, and @code{delete} are in this category. Type @kbd{help
3791 breakpoints} at the @value{GDBN} prompt to see a list of commands in
3794 @findex COMMAND_TRACEPOINTS
3795 @findex gdb.COMMAND_TRACEPOINTS
3796 @item gdb.COMMAND_TRACEPOINTS
3797 The command has to do with tracepoints. For example, @code{trace},
3798 @code{actions}, and @code{tfind} are in this category. Type
3799 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
3800 commands in this category.
3802 @findex COMMAND_USER
3803 @findex gdb.COMMAND_USER
3804 @item gdb.COMMAND_USER
3805 The command is a general purpose command for the user, and typically
3806 does not fit in one of the other categories.
3807 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
3808 a list of commands in this category, as well as the list of gdb macros
3809 (@pxref{Sequences}).
3811 @findex COMMAND_OBSCURE
3812 @findex gdb.COMMAND_OBSCURE
3813 @item gdb.COMMAND_OBSCURE
3814 The command is only used in unusual circumstances, or is not of
3815 general interest to users. For example, @code{checkpoint},
3816 @code{fork}, and @code{stop} are in this category. Type @kbd{help
3817 obscure} at the @value{GDBN} prompt to see a list of commands in this
3820 @findex COMMAND_MAINTENANCE
3821 @findex gdb.COMMAND_MAINTENANCE
3822 @item gdb.COMMAND_MAINTENANCE
3823 The command is only useful to @value{GDBN} maintainers. The
3824 @code{maintenance} and @code{flushregs} commands are in this category.
3825 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
3826 commands in this category.
3829 A new command can use a predefined completion function, either by
3830 specifying it via an argument at initialization, or by returning it
3831 from the @code{complete} method. These predefined completion
3832 constants are all defined in the @code{gdb} module:
3835 @vindex COMPLETE_NONE
3836 @item gdb.COMPLETE_NONE
3837 This constant means that no completion should be done.
3839 @vindex COMPLETE_FILENAME
3840 @item gdb.COMPLETE_FILENAME
3841 This constant means that filename completion should be performed.
3843 @vindex COMPLETE_LOCATION
3844 @item gdb.COMPLETE_LOCATION
3845 This constant means that location completion should be done.
3846 @xref{Specify Location}.
3848 @vindex COMPLETE_COMMAND
3849 @item gdb.COMPLETE_COMMAND
3850 This constant means that completion should examine @value{GDBN}
3853 @vindex COMPLETE_SYMBOL
3854 @item gdb.COMPLETE_SYMBOL
3855 This constant means that completion should be done using symbol names
3858 @vindex COMPLETE_EXPRESSION
3859 @item gdb.COMPLETE_EXPRESSION
3860 This constant means that completion should be done on expressions.
3861 Often this means completing on symbol names, but some language
3862 parsers also have support for completing on field names.
3865 The following code snippet shows how a trivial CLI command can be
3866 implemented in Python:
3869 class HelloWorld (gdb.Command):
3870 """Greet the whole world."""
3872 def __init__ (self):
3873 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
3875 def invoke (self, arg, from_tty):
3876 print "Hello, World!"
3881 The last line instantiates the class, and is necessary to trigger the
3882 registration of the command with @value{GDBN}. Depending on how the
3883 Python code is read into @value{GDBN}, you may need to import the
3884 @code{gdb} module explicitly.
3886 @node Parameters In Python
3887 @subsubsection Parameters In Python
3889 @cindex parameters in python
3890 @cindex python parameters
3891 @tindex gdb.Parameter
3893 You can implement new @value{GDBN} parameters using Python. A new
3894 parameter is implemented as an instance of the @code{gdb.Parameter}
3897 Parameters are exposed to the user via the @code{set} and
3898 @code{show} commands. @xref{Help}.
3900 There are many parameters that already exist and can be set in
3901 @value{GDBN}. Two examples are: @code{set follow fork} and
3902 @code{set charset}. Setting these parameters influences certain
3903 behavior in @value{GDBN}. Similarly, you can define parameters that
3904 can be used to influence behavior in custom Python scripts and commands.
3906 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
3907 The object initializer for @code{Parameter} registers the new
3908 parameter with @value{GDBN}. This initializer is normally invoked
3909 from the subclass' own @code{__init__} method.
3911 @var{name} is the name of the new parameter. If @var{name} consists
3912 of multiple words, then the initial words are looked for as prefix
3913 parameters. An example of this can be illustrated with the
3914 @code{set print} set of parameters. If @var{name} is
3915 @code{print foo}, then @code{print} will be searched as the prefix
3916 parameter. In this case the parameter can subsequently be accessed in
3917 @value{GDBN} as @code{set print foo}.
3919 If @var{name} consists of multiple words, and no prefix parameter group
3920 can be found, an exception is raised.
3922 @var{command-class} should be one of the @samp{COMMAND_} constants
3923 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
3924 categorize the new parameter in the help system.
3926 @var{parameter-class} should be one of the @samp{PARAM_} constants
3927 defined below. This argument tells @value{GDBN} the type of the new
3928 parameter; this information is used for input validation and
3931 If @var{parameter-class} is @code{PARAM_ENUM}, then
3932 @var{enum-sequence} must be a sequence of strings. These strings
3933 represent the possible values for the parameter.
3935 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
3936 of a fourth argument will cause an exception to be thrown.
3938 The help text for the new parameter is taken from the Python
3939 documentation string for the parameter's class, if there is one. If
3940 there is no documentation string, a default value is used.
3943 @defvar Parameter.set_doc
3944 If this attribute exists, and is a string, then its value is used as
3945 the help text for this parameter's @code{set} command. The value is
3946 examined when @code{Parameter.__init__} is invoked; subsequent changes
3950 @defvar Parameter.show_doc
3951 If this attribute exists, and is a string, then its value is used as
3952 the help text for this parameter's @code{show} command. The value is
3953 examined when @code{Parameter.__init__} is invoked; subsequent changes
3957 @defvar Parameter.value
3958 The @code{value} attribute holds the underlying value of the
3959 parameter. It can be read and assigned to just as any other
3960 attribute. @value{GDBN} does validation when assignments are made.
3963 There are two methods that may be implemented in any @code{Parameter}
3966 @defun Parameter.get_set_string (self)
3967 If this method exists, @value{GDBN} will call it when a
3968 @var{parameter}'s value has been changed via the @code{set} API (for
3969 example, @kbd{set foo off}). The @code{value} attribute has already
3970 been populated with the new value and may be used in output. This
3971 method must return a string. If the returned string is not empty,
3972 @value{GDBN} will present it to the user.
3974 If this method raises the @code{gdb.GdbError} exception
3975 (@pxref{Exception Handling}), then @value{GDBN} will print the
3976 exception's string and the @code{set} command will fail. Note,
3977 however, that the @code{value} attribute will not be reset in this
3978 case. So, if your parameter must validate values, it should store the
3979 old value internally and reset the exposed value, like so:
3982 class ExampleParam (gdb.Parameter):
3983 def __init__ (self, name):
3984 super (ExampleParam, self).__init__ (name,
3988 self.saved_value = True
3991 def get_set_string (self):
3992 if not self.validate():
3993 self.value = self.saved_value
3994 raise gdb.GdbError('Failed to validate')
3995 self.saved_value = self.value
3999 @defun Parameter.get_show_string (self, svalue)
4000 @value{GDBN} will call this method when a @var{parameter}'s
4001 @code{show} API has been invoked (for example, @kbd{show foo}). The
4002 argument @code{svalue} receives the string representation of the
4003 current value. This method must return a string.
4006 When a new parameter is defined, its type must be specified. The
4007 available types are represented by constants defined in the @code{gdb}
4011 @findex PARAM_BOOLEAN
4012 @findex gdb.PARAM_BOOLEAN
4013 @item gdb.PARAM_BOOLEAN
4014 The value is a plain boolean. The Python boolean values, @code{True}
4015 and @code{False} are the only valid values.
4017 @findex PARAM_AUTO_BOOLEAN
4018 @findex gdb.PARAM_AUTO_BOOLEAN
4019 @item gdb.PARAM_AUTO_BOOLEAN
4020 The value has three possible states: true, false, and @samp{auto}. In
4021 Python, true and false are represented using boolean constants, and
4022 @samp{auto} is represented using @code{None}.
4024 @findex PARAM_UINTEGER
4025 @findex gdb.PARAM_UINTEGER
4026 @item gdb.PARAM_UINTEGER
4027 The value is an unsigned integer. The value of 0 should be
4028 interpreted to mean ``unlimited''.
4030 @findex PARAM_INTEGER
4031 @findex gdb.PARAM_INTEGER
4032 @item gdb.PARAM_INTEGER
4033 The value is a signed integer. The value of 0 should be interpreted
4034 to mean ``unlimited''.
4036 @findex PARAM_STRING
4037 @findex gdb.PARAM_STRING
4038 @item gdb.PARAM_STRING
4039 The value is a string. When the user modifies the string, any escape
4040 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
4041 translated into corresponding characters and encoded into the current
4044 @findex PARAM_STRING_NOESCAPE
4045 @findex gdb.PARAM_STRING_NOESCAPE
4046 @item gdb.PARAM_STRING_NOESCAPE
4047 The value is a string. When the user modifies the string, escapes are
4048 passed through untranslated.
4050 @findex PARAM_OPTIONAL_FILENAME
4051 @findex gdb.PARAM_OPTIONAL_FILENAME
4052 @item gdb.PARAM_OPTIONAL_FILENAME
4053 The value is a either a filename (a string), or @code{None}.
4055 @findex PARAM_FILENAME
4056 @findex gdb.PARAM_FILENAME
4057 @item gdb.PARAM_FILENAME
4058 The value is a filename. This is just like
4059 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
4061 @findex PARAM_ZINTEGER
4062 @findex gdb.PARAM_ZINTEGER
4063 @item gdb.PARAM_ZINTEGER
4064 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
4065 is interpreted as itself.
4067 @findex PARAM_ZUINTEGER
4068 @findex gdb.PARAM_ZUINTEGER
4069 @item gdb.PARAM_ZUINTEGER
4070 The value is an unsigned integer. This is like @code{PARAM_INTEGER},
4071 except 0 is interpreted as itself, and the value cannot be negative.
4073 @findex PARAM_ZUINTEGER_UNLIMITED
4074 @findex gdb.PARAM_ZUINTEGER_UNLIMITED
4075 @item gdb.PARAM_ZUINTEGER_UNLIMITED
4076 The value is a signed integer. This is like @code{PARAM_ZUINTEGER},
4077 except the special value -1 should be interpreted to mean
4078 ``unlimited''. Other negative values are not allowed.
4081 @findex gdb.PARAM_ENUM
4082 @item gdb.PARAM_ENUM
4083 The value is a string, which must be one of a collection string
4084 constants provided when the parameter is created.
4087 @node Functions In Python
4088 @subsubsection Writing new convenience functions
4090 @cindex writing convenience functions
4091 @cindex convenience functions in python
4092 @cindex python convenience functions
4093 @tindex gdb.Function
4095 You can implement new convenience functions (@pxref{Convenience Vars})
4096 in Python. A convenience function is an instance of a subclass of the
4097 class @code{gdb.Function}.
4099 @defun Function.__init__ (name)
4100 The initializer for @code{Function} registers the new function with
4101 @value{GDBN}. The argument @var{name} is the name of the function,
4102 a string. The function will be visible to the user as a convenience
4103 variable of type @code{internal function}, whose name is the same as
4104 the given @var{name}.
4106 The documentation for the new function is taken from the documentation
4107 string for the new class.
4110 @defun Function.invoke (@var{*args})
4111 When a convenience function is evaluated, its arguments are converted
4112 to instances of @code{gdb.Value}, and then the function's
4113 @code{invoke} method is called. Note that @value{GDBN} does not
4114 predetermine the arity of convenience functions. Instead, all
4115 available arguments are passed to @code{invoke}, following the
4116 standard Python calling convention. In particular, a convenience
4117 function can have default values for parameters without ill effect.
4119 The return value of this method is used as its value in the enclosing
4120 expression. If an ordinary Python value is returned, it is converted
4121 to a @code{gdb.Value} following the usual rules.
4124 The following code snippet shows how a trivial convenience function can
4125 be implemented in Python:
4128 class Greet (gdb.Function):
4129 """Return string to greet someone.
4130 Takes a name as argument."""
4132 def __init__ (self):
4133 super (Greet, self).__init__ ("greet")
4135 def invoke (self, name):
4136 return "Hello, %s!" % name.string ()
4141 The last line instantiates the class, and is necessary to trigger the
4142 registration of the function with @value{GDBN}. Depending on how the
4143 Python code is read into @value{GDBN}, you may need to import the
4144 @code{gdb} module explicitly.
4146 Now you can use the function in an expression:
4149 (gdb) print $greet("Bob")
4153 @node Progspaces In Python
4154 @subsubsection Program Spaces In Python
4156 @cindex progspaces in python
4157 @tindex gdb.Progspace
4159 A program space, or @dfn{progspace}, represents a symbolic view
4160 of an address space.
4161 It consists of all of the objfiles of the program.
4162 @xref{Objfiles In Python}.
4163 @xref{Inferiors and Programs, program spaces}, for more details
4164 about program spaces.
4166 The following progspace-related functions are available in the
4169 @findex gdb.current_progspace
4170 @defun gdb.current_progspace ()
4171 This function returns the program space of the currently selected inferior.
4172 @xref{Inferiors and Programs}. This is identical to
4173 @code{gdb.selected_inferior().progspace} (@pxref{Inferiors In Python}) and is
4174 included for historical compatibility.
4177 @findex gdb.progspaces
4178 @defun gdb.progspaces ()
4179 Return a sequence of all the progspaces currently known to @value{GDBN}.
4182 Each progspace is represented by an instance of the @code{gdb.Progspace}
4185 @defvar Progspace.filename
4186 The file name of the progspace as a string.
4189 @defvar Progspace.pretty_printers
4190 The @code{pretty_printers} attribute is a list of functions. It is
4191 used to look up pretty-printers. A @code{Value} is passed to each
4192 function in order; if the function returns @code{None}, then the
4193 search continues. Otherwise, the return value should be an object
4194 which is used to format the value. @xref{Pretty Printing API}, for more
4198 @defvar Progspace.type_printers
4199 The @code{type_printers} attribute is a list of type printer objects.
4200 @xref{Type Printing API}, for more information.
4203 @defvar Progspace.frame_filters
4204 The @code{frame_filters} attribute is a dictionary of frame filter
4205 objects. @xref{Frame Filter API}, for more information.
4208 A program space has the following methods:
4210 @findex Progspace.block_for_pc
4211 @defun Progspace.block_for_pc (pc)
4212 Return the innermost @code{gdb.Block} containing the given @var{pc}
4213 value. If the block cannot be found for the @var{pc} value specified,
4214 the function will return @code{None}.
4217 @findex Progspace.find_pc_line
4218 @defun Progspace.find_pc_line (pc)
4219 Return the @code{gdb.Symtab_and_line} object corresponding to the
4220 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid value
4221 of @var{pc} is passed as an argument, then the @code{symtab} and
4222 @code{line} attributes of the returned @code{gdb.Symtab_and_line}
4223 object will be @code{None} and 0 respectively.
4226 @findex Progspace.is_valid
4227 @defun Progspace.is_valid ()
4228 Returns @code{True} if the @code{gdb.Progspace} object is valid,
4229 @code{False} if not. A @code{gdb.Progspace} object can become invalid
4230 if the program space file it refers to is not referenced by any
4231 inferior. All other @code{gdb.Progspace} methods will throw an
4232 exception if it is invalid at the time the method is called.
4235 @findex Progspace.objfiles
4236 @defun Progspace.objfiles ()
4237 Return a sequence of all the objfiles referenced by this program
4238 space. @xref{Objfiles In Python}.
4241 @findex Progspace.solib_name
4242 @defun Progspace.solib_name (address)
4243 Return the name of the shared library holding the given @var{address}
4244 as a string, or @code{None}.
4247 One may add arbitrary attributes to @code{gdb.Progspace} objects
4248 in the usual Python way.
4249 This is useful if, for example, one needs to do some extra record keeping
4250 associated with the program space.
4252 In this contrived example, we want to perform some processing when
4253 an objfile with a certain symbol is loaded, but we only want to do
4254 this once because it is expensive. To achieve this we record the results
4255 with the program space because we can't predict when the desired objfile
4260 def clear_objfiles_handler(event):
4261 event.progspace.expensive_computation = None
4262 def expensive(symbol):
4263 """A mock routine to perform an "expensive" computation on symbol."""
4264 print "Computing the answer to the ultimate question ..."
4266 def new_objfile_handler(event):
4267 objfile = event.new_objfile
4268 progspace = objfile.progspace
4269 if not hasattr(progspace, 'expensive_computation') or \
4270 progspace.expensive_computation is None:
4271 # We use 'main' for the symbol to keep the example simple.
4272 # Note: There's no current way to constrain the lookup
4274 symbol = gdb.lookup_global_symbol('main')
4275 if symbol is not None:
4276 progspace.expensive_computation = expensive(symbol)
4277 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
4278 gdb.events.new_objfile.connect(new_objfile_handler)
4280 (gdb) file /tmp/hello
4281 Reading symbols from /tmp/hello...done.
4282 Computing the answer to the ultimate question ...
4283 (gdb) python print gdb.current_progspace().expensive_computation
4286 Starting program: /tmp/hello
4288 [Inferior 1 (process 4242) exited normally]
4291 @node Objfiles In Python
4292 @subsubsection Objfiles In Python
4294 @cindex objfiles in python
4297 @value{GDBN} loads symbols for an inferior from various
4298 symbol-containing files (@pxref{Files}). These include the primary
4299 executable file, any shared libraries used by the inferior, and any
4300 separate debug info files (@pxref{Separate Debug Files}).
4301 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
4303 The following objfile-related functions are available in the
4306 @findex gdb.current_objfile
4307 @defun gdb.current_objfile ()
4308 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
4309 sets the ``current objfile'' to the corresponding objfile. This
4310 function returns the current objfile. If there is no current objfile,
4311 this function returns @code{None}.
4314 @findex gdb.objfiles
4315 @defun gdb.objfiles ()
4316 Return a sequence of objfiles referenced by the current program space.
4317 @xref{Objfiles In Python}, and @ref{Progspaces In Python}. This is identical
4318 to @code{gdb.selected_inferior().progspace.objfiles()} and is included for
4319 historical compatibility.
4322 @findex gdb.lookup_objfile
4323 @defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
4324 Look up @var{name}, a file name or build ID, in the list of objfiles
4325 for the current program space (@pxref{Progspaces In Python}).
4326 If the objfile is not found throw the Python @code{ValueError} exception.
4328 If @var{name} is a relative file name, then it will match any
4329 source file name with the same trailing components. For example, if
4330 @var{name} is @samp{gcc/expr.c}, then it will match source file
4331 name of @file{/build/trunk/gcc/expr.c}, but not
4332 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
4334 If @var{by_build_id} is provided and is @code{True} then @var{name}
4335 is the build ID of the objfile. Otherwise, @var{name} is a file name.
4336 This is supported only on some operating systems, notably those which use
4337 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4338 about this feature, see the description of the @option{--build-id}
4339 command-line option in @ref{Options, , Command Line Options, ld,
4343 Each objfile is represented by an instance of the @code{gdb.Objfile}
4346 @defvar Objfile.filename
4347 The file name of the objfile as a string, with symbolic links resolved.
4349 The value is @code{None} if the objfile is no longer valid.
4350 See the @code{gdb.Objfile.is_valid} method, described below.
4353 @defvar Objfile.username
4354 The file name of the objfile as specified by the user as a string.
4356 The value is @code{None} if the objfile is no longer valid.
4357 See the @code{gdb.Objfile.is_valid} method, described below.
4360 @defvar Objfile.owner
4361 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
4362 object that debug info is being provided for.
4363 Otherwise this is @code{None}.
4364 Separate debug info objfiles are added with the
4365 @code{gdb.Objfile.add_separate_debug_file} method, described below.
4368 @defvar Objfile.build_id
4369 The build ID of the objfile as a string.
4370 If the objfile does not have a build ID then the value is @code{None}.
4372 This is supported only on some operating systems, notably those which use
4373 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4374 about this feature, see the description of the @option{--build-id}
4375 command-line option in @ref{Options, , Command Line Options, ld,
4379 @defvar Objfile.progspace
4380 The containing program space of the objfile as a @code{gdb.Progspace}
4381 object. @xref{Progspaces In Python}.
4384 @defvar Objfile.pretty_printers
4385 The @code{pretty_printers} attribute is a list of functions. It is
4386 used to look up pretty-printers. A @code{Value} is passed to each
4387 function in order; if the function returns @code{None}, then the
4388 search continues. Otherwise, the return value should be an object
4389 which is used to format the value. @xref{Pretty Printing API}, for more
4393 @defvar Objfile.type_printers
4394 The @code{type_printers} attribute is a list of type printer objects.
4395 @xref{Type Printing API}, for more information.
4398 @defvar Objfile.frame_filters
4399 The @code{frame_filters} attribute is a dictionary of frame filter
4400 objects. @xref{Frame Filter API}, for more information.
4403 One may add arbitrary attributes to @code{gdb.Objfile} objects
4404 in the usual Python way.
4405 This is useful if, for example, one needs to do some extra record keeping
4406 associated with the objfile.
4408 In this contrived example we record the time when @value{GDBN}
4414 def new_objfile_handler(event):
4415 # Set the time_loaded attribute of the new objfile.
4416 event.new_objfile.time_loaded = datetime.datetime.today()
4417 gdb.events.new_objfile.connect(new_objfile_handler)
4420 Reading symbols from ./hello...done.
4421 (gdb) python print gdb.objfiles()[0].time_loaded
4422 2014-10-09 11:41:36.770345
4425 A @code{gdb.Objfile} object has the following methods:
4427 @defun Objfile.is_valid ()
4428 Returns @code{True} if the @code{gdb.Objfile} object is valid,
4429 @code{False} if not. A @code{gdb.Objfile} object can become invalid
4430 if the object file it refers to is not loaded in @value{GDBN} any
4431 longer. All other @code{gdb.Objfile} methods will throw an exception
4432 if it is invalid at the time the method is called.
4435 @defun Objfile.add_separate_debug_file (file)
4436 Add @var{file} to the list of files that @value{GDBN} will search for
4437 debug information for the objfile.
4438 This is useful when the debug info has been removed from the program
4439 and stored in a separate file. @value{GDBN} has built-in support for
4440 finding separate debug info files (@pxref{Separate Debug Files}), but if
4441 the file doesn't live in one of the standard places that @value{GDBN}
4442 searches then this function can be used to add a debug info file
4443 from a different place.
4446 @node Frames In Python
4447 @subsubsection Accessing inferior stack frames from Python
4449 @cindex frames in python
4450 When the debugged program stops, @value{GDBN} is able to analyze its call
4451 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
4452 represents a frame in the stack. A @code{gdb.Frame} object is only valid
4453 while its corresponding frame exists in the inferior's stack. If you try
4454 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
4455 exception (@pxref{Exception Handling}).
4457 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
4461 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
4465 The following frame-related functions are available in the @code{gdb} module:
4467 @findex gdb.selected_frame
4468 @defun gdb.selected_frame ()
4469 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
4472 @findex gdb.newest_frame
4473 @defun gdb.newest_frame ()
4474 Return the newest frame object for the selected thread.
4477 @defun gdb.frame_stop_reason_string (reason)
4478 Return a string explaining the reason why @value{GDBN} stopped unwinding
4479 frames, as expressed by the given @var{reason} code (an integer, see the
4480 @code{unwind_stop_reason} method further down in this section).
4483 @findex gdb.invalidate_cached_frames
4484 @defun gdb.invalidate_cached_frames
4485 @value{GDBN} internally keeps a cache of the frames that have been
4486 unwound. This function invalidates this cache.
4488 This function should not generally be called by ordinary Python code.
4489 It is documented for the sake of completeness.
4492 A @code{gdb.Frame} object has the following methods:
4494 @defun Frame.is_valid ()
4495 Returns true if the @code{gdb.Frame} object is valid, false if not.
4496 A frame object can become invalid if the frame it refers to doesn't
4497 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
4498 an exception if it is invalid at the time the method is called.
4501 @defun Frame.name ()
4502 Returns the function name of the frame, or @code{None} if it can't be
4506 @defun Frame.architecture ()
4507 Returns the @code{gdb.Architecture} object corresponding to the frame's
4508 architecture. @xref{Architectures In Python}.
4511 @defun Frame.type ()
4512 Returns the type of the frame. The value can be one of:
4514 @item gdb.NORMAL_FRAME
4515 An ordinary stack frame.
4517 @item gdb.DUMMY_FRAME
4518 A fake stack frame that was created by @value{GDBN} when performing an
4519 inferior function call.
4521 @item gdb.INLINE_FRAME
4522 A frame representing an inlined function. The function was inlined
4523 into a @code{gdb.NORMAL_FRAME} that is older than this one.
4525 @item gdb.TAILCALL_FRAME
4526 A frame representing a tail call. @xref{Tail Call Frames}.
4528 @item gdb.SIGTRAMP_FRAME
4529 A signal trampoline frame. This is the frame created by the OS when
4530 it calls into a signal handler.
4532 @item gdb.ARCH_FRAME
4533 A fake stack frame representing a cross-architecture call.
4535 @item gdb.SENTINEL_FRAME
4536 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
4541 @defun Frame.unwind_stop_reason ()
4542 Return an integer representing the reason why it's not possible to find
4543 more frames toward the outermost frame. Use
4544 @code{gdb.frame_stop_reason_string} to convert the value returned by this
4545 function to a string. The value can be one of:
4548 @item gdb.FRAME_UNWIND_NO_REASON
4549 No particular reason (older frames should be available).
4551 @item gdb.FRAME_UNWIND_NULL_ID
4552 The previous frame's analyzer returns an invalid result. This is no
4553 longer used by @value{GDBN}, and is kept only for backward
4556 @item gdb.FRAME_UNWIND_OUTERMOST
4557 This frame is the outermost.
4559 @item gdb.FRAME_UNWIND_UNAVAILABLE
4560 Cannot unwind further, because that would require knowing the
4561 values of registers or memory that have not been collected.
4563 @item gdb.FRAME_UNWIND_INNER_ID
4564 This frame ID looks like it ought to belong to a NEXT frame,
4565 but we got it for a PREV frame. Normally, this is a sign of
4566 unwinder failure. It could also indicate stack corruption.
4568 @item gdb.FRAME_UNWIND_SAME_ID
4569 This frame has the same ID as the previous one. That means
4570 that unwinding further would almost certainly give us another
4571 frame with exactly the same ID, so break the chain. Normally,
4572 this is a sign of unwinder failure. It could also indicate
4575 @item gdb.FRAME_UNWIND_NO_SAVED_PC
4576 The frame unwinder did not find any saved PC, but we needed
4577 one to unwind further.
4579 @item gdb.FRAME_UNWIND_MEMORY_ERROR
4580 The frame unwinder caused an error while trying to access memory.
4582 @item gdb.FRAME_UNWIND_FIRST_ERROR
4583 Any stop reason greater or equal to this value indicates some kind
4584 of error. This special value facilitates writing code that tests
4585 for errors in unwinding in a way that will work correctly even if
4586 the list of the other values is modified in future @value{GDBN}
4587 versions. Using it, you could write:
4589 reason = gdb.selected_frame().unwind_stop_reason ()
4590 reason_str = gdb.frame_stop_reason_string (reason)
4591 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
4592 print "An error occured: %s" % reason_str
4599 Returns the frame's resume address.
4602 @defun Frame.block ()
4603 Return the frame's code block. @xref{Blocks In Python}. If the frame
4604 does not have a block -- for example, if there is no debugging
4605 information for the code in question -- then this will throw an
4609 @defun Frame.function ()
4610 Return the symbol for the function corresponding to this frame.
4611 @xref{Symbols In Python}.
4614 @defun Frame.older ()
4615 Return the frame that called this frame.
4618 @defun Frame.newer ()
4619 Return the frame called by this frame.
4622 @defun Frame.find_sal ()
4623 Return the frame's symtab and line object.
4624 @xref{Symbol Tables In Python}.
4627 @defun Frame.read_register (register)
4628 Return the value of @var{register} in this frame. The @var{register}
4629 argument must be a string (e.g., @code{'sp'} or @code{'rax'}).
4630 Returns a @code{Gdb.Value} object. Throws an exception if @var{register}
4634 @defun Frame.read_var (variable @r{[}, block@r{]})
4635 Return the value of @var{variable} in this frame. If the optional
4636 argument @var{block} is provided, search for the variable from that
4637 block; otherwise start at the frame's current block (which is
4638 determined by the frame's current program counter). The @var{variable}
4639 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
4640 @code{gdb.Block} object.
4643 @defun Frame.select ()
4644 Set this frame to be the selected frame. @xref{Stack, ,Examining the
4648 @node Blocks In Python
4649 @subsubsection Accessing blocks from Python
4651 @cindex blocks in python
4654 In @value{GDBN}, symbols are stored in blocks. A block corresponds
4655 roughly to a scope in the source code. Blocks are organized
4656 hierarchically, and are represented individually in Python as a
4657 @code{gdb.Block}. Blocks rely on debugging information being
4660 A frame has a block. Please see @ref{Frames In Python}, for a more
4661 in-depth discussion of frames.
4663 The outermost block is known as the @dfn{global block}. The global
4664 block typically holds public global variables and functions.
4666 The block nested just inside the global block is the @dfn{static
4667 block}. The static block typically holds file-scoped variables and
4670 @value{GDBN} provides a method to get a block's superblock, but there
4671 is currently no way to examine the sub-blocks of a block, or to
4672 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
4675 Here is a short example that should help explain blocks:
4678 /* This is in the global block. */
4681 /* This is in the static block. */
4682 static int file_scope;
4684 /* 'function' is in the global block, and 'argument' is
4685 in a block nested inside of 'function'. */
4686 int function (int argument)
4688 /* 'local' is in a block inside 'function'. It may or may
4689 not be in the same block as 'argument'. */
4693 /* 'inner' is in a block whose superblock is the one holding
4697 /* If this call is expanded by the compiler, you may see
4698 a nested block here whose function is 'inline_function'
4699 and whose superblock is the one holding 'inner'. */
4705 A @code{gdb.Block} is iterable. The iterator returns the symbols
4706 (@pxref{Symbols In Python}) local to the block. Python programs
4707 should not assume that a specific block object will always contain a
4708 given symbol, since changes in @value{GDBN} features and
4709 infrastructure may cause symbols move across blocks in a symbol
4712 The following block-related functions are available in the @code{gdb}
4715 @findex gdb.block_for_pc
4716 @defun gdb.block_for_pc (pc)
4717 Return the innermost @code{gdb.Block} containing the given @var{pc}
4718 value. If the block cannot be found for the @var{pc} value specified,
4719 the function will return @code{None}. This is identical to
4720 @code{gdb.current_progspace().block_for_pc(pc)} and is included for
4721 historical compatibility.
4724 A @code{gdb.Block} object has the following methods:
4726 @defun Block.is_valid ()
4727 Returns @code{True} if the @code{gdb.Block} object is valid,
4728 @code{False} if not. A block object can become invalid if the block it
4729 refers to doesn't exist anymore in the inferior. All other
4730 @code{gdb.Block} methods will throw an exception if it is invalid at
4731 the time the method is called. The block's validity is also checked
4732 during iteration over symbols of the block.
4735 A @code{gdb.Block} object has the following attributes:
4738 The start address of the block. This attribute is not writable.
4742 One past the last address that appears in the block. This attribute
4746 @defvar Block.function
4747 The name of the block represented as a @code{gdb.Symbol}. If the
4748 block is not named, then this attribute holds @code{None}. This
4749 attribute is not writable.
4751 For ordinary function blocks, the superblock is the static block.
4752 However, you should note that it is possible for a function block to
4753 have a superblock that is not the static block -- for instance this
4754 happens for an inlined function.
4757 @defvar Block.superblock
4758 The block containing this block. If this parent block does not exist,
4759 this attribute holds @code{None}. This attribute is not writable.
4762 @defvar Block.global_block
4763 The global block associated with this block. This attribute is not
4767 @defvar Block.static_block
4768 The static block associated with this block. This attribute is not
4772 @defvar Block.is_global
4773 @code{True} if the @code{gdb.Block} object is a global block,
4774 @code{False} if not. This attribute is not
4778 @defvar Block.is_static
4779 @code{True} if the @code{gdb.Block} object is a static block,
4780 @code{False} if not. This attribute is not writable.
4783 @node Symbols In Python
4784 @subsubsection Python representation of Symbols
4786 @cindex symbols in python
4789 @value{GDBN} represents every variable, function and type as an
4790 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
4791 Similarly, Python represents these symbols in @value{GDBN} with the
4792 @code{gdb.Symbol} object.
4794 The following symbol-related functions are available in the @code{gdb}
4797 @findex gdb.lookup_symbol
4798 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
4799 This function searches for a symbol by name. The search scope can be
4800 restricted to the parameters defined in the optional domain and block
4803 @var{name} is the name of the symbol. It must be a string. The
4804 optional @var{block} argument restricts the search to symbols visible
4805 in that @var{block}. The @var{block} argument must be a
4806 @code{gdb.Block} object. If omitted, the block for the current frame
4807 is used. The optional @var{domain} argument restricts
4808 the search to the domain type. The @var{domain} argument must be a
4809 domain constant defined in the @code{gdb} module and described later
4812 The result is a tuple of two elements.
4813 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
4815 If the symbol is found, the second element is @code{True} if the symbol
4816 is a field of a method's object (e.g., @code{this} in C@t{++}),
4817 otherwise it is @code{False}.
4818 If the symbol is not found, the second element is @code{False}.
4821 @findex gdb.lookup_global_symbol
4822 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
4823 This function searches for a global symbol by name.
4824 The search scope can be restricted to by the domain argument.
4826 @var{name} is the name of the symbol. It must be a string.
4827 The optional @var{domain} argument restricts the search to the domain type.
4828 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4829 module and described later in this chapter.
4831 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4835 A @code{gdb.Symbol} object has the following attributes:
4838 The type of the symbol or @code{None} if no type is recorded.
4839 This attribute is represented as a @code{gdb.Type} object.
4840 @xref{Types In Python}. This attribute is not writable.
4843 @defvar Symbol.symtab
4844 The symbol table in which the symbol appears. This attribute is
4845 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
4846 Python}. This attribute is not writable.
4850 The line number in the source code at which the symbol was defined.
4855 The name of the symbol as a string. This attribute is not writable.
4858 @defvar Symbol.linkage_name
4859 The name of the symbol, as used by the linker (i.e., may be mangled).
4860 This attribute is not writable.
4863 @defvar Symbol.print_name
4864 The name of the symbol in a form suitable for output. This is either
4865 @code{name} or @code{linkage_name}, depending on whether the user
4866 asked @value{GDBN} to display demangled or mangled names.
4869 @defvar Symbol.addr_class
4870 The address class of the symbol. This classifies how to find the value
4871 of a symbol. Each address class is a constant defined in the
4872 @code{gdb} module and described later in this chapter.
4875 @defvar Symbol.needs_frame
4876 This is @code{True} if evaluating this symbol's value requires a frame
4877 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
4878 local variables will require a frame, but other symbols will not.
4881 @defvar Symbol.is_argument
4882 @code{True} if the symbol is an argument of a function.
4885 @defvar Symbol.is_constant
4886 @code{True} if the symbol is a constant.
4889 @defvar Symbol.is_function
4890 @code{True} if the symbol is a function or a method.
4893 @defvar Symbol.is_variable
4894 @code{True} if the symbol is a variable.
4897 A @code{gdb.Symbol} object has the following methods:
4899 @defun Symbol.is_valid ()
4900 Returns @code{True} if the @code{gdb.Symbol} object is valid,
4901 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
4902 the symbol it refers to does not exist in @value{GDBN} any longer.
4903 All other @code{gdb.Symbol} methods will throw an exception if it is
4904 invalid at the time the method is called.
4907 @defun Symbol.value (@r{[}frame@r{]})
4908 Compute the value of the symbol, as a @code{gdb.Value}. For
4909 functions, this computes the address of the function, cast to the
4910 appropriate type. If the symbol requires a frame in order to compute
4911 its value, then @var{frame} must be given. If @var{frame} is not
4912 given, or if @var{frame} is invalid, then this method will throw an
4916 The available domain categories in @code{gdb.Symbol} are represented
4917 as constants in the @code{gdb} module:
4920 @vindex SYMBOL_UNDEF_DOMAIN
4921 @item gdb.SYMBOL_UNDEF_DOMAIN
4922 This is used when a domain has not been discovered or none of the
4923 following domains apply. This usually indicates an error either
4924 in the symbol information or in @value{GDBN}'s handling of symbols.
4926 @vindex SYMBOL_VAR_DOMAIN
4927 @item gdb.SYMBOL_VAR_DOMAIN
4928 This domain contains variables, function names, typedef names and enum
4931 @vindex SYMBOL_STRUCT_DOMAIN
4932 @item gdb.SYMBOL_STRUCT_DOMAIN
4933 This domain holds struct, union and enum type names.
4935 @vindex SYMBOL_LABEL_DOMAIN
4936 @item gdb.SYMBOL_LABEL_DOMAIN
4937 This domain contains names of labels (for gotos).
4939 @vindex SYMBOL_MODULE_DOMAIN
4940 @item gdb.SYMBOL_MODULE_DOMAIN
4941 This domain contains names of Fortran module types.
4943 @vindex SYMBOL_COMMON_BLOCK_DOMAIN
4944 @item gdb.SYMBOL_COMMON_BLOCK_DOMAIN
4945 This domain contains names of Fortran common blocks.
4948 The available address class categories in @code{gdb.Symbol} are represented
4949 as constants in the @code{gdb} module:
4952 @vindex SYMBOL_LOC_UNDEF
4953 @item gdb.SYMBOL_LOC_UNDEF
4954 If this is returned by address class, it indicates an error either in
4955 the symbol information or in @value{GDBN}'s handling of symbols.
4957 @vindex SYMBOL_LOC_CONST
4958 @item gdb.SYMBOL_LOC_CONST
4959 Value is constant int.
4961 @vindex SYMBOL_LOC_STATIC
4962 @item gdb.SYMBOL_LOC_STATIC
4963 Value is at a fixed address.
4965 @vindex SYMBOL_LOC_REGISTER
4966 @item gdb.SYMBOL_LOC_REGISTER
4967 Value is in a register.
4969 @vindex SYMBOL_LOC_ARG
4970 @item gdb.SYMBOL_LOC_ARG
4971 Value is an argument. This value is at the offset stored within the
4972 symbol inside the frame's argument list.
4974 @vindex SYMBOL_LOC_REF_ARG
4975 @item gdb.SYMBOL_LOC_REF_ARG
4976 Value address is stored in the frame's argument list. Just like
4977 @code{LOC_ARG} except that the value's address is stored at the
4978 offset, not the value itself.
4980 @vindex SYMBOL_LOC_REGPARM_ADDR
4981 @item gdb.SYMBOL_LOC_REGPARM_ADDR
4982 Value is a specified register. Just like @code{LOC_REGISTER} except
4983 the register holds the address of the argument instead of the argument
4986 @vindex SYMBOL_LOC_LOCAL
4987 @item gdb.SYMBOL_LOC_LOCAL
4988 Value is a local variable.
4990 @vindex SYMBOL_LOC_TYPEDEF
4991 @item gdb.SYMBOL_LOC_TYPEDEF
4992 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
4995 @vindex SYMBOL_LOC_BLOCK
4996 @item gdb.SYMBOL_LOC_BLOCK
4999 @vindex SYMBOL_LOC_CONST_BYTES
5000 @item gdb.SYMBOL_LOC_CONST_BYTES
5001 Value is a byte-sequence.
5003 @vindex SYMBOL_LOC_UNRESOLVED
5004 @item gdb.SYMBOL_LOC_UNRESOLVED
5005 Value is at a fixed address, but the address of the variable has to be
5006 determined from the minimal symbol table whenever the variable is
5009 @vindex SYMBOL_LOC_OPTIMIZED_OUT
5010 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
5011 The value does not actually exist in the program.
5013 @vindex SYMBOL_LOC_COMPUTED
5014 @item gdb.SYMBOL_LOC_COMPUTED
5015 The value's address is a computed location.
5017 @vindex SYMBOL_LOC_COMPUTED
5018 @item gdb.SYMBOL_LOC_COMPUTED
5019 The value's address is a symbol. This is only used for Fortran common
5023 @node Symbol Tables In Python
5024 @subsubsection Symbol table representation in Python
5026 @cindex symbol tables in python
5028 @tindex gdb.Symtab_and_line
5030 Access to symbol table data maintained by @value{GDBN} on the inferior
5031 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
5032 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
5033 from the @code{find_sal} method in @code{gdb.Frame} object.
5034 @xref{Frames In Python}.
5036 For more information on @value{GDBN}'s symbol table management, see
5037 @ref{Symbols, ,Examining the Symbol Table}, for more information.
5039 A @code{gdb.Symtab_and_line} object has the following attributes:
5041 @defvar Symtab_and_line.symtab
5042 The symbol table object (@code{gdb.Symtab}) for this frame.
5043 This attribute is not writable.
5046 @defvar Symtab_and_line.pc
5047 Indicates the start of the address range occupied by code for the
5048 current source line. This attribute is not writable.
5051 @defvar Symtab_and_line.last
5052 Indicates the end of the address range occupied by code for the current
5053 source line. This attribute is not writable.
5056 @defvar Symtab_and_line.line
5057 Indicates the current line number for this object. This
5058 attribute is not writable.
5061 A @code{gdb.Symtab_and_line} object has the following methods:
5063 @defun Symtab_and_line.is_valid ()
5064 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
5065 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
5066 invalid if the Symbol table and line object it refers to does not
5067 exist in @value{GDBN} any longer. All other
5068 @code{gdb.Symtab_and_line} methods will throw an exception if it is
5069 invalid at the time the method is called.
5072 A @code{gdb.Symtab} object has the following attributes:
5074 @defvar Symtab.filename
5075 The symbol table's source filename. This attribute is not writable.
5078 @defvar Symtab.objfile
5079 The symbol table's backing object file. @xref{Objfiles In Python}.
5080 This attribute is not writable.
5083 @defvar Symtab.producer
5084 The name and possibly version number of the program that
5085 compiled the code in the symbol table.
5086 The contents of this string is up to the compiler.
5087 If no producer information is available then @code{None} is returned.
5088 This attribute is not writable.
5091 A @code{gdb.Symtab} object has the following methods:
5093 @defun Symtab.is_valid ()
5094 Returns @code{True} if the @code{gdb.Symtab} object is valid,
5095 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
5096 the symbol table it refers to does not exist in @value{GDBN} any
5097 longer. All other @code{gdb.Symtab} methods will throw an exception
5098 if it is invalid at the time the method is called.
5101 @defun Symtab.fullname ()
5102 Return the symbol table's source absolute file name.
5105 @defun Symtab.global_block ()
5106 Return the global block of the underlying symbol table.
5107 @xref{Blocks In Python}.
5110 @defun Symtab.static_block ()
5111 Return the static block of the underlying symbol table.
5112 @xref{Blocks In Python}.
5115 @defun Symtab.linetable ()
5116 Return the line table associated with the symbol table.
5117 @xref{Line Tables In Python}.
5120 @node Line Tables In Python
5121 @subsubsection Manipulating line tables using Python
5123 @cindex line tables in python
5124 @tindex gdb.LineTable
5126 Python code can request and inspect line table information from a
5127 symbol table that is loaded in @value{GDBN}. A line table is a
5128 mapping of source lines to their executable locations in memory. To
5129 acquire the line table information for a particular symbol table, use
5130 the @code{linetable} function (@pxref{Symbol Tables In Python}).
5132 A @code{gdb.LineTable} is iterable. The iterator returns
5133 @code{LineTableEntry} objects that correspond to the source line and
5134 address for each line table entry. @code{LineTableEntry} objects have
5135 the following attributes:
5137 @defvar LineTableEntry.line
5138 The source line number for this line table entry. This number
5139 corresponds to the actual line of source. This attribute is not
5143 @defvar LineTableEntry.pc
5144 The address that is associated with the line table entry where the
5145 executable code for that source line resides in memory. This
5146 attribute is not writable.
5149 As there can be multiple addresses for a single source line, you may
5150 receive multiple @code{LineTableEntry} objects with matching
5151 @code{line} attributes, but with different @code{pc} attributes. The
5152 iterator is sorted in ascending @code{pc} order. Here is a small
5153 example illustrating iterating over a line table.
5156 symtab = gdb.selected_frame().find_sal().symtab
5157 linetable = symtab.linetable()
5158 for line in linetable:
5159 print "Line: "+str(line.line)+" Address: "+hex(line.pc)
5162 This will have the following output:
5165 Line: 33 Address: 0x4005c8L
5166 Line: 37 Address: 0x4005caL
5167 Line: 39 Address: 0x4005d2L
5168 Line: 40 Address: 0x4005f8L
5169 Line: 42 Address: 0x4005ffL
5170 Line: 44 Address: 0x400608L
5171 Line: 42 Address: 0x40060cL
5172 Line: 45 Address: 0x400615L
5175 In addition to being able to iterate over a @code{LineTable}, it also
5176 has the following direct access methods:
5178 @defun LineTable.line (line)
5179 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
5180 entries in the line table for the given @var{line}, which specifies
5181 the source code line. If there are no entries for that source code
5182 @var{line}, the Python @code{None} is returned.
5185 @defun LineTable.has_line (line)
5186 Return a Python @code{Boolean} indicating whether there is an entry in
5187 the line table for this source line. Return @code{True} if an entry
5188 is found, or @code{False} if not.
5191 @defun LineTable.source_lines ()
5192 Return a Python @code{List} of the source line numbers in the symbol
5193 table. Only lines with executable code locations are returned. The
5194 contents of the @code{List} will just be the source line entries
5195 represented as Python @code{Long} values.
5198 @node Breakpoints In Python
5199 @subsubsection Manipulating breakpoints using Python
5201 @cindex breakpoints in python
5202 @tindex gdb.Breakpoint
5204 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
5207 A breakpoint can be created using one of the two forms of the
5208 @code{gdb.Breakpoint} constructor. The first one accepts a string
5209 like one would pass to the @code{break}
5210 (@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
5211 (@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
5212 create both breakpoints and watchpoints. The second accepts separate Python
5213 arguments similar to @ref{Explicit Locations}, and can only be used to create
5216 @defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]})
5217 Create a new breakpoint according to @var{spec}, which is a string naming the
5218 location of a breakpoint, or an expression that defines a watchpoint. The
5219 string should describe a location in a format recognized by the @code{break}
5220 command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
5221 watchpoint, by the @code{watch} command
5222 (@pxref{Set Watchpoints, , Setting Watchpoints}).
5224 The optional @var{type} argument specifies the type of the breakpoint to create,
5227 The optional @var{wp_class} argument defines the class of watchpoint to create,
5228 if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
5229 defaults to @code{gdb.WP_WRITE}.
5231 The optional @var{internal} argument allows the breakpoint to become invisible
5232 to the user. The breakpoint will neither be reported when created, nor will it
5233 be listed in the output from @code{info breakpoints} (but will be listed with
5234 the @code{maint info breakpoints} command).
5236 The optional @var{temporary} argument makes the breakpoint a temporary
5237 breakpoint. Temporary breakpoints are deleted after they have been hit. Any
5238 further access to the Python breakpoint after it has been hit will result in a
5239 runtime error (as that breakpoint has now been automatically deleted).
5241 The optional @var{qualified} argument is a boolean that allows interpreting
5242 the function passed in @code{spec} as a fully-qualified name. It is equivalent
5243 to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
5244 @ref{Explicit Locations}).
5248 @defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]})
5249 This second form of creating a new breakpoint specifies the explicit
5250 location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
5251 be created in the specified source file @var{source}, at the specified
5252 @var{function}, @var{label} and @var{line}.
5254 @var{internal}, @var{temporary} and @var{qualified} have the same usage as
5255 explained previously.
5258 The available types are represented by constants defined in the @code{gdb}
5262 @vindex BP_BREAKPOINT
5263 @item gdb.BP_BREAKPOINT
5264 Normal code breakpoint.
5266 @vindex BP_WATCHPOINT
5267 @item gdb.BP_WATCHPOINT
5268 Watchpoint breakpoint.
5270 @vindex BP_HARDWARE_WATCHPOINT
5271 @item gdb.BP_HARDWARE_WATCHPOINT
5272 Hardware assisted watchpoint.
5274 @vindex BP_READ_WATCHPOINT
5275 @item gdb.BP_READ_WATCHPOINT
5276 Hardware assisted read watchpoint.
5278 @vindex BP_ACCESS_WATCHPOINT
5279 @item gdb.BP_ACCESS_WATCHPOINT
5280 Hardware assisted access watchpoint.
5283 The available watchpoint types represented by constants are defined in the
5289 Read only watchpoint.
5293 Write only watchpoint.
5297 Read/Write watchpoint.
5300 @defun Breakpoint.stop (self)
5301 The @code{gdb.Breakpoint} class can be sub-classed and, in
5302 particular, you may choose to implement the @code{stop} method.
5303 If this method is defined in a sub-class of @code{gdb.Breakpoint},
5304 it will be called when the inferior reaches any location of a
5305 breakpoint which instantiates that sub-class. If the method returns
5306 @code{True}, the inferior will be stopped at the location of the
5307 breakpoint, otherwise the inferior will continue.
5309 If there are multiple breakpoints at the same location with a
5310 @code{stop} method, each one will be called regardless of the
5311 return status of the previous. This ensures that all @code{stop}
5312 methods have a chance to execute at that location. In this scenario
5313 if one of the methods returns @code{True} but the others return
5314 @code{False}, the inferior will still be stopped.
5316 You should not alter the execution state of the inferior (i.e.@:, step,
5317 next, etc.), alter the current frame context (i.e.@:, change the current
5318 active frame), or alter, add or delete any breakpoint. As a general
5319 rule, you should not alter any data within @value{GDBN} or the inferior
5322 Example @code{stop} implementation:
5325 class MyBreakpoint (gdb.Breakpoint):
5327 inf_val = gdb.parse_and_eval("foo")
5334 @defun Breakpoint.is_valid ()
5335 Return @code{True} if this @code{Breakpoint} object is valid,
5336 @code{False} otherwise. A @code{Breakpoint} object can become invalid
5337 if the user deletes the breakpoint. In this case, the object still
5338 exists, but the underlying breakpoint does not. In the cases of
5339 watchpoint scope, the watchpoint remains valid even if execution of the
5340 inferior leaves the scope of that watchpoint.
5343 @defun Breakpoint.delete ()
5344 Permanently deletes the @value{GDBN} breakpoint. This also
5345 invalidates the Python @code{Breakpoint} object. Any further access
5346 to this object's attributes or methods will raise an error.
5349 @defvar Breakpoint.enabled
5350 This attribute is @code{True} if the breakpoint is enabled, and
5351 @code{False} otherwise. This attribute is writable. You can use it to enable
5352 or disable the breakpoint.
5355 @defvar Breakpoint.silent
5356 This attribute is @code{True} if the breakpoint is silent, and
5357 @code{False} otherwise. This attribute is writable.
5359 Note that a breakpoint can also be silent if it has commands and the
5360 first command is @code{silent}. This is not reported by the
5361 @code{silent} attribute.
5364 @defvar Breakpoint.pending
5365 This attribute is @code{True} if the breakpoint is pending, and
5366 @code{False} otherwise. @xref{Set Breaks}. This attribute is
5370 @anchor{python_breakpoint_thread}
5371 @defvar Breakpoint.thread
5372 If the breakpoint is thread-specific, this attribute holds the
5373 thread's global id. If the breakpoint is not thread-specific, this
5374 attribute is @code{None}. This attribute is writable.
5377 @defvar Breakpoint.task
5378 If the breakpoint is Ada task-specific, this attribute holds the Ada task
5379 id. If the breakpoint is not task-specific (or the underlying
5380 language is not Ada), this attribute is @code{None}. This attribute
5384 @defvar Breakpoint.ignore_count
5385 This attribute holds the ignore count for the breakpoint, an integer.
5386 This attribute is writable.
5389 @defvar Breakpoint.number
5390 This attribute holds the breakpoint's number --- the identifier used by
5391 the user to manipulate the breakpoint. This attribute is not writable.
5394 @defvar Breakpoint.type
5395 This attribute holds the breakpoint's type --- the identifier used to
5396 determine the actual breakpoint type or use-case. This attribute is not
5400 @defvar Breakpoint.visible
5401 This attribute tells whether the breakpoint is visible to the user
5402 when set, or when the @samp{info breakpoints} command is run. This
5403 attribute is not writable.
5406 @defvar Breakpoint.temporary
5407 This attribute indicates whether the breakpoint was created as a
5408 temporary breakpoint. Temporary breakpoints are automatically deleted
5409 after that breakpoint has been hit. Access to this attribute, and all
5410 other attributes and functions other than the @code{is_valid}
5411 function, will result in an error after the breakpoint has been hit
5412 (as it has been automatically deleted). This attribute is not
5416 @defvar Breakpoint.hit_count
5417 This attribute holds the hit count for the breakpoint, an integer.
5418 This attribute is writable, but currently it can only be set to zero.
5421 @defvar Breakpoint.location
5422 This attribute holds the location of the breakpoint, as specified by
5423 the user. It is a string. If the breakpoint does not have a location
5424 (that is, it is a watchpoint) the attribute's value is @code{None}. This
5425 attribute is not writable.
5428 @defvar Breakpoint.expression
5429 This attribute holds a breakpoint expression, as specified by
5430 the user. It is a string. If the breakpoint does not have an
5431 expression (the breakpoint is not a watchpoint) the attribute's value
5432 is @code{None}. This attribute is not writable.
5435 @defvar Breakpoint.condition
5436 This attribute holds the condition of the breakpoint, as specified by
5437 the user. It is a string. If there is no condition, this attribute's
5438 value is @code{None}. This attribute is writable.
5441 @defvar Breakpoint.commands
5442 This attribute holds the commands attached to the breakpoint. If
5443 there are commands, this attribute's value is a string holding all the
5444 commands, separated by newlines. If there are no commands, this
5445 attribute is @code{None}. This attribute is writable.
5448 @node Finish Breakpoints in Python
5449 @subsubsection Finish Breakpoints
5451 @cindex python finish breakpoints
5452 @tindex gdb.FinishBreakpoint
5454 A finish breakpoint is a temporary breakpoint set at the return address of
5455 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
5456 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
5457 and deleted when the execution will run out of the breakpoint scope (i.e.@:
5458 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
5459 Finish breakpoints are thread specific and must be create with the right
5462 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
5463 Create a finish breakpoint at the return address of the @code{gdb.Frame}
5464 object @var{frame}. If @var{frame} is not provided, this defaults to the
5465 newest frame. The optional @var{internal} argument allows the breakpoint to
5466 become invisible to the user. @xref{Breakpoints In Python}, for further
5467 details about this argument.
5470 @defun FinishBreakpoint.out_of_scope (self)
5471 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
5472 @code{return} command, @dots{}), a function may not properly terminate, and
5473 thus never hit the finish breakpoint. When @value{GDBN} notices such a
5474 situation, the @code{out_of_scope} callback will be triggered.
5476 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
5480 class MyFinishBreakpoint (gdb.FinishBreakpoint)
5482 print "normal finish"
5485 def out_of_scope ():
5486 print "abnormal finish"
5490 @defvar FinishBreakpoint.return_value
5491 When @value{GDBN} is stopped at a finish breakpoint and the frame
5492 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
5493 attribute will contain a @code{gdb.Value} object corresponding to the return
5494 value of the function. The value will be @code{None} if the function return
5495 type is @code{void} or if the return value was not computable. This attribute
5499 @node Lazy Strings In Python
5500 @subsubsection Python representation of lazy strings
5502 @cindex lazy strings in python
5503 @tindex gdb.LazyString
5505 A @dfn{lazy string} is a string whose contents is not retrieved or
5506 encoded until it is needed.
5508 A @code{gdb.LazyString} is represented in @value{GDBN} as an
5509 @code{address} that points to a region of memory, an @code{encoding}
5510 that will be used to encode that region of memory, and a @code{length}
5511 to delimit the region of memory that represents the string. The
5512 difference between a @code{gdb.LazyString} and a string wrapped within
5513 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
5514 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
5515 retrieved and encoded during printing, while a @code{gdb.Value}
5516 wrapping a string is immediately retrieved and encoded on creation.
5518 A @code{gdb.LazyString} object has the following functions:
5520 @defun LazyString.value ()
5521 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
5522 will point to the string in memory, but will lose all the delayed
5523 retrieval, encoding and handling that @value{GDBN} applies to a
5524 @code{gdb.LazyString}.
5527 @defvar LazyString.address
5528 This attribute holds the address of the string. This attribute is not
5532 @defvar LazyString.length
5533 This attribute holds the length of the string in characters. If the
5534 length is -1, then the string will be fetched and encoded up to the
5535 first null of appropriate width. This attribute is not writable.
5538 @defvar LazyString.encoding
5539 This attribute holds the encoding that will be applied to the string
5540 when the string is printed by @value{GDBN}. If the encoding is not
5541 set, or contains an empty string, then @value{GDBN} will select the
5542 most appropriate encoding when the string is printed. This attribute
5546 @defvar LazyString.type
5547 This attribute holds the type that is represented by the lazy string's
5548 type. For a lazy string this is a pointer or array type. To
5549 resolve this to the lazy string's character type, use the type's
5550 @code{target} method. @xref{Types In Python}. This attribute is not
5554 @node Architectures In Python
5555 @subsubsection Python representation of architectures
5556 @cindex Python architectures
5558 @value{GDBN} uses architecture specific parameters and artifacts in a
5559 number of its various computations. An architecture is represented
5560 by an instance of the @code{gdb.Architecture} class.
5562 A @code{gdb.Architecture} class has the following methods:
5564 @defun Architecture.name ()
5565 Return the name (string value) of the architecture.
5568 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
5569 Return a list of disassembled instructions starting from the memory
5570 address @var{start_pc}. The optional arguments @var{end_pc} and
5571 @var{count} determine the number of instructions in the returned list.
5572 If both the optional arguments @var{end_pc} and @var{count} are
5573 specified, then a list of at most @var{count} disassembled instructions
5574 whose start address falls in the closed memory address interval from
5575 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
5576 specified, but @var{count} is specified, then @var{count} number of
5577 instructions starting from the address @var{start_pc} are returned. If
5578 @var{count} is not specified but @var{end_pc} is specified, then all
5579 instructions whose start address falls in the closed memory address
5580 interval from @var{start_pc} to @var{end_pc} are returned. If neither
5581 @var{end_pc} nor @var{count} are specified, then a single instruction at
5582 @var{start_pc} is returned. For all of these cases, each element of the
5583 returned list is a Python @code{dict} with the following string keys:
5588 The value corresponding to this key is a Python long integer capturing
5589 the memory address of the instruction.
5592 The value corresponding to this key is a string value which represents
5593 the instruction with assembly language mnemonics. The assembly
5594 language flavor used is the same as that specified by the current CLI
5595 variable @code{disassembly-flavor}. @xref{Machine Code}.
5598 The value corresponding to this key is the length (integer value) of the
5599 instruction in bytes.
5604 @node Python Auto-loading
5605 @subsection Python Auto-loading
5606 @cindex Python auto-loading
5608 When a new object file is read (for example, due to the @code{file}
5609 command, or because the inferior has loaded a shared library),
5610 @value{GDBN} will look for Python support scripts in several ways:
5611 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
5612 @xref{Auto-loading extensions}.
5614 The auto-loading feature is useful for supplying application-specific
5615 debugging commands and scripts.
5617 Auto-loading can be enabled or disabled,
5618 and the list of auto-loaded scripts can be printed.
5621 @anchor{set auto-load python-scripts}
5622 @kindex set auto-load python-scripts
5623 @item set auto-load python-scripts [on|off]
5624 Enable or disable the auto-loading of Python scripts.
5626 @anchor{show auto-load python-scripts}
5627 @kindex show auto-load python-scripts
5628 @item show auto-load python-scripts
5629 Show whether auto-loading of Python scripts is enabled or disabled.
5631 @anchor{info auto-load python-scripts}
5632 @kindex info auto-load python-scripts
5633 @cindex print list of auto-loaded Python scripts
5634 @item info auto-load python-scripts [@var{regexp}]
5635 Print the list of all Python scripts that @value{GDBN} auto-loaded.
5637 Also printed is the list of Python scripts that were mentioned in
5638 the @code{.debug_gdb_scripts} section and were either not found
5639 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
5640 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
5641 This is useful because their names are not printed when @value{GDBN}
5642 tries to load them and fails. There may be many of them, and printing
5643 an error message for each one is problematic.
5645 If @var{regexp} is supplied only Python scripts with matching names are printed.
5650 (gdb) info auto-load python-scripts
5652 Yes py-section-script.py
5653 full name: /tmp/py-section-script.py
5654 No my-foo-pretty-printers.py
5658 When reading an auto-loaded file or script, @value{GDBN} sets the
5659 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
5660 function (@pxref{Objfiles In Python}). This can be useful for
5661 registering objfile-specific pretty-printers and frame-filters.
5663 @node Python modules
5664 @subsection Python modules
5665 @cindex python modules
5667 @value{GDBN} comes with several modules to assist writing Python code.
5670 * gdb.printing:: Building and registering pretty-printers.
5671 * gdb.types:: Utilities for working with types.
5672 * gdb.prompt:: Utilities for prompt value substitution.
5676 @subsubsection gdb.printing
5677 @cindex gdb.printing
5679 This module provides a collection of utilities for working with
5683 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
5684 This class specifies the API that makes @samp{info pretty-printer},
5685 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
5686 Pretty-printers should generally inherit from this class.
5688 @item SubPrettyPrinter (@var{name})
5689 For printers that handle multiple types, this class specifies the
5690 corresponding API for the subprinters.
5692 @item RegexpCollectionPrettyPrinter (@var{name})
5693 Utility class for handling multiple printers, all recognized via
5694 regular expressions.
5695 @xref{Writing a Pretty-Printer}, for an example.
5697 @item FlagEnumerationPrinter (@var{name})
5698 A pretty-printer which handles printing of @code{enum} values. Unlike
5699 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
5700 work properly when there is some overlap between the enumeration
5701 constants. The argument @var{name} is the name of the printer and
5702 also the name of the @code{enum} type to look up.
5704 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
5705 Register @var{printer} with the pretty-printer list of @var{obj}.
5706 If @var{replace} is @code{True} then any existing copy of the printer
5707 is replaced. Otherwise a @code{RuntimeError} exception is raised
5708 if a printer with the same name already exists.
5712 @subsubsection gdb.types
5715 This module provides a collection of utilities for working with
5716 @code{gdb.Type} objects.
5719 @item get_basic_type (@var{type})
5720 Return @var{type} with const and volatile qualifiers stripped,
5721 and with typedefs and C@t{++} references converted to the underlying type.
5726 typedef const int const_int;
5728 const_int& foo_ref (foo);
5729 int main () @{ return 0; @}
5736 (gdb) python import gdb.types
5737 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
5738 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
5742 @item has_field (@var{type}, @var{field})
5743 Return @code{True} if @var{type}, assumed to be a type with fields
5744 (e.g., a structure or union), has field @var{field}.
5746 @item make_enum_dict (@var{enum_type})
5747 Return a Python @code{dictionary} type produced from @var{enum_type}.
5749 @item deep_items (@var{type})
5750 Returns a Python iterator similar to the standard
5751 @code{gdb.Type.iteritems} method, except that the iterator returned
5752 by @code{deep_items} will recursively traverse anonymous struct or
5753 union fields. For example:
5767 Then in @value{GDBN}:
5769 (@value{GDBP}) python import gdb.types
5770 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
5771 (@value{GDBP}) python print struct_a.keys ()
5773 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
5774 @{['a', 'b0', 'b1']@}
5777 @item get_type_recognizers ()
5778 Return a list of the enabled type recognizers for the current context.
5779 This is called by @value{GDBN} during the type-printing process
5780 (@pxref{Type Printing API}).
5782 @item apply_type_recognizers (recognizers, type_obj)
5783 Apply the type recognizers, @var{recognizers}, to the type object
5784 @var{type_obj}. If any recognizer returns a string, return that
5785 string. Otherwise, return @code{None}. This is called by
5786 @value{GDBN} during the type-printing process (@pxref{Type Printing
5789 @item register_type_printer (locus, printer)
5790 This is a convenience function to register a type printer
5791 @var{printer}. The printer must implement the type printer protocol.
5792 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
5793 the printer is registered with that objfile; a @code{gdb.Progspace},
5794 in which case the printer is registered with that progspace; or
5795 @code{None}, in which case the printer is registered globally.
5798 This is a base class that implements the type printer protocol. Type
5799 printers are encouraged, but not required, to derive from this class.
5800 It defines a constructor:
5802 @defmethod TypePrinter __init__ (self, name)
5803 Initialize the type printer with the given name. The new printer
5804 starts in the enabled state.
5810 @subsubsection gdb.prompt
5813 This module provides a method for prompt value-substitution.
5816 @item substitute_prompt (@var{string})
5817 Return @var{string} with escape sequences substituted by values. Some
5818 escape sequences take arguments. You can specify arguments inside
5819 ``@{@}'' immediately following the escape sequence.
5821 The escape sequences you can pass to this function are:
5825 Substitute a backslash.
5827 Substitute an ESC character.
5829 Substitute the selected frame; an argument names a frame parameter.
5831 Substitute a newline.
5833 Substitute a parameter's value; the argument names the parameter.
5835 Substitute a carriage return.
5837 Substitute the selected thread; an argument names a thread parameter.
5839 Substitute the version of GDB.
5841 Substitute the current working directory.
5843 Begin a sequence of non-printing characters. These sequences are
5844 typically used with the ESC character, and are not counted in the string
5845 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
5846 blue-colored ``(gdb)'' prompt where the length is five.
5848 End a sequence of non-printing characters.
5854 substitute_prompt (``frame: \f,
5855 print arguments: \p@{print frame-arguments@}'')
5858 @exdent will return the string:
5861 "frame: main, print arguments: scalars"