1 @c Copyright (C) 2008-2018 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 @findex gdb.PYTHONDIR
211 @defvar gdb.PYTHONDIR
212 A string containing the python directory (@pxref{Python}).
216 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
217 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
218 If a GDB exception happens while @var{command} runs, it is
219 translated as described in @ref{Exception Handling,,Exception Handling}.
221 The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
222 command as having originated from the user invoking it interactively.
223 It must be a boolean value. If omitted, it defaults to @code{False}.
225 By default, any output produced by @var{command} is sent to
226 @value{GDBN}'s standard output (and to the log output if logging is
227 turned on). If the @var{to_string} parameter is
228 @code{True}, then output will be collected by @code{gdb.execute} and
229 returned as a string. The default is @code{False}, in which case the
230 return value is @code{None}. If @var{to_string} is @code{True}, the
231 @value{GDBN} virtual terminal will be temporarily set to unlimited width
232 and height, and its pagination will be disabled; @pxref{Screen Size}.
235 @findex gdb.breakpoints
236 @defun gdb.breakpoints ()
237 Return a sequence holding all of @value{GDBN}'s breakpoints.
238 @xref{Breakpoints In Python}, for more information. In @value{GDBN}
239 version 7.11 and earlier, this function returned @code{None} if there
240 were no breakpoints. This peculiarity was subsequently fixed, and now
241 @code{gdb.breakpoints} returns an empty sequence in this case.
244 @defun gdb.rbreak (regex @r{[}, minsyms @r{[}, throttle, @r{[}, symtabs @r{]]]})
245 Return a Python list holding a collection of newly set
246 @code{gdb.Breakpoint} objects matching function names defined by the
247 @var{regex} pattern. If the @var{minsyms} keyword is @code{True}, all
248 system functions (those not explicitly defined in the inferior) will
249 also be included in the match. The @var{throttle} keyword takes an
250 integer that defines the maximum number of pattern matches for
251 functions matched by the @var{regex} pattern. If the number of
252 matches exceeds the integer value of @var{throttle}, a
253 @code{RuntimeError} will be raised and no breakpoints will be created.
254 If @var{throttle} is not defined then there is no imposed limit on the
255 maximum number of matches and breakpoints to be created. The
256 @var{symtabs} keyword takes a Python iterable that yields a collection
257 of @code{gdb.Symtab} objects and will restrict the search to those
258 functions only contained within the @code{gdb.Symtab} objects.
261 @findex gdb.parameter
262 @defun gdb.parameter (parameter)
263 Return the value of a @value{GDBN} @var{parameter} given by its name,
264 a string; the parameter name string may contain spaces if the parameter has a
265 multi-part name. For example, @samp{print object} is a valid
268 If the named parameter does not exist, this function throws a
269 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
270 parameter's value is converted to a Python value of the appropriate
275 @defun gdb.history (number)
276 Return a value from @value{GDBN}'s value history (@pxref{Value
277 History}). The @var{number} argument indicates which history element to return.
278 If @var{number} is negative, then @value{GDBN} will take its absolute value
279 and count backward from the last element (i.e., the most recent element) to
280 find the value to return. If @var{number} is zero, then @value{GDBN} will
281 return the most recent element. If the element specified by @var{number}
282 doesn't exist in the value history, a @code{gdb.error} exception will be
285 If no exception is raised, the return value is always an instance of
286 @code{gdb.Value} (@pxref{Values From Inferior}).
289 @findex gdb.convenience_variable
290 @defun gdb.convenience_variable (name)
291 Return the value of the convenience variable (@pxref{Convenience
292 Vars}) named @var{name}. @var{name} must be a string. The name
293 should not include the @samp{$} that is used to mark a convenience
294 variable in an expression. If the convenience variable does not
295 exist, then @code{None} is returned.
298 @findex gdb.set_convenience_variable
299 @defun gdb.set_convenience_variable (name, value)
300 Set the value of the convenience variable (@pxref{Convenience Vars})
301 named @var{name}. @var{name} must be a string. The name should not
302 include the @samp{$} that is used to mark a convenience variable in an
303 expression. If @var{value} is @code{None}, then the convenience
304 variable is removed. Otherwise, if @var{value} is not a
305 @code{gdb.Value} (@pxref{Values From Inferior}), it is is converted
306 using the @code{gdb.Value} constructor.
309 @findex gdb.parse_and_eval
310 @defun gdb.parse_and_eval (expression)
311 Parse @var{expression}, which must be a string, as an expression in
312 the current language, evaluate it, and return the result as a
315 This function can be useful when implementing a new command
316 (@pxref{Commands In Python}), as it provides a way to parse the
317 command's argument as an expression. It is also useful simply to
321 @findex gdb.find_pc_line
322 @defun gdb.find_pc_line (pc)
323 Return the @code{gdb.Symtab_and_line} object corresponding to the
324 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
325 value of @var{pc} is passed as an argument, then the @code{symtab} and
326 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
327 will be @code{None} and 0 respectively.
330 @findex gdb.post_event
331 @defun gdb.post_event (event)
332 Put @var{event}, a callable object taking no arguments, into
333 @value{GDBN}'s internal event queue. This callable will be invoked at
334 some later point, during @value{GDBN}'s event processing. Events
335 posted using @code{post_event} will be run in the order in which they
336 were posted; however, there is no way to know when they will be
337 processed relative to other events inside @value{GDBN}.
339 @value{GDBN} is not thread-safe. If your Python program uses multiple
340 threads, you must be careful to only call @value{GDBN}-specific
341 functions in the @value{GDBN} thread. @code{post_event} ensures
345 (@value{GDBP}) python
349 > def __init__(self, message):
350 > self.message = message;
351 > def __call__(self):
352 > gdb.write(self.message)
354 >class MyThread1 (threading.Thread):
356 > gdb.post_event(Writer("Hello "))
358 >class MyThread2 (threading.Thread):
360 > gdb.post_event(Writer("World\n"))
365 (@value{GDBP}) Hello World
370 @defun gdb.write (string @r{[}, stream{]})
371 Print a string to @value{GDBN}'s paginated output stream. The
372 optional @var{stream} determines the stream to print to. The default
373 stream is @value{GDBN}'s standard output stream. Possible stream
380 @value{GDBN}'s standard output stream.
385 @value{GDBN}'s standard error stream.
390 @value{GDBN}'s log stream (@pxref{Logging Output}).
393 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
394 call this function and will automatically direct the output to the
400 Flush the buffer of a @value{GDBN} paginated stream so that the
401 contents are displayed immediately. @value{GDBN} will flush the
402 contents of a stream automatically when it encounters a newline in the
403 buffer. The optional @var{stream} determines the stream to flush. The
404 default stream is @value{GDBN}'s standard output stream. Possible
411 @value{GDBN}'s standard output stream.
416 @value{GDBN}'s standard error stream.
421 @value{GDBN}'s log stream (@pxref{Logging Output}).
425 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
426 call this function for the relevant stream.
429 @findex gdb.target_charset
430 @defun gdb.target_charset ()
431 Return the name of the current target character set (@pxref{Character
432 Sets}). This differs from @code{gdb.parameter('target-charset')} in
433 that @samp{auto} is never returned.
436 @findex gdb.target_wide_charset
437 @defun gdb.target_wide_charset ()
438 Return the name of the current target wide character set
439 (@pxref{Character Sets}). This differs from
440 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
444 @findex gdb.solib_name
445 @defun gdb.solib_name (address)
446 Return the name of the shared library holding the given @var{address}
447 as a string, or @code{None}.
450 @findex gdb.decode_line
451 @defun gdb.decode_line (@r{[}expression@r{]})
452 Return locations of the line specified by @var{expression}, or of the
453 current line if no argument was given. This function returns a Python
454 tuple containing two elements. The first element contains a string
455 holding any unparsed section of @var{expression} (or @code{None} if
456 the expression has been fully parsed). The second element contains
457 either @code{None} or another tuple that contains all the locations
458 that match the expression represented as @code{gdb.Symtab_and_line}
459 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
460 provided, it is decoded the way that @value{GDBN}'s inbuilt
461 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
464 @defun gdb.prompt_hook (current_prompt)
467 If @var{prompt_hook} is callable, @value{GDBN} will call the method
468 assigned to this operation before a prompt is displayed by
471 The parameter @code{current_prompt} contains the current @value{GDBN}
472 prompt. This method must return a Python string, or @code{None}. If
473 a string is returned, the @value{GDBN} prompt will be set to that
474 string. If @code{None} is returned, @value{GDBN} will continue to use
477 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
478 such as those used by readline for command input, and annotation
479 related prompts are prohibited from being changed.
482 @node Exception Handling
483 @subsubsection Exception Handling
484 @cindex python exceptions
485 @cindex exceptions, python
487 When executing the @code{python} command, Python exceptions
488 uncaught within the Python code are translated to calls to
489 @value{GDBN} error-reporting mechanism. If the command that called
490 @code{python} does not handle the error, @value{GDBN} will
491 terminate it and print an error message containing the Python
492 exception name, the associated value, and the Python call stack
493 backtrace at the point where the exception was raised. Example:
496 (@value{GDBP}) python print foo
497 Traceback (most recent call last):
498 File "<string>", line 1, in <module>
499 NameError: name 'foo' is not defined
502 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
503 Python code are converted to Python exceptions. The type of the
504 Python exception depends on the error.
508 This is the base class for most exceptions generated by @value{GDBN}.
509 It is derived from @code{RuntimeError}, for compatibility with earlier
510 versions of @value{GDBN}.
512 If an error occurring in @value{GDBN} does not fit into some more
513 specific category, then the generated exception will have this type.
515 @item gdb.MemoryError
516 This is a subclass of @code{gdb.error} which is thrown when an
517 operation tried to access invalid memory in the inferior.
519 @item KeyboardInterrupt
520 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
521 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
524 In all cases, your exception handler will see the @value{GDBN} error
525 message as its value and the Python call stack backtrace at the Python
526 statement closest to where the @value{GDBN} error occured as the
530 When implementing @value{GDBN} commands in Python via
531 @code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
532 to be able to throw an exception that doesn't cause a traceback to be
533 printed. For example, the user may have invoked the command
534 incorrectly. @value{GDBN} provides a special exception class that can
535 be used for this purpose.
539 When thrown from a command or function, this exception will cause the
540 command or function to fail, but the Python stack will not be
541 displayed. @value{GDBN} does not throw this exception itself, but
542 rather recognizes it when thrown from user Python code. Example:
546 >class HelloWorld (gdb.Command):
547 > """Greet the whole world."""
548 > def __init__ (self):
549 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
550 > def invoke (self, args, from_tty):
551 > argv = gdb.string_to_argv (args)
552 > if len (argv) != 0:
553 > raise gdb.GdbError ("hello-world takes no arguments")
554 > print "Hello, World!"
558 hello-world takes no arguments
562 @node Values From Inferior
563 @subsubsection Values From Inferior
564 @cindex values from inferior, with Python
565 @cindex python, working with values from inferior
567 @cindex @code{gdb.Value}
568 @value{GDBN} provides values it obtains from the inferior program in
569 an object of type @code{gdb.Value}. @value{GDBN} uses this object
570 for its internal bookkeeping of the inferior's values, and for
571 fetching values when necessary.
573 Inferior values that are simple scalars can be used directly in
574 Python expressions that are valid for the value's data type. Here's
575 an example for an integer or floating-point value @code{some_val}:
582 As result of this, @code{bar} will also be a @code{gdb.Value} object
583 whose values are of the same type as those of @code{some_val}. Valid
584 Python operations can also be performed on @code{gdb.Value} objects
585 representing a @code{struct} or @code{class} object. For such cases,
586 the overloaded operator (if present), is used to perform the operation.
587 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
588 representing instances of a @code{class} which overloads the @code{+}
589 operator, then one can use the @code{+} operator in their Python script
597 The result of the operation @code{val3} is also a @code{gdb.Value}
598 object corresponding to the value returned by the overloaded @code{+}
599 operator. In general, overloaded operators are invoked for the
600 following operations: @code{+} (binary addition), @code{-} (binary
601 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
602 @code{>>}, @code{|}, @code{&}, @code{^}.
604 Inferior values that are structures or instances of some class can
605 be accessed using the Python @dfn{dictionary syntax}. For example, if
606 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
607 can access its @code{foo} element with:
610 bar = some_val['foo']
613 @cindex getting structure elements using gdb.Field objects as subscripts
614 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
615 elements can also be accessed by using @code{gdb.Field} objects as
616 subscripts (@pxref{Types In Python}, for more information on
617 @code{gdb.Field} objects). For example, if @code{foo_field} is a
618 @code{gdb.Field} object corresponding to element @code{foo} of the above
619 structure, then @code{bar} can also be accessed as follows:
622 bar = some_val[foo_field]
625 A @code{gdb.Value} that represents a function can be executed via
626 inferior function call. Any arguments provided to the call must match
627 the function's prototype, and must be provided in the order specified
630 For example, @code{some_val} is a @code{gdb.Value} instance
631 representing a function that takes two integers as arguments. To
632 execute this function, call it like so:
635 result = some_val (10,20)
638 Any values returned from a function call will be stored as a
641 The following attributes are provided:
643 @defvar Value.address
644 If this object is addressable, this read-only attribute holds a
645 @code{gdb.Value} object representing the address. Otherwise,
646 this attribute holds @code{None}.
649 @cindex optimized out value in Python
650 @defvar Value.is_optimized_out
651 This read-only boolean attribute is true if the compiler optimized out
652 this value, thus it is not available for fetching from the inferior.
656 The type of this @code{gdb.Value}. The value of this attribute is a
657 @code{gdb.Type} object (@pxref{Types In Python}).
660 @defvar Value.dynamic_type
661 The dynamic type of this @code{gdb.Value}. This uses the object's
662 virtual table and the C@t{++} run-time type information
663 (@acronym{RTTI}) to determine the dynamic type of the value. If this
664 value is of class type, it will return the class in which the value is
665 embedded, if any. If this value is of pointer or reference to a class
666 type, it will compute the dynamic type of the referenced object, and
667 return a pointer or reference to that type, respectively. In all
668 other cases, it will return the value's static type.
670 Note that this feature will only work when debugging a C@t{++} program
671 that includes @acronym{RTTI} for the object in question. Otherwise,
672 it will just return the static type of the value as in @kbd{ptype foo}
673 (@pxref{Symbols, ptype}).
676 @defvar Value.is_lazy
677 The value of this read-only boolean attribute is @code{True} if this
678 @code{gdb.Value} has not yet been fetched from the inferior.
679 @value{GDBN} does not fetch values until necessary, for efficiency.
683 myval = gdb.parse_and_eval ('somevar')
686 The value of @code{somevar} is not fetched at this time. It will be
687 fetched when the value is needed, or when the @code{fetch_lazy}
691 The following methods are provided:
693 @defun Value.__init__ (@var{val})
694 Many Python values can be converted directly to a @code{gdb.Value} via
695 this object initializer. Specifically:
699 A Python boolean is converted to the boolean type from the current
703 A Python integer is converted to the C @code{long} type for the
704 current architecture.
707 A Python long is converted to the C @code{long long} type for the
708 current architecture.
711 A Python float is converted to the C @code{double} type for the
712 current architecture.
715 A Python string is converted to a target string in the current target
716 language using the current target encoding.
717 If a character cannot be represented in the current target encoding,
718 then an exception is thrown.
720 @item @code{gdb.Value}
721 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
723 @item @code{gdb.LazyString}
724 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
725 Python}), then the lazy string's @code{value} method is called, and
730 @defun Value.cast (type)
731 Return a new instance of @code{gdb.Value} that is the result of
732 casting this instance to the type described by @var{type}, which must
733 be a @code{gdb.Type} object. If the cast cannot be performed for some
734 reason, this method throws an exception.
737 @defun Value.dereference ()
738 For pointer data types, this method returns a new @code{gdb.Value} object
739 whose contents is the object pointed to by the pointer. For example, if
740 @code{foo} is a C pointer to an @code{int}, declared in your C program as
747 then you can use the corresponding @code{gdb.Value} to access what
748 @code{foo} points to like this:
751 bar = foo.dereference ()
754 The result @code{bar} will be a @code{gdb.Value} object holding the
755 value pointed to by @code{foo}.
757 A similar function @code{Value.referenced_value} exists which also
758 returns @code{gdb.Value} objects corresonding to the values pointed to
759 by pointer values (and additionally, values referenced by reference
760 values). However, the behavior of @code{Value.dereference}
761 differs from @code{Value.referenced_value} by the fact that the
762 behavior of @code{Value.dereference} is identical to applying the C
763 unary operator @code{*} on a given value. For example, consider a
764 reference to a pointer @code{ptrref}, declared in your C@t{++} program
772 intptr &ptrref = ptr;
775 Though @code{ptrref} is a reference value, one can apply the method
776 @code{Value.dereference} to the @code{gdb.Value} object corresponding
777 to it and obtain a @code{gdb.Value} which is identical to that
778 corresponding to @code{val}. However, if you apply the method
779 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
780 object identical to that corresponding to @code{ptr}.
783 py_ptrref = gdb.parse_and_eval ("ptrref")
784 py_val = py_ptrref.dereference ()
785 py_ptr = py_ptrref.referenced_value ()
788 The @code{gdb.Value} object @code{py_val} is identical to that
789 corresponding to @code{val}, and @code{py_ptr} is identical to that
790 corresponding to @code{ptr}. In general, @code{Value.dereference} can
791 be applied whenever the C unary operator @code{*} can be applied
792 to the corresponding C value. For those cases where applying both
793 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
794 the results obtained need not be identical (as we have seen in the above
795 example). The results are however identical when applied on
796 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
797 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
800 @defun Value.referenced_value ()
801 For pointer or reference data types, this method returns a new
802 @code{gdb.Value} object corresponding to the value referenced by the
803 pointer/reference value. For pointer data types,
804 @code{Value.dereference} and @code{Value.referenced_value} produce
805 identical results. The difference between these methods is that
806 @code{Value.dereference} cannot get the values referenced by reference
807 values. For example, consider a reference to an @code{int}, declared
808 in your C@t{++} program as
816 then applying @code{Value.dereference} to the @code{gdb.Value} object
817 corresponding to @code{ref} will result in an error, while applying
818 @code{Value.referenced_value} will result in a @code{gdb.Value} object
819 identical to that corresponding to @code{val}.
822 py_ref = gdb.parse_and_eval ("ref")
823 er_ref = py_ref.dereference () # Results in error
824 py_val = py_ref.referenced_value () # Returns the referenced value
827 The @code{gdb.Value} object @code{py_val} is identical to that
828 corresponding to @code{val}.
831 @defun Value.reference_value ()
832 Return a @code{gdb.Value} object which is a reference to the value
833 encapsulated by this instance.
836 @defun Value.const_value ()
837 Return a @code{gdb.Value} object which is a @code{const} version of the
838 value encapsulated by this instance.
841 @defun Value.dynamic_cast (type)
842 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
843 operator were used. Consult a C@t{++} reference for details.
846 @defun Value.reinterpret_cast (type)
847 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
848 operator were used. Consult a C@t{++} reference for details.
851 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
852 If this @code{gdb.Value} represents a string, then this method
853 converts the contents to a Python string. Otherwise, this method will
856 Values are interpreted as strings according to the rules of the
857 current language. If the optional length argument is given, the
858 string will be converted to that length, and will include any embedded
859 zeroes that the string may contain. Otherwise, for languages
860 where the string is zero-terminated, the entire string will be
863 For example, in C-like languages, a value is a string if it is a pointer
864 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
867 If the optional @var{encoding} argument is given, it must be a string
868 naming the encoding of the string in the @code{gdb.Value}, such as
869 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
870 the same encodings as the corresponding argument to Python's
871 @code{string.decode} method, and the Python codec machinery will be used
872 to convert the string. If @var{encoding} is not given, or if
873 @var{encoding} is the empty string, then either the @code{target-charset}
874 (@pxref{Character Sets}) will be used, or a language-specific encoding
875 will be used, if the current language is able to supply one.
877 The optional @var{errors} argument is the same as the corresponding
878 argument to Python's @code{string.decode} method.
880 If the optional @var{length} argument is given, the string will be
881 fetched and converted to the given length.
884 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
885 If this @code{gdb.Value} represents a string, then this method
886 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
887 In Python}). Otherwise, this method will throw an exception.
889 If the optional @var{encoding} argument is given, it must be a string
890 naming the encoding of the @code{gdb.LazyString}. Some examples are:
891 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
892 @var{encoding} argument is an encoding that @value{GDBN} does
893 recognize, @value{GDBN} will raise an error.
895 When a lazy string is printed, the @value{GDBN} encoding machinery is
896 used to convert the string during printing. If the optional
897 @var{encoding} argument is not provided, or is an empty string,
898 @value{GDBN} will automatically select the encoding most suitable for
899 the string type. For further information on encoding in @value{GDBN}
900 please see @ref{Character Sets}.
902 If the optional @var{length} argument is given, the string will be
903 fetched and encoded to the length of characters specified. If
904 the @var{length} argument is not provided, the string will be fetched
905 and encoded until a null of appropriate width is found.
908 @defun Value.fetch_lazy ()
909 If the @code{gdb.Value} object is currently a lazy value
910 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
911 fetched from the inferior. Any errors that occur in the process
912 will produce a Python exception.
914 If the @code{gdb.Value} object is not a lazy value, this method
917 This method does not return a value.
921 @node Types In Python
922 @subsubsection Types In Python
923 @cindex types in Python
924 @cindex Python, working with types
927 @value{GDBN} represents types from the inferior using the class
930 The following type-related functions are available in the @code{gdb}
933 @findex gdb.lookup_type
934 @defun gdb.lookup_type (name @r{[}, block@r{]})
935 This function looks up a type by its @var{name}, which must be a string.
937 If @var{block} is given, then @var{name} is looked up in that scope.
938 Otherwise, it is searched for globally.
940 Ordinarily, this function will return an instance of @code{gdb.Type}.
941 If the named type cannot be found, it will throw an exception.
944 If the type is a structure or class type, or an enum type, the fields
945 of that type can be accessed using the Python @dfn{dictionary syntax}.
946 For example, if @code{some_type} is a @code{gdb.Type} instance holding
947 a structure type, you can access its @code{foo} field with:
950 bar = some_type['foo']
953 @code{bar} will be a @code{gdb.Field} object; see below under the
954 description of the @code{Type.fields} method for a description of the
955 @code{gdb.Field} class.
957 An instance of @code{Type} has the following attributes:
960 The alignment of this type, in bytes. Type alignment comes from the
961 debugging information; if it was not specified, then @value{GDBN} will
962 use the relevant ABI to try to determine the alignment. In some
963 cases, even this is not possible, and zero will be returned.
967 The type code for this type. The type code will be one of the
968 @code{TYPE_CODE_} constants defined below.
972 The name of this type. If this type has no name, then @code{None}
977 The size of this type, in target @code{char} units. Usually, a
978 target's @code{char} type will be an 8-bit byte. However, on some
979 unusual platforms, this type may have a different size.
983 The tag name for this type. The tag name is the name after
984 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
985 languages have this concept. If this type has no tag name, then
986 @code{None} is returned.
989 The following methods are provided:
991 @defun Type.fields ()
992 For structure and union types, this method returns the fields. Range
993 types have two fields, the minimum and maximum values. Enum types
994 have one field per enum constant. Function and method types have one
995 field per parameter. The base types of C@t{++} classes are also
996 represented as fields. If the type has no fields, or does not fit
997 into one of these categories, an empty sequence will be returned.
999 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
1002 This attribute is not available for @code{enum} or @code{static}
1003 (as in C@t{++}) fields. The value is the position, counting
1004 in bits, from the start of the containing type.
1007 This attribute is only available for @code{enum} fields, and its value
1008 is the enumeration member's integer representation.
1011 The name of the field, or @code{None} for anonymous fields.
1014 This is @code{True} if the field is artificial, usually meaning that
1015 it was provided by the compiler and not the user. This attribute is
1016 always provided, and is @code{False} if the field is not artificial.
1019 This is @code{True} if the field represents a base class of a C@t{++}
1020 structure. This attribute is always provided, and is @code{False}
1021 if the field is not a base class of the type that is the argument of
1022 @code{fields}, or if that type was not a C@t{++} class.
1025 If the field is packed, or is a bitfield, then this will have a
1026 non-zero value, which is the size of the field in bits. Otherwise,
1027 this will be zero; in this case the field's size is given by its type.
1030 The type of the field. This is usually an instance of @code{Type},
1031 but it can be @code{None} in some situations.
1034 The type which contains this field. This is an instance of
1039 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
1040 Return a new @code{gdb.Type} object which represents an array of this
1041 type. If one argument is given, it is the inclusive upper bound of
1042 the array; in this case the lower bound is zero. If two arguments are
1043 given, the first argument is the lower bound of the array, and the
1044 second argument is the upper bound of the array. An array's length
1045 must not be negative, but the bounds can be.
1048 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
1049 Return a new @code{gdb.Type} object which represents a vector of this
1050 type. If one argument is given, it is the inclusive upper bound of
1051 the vector; in this case the lower bound is zero. If two arguments are
1052 given, the first argument is the lower bound of the vector, and the
1053 second argument is the upper bound of the vector. A vector's length
1054 must not be negative, but the bounds can be.
1056 The difference between an @code{array} and a @code{vector} is that
1057 arrays behave like in C: when used in expressions they decay to a pointer
1058 to the first element whereas vectors are treated as first class values.
1061 @defun Type.const ()
1062 Return a new @code{gdb.Type} object which represents a
1063 @code{const}-qualified variant of this type.
1066 @defun Type.volatile ()
1067 Return a new @code{gdb.Type} object which represents a
1068 @code{volatile}-qualified variant of this type.
1071 @defun Type.unqualified ()
1072 Return a new @code{gdb.Type} object which represents an unqualified
1073 variant of this type. That is, the result is neither @code{const} nor
1077 @defun Type.range ()
1078 Return a Python @code{Tuple} object that contains two elements: the
1079 low bound of the argument type and the high bound of that type. If
1080 the type does not have a range, @value{GDBN} will raise a
1081 @code{gdb.error} exception (@pxref{Exception Handling}).
1084 @defun Type.reference ()
1085 Return a new @code{gdb.Type} object which represents a reference to this
1089 @defun Type.pointer ()
1090 Return a new @code{gdb.Type} object which represents a pointer to this
1094 @defun Type.strip_typedefs ()
1095 Return a new @code{gdb.Type} that represents the real type,
1096 after removing all layers of typedefs.
1099 @defun Type.target ()
1100 Return a new @code{gdb.Type} object which represents the target type
1103 For a pointer type, the target type is the type of the pointed-to
1104 object. For an array type (meaning C-like arrays), the target type is
1105 the type of the elements of the array. For a function or method type,
1106 the target type is the type of the return value. For a complex type,
1107 the target type is the type of the elements. For a typedef, the
1108 target type is the aliased type.
1110 If the type does not have a target, this method will throw an
1114 @defun Type.template_argument (n @r{[}, block@r{]})
1115 If this @code{gdb.Type} is an instantiation of a template, this will
1116 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1117 value of the @var{n}th template argument (indexed starting at 0).
1119 If this @code{gdb.Type} is not a template type, or if the type has fewer
1120 than @var{n} template arguments, this will throw an exception.
1121 Ordinarily, only C@t{++} code will have template types.
1123 If @var{block} is given, then @var{name} is looked up in that scope.
1124 Otherwise, it is searched for globally.
1127 @defun Type.optimized_out ()
1128 Return @code{gdb.Value} instance of this type whose value is optimized
1129 out. This allows a frame decorator to indicate that the value of an
1130 argument or a local variable is not known.
1133 Each type has a code, which indicates what category this type falls
1134 into. The available type categories are represented by constants
1135 defined in the @code{gdb} module:
1138 @vindex TYPE_CODE_PTR
1139 @item gdb.TYPE_CODE_PTR
1140 The type is a pointer.
1142 @vindex TYPE_CODE_ARRAY
1143 @item gdb.TYPE_CODE_ARRAY
1144 The type is an array.
1146 @vindex TYPE_CODE_STRUCT
1147 @item gdb.TYPE_CODE_STRUCT
1148 The type is a structure.
1150 @vindex TYPE_CODE_UNION
1151 @item gdb.TYPE_CODE_UNION
1152 The type is a union.
1154 @vindex TYPE_CODE_ENUM
1155 @item gdb.TYPE_CODE_ENUM
1156 The type is an enum.
1158 @vindex TYPE_CODE_FLAGS
1159 @item gdb.TYPE_CODE_FLAGS
1160 A bit flags type, used for things such as status registers.
1162 @vindex TYPE_CODE_FUNC
1163 @item gdb.TYPE_CODE_FUNC
1164 The type is a function.
1166 @vindex TYPE_CODE_INT
1167 @item gdb.TYPE_CODE_INT
1168 The type is an integer type.
1170 @vindex TYPE_CODE_FLT
1171 @item gdb.TYPE_CODE_FLT
1172 A floating point type.
1174 @vindex TYPE_CODE_VOID
1175 @item gdb.TYPE_CODE_VOID
1176 The special type @code{void}.
1178 @vindex TYPE_CODE_SET
1179 @item gdb.TYPE_CODE_SET
1182 @vindex TYPE_CODE_RANGE
1183 @item gdb.TYPE_CODE_RANGE
1184 A range type, that is, an integer type with bounds.
1186 @vindex TYPE_CODE_STRING
1187 @item gdb.TYPE_CODE_STRING
1188 A string type. Note that this is only used for certain languages with
1189 language-defined string types; C strings are not represented this way.
1191 @vindex TYPE_CODE_BITSTRING
1192 @item gdb.TYPE_CODE_BITSTRING
1193 A string of bits. It is deprecated.
1195 @vindex TYPE_CODE_ERROR
1196 @item gdb.TYPE_CODE_ERROR
1197 An unknown or erroneous type.
1199 @vindex TYPE_CODE_METHOD
1200 @item gdb.TYPE_CODE_METHOD
1201 A method type, as found in C@t{++}.
1203 @vindex TYPE_CODE_METHODPTR
1204 @item gdb.TYPE_CODE_METHODPTR
1205 A pointer-to-member-function.
1207 @vindex TYPE_CODE_MEMBERPTR
1208 @item gdb.TYPE_CODE_MEMBERPTR
1209 A pointer-to-member.
1211 @vindex TYPE_CODE_REF
1212 @item gdb.TYPE_CODE_REF
1215 @vindex TYPE_CODE_RVALUE_REF
1216 @item gdb.TYPE_CODE_RVALUE_REF
1217 A C@t{++}11 rvalue reference type.
1219 @vindex TYPE_CODE_CHAR
1220 @item gdb.TYPE_CODE_CHAR
1223 @vindex TYPE_CODE_BOOL
1224 @item gdb.TYPE_CODE_BOOL
1227 @vindex TYPE_CODE_COMPLEX
1228 @item gdb.TYPE_CODE_COMPLEX
1229 A complex float type.
1231 @vindex TYPE_CODE_TYPEDEF
1232 @item gdb.TYPE_CODE_TYPEDEF
1233 A typedef to some other type.
1235 @vindex TYPE_CODE_NAMESPACE
1236 @item gdb.TYPE_CODE_NAMESPACE
1237 A C@t{++} namespace.
1239 @vindex TYPE_CODE_DECFLOAT
1240 @item gdb.TYPE_CODE_DECFLOAT
1241 A decimal floating point type.
1243 @vindex TYPE_CODE_INTERNAL_FUNCTION
1244 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1245 A function internal to @value{GDBN}. This is the type used to represent
1246 convenience functions.
1249 Further support for types is provided in the @code{gdb.types}
1250 Python module (@pxref{gdb.types}).
1252 @node Pretty Printing API
1253 @subsubsection Pretty Printing API
1254 @cindex python pretty printing api
1256 A pretty-printer is just an object that holds a value and implements a
1257 specific interface, defined here. An example output is provided
1258 (@pxref{Pretty Printing}).
1260 @defun pretty_printer.children (self)
1261 @value{GDBN} will call this method on a pretty-printer to compute the
1262 children of the pretty-printer's value.
1264 This method must return an object conforming to the Python iterator
1265 protocol. Each item returned by the iterator must be a tuple holding
1266 two elements. The first element is the ``name'' of the child; the
1267 second element is the child's value. The value can be any Python
1268 object which is convertible to a @value{GDBN} value.
1270 This method is optional. If it does not exist, @value{GDBN} will act
1271 as though the value has no children.
1274 @defun pretty_printer.display_hint (self)
1275 The CLI may call this method and use its result to change the
1276 formatting of a value. The result will also be supplied to an MI
1277 consumer as a @samp{displayhint} attribute of the variable being
1280 This method is optional. If it does exist, this method must return a
1283 Some display hints are predefined by @value{GDBN}:
1287 Indicate that the object being printed is ``array-like''. The CLI
1288 uses this to respect parameters such as @code{set print elements} and
1289 @code{set print array}.
1292 Indicate that the object being printed is ``map-like'', and that the
1293 children of this value can be assumed to alternate between keys and
1297 Indicate that the object being printed is ``string-like''. If the
1298 printer's @code{to_string} method returns a Python string of some
1299 kind, then @value{GDBN} will call its internal language-specific
1300 string-printing function to format the string. For the CLI this means
1301 adding quotation marks, possibly escaping some characters, respecting
1302 @code{set print elements}, and the like.
1306 @defun pretty_printer.to_string (self)
1307 @value{GDBN} will call this method to display the string
1308 representation of the value passed to the object's constructor.
1310 When printing from the CLI, if the @code{to_string} method exists,
1311 then @value{GDBN} will prepend its result to the values returned by
1312 @code{children}. Exactly how this formatting is done is dependent on
1313 the display hint, and may change as more hints are added. Also,
1314 depending on the print settings (@pxref{Print Settings}), the CLI may
1315 print just the result of @code{to_string} in a stack trace, omitting
1316 the result of @code{children}.
1318 If this method returns a string, it is printed verbatim.
1320 Otherwise, if this method returns an instance of @code{gdb.Value},
1321 then @value{GDBN} prints this value. This may result in a call to
1322 another pretty-printer.
1324 If instead the method returns a Python value which is convertible to a
1325 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1326 the resulting value. Again, this may result in a call to another
1327 pretty-printer. Python scalars (integers, floats, and booleans) and
1328 strings are convertible to @code{gdb.Value}; other types are not.
1330 Finally, if this method returns @code{None} then no further operations
1331 are peformed in this method and nothing is printed.
1333 If the result is not one of these types, an exception is raised.
1336 @value{GDBN} provides a function which can be used to look up the
1337 default pretty-printer for a @code{gdb.Value}:
1339 @findex gdb.default_visualizer
1340 @defun gdb.default_visualizer (value)
1341 This function takes a @code{gdb.Value} object as an argument. If a
1342 pretty-printer for this value exists, then it is returned. If no such
1343 printer exists, then this returns @code{None}.
1346 @node Selecting Pretty-Printers
1347 @subsubsection Selecting Pretty-Printers
1348 @cindex selecting python pretty-printers
1350 The Python list @code{gdb.pretty_printers} contains an array of
1351 functions or callable objects that have been registered via addition
1352 as a pretty-printer. Printers in this list are called @code{global}
1353 printers, they're available when debugging all inferiors.
1354 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1355 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1358 Each function on these lists is passed a single @code{gdb.Value}
1359 argument and should return a pretty-printer object conforming to the
1360 interface definition above (@pxref{Pretty Printing API}). If a function
1361 cannot create a pretty-printer for the value, it should return
1364 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1365 @code{gdb.Objfile} in the current program space and iteratively calls
1366 each enabled lookup routine in the list for that @code{gdb.Objfile}
1367 until it receives a pretty-printer object.
1368 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1369 searches the pretty-printer list of the current program space,
1370 calling each enabled function until an object is returned.
1371 After these lists have been exhausted, it tries the global
1372 @code{gdb.pretty_printers} list, again calling each enabled function until an
1375 The order in which the objfiles are searched is not specified. For a
1376 given list, functions are always invoked from the head of the list,
1377 and iterated over sequentially until the end of the list, or a printer
1380 For various reasons a pretty-printer may not work.
1381 For example, the underlying data structure may have changed and
1382 the pretty-printer is out of date.
1384 The consequences of a broken pretty-printer are severe enough that
1385 @value{GDBN} provides support for enabling and disabling individual
1386 printers. For example, if @code{print frame-arguments} is on,
1387 a backtrace can become highly illegible if any argument is printed
1388 with a broken printer.
1390 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1391 attribute to the registered function or callable object. If this attribute
1392 is present and its value is @code{False}, the printer is disabled, otherwise
1393 the printer is enabled.
1395 @node Writing a Pretty-Printer
1396 @subsubsection Writing a Pretty-Printer
1397 @cindex writing a pretty-printer
1399 A pretty-printer consists of two parts: a lookup function to detect
1400 if the type is supported, and the printer itself.
1402 Here is an example showing how a @code{std::string} printer might be
1403 written. @xref{Pretty Printing API}, for details on the API this class
1407 class StdStringPrinter(object):
1408 "Print a std::string"
1410 def __init__(self, val):
1413 def to_string(self):
1414 return self.val['_M_dataplus']['_M_p']
1416 def display_hint(self):
1420 And here is an example showing how a lookup function for the printer
1421 example above might be written.
1424 def str_lookup_function(val):
1425 lookup_tag = val.type.tag
1426 if lookup_tag == None:
1428 regex = re.compile("^std::basic_string<char,.*>$")
1429 if regex.match(lookup_tag):
1430 return StdStringPrinter(val)
1434 The example lookup function extracts the value's type, and attempts to
1435 match it to a type that it can pretty-print. If it is a type the
1436 printer can pretty-print, it will return a printer object. If not, it
1437 returns @code{None}.
1439 We recommend that you put your core pretty-printers into a Python
1440 package. If your pretty-printers are for use with a library, we
1441 further recommend embedding a version number into the package name.
1442 This practice will enable @value{GDBN} to load multiple versions of
1443 your pretty-printers at the same time, because they will have
1446 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1447 can be evaluated multiple times without changing its meaning. An
1448 ideal auto-load file will consist solely of @code{import}s of your
1449 printer modules, followed by a call to a register pretty-printers with
1450 the current objfile.
1452 Taken as a whole, this approach will scale nicely to multiple
1453 inferiors, each potentially using a different library version.
1454 Embedding a version number in the Python package name will ensure that
1455 @value{GDBN} is able to load both sets of printers simultaneously.
1456 Then, because the search for pretty-printers is done by objfile, and
1457 because your auto-loaded code took care to register your library's
1458 printers with a specific objfile, @value{GDBN} will find the correct
1459 printers for the specific version of the library used by each
1462 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1463 this code might appear in @code{gdb.libstdcxx.v6}:
1466 def register_printers(objfile):
1467 objfile.pretty_printers.append(str_lookup_function)
1471 And then the corresponding contents of the auto-load file would be:
1474 import gdb.libstdcxx.v6
1475 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1478 The previous example illustrates a basic pretty-printer.
1479 There are a few things that can be improved on.
1480 The printer doesn't have a name, making it hard to identify in a
1481 list of installed printers. The lookup function has a name, but
1482 lookup functions can have arbitrary, even identical, names.
1484 Second, the printer only handles one type, whereas a library typically has
1485 several types. One could install a lookup function for each desired type
1486 in the library, but one could also have a single lookup function recognize
1487 several types. The latter is the conventional way this is handled.
1488 If a pretty-printer can handle multiple data types, then its
1489 @dfn{subprinters} are the printers for the individual data types.
1491 The @code{gdb.printing} module provides a formal way of solving these
1492 problems (@pxref{gdb.printing}).
1493 Here is another example that handles multiple types.
1495 These are the types we are going to pretty-print:
1498 struct foo @{ int a, b; @};
1499 struct bar @{ struct foo x, y; @};
1502 Here are the printers:
1506 """Print a foo object."""
1508 def __init__(self, val):
1511 def to_string(self):
1512 return ("a=<" + str(self.val["a"]) +
1513 "> b=<" + str(self.val["b"]) + ">")
1516 """Print a bar object."""
1518 def __init__(self, val):
1521 def to_string(self):
1522 return ("x=<" + str(self.val["x"]) +
1523 "> y=<" + str(self.val["y"]) + ">")
1526 This example doesn't need a lookup function, that is handled by the
1527 @code{gdb.printing} module. Instead a function is provided to build up
1528 the object that handles the lookup.
1533 def build_pretty_printer():
1534 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1536 pp.add_printer('foo', '^foo$', fooPrinter)
1537 pp.add_printer('bar', '^bar$', barPrinter)
1541 And here is the autoload support:
1546 gdb.printing.register_pretty_printer(
1547 gdb.current_objfile(),
1548 my_library.build_pretty_printer())
1551 Finally, when this printer is loaded into @value{GDBN}, here is the
1552 corresponding output of @samp{info pretty-printer}:
1555 (gdb) info pretty-printer
1562 @node Type Printing API
1563 @subsubsection Type Printing API
1564 @cindex type printing API for Python
1566 @value{GDBN} provides a way for Python code to customize type display.
1567 This is mainly useful for substituting canonical typedef names for
1570 @cindex type printer
1571 A @dfn{type printer} is just a Python object conforming to a certain
1572 protocol. A simple base class implementing the protocol is provided;
1573 see @ref{gdb.types}. A type printer must supply at least:
1575 @defivar type_printer enabled
1576 A boolean which is True if the printer is enabled, and False
1577 otherwise. This is manipulated by the @code{enable type-printer}
1578 and @code{disable type-printer} commands.
1581 @defivar type_printer name
1582 The name of the type printer. This must be a string. This is used by
1583 the @code{enable type-printer} and @code{disable type-printer}
1587 @defmethod type_printer instantiate (self)
1588 This is called by @value{GDBN} at the start of type-printing. It is
1589 only called if the type printer is enabled. This method must return a
1590 new object that supplies a @code{recognize} method, as described below.
1594 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1595 will compute a list of type recognizers. This is done by iterating
1596 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1597 followed by the per-progspace type printers (@pxref{Progspaces In
1598 Python}), and finally the global type printers.
1600 @value{GDBN} will call the @code{instantiate} method of each enabled
1601 type printer. If this method returns @code{None}, then the result is
1602 ignored; otherwise, it is appended to the list of recognizers.
1604 Then, when @value{GDBN} is going to display a type name, it iterates
1605 over the list of recognizers. For each one, it calls the recognition
1606 function, stopping if the function returns a non-@code{None} value.
1607 The recognition function is defined as:
1609 @defmethod type_recognizer recognize (self, type)
1610 If @var{type} is not recognized, return @code{None}. Otherwise,
1611 return a string which is to be printed as the name of @var{type}.
1612 The @var{type} argument will be an instance of @code{gdb.Type}
1613 (@pxref{Types In Python}).
1616 @value{GDBN} uses this two-pass approach so that type printers can
1617 efficiently cache information without holding on to it too long. For
1618 example, it can be convenient to look up type information in a type
1619 printer and hold it for a recognizer's lifetime; if a single pass were
1620 done then type printers would have to make use of the event system in
1621 order to avoid holding information that could become stale as the
1624 @node Frame Filter API
1625 @subsubsection Filtering Frames
1626 @cindex frame filters api
1628 Frame filters are Python objects that manipulate the visibility of a
1629 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1632 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1633 commands (@pxref{GDB/MI}), those that return a collection of frames
1634 are affected. The commands that work with frame filters are:
1636 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1637 @code{-stack-list-frames}
1638 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1639 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1640 -stack-list-variables command}), @code{-stack-list-arguments}
1641 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1642 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1643 -stack-list-locals command}).
1645 A frame filter works by taking an iterator as an argument, applying
1646 actions to the contents of that iterator, and returning another
1647 iterator (or, possibly, the same iterator it was provided in the case
1648 where the filter does not perform any operations). Typically, frame
1649 filters utilize tools such as the Python's @code{itertools} module to
1650 work with and create new iterators from the source iterator.
1651 Regardless of how a filter chooses to apply actions, it must not alter
1652 the underlying @value{GDBN} frame or frames, or attempt to alter the
1653 call-stack within @value{GDBN}. This preserves data integrity within
1654 @value{GDBN}. Frame filters are executed on a priority basis and care
1655 should be taken that some frame filters may have been executed before,
1656 and that some frame filters will be executed after.
1658 An important consideration when designing frame filters, and well
1659 worth reflecting upon, is that frame filters should avoid unwinding
1660 the call stack if possible. Some stacks can run very deep, into the
1661 tens of thousands in some cases. To search every frame when a frame
1662 filter executes may be too expensive at that step. The frame filter
1663 cannot know how many frames it has to iterate over, and it may have to
1664 iterate through them all. This ends up duplicating effort as
1665 @value{GDBN} performs this iteration when it prints the frames. If
1666 the filter can defer unwinding frames until frame decorators are
1667 executed, after the last filter has executed, it should. @xref{Frame
1668 Decorator API}, for more information on decorators. Also, there are
1669 examples for both frame decorators and filters in later chapters.
1670 @xref{Writing a Frame Filter}, for more information.
1672 The Python dictionary @code{gdb.frame_filters} contains key/object
1673 pairings that comprise a frame filter. Frame filters in this
1674 dictionary are called @code{global} frame filters, and they are
1675 available when debugging all inferiors. These frame filters must
1676 register with the dictionary directly. In addition to the
1677 @code{global} dictionary, there are other dictionaries that are loaded
1678 with different inferiors via auto-loading (@pxref{Python
1679 Auto-loading}). The two other areas where frame filter dictionaries
1680 can be found are: @code{gdb.Progspace} which contains a
1681 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1682 object which also contains a @code{frame_filters} dictionary
1685 When a command is executed from @value{GDBN} that is compatible with
1686 frame filters, @value{GDBN} combines the @code{global},
1687 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1688 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1689 several frames, and thus several object files, might be in use.
1690 @value{GDBN} then prunes any frame filter whose @code{enabled}
1691 attribute is @code{False}. This pruned list is then sorted according
1692 to the @code{priority} attribute in each filter.
1694 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1695 creates an iterator which wraps each frame in the call stack in a
1696 @code{FrameDecorator} object, and calls each filter in order. The
1697 output from the previous filter will always be the input to the next
1700 Frame filters have a mandatory interface which each frame filter must
1701 implement, defined here:
1703 @defun FrameFilter.filter (iterator)
1704 @value{GDBN} will call this method on a frame filter when it has
1705 reached the order in the priority list for that filter.
1707 For example, if there are four frame filters:
1718 The order that the frame filters will be called is:
1721 Filter3 -> Filter2 -> Filter1 -> Filter4
1724 Note that the output from @code{Filter3} is passed to the input of
1725 @code{Filter2}, and so on.
1727 This @code{filter} method is passed a Python iterator. This iterator
1728 contains a sequence of frame decorators that wrap each
1729 @code{gdb.Frame}, or a frame decorator that wraps another frame
1730 decorator. The first filter that is executed in the sequence of frame
1731 filters will receive an iterator entirely comprised of default
1732 @code{FrameDecorator} objects. However, after each frame filter is
1733 executed, the previous frame filter may have wrapped some or all of
1734 the frame decorators with their own frame decorator. As frame
1735 decorators must also conform to a mandatory interface, these
1736 decorators can be assumed to act in a uniform manner (@pxref{Frame
1739 This method must return an object conforming to the Python iterator
1740 protocol. Each item in the iterator must be an object conforming to
1741 the frame decorator interface. If a frame filter does not wish to
1742 perform any operations on this iterator, it should return that
1745 This method is not optional. If it does not exist, @value{GDBN} will
1746 raise and print an error.
1749 @defvar FrameFilter.name
1750 The @code{name} attribute must be Python string which contains the
1751 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1752 Management}). This attribute may contain any combination of letters
1753 or numbers. Care should be taken to ensure that it is unique. This
1754 attribute is mandatory.
1757 @defvar FrameFilter.enabled
1758 The @code{enabled} attribute must be Python boolean. This attribute
1759 indicates to @value{GDBN} whether the frame filter is enabled, and
1760 should be considered when frame filters are executed. If
1761 @code{enabled} is @code{True}, then the frame filter will be executed
1762 when any of the backtrace commands detailed earlier in this chapter
1763 are executed. If @code{enabled} is @code{False}, then the frame
1764 filter will not be executed. This attribute is mandatory.
1767 @defvar FrameFilter.priority
1768 The @code{priority} attribute must be Python integer. This attribute
1769 controls the order of execution in relation to other frame filters.
1770 There are no imposed limits on the range of @code{priority} other than
1771 it must be a valid integer. The higher the @code{priority} attribute,
1772 the sooner the frame filter will be executed in relation to other
1773 frame filters. Although @code{priority} can be negative, it is
1774 recommended practice to assume zero is the lowest priority that a
1775 frame filter can be assigned. Frame filters that have the same
1776 priority are executed in unsorted order in that priority slot. This
1777 attribute is mandatory. 100 is a good default priority.
1780 @node Frame Decorator API
1781 @subsubsection Decorating Frames
1782 @cindex frame decorator api
1784 Frame decorators are sister objects to frame filters (@pxref{Frame
1785 Filter API}). Frame decorators are applied by a frame filter and can
1786 only be used in conjunction with frame filters.
1788 The purpose of a frame decorator is to customize the printed content
1789 of each @code{gdb.Frame} in commands where frame filters are executed.
1790 This concept is called decorating a frame. Frame decorators decorate
1791 a @code{gdb.Frame} with Python code contained within each API call.
1792 This separates the actual data contained in a @code{gdb.Frame} from
1793 the decorated data produced by a frame decorator. This abstraction is
1794 necessary to maintain integrity of the data contained in each
1797 Frame decorators have a mandatory interface, defined below.
1799 @value{GDBN} already contains a frame decorator called
1800 @code{FrameDecorator}. This contains substantial amounts of
1801 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
1802 recommended that other frame decorators inherit and extend this
1803 object, and only to override the methods needed.
1805 @tindex gdb.FrameDecorator
1806 @code{FrameDecorator} is defined in the Python module
1807 @code{gdb.FrameDecorator}, so your code can import it like:
1809 from gdb.FrameDecorator import FrameDecorator
1812 @defun FrameDecorator.elided (self)
1814 The @code{elided} method groups frames together in a hierarchical
1815 system. An example would be an interpreter, where multiple low-level
1816 frames make up a single call in the interpreted language. In this
1817 example, the frame filter would elide the low-level frames and present
1818 a single high-level frame, representing the call in the interpreted
1819 language, to the user.
1821 The @code{elided} function must return an iterable and this iterable
1822 must contain the frames that are being elided wrapped in a suitable
1823 frame decorator. If no frames are being elided this function may
1824 return an empty iterable, or @code{None}. Elided frames are indented
1825 from normal frames in a @code{CLI} backtrace, or in the case of
1826 @code{GDB/MI}, are placed in the @code{children} field of the eliding
1829 It is the frame filter's task to also filter out the elided frames from
1830 the source iterator. This will avoid printing the frame twice.
1833 @defun FrameDecorator.function (self)
1835 This method returns the name of the function in the frame that is to
1838 This method must return a Python string describing the function, or
1841 If this function returns @code{None}, @value{GDBN} will not print any
1842 data for this field.
1845 @defun FrameDecorator.address (self)
1847 This method returns the address of the frame that is to be printed.
1849 This method must return a Python numeric integer type of sufficient
1850 size to describe the address of the frame, or @code{None}.
1852 If this function returns a @code{None}, @value{GDBN} will not print
1853 any data for this field.
1856 @defun FrameDecorator.filename (self)
1858 This method returns the filename and path associated with this frame.
1860 This method must return a Python string containing the filename and
1861 the path to the object file backing the frame, or @code{None}.
1863 If this function returns a @code{None}, @value{GDBN} will not print
1864 any data for this field.
1867 @defun FrameDecorator.line (self):
1869 This method returns the line number associated with the current
1870 position within the function addressed by this frame.
1872 This method must return a Python integer type, or @code{None}.
1874 If this function returns a @code{None}, @value{GDBN} will not print
1875 any data for this field.
1878 @defun FrameDecorator.frame_args (self)
1881 This method must return an iterable, or @code{None}. Returning an
1882 empty iterable, or @code{None} means frame arguments will not be
1883 printed for this frame. This iterable must contain objects that
1884 implement two methods, described here.
1886 This object must implement a @code{argument} method which takes a
1887 single @code{self} parameter and must return a @code{gdb.Symbol}
1888 (@pxref{Symbols In Python}), or a Python string. The object must also
1889 implement a @code{value} method which takes a single @code{self}
1890 parameter and must return a @code{gdb.Value} (@pxref{Values From
1891 Inferior}), a Python value, or @code{None}. If the @code{value}
1892 method returns @code{None}, and the @code{argument} method returns a
1893 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
1894 the @code{gdb.Symbol} automatically.
1899 class SymValueWrapper():
1901 def __init__(self, symbol, value):
1911 class SomeFrameDecorator()
1914 def frame_args(self):
1917 block = self.inferior_frame.block()
1921 # Iterate over all symbols in a block. Only add
1922 # symbols that are arguments.
1924 if not sym.is_argument:
1926 args.append(SymValueWrapper(sym,None))
1928 # Add example synthetic argument.
1929 args.append(SymValueWrapper(``foo'', 42))
1935 @defun FrameDecorator.frame_locals (self)
1937 This method must return an iterable or @code{None}. Returning an
1938 empty iterable, or @code{None} means frame local arguments will not be
1939 printed for this frame.
1941 The object interface, the description of the various strategies for
1942 reading frame locals, and the example are largely similar to those
1943 described in the @code{frame_args} function, (@pxref{frame_args,,The
1944 frame filter frame_args function}). Below is a modified example:
1947 class SomeFrameDecorator()
1950 def frame_locals(self):
1953 block = self.inferior_frame.block()
1957 # Iterate over all symbols in a block. Add all
1958 # symbols, except arguments.
1962 vars.append(SymValueWrapper(sym,None))
1964 # Add an example of a synthetic local variable.
1965 vars.append(SymValueWrapper(``bar'', 99))
1971 @defun FrameDecorator.inferior_frame (self):
1973 This method must return the underlying @code{gdb.Frame} that this
1974 frame decorator is decorating. @value{GDBN} requires the underlying
1975 frame for internal frame information to determine how to print certain
1976 values when printing a frame.
1979 @node Writing a Frame Filter
1980 @subsubsection Writing a Frame Filter
1981 @cindex writing a frame filter
1983 There are three basic elements that a frame filter must implement: it
1984 must correctly implement the documented interface (@pxref{Frame Filter
1985 API}), it must register itself with @value{GDBN}, and finally, it must
1986 decide if it is to work on the data provided by @value{GDBN}. In all
1987 cases, whether it works on the iterator or not, each frame filter must
1988 return an iterator. A bare-bones frame filter follows the pattern in
1989 the following example.
1994 class FrameFilter():
1997 # Frame filter attribute creation.
1999 # 'name' is the name of the filter that GDB will display.
2001 # 'priority' is the priority of the filter relative to other
2004 # 'enabled' is a boolean that indicates whether this filter is
2005 # enabled and should be executed.
2011 # Register this frame filter with the global frame_filters
2013 gdb.frame_filters[self.name] = self
2015 def filter(self, frame_iter):
2016 # Just return the iterator.
2020 The frame filter in the example above implements the three
2021 requirements for all frame filters. It implements the API, self
2022 registers, and makes a decision on the iterator (in this case, it just
2023 returns the iterator untouched).
2025 The first step is attribute creation and assignment, and as shown in
2026 the comments the filter assigns the following attributes: @code{name},
2027 @code{priority} and whether the filter should be enabled with the
2028 @code{enabled} attribute.
2030 The second step is registering the frame filter with the dictionary or
2031 dictionaries that the frame filter has interest in. As shown in the
2032 comments, this filter just registers itself with the global dictionary
2033 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
2034 is a dictionary that is initialized in the @code{gdb} module when
2035 @value{GDBN} starts. What dictionary a filter registers with is an
2036 important consideration. Generally, if a filter is specific to a set
2037 of code, it should be registered either in the @code{objfile} or
2038 @code{progspace} dictionaries as they are specific to the program
2039 currently loaded in @value{GDBN}. The global dictionary is always
2040 present in @value{GDBN} and is never unloaded. Any filters registered
2041 with the global dictionary will exist until @value{GDBN} exits. To
2042 avoid filters that may conflict, it is generally better to register
2043 frame filters against the dictionaries that more closely align with
2044 the usage of the filter currently in question. @xref{Python
2045 Auto-loading}, for further information on auto-loading Python scripts.
2047 @value{GDBN} takes a hands-off approach to frame filter registration,
2048 therefore it is the frame filter's responsibility to ensure
2049 registration has occurred, and that any exceptions are handled
2050 appropriately. In particular, you may wish to handle exceptions
2051 relating to Python dictionary key uniqueness. It is mandatory that
2052 the dictionary key is the same as frame filter's @code{name}
2053 attribute. When a user manages frame filters (@pxref{Frame Filter
2054 Management}), the names @value{GDBN} will display are those contained
2055 in the @code{name} attribute.
2057 The final step of this example is the implementation of the
2058 @code{filter} method. As shown in the example comments, we define the
2059 @code{filter} method and note that the method must take an iterator,
2060 and also must return an iterator. In this bare-bones example, the
2061 frame filter is not very useful as it just returns the iterator
2062 untouched. However this is a valid operation for frame filters that
2063 have the @code{enabled} attribute set, but decide not to operate on
2066 In the next example, the frame filter operates on all frames and
2067 utilizes a frame decorator to perform some work on the frames.
2068 @xref{Frame Decorator API}, for further information on the frame
2069 decorator interface.
2071 This example works on inlined frames. It highlights frames which are
2072 inlined by tagging them with an ``[inlined]'' tag. By applying a
2073 frame decorator to all frames with the Python @code{itertools imap}
2074 method, the example defers actions to the frame decorator. Frame
2075 decorators are only processed when @value{GDBN} prints the backtrace.
2077 This introduces a new decision making topic: whether to perform
2078 decision making operations at the filtering step, or at the printing
2079 step. In this example's approach, it does not perform any filtering
2080 decisions at the filtering step beyond mapping a frame decorator to
2081 each frame. This allows the actual decision making to be performed
2082 when each frame is printed. This is an important consideration, and
2083 well worth reflecting upon when designing a frame filter. An issue
2084 that frame filters should avoid is unwinding the stack if possible.
2085 Some stacks can run very deep, into the tens of thousands in some
2086 cases. To search every frame to determine if it is inlined ahead of
2087 time may be too expensive at the filtering step. The frame filter
2088 cannot know how many frames it has to iterate over, and it would have
2089 to iterate through them all. This ends up duplicating effort as
2090 @value{GDBN} performs this iteration when it prints the frames.
2092 In this example decision making can be deferred to the printing step.
2093 As each frame is printed, the frame decorator can examine each frame
2094 in turn when @value{GDBN} iterates. From a performance viewpoint,
2095 this is the most appropriate decision to make as it avoids duplicating
2096 the effort that the printing step would undertake anyway. Also, if
2097 there are many frame filters unwinding the stack during filtering, it
2098 can substantially delay the printing of the backtrace which will
2099 result in large memory usage, and a poor user experience.
2102 class InlineFilter():
2105 self.name = "InlinedFrameFilter"
2108 gdb.frame_filters[self.name] = self
2110 def filter(self, frame_iter):
2111 frame_iter = itertools.imap(InlinedFrameDecorator,
2116 This frame filter is somewhat similar to the earlier example, except
2117 that the @code{filter} method applies a frame decorator object called
2118 @code{InlinedFrameDecorator} to each element in the iterator. The
2119 @code{imap} Python method is light-weight. It does not proactively
2120 iterate over the iterator, but rather creates a new iterator which
2121 wraps the existing one.
2123 Below is the frame decorator for this example.
2126 class InlinedFrameDecorator(FrameDecorator):
2128 def __init__(self, fobj):
2129 super(InlinedFrameDecorator, self).__init__(fobj)
2132 frame = fobj.inferior_frame()
2133 name = str(frame.name())
2135 if frame.type() == gdb.INLINE_FRAME:
2136 name = name + " [inlined]"
2141 This frame decorator only defines and overrides the @code{function}
2142 method. It lets the supplied @code{FrameDecorator}, which is shipped
2143 with @value{GDBN}, perform the other work associated with printing
2146 The combination of these two objects create this output from a
2150 #0 0x004004e0 in bar () at inline.c:11
2151 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2152 #2 0x00400566 in main () at inline.c:31
2155 So in the case of this example, a frame decorator is applied to all
2156 frames, regardless of whether they may be inlined or not. As
2157 @value{GDBN} iterates over the iterator produced by the frame filters,
2158 @value{GDBN} executes each frame decorator which then makes a decision
2159 on what to print in the @code{function} callback. Using a strategy
2160 like this is a way to defer decisions on the frame content to printing
2163 @subheading Eliding Frames
2165 It might be that the above example is not desirable for representing
2166 inlined frames, and a hierarchical approach may be preferred. If we
2167 want to hierarchically represent frames, the @code{elided} frame
2168 decorator interface might be preferable.
2170 This example approaches the issue with the @code{elided} method. This
2171 example is quite long, but very simplistic. It is out-of-scope for
2172 this section to write a complete example that comprehensively covers
2173 all approaches of finding and printing inlined frames. However, this
2174 example illustrates the approach an author might use.
2176 This example comprises of three sections.
2179 class InlineFrameFilter():
2182 self.name = "InlinedFrameFilter"
2185 gdb.frame_filters[self.name] = self
2187 def filter(self, frame_iter):
2188 return ElidingInlineIterator(frame_iter)
2191 This frame filter is very similar to the other examples. The only
2192 difference is this frame filter is wrapping the iterator provided to
2193 it (@code{frame_iter}) with a custom iterator called
2194 @code{ElidingInlineIterator}. This again defers actions to when
2195 @value{GDBN} prints the backtrace, as the iterator is not traversed
2198 The iterator for this example is as follows. It is in this section of
2199 the example where decisions are made on the content of the backtrace.
2202 class ElidingInlineIterator:
2203 def __init__(self, ii):
2204 self.input_iterator = ii
2210 frame = next(self.input_iterator)
2212 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2216 eliding_frame = next(self.input_iterator)
2217 except StopIteration:
2219 return ElidingFrameDecorator(eliding_frame, [frame])
2222 This iterator implements the Python iterator protocol. When the
2223 @code{next} function is called (when @value{GDBN} prints each frame),
2224 the iterator checks if this frame decorator, @code{frame}, is wrapping
2225 an inlined frame. If it is not, it returns the existing frame decorator
2226 untouched. If it is wrapping an inlined frame, it assumes that the
2227 inlined frame was contained within the next oldest frame,
2228 @code{eliding_frame}, which it fetches. It then creates and returns a
2229 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2230 elided frame, and the eliding frame.
2233 class ElidingInlineDecorator(FrameDecorator):
2235 def __init__(self, frame, elided_frames):
2236 super(ElidingInlineDecorator, self).__init__(frame)
2238 self.elided_frames = elided_frames
2241 return iter(self.elided_frames)
2244 This frame decorator overrides one function and returns the inlined
2245 frame in the @code{elided} method. As before it lets
2246 @code{FrameDecorator} do the rest of the work involved in printing
2247 this frame. This produces the following output.
2250 #0 0x004004e0 in bar () at inline.c:11
2251 #2 0x00400529 in main () at inline.c:25
2252 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2255 In that output, @code{max} which has been inlined into @code{main} is
2256 printed hierarchically. Another approach would be to combine the
2257 @code{function} method, and the @code{elided} method to both print a
2258 marker in the inlined frame, and also show the hierarchical
2261 @node Unwinding Frames in Python
2262 @subsubsection Unwinding Frames in Python
2263 @cindex unwinding frames in Python
2265 In @value{GDBN} terminology ``unwinding'' is the process of finding
2266 the previous frame (that is, caller's) from the current one. An
2267 unwinder has three methods. The first one checks if it can handle
2268 given frame (``sniff'' it). For the frames it can sniff an unwinder
2269 provides two additional methods: it can return frame's ID, and it can
2270 fetch registers from the previous frame. A running @value{GDBN}
2271 mantains a list of the unwinders and calls each unwinder's sniffer in
2272 turn until it finds the one that recognizes the current frame. There
2273 is an API to register an unwinder.
2275 The unwinders that come with @value{GDBN} handle standard frames.
2276 However, mixed language applications (for example, an application
2277 running Java Virtual Machine) sometimes use frame layouts that cannot
2278 be handled by the @value{GDBN} unwinders. You can write Python code
2279 that can handle such custom frames.
2281 You implement a frame unwinder in Python as a class with which has two
2282 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2283 a single method @code{__call__}, which examines a given frame and
2284 returns an object (an instance of @code{gdb.UnwindInfo class)}
2285 describing it. If an unwinder does not recognize a frame, it should
2286 return @code{None}. The code in @value{GDBN} that enables writing
2287 unwinders in Python uses this object to return frame's ID and previous
2288 frame registers when @value{GDBN} core asks for them.
2290 An unwinder should do as little work as possible. Some otherwise
2291 innocuous operations can cause problems (even crashes, as this code is
2292 not not well-hardened yet). For example, making an inferior call from
2293 an unwinder is unadvisable, as an inferior call will reset
2294 @value{GDBN}'s stack unwinding process, potentially causing re-entrant
2297 @subheading Unwinder Input
2299 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2300 provides a method to read frame's registers:
2302 @defun PendingFrame.read_register (reg)
2303 This method returns the contents of the register @var{reg} in the
2304 frame as a @code{gdb.Value} object. @var{reg} can be either a
2305 register number or a register name; the values are platform-specific.
2306 They are usually found in the corresponding
2307 @file{@var{platform}-tdep.h} file in the @value{GDBN} source tree. If
2308 @var{reg} does not name a register for the current architecture, this
2309 method will throw an exception.
2311 Note that this method will always return a @code{gdb.Value} for a
2312 valid register name. This does not mean that the value will be valid.
2313 For example, you may request a register that an earlier unwinder could
2314 not unwind---the value will be unavailable. Instead, the
2315 @code{gdb.Value} returned from this method will be lazy; that is, its
2316 underlying bits will not be fetched until it is first used. So,
2317 attempting to use such a value will cause an exception at the point of
2320 The type of the returned @code{gdb.Value} depends on the register and
2321 the architecture. It is common for registers to have a scalar type,
2322 like @code{long long}; but many other types are possible, such as
2323 pointer, pointer-to-function, floating point or vector types.
2326 It also provides a factory method to create a @code{gdb.UnwindInfo}
2327 instance to be returned to @value{GDBN}:
2329 @defun PendingFrame.create_unwind_info (frame_id)
2330 Returns a new @code{gdb.UnwindInfo} instance identified by given
2331 @var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2332 using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2333 determine which function will be used, as follows:
2337 The frame is identified by the given stack address and PC. The stack
2338 address must be chosen so that it is constant throughout the lifetime
2339 of the frame, so a typical choice is the value of the stack pointer at
2340 the start of the function---in the DWARF standard, this would be the
2341 ``Call Frame Address''.
2343 This is the most common case by far. The other cases are documented
2344 for completeness but are only useful in specialized situations.
2346 @item sp, pc, special
2347 The frame is identified by the stack address, the PC, and a
2348 ``special'' address. The special address is used on architectures
2349 that can have frames that do not change the stack, but which are still
2350 distinct, for example the IA-64, which has a second stack for
2351 registers. Both @var{sp} and @var{special} must be constant
2352 throughout the lifetime of the frame.
2355 The frame is identified by the stack address only. Any other stack
2356 frame with a matching @var{sp} will be considered to match this frame.
2357 Inside gdb, this is called a ``wild frame''. You will never need
2361 Each attribute value should be an instance of @code{gdb.Value}.
2365 @subheading Unwinder Output: UnwindInfo
2367 Use @code{PendingFrame.create_unwind_info} method described above to
2368 create a @code{gdb.UnwindInfo} instance. Use the following method to
2369 specify caller registers that have been saved in this frame:
2371 @defun gdb.UnwindInfo.add_saved_register (reg, value)
2372 @var{reg} identifies the register. It can be a number or a name, just
2373 as for the @code{PendingFrame.read_register} method above.
2374 @var{value} is a register value (a @code{gdb.Value} object).
2377 @subheading Unwinder Skeleton Code
2379 @value{GDBN} comes with the module containing the base @code{Unwinder}
2380 class. Derive your unwinder class from it and structure the code as
2384 from gdb.unwinders import Unwinder
2386 class FrameId(object):
2387 def __init__(self, sp, pc):
2392 class MyUnwinder(Unwinder):
2394 supe(MyUnwinder, self).__init___(<expects unwinder name argument>)
2396 def __call__(pending_frame):
2397 if not <we recognize frame>:
2399 # Create UnwindInfo. Usually the frame is identified by the stack
2400 # pointer and the program counter.
2401 sp = pending_frame.read_register(<SP number>)
2402 pc = pending_frame.read_register(<PC number>)
2403 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2405 # Find the values of the registers in the caller's frame and
2406 # save them in the result:
2407 unwind_info.add_saved_register(<register>, <value>)
2410 # Return the result:
2415 @subheading Registering a Unwinder
2417 An object file, a program space, and the @value{GDBN} proper can have
2418 unwinders registered with it.
2420 The @code{gdb.unwinders} module provides the function to register a
2423 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2424 @var{locus} is specifies an object file or a program space to which
2425 @var{unwinder} is added. Passing @code{None} or @code{gdb} adds
2426 @var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
2427 added @var{unwinder} will be called before any other unwinder from the
2428 same locus. Two unwinders in the same locus cannot have the same
2429 name. An attempt to add a unwinder with already existing name raises
2430 an exception unless @var{replace} is @code{True}, in which case the
2431 old unwinder is deleted.
2434 @subheading Unwinder Precedence
2436 @value{GDBN} first calls the unwinders from all the object files in no
2437 particular order, then the unwinders from the current program space,
2438 and finally the unwinders from @value{GDBN}.
2440 @node Xmethods In Python
2441 @subsubsection Xmethods In Python
2442 @cindex xmethods in Python
2444 @dfn{Xmethods} are additional methods or replacements for existing
2445 methods of a C@t{++} class. This feature is useful for those cases
2446 where a method defined in C@t{++} source code could be inlined or
2447 optimized out by the compiler, making it unavailable to @value{GDBN}.
2448 For such cases, one can define an xmethod to serve as a replacement
2449 for the method defined in the C@t{++} source code. @value{GDBN} will
2450 then invoke the xmethod, instead of the C@t{++} method, to
2451 evaluate expressions. One can also use xmethods when debugging
2452 with core files. Moreover, when debugging live programs, invoking an
2453 xmethod need not involve running the inferior (which can potentially
2454 perturb its state). Hence, even if the C@t{++} method is available, it
2455 is better to use its replacement xmethod if one is defined.
2457 The xmethods feature in Python is available via the concepts of an
2458 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2459 implement an xmethod, one has to implement a matcher and a
2460 corresponding worker for it (more than one worker can be
2461 implemented, each catering to a different overloaded instance of the
2462 method). Internally, @value{GDBN} invokes the @code{match} method of a
2463 matcher to match the class type and method name. On a match, the
2464 @code{match} method returns a list of matching @emph{worker} objects.
2465 Each worker object typically corresponds to an overloaded instance of
2466 the xmethod. They implement a @code{get_arg_types} method which
2467 returns a sequence of types corresponding to the arguments the xmethod
2468 requires. @value{GDBN} uses this sequence of types to perform
2469 overload resolution and picks a winning xmethod worker. A winner
2470 is also selected from among the methods @value{GDBN} finds in the
2471 C@t{++} source code. Next, the winning xmethod worker and the
2472 winning C@t{++} method are compared to select an overall winner. In
2473 case of a tie between a xmethod worker and a C@t{++} method, the
2474 xmethod worker is selected as the winner. That is, if a winning
2475 xmethod worker is found to be equivalent to the winning C@t{++}
2476 method, then the xmethod worker is treated as a replacement for
2477 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2478 method. If the winning xmethod worker is the overall winner, then
2479 the corresponding xmethod is invoked via the @code{__call__} method
2480 of the worker object.
2482 If one wants to implement an xmethod as a replacement for an
2483 existing C@t{++} method, then they have to implement an equivalent
2484 xmethod which has exactly the same name and takes arguments of
2485 exactly the same type as the C@t{++} method. If the user wants to
2486 invoke the C@t{++} method even though a replacement xmethod is
2487 available for that method, then they can disable the xmethod.
2489 @xref{Xmethod API}, for API to implement xmethods in Python.
2490 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2493 @subsubsection Xmethod API
2496 The @value{GDBN} Python API provides classes, interfaces and functions
2497 to implement, register and manipulate xmethods.
2498 @xref{Xmethods In Python}.
2500 An xmethod matcher should be an instance of a class derived from
2501 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2502 object with similar interface and attributes. An instance of
2503 @code{XMethodMatcher} has the following attributes:
2506 The name of the matcher.
2510 A boolean value indicating whether the matcher is enabled or disabled.
2514 A list of named methods managed by the matcher. Each object in the list
2515 is an instance of the class @code{XMethod} defined in the module
2516 @code{gdb.xmethod}, or any object with the following attributes:
2521 Name of the xmethod which should be unique for each xmethod
2522 managed by the matcher.
2525 A boolean value indicating whether the xmethod is enabled or
2530 The class @code{XMethod} is a convenience class with same
2531 attributes as above along with the following constructor:
2533 @defun XMethod.__init__ (self, name)
2534 Constructs an enabled xmethod with name @var{name}.
2539 The @code{XMethodMatcher} class has the following methods:
2541 @defun XMethodMatcher.__init__ (self, name)
2542 Constructs an enabled xmethod matcher with name @var{name}. The
2543 @code{methods} attribute is initialized to @code{None}.
2546 @defun XMethodMatcher.match (self, class_type, method_name)
2547 Derived classes should override this method. It should return a
2548 xmethod worker object (or a sequence of xmethod worker
2549 objects) matching the @var{class_type} and @var{method_name}.
2550 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2551 is a string value. If the matcher manages named methods as listed in
2552 its @code{methods} attribute, then only those worker objects whose
2553 corresponding entries in the @code{methods} list are enabled should be
2557 An xmethod worker should be an instance of a class derived from
2558 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
2559 or support the following interface:
2561 @defun XMethodWorker.get_arg_types (self)
2562 This method returns a sequence of @code{gdb.Type} objects corresponding
2563 to the arguments that the xmethod takes. It can return an empty
2564 sequence or @code{None} if the xmethod does not take any arguments.
2565 If the xmethod takes a single argument, then a single
2566 @code{gdb.Type} object corresponding to it can be returned.
2569 @defun XMethodWorker.get_result_type (self, *args)
2570 This method returns a @code{gdb.Type} object representing the type
2571 of the result of invoking this xmethod.
2572 The @var{args} argument is the same tuple of arguments that would be
2573 passed to the @code{__call__} method of this worker.
2576 @defun XMethodWorker.__call__ (self, *args)
2577 This is the method which does the @emph{work} of the xmethod. The
2578 @var{args} arguments is the tuple of arguments to the xmethod. Each
2579 element in this tuple is a gdb.Value object. The first element is
2580 always the @code{this} pointer value.
2583 For @value{GDBN} to lookup xmethods, the xmethod matchers
2584 should be registered using the following function defined in the module
2587 @defun register_xmethod_matcher (locus, matcher, replace=False)
2588 The @code{matcher} is registered with @code{locus}, replacing an
2589 existing matcher with the same name as @code{matcher} if
2590 @code{replace} is @code{True}. @code{locus} can be a
2591 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
2592 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
2593 @code{None}. If it is @code{None}, then @code{matcher} is registered
2597 @node Writing an Xmethod
2598 @subsubsection Writing an Xmethod
2599 @cindex writing xmethods in Python
2601 Implementing xmethods in Python will require implementing xmethod
2602 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2603 the following C@t{++} class:
2609 MyClass (int a) : a_(a) @{ @}
2611 int geta (void) @{ return a_; @}
2612 int operator+ (int b);
2619 MyClass::operator+ (int b)
2626 Let us define two xmethods for the class @code{MyClass}, one
2627 replacing the method @code{geta}, and another adding an overloaded
2628 flavor of @code{operator+} which takes a @code{MyClass} argument (the
2629 C@t{++} code above already has an overloaded @code{operator+}
2630 which takes an @code{int} argument). The xmethod matcher can be
2634 class MyClass_geta(gdb.xmethod.XMethod):
2636 gdb.xmethod.XMethod.__init__(self, 'geta')
2638 def get_worker(self, method_name):
2639 if method_name == 'geta':
2640 return MyClassWorker_geta()
2643 class MyClass_sum(gdb.xmethod.XMethod):
2645 gdb.xmethod.XMethod.__init__(self, 'sum')
2647 def get_worker(self, method_name):
2648 if method_name == 'operator+':
2649 return MyClassWorker_plus()
2652 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2654 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2655 # List of methods 'managed' by this matcher
2656 self.methods = [MyClass_geta(), MyClass_sum()]
2658 def match(self, class_type, method_name):
2659 if class_type.tag != 'MyClass':
2662 for method in self.methods:
2664 worker = method.get_worker(method_name)
2666 workers.append(worker)
2672 Notice that the @code{match} method of @code{MyClassMatcher} returns
2673 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
2674 method, and a worker object of type @code{MyClassWorker_plus} for the
2675 @code{operator+} method. This is done indirectly via helper classes
2676 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
2677 @code{methods} attribute in a matcher as it is optional. However, if a
2678 matcher manages more than one xmethod, it is a good practice to list the
2679 xmethods in the @code{methods} attribute of the matcher. This will then
2680 facilitate enabling and disabling individual xmethods via the
2681 @code{enable/disable} commands. Notice also that a worker object is
2682 returned only if the corresponding entry in the @code{methods} attribute
2683 of the matcher is enabled.
2685 The implementation of the worker classes returned by the matcher setup
2686 above is as follows:
2689 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
2690 def get_arg_types(self):
2693 def get_result_type(self, obj):
2694 return gdb.lookup_type('int')
2696 def __call__(self, obj):
2700 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
2701 def get_arg_types(self):
2702 return gdb.lookup_type('MyClass')
2704 def get_result_type(self, obj):
2705 return gdb.lookup_type('int')
2707 def __call__(self, obj, other):
2708 return obj['a_'] + other['a_']
2711 For @value{GDBN} to actually lookup a xmethod, it has to be
2712 registered with it. The matcher defined above is registered with
2713 @value{GDBN} globally as follows:
2716 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
2719 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
2727 then, after loading the Python script defining the xmethod matchers
2728 and workers into @code{GDBN}, invoking the method @code{geta} or using
2729 the operator @code{+} on @code{obj} will invoke the xmethods
2740 Consider another example with a C++ template class:
2747 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
2748 ~MyTemplate () @{ delete [] data_; @}
2750 int footprint (void)
2752 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
2761 Let us implement an xmethod for the above class which serves as a
2762 replacement for the @code{footprint} method. The full code listing
2763 of the xmethod workers and xmethod matchers is as follows:
2766 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
2767 def __init__(self, class_type):
2768 self.class_type = class_type
2770 def get_arg_types(self):
2773 def get_result_type(self):
2774 return gdb.lookup_type('int')
2776 def __call__(self, obj):
2777 return (self.class_type.sizeof +
2779 self.class_type.template_argument(0).sizeof)
2782 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
2784 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
2786 def match(self, class_type, method_name):
2787 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
2789 method_name == 'footprint'):
2790 return MyTemplateWorker_footprint(class_type)
2793 Notice that, in this example, we have not used the @code{methods}
2794 attribute of the matcher as the matcher manages only one xmethod. The
2795 user can enable/disable this xmethod by enabling/disabling the matcher
2798 @node Inferiors In Python
2799 @subsubsection Inferiors In Python
2800 @cindex inferiors in Python
2802 @findex gdb.Inferior
2803 Programs which are being run under @value{GDBN} are called inferiors
2804 (@pxref{Inferiors and Programs}). Python scripts can access
2805 information about and manipulate inferiors controlled by @value{GDBN}
2806 via objects of the @code{gdb.Inferior} class.
2808 The following inferior-related functions are available in the @code{gdb}
2811 @defun gdb.inferiors ()
2812 Return a tuple containing all inferior objects.
2815 @defun gdb.selected_inferior ()
2816 Return an object representing the current inferior.
2819 A @code{gdb.Inferior} object has the following attributes:
2821 @defvar Inferior.num
2822 ID of inferior, as assigned by GDB.
2825 @defvar Inferior.pid
2826 Process ID of the inferior, as assigned by the underlying operating
2830 @defvar Inferior.was_attached
2831 Boolean signaling whether the inferior was created using `attach', or
2832 started by @value{GDBN} itself.
2835 A @code{gdb.Inferior} object has the following methods:
2837 @defun Inferior.is_valid ()
2838 Returns @code{True} if the @code{gdb.Inferior} object is valid,
2839 @code{False} if not. A @code{gdb.Inferior} object will become invalid
2840 if the inferior no longer exists within @value{GDBN}. All other
2841 @code{gdb.Inferior} methods will throw an exception if it is invalid
2842 at the time the method is called.
2845 @defun Inferior.threads ()
2846 This method returns a tuple holding all the threads which are valid
2847 when it is called. If there are no valid threads, the method will
2848 return an empty tuple.
2851 @findex Inferior.read_memory
2852 @defun Inferior.read_memory (address, length)
2853 Read @var{length} addressable memory units from the inferior, starting at
2854 @var{address}. Returns a buffer object, which behaves much like an array
2855 or a string. It can be modified and given to the
2856 @code{Inferior.write_memory} function. In Python 3, the return
2857 value is a @code{memoryview} object.
2860 @findex Inferior.write_memory
2861 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
2862 Write the contents of @var{buffer} to the inferior, starting at
2863 @var{address}. The @var{buffer} parameter must be a Python object
2864 which supports the buffer protocol, i.e., a string, an array or the
2865 object returned from @code{Inferior.read_memory}. If given, @var{length}
2866 determines the number of addressable memory units from @var{buffer} to be
2870 @findex gdb.search_memory
2871 @defun Inferior.search_memory (address, length, pattern)
2872 Search a region of the inferior memory starting at @var{address} with
2873 the given @var{length} using the search pattern supplied in
2874 @var{pattern}. The @var{pattern} parameter must be a Python object
2875 which supports the buffer protocol, i.e., a string, an array or the
2876 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
2877 containing the address where the pattern was found, or @code{None} if
2878 the pattern could not be found.
2881 @findex Inferior.thread_from_thread_handle
2882 @defun Inferior.thread_from_thread_handle (thread_handle)
2883 Return the thread object corresponding to @var{thread_handle}, a thread
2884 library specific data structure such as @code{pthread_t} for pthreads
2885 library implementations.
2888 @node Events In Python
2889 @subsubsection Events In Python
2890 @cindex inferior events in Python
2892 @value{GDBN} provides a general event facility so that Python code can be
2893 notified of various state changes, particularly changes that occur in
2896 An @dfn{event} is just an object that describes some state change. The
2897 type of the object and its attributes will vary depending on the details
2898 of the change. All the existing events are described below.
2900 In order to be notified of an event, you must register an event handler
2901 with an @dfn{event registry}. An event registry is an object in the
2902 @code{gdb.events} module which dispatches particular events. A registry
2903 provides methods to register and unregister event handlers:
2905 @defun EventRegistry.connect (object)
2906 Add the given callable @var{object} to the registry. This object will be
2907 called when an event corresponding to this registry occurs.
2910 @defun EventRegistry.disconnect (object)
2911 Remove the given @var{object} from the registry. Once removed, the object
2912 will no longer receive notifications of events.
2918 def exit_handler (event):
2919 print "event type: exit"
2920 print "exit code: %d" % (event.exit_code)
2922 gdb.events.exited.connect (exit_handler)
2925 In the above example we connect our handler @code{exit_handler} to the
2926 registry @code{events.exited}. Once connected, @code{exit_handler} gets
2927 called when the inferior exits. The argument @dfn{event} in this example is
2928 of type @code{gdb.ExitedEvent}. As you can see in the example the
2929 @code{ExitedEvent} object has an attribute which indicates the exit code of
2932 The following is a listing of the event registries that are available and
2933 details of the events they emit:
2938 Emits @code{gdb.ThreadEvent}.
2940 Some events can be thread specific when @value{GDBN} is running in non-stop
2941 mode. When represented in Python, these events all extend
2942 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
2943 events which are emitted by this or other modules might extend this event.
2944 Examples of these events are @code{gdb.BreakpointEvent} and
2945 @code{gdb.ContinueEvent}.
2947 @defvar ThreadEvent.inferior_thread
2948 In non-stop mode this attribute will be set to the specific thread which was
2949 involved in the emitted event. Otherwise, it will be set to @code{None}.
2952 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
2954 This event indicates that the inferior has been continued after a stop. For
2955 inherited attribute refer to @code{gdb.ThreadEvent} above.
2958 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
2959 @code{events.ExitedEvent} has two attributes:
2960 @defvar ExitedEvent.exit_code
2961 An integer representing the exit code, if available, which the inferior
2962 has returned. (The exit code could be unavailable if, for example,
2963 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
2964 the attribute does not exist.
2966 @defvar ExitedEvent.inferior
2967 A reference to the inferior which triggered the @code{exited} event.
2971 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
2973 Indicates that the inferior has stopped. All events emitted by this registry
2974 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
2975 will indicate the stopped thread when @value{GDBN} is running in non-stop
2976 mode. Refer to @code{gdb.ThreadEvent} above for more details.
2978 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
2980 This event indicates that the inferior or one of its threads has received as
2981 signal. @code{gdb.SignalEvent} has the following attributes:
2983 @defvar SignalEvent.stop_signal
2984 A string representing the signal received by the inferior. A list of possible
2985 signal values can be obtained by running the command @code{info signals} in
2986 the @value{GDBN} command prompt.
2989 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
2991 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
2992 been hit, and has the following attributes:
2994 @defvar BreakpointEvent.breakpoints
2995 A sequence containing references to all the breakpoints (type
2996 @code{gdb.Breakpoint}) that were hit.
2997 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
2999 @defvar BreakpointEvent.breakpoint
3000 A reference to the first breakpoint that was hit.
3001 This function is maintained for backward compatibility and is now deprecated
3002 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
3005 @item events.new_objfile
3006 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
3007 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
3009 @defvar NewObjFileEvent.new_objfile
3010 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
3011 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
3014 @item events.clear_objfiles
3015 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
3016 files for a program space has been reset.
3017 @code{gdb.ClearObjFilesEvent} has one attribute:
3019 @defvar ClearObjFilesEvent.progspace
3020 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
3021 been cleared. @xref{Progspaces In Python}.
3024 @item events.inferior_call
3025 Emits events just before and after a function in the inferior is
3026 called by @value{GDBN}. Before an inferior call, this emits an event
3027 of type @code{gdb.InferiorCallPreEvent}, and after an inferior call,
3028 this emits an event of type @code{gdb.InferiorCallPostEvent}.
3031 @tindex gdb.InferiorCallPreEvent
3032 @item @code{gdb.InferiorCallPreEvent}
3033 Indicates that a function in the inferior is about to be called.
3035 @defvar InferiorCallPreEvent.ptid
3036 The thread in which the call will be run.
3039 @defvar InferiorCallPreEvent.address
3040 The location of the function to be called.
3043 @tindex gdb.InferiorCallPostEvent
3044 @item @code{gdb.InferiorCallPostEvent}
3045 Indicates that a function in the inferior has just been called.
3047 @defvar InferiorCallPostEvent.ptid
3048 The thread in which the call was run.
3051 @defvar InferiorCallPostEvent.address
3052 The location of the function that was called.
3056 @item events.memory_changed
3057 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
3058 inferior has been modified by the @value{GDBN} user, for instance via a
3059 command like @w{@code{set *addr = value}}. The event has the following
3062 @defvar MemoryChangedEvent.address
3063 The start address of the changed region.
3066 @defvar MemoryChangedEvent.length
3067 Length in bytes of the changed region.
3070 @item events.register_changed
3071 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
3072 inferior has been modified by the @value{GDBN} user.
3074 @defvar RegisterChangedEvent.frame
3075 A gdb.Frame object representing the frame in which the register was modified.
3077 @defvar RegisterChangedEvent.regnum
3078 Denotes which register was modified.
3081 @item events.breakpoint_created
3082 This is emitted when a new breakpoint has been created. The argument
3083 that is passed is the new @code{gdb.Breakpoint} object.
3085 @item events.breakpoint_modified
3086 This is emitted when a breakpoint has been modified in some way. The
3087 argument that is passed is the new @code{gdb.Breakpoint} object.
3089 @item events.breakpoint_deleted
3090 This is emitted when a breakpoint has been deleted. The argument that
3091 is passed is the @code{gdb.Breakpoint} object. When this event is
3092 emitted, the @code{gdb.Breakpoint} object will already be in its
3093 invalid state; that is, the @code{is_valid} method will return
3096 @item events.before_prompt
3097 This event carries no payload. It is emitted each time @value{GDBN}
3098 presents a prompt to the user.
3100 @item events.new_inferior
3101 This is emitted when a new inferior is created. Note that the
3102 inferior is not necessarily running; in fact, it may not even have an
3103 associated executable.
3105 The event is of type @code{gdb.NewInferiorEvent}. This has a single
3108 @defvar NewInferiorEvent.inferior
3109 The new inferior, a @code{gdb.Inferior} object.
3112 @item events.inferior_deleted
3113 This is emitted when an inferior has been deleted. Note that this is
3114 not the same as process exit; it is notified when the inferior itself
3115 is removed, say via @code{remove-inferiors}.
3117 The event is of type @code{gdb.InferiorDeletedEvent}. This has a single
3120 @defvar NewInferiorEvent.inferior
3121 The inferior that is being removed, a @code{gdb.Inferior} object.
3124 @item events.new_thread
3125 This is emitted when @value{GDBN} notices a new thread. The event is of
3126 type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}.
3127 This has a single attribute:
3129 @defvar NewThreadEvent.inferior_thread
3135 @node Threads In Python
3136 @subsubsection Threads In Python
3137 @cindex threads in python
3139 @findex gdb.InferiorThread
3140 Python scripts can access information about, and manipulate inferior threads
3141 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
3143 The following thread-related functions are available in the @code{gdb}
3146 @findex gdb.selected_thread
3147 @defun gdb.selected_thread ()
3148 This function returns the thread object for the selected thread. If there
3149 is no selected thread, this will return @code{None}.
3152 A @code{gdb.InferiorThread} object has the following attributes:
3154 @defvar InferiorThread.name
3155 The name of the thread. If the user specified a name using
3156 @code{thread name}, then this returns that name. Otherwise, if an
3157 OS-supplied name is available, then it is returned. Otherwise, this
3158 returns @code{None}.
3160 This attribute can be assigned to. The new value must be a string
3161 object, which sets the new name, or @code{None}, which removes any
3162 user-specified thread name.
3165 @defvar InferiorThread.num
3166 The per-inferior number of the thread, as assigned by GDB.
3169 @defvar InferiorThread.global_num
3170 The global ID of the thread, as assigned by GDB. You can use this to
3171 make Python breakpoints thread-specific, for example
3172 (@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
3175 @defvar InferiorThread.ptid
3176 ID of the thread, as assigned by the operating system. This attribute is a
3177 tuple containing three integers. The first is the Process ID (PID); the second
3178 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
3179 Either the LWPID or TID may be 0, which indicates that the operating system
3180 does not use that identifier.
3183 @defvar InferiorThread.inferior
3184 The inferior this thread belongs to. This attribute is represented as
3185 a @code{gdb.Inferior} object. This attribute is not writable.
3188 A @code{gdb.InferiorThread} object has the following methods:
3190 @defun InferiorThread.is_valid ()
3191 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
3192 @code{False} if not. A @code{gdb.InferiorThread} object will become
3193 invalid if the thread exits, or the inferior that the thread belongs
3194 is deleted. All other @code{gdb.InferiorThread} methods will throw an
3195 exception if it is invalid at the time the method is called.
3198 @defun InferiorThread.switch ()
3199 This changes @value{GDBN}'s currently selected thread to the one represented
3203 @defun InferiorThread.is_stopped ()
3204 Return a Boolean indicating whether the thread is stopped.
3207 @defun InferiorThread.is_running ()
3208 Return a Boolean indicating whether the thread is running.
3211 @defun InferiorThread.is_exited ()
3212 Return a Boolean indicating whether the thread is exited.
3215 @node Recordings In Python
3216 @subsubsection Recordings In Python
3217 @cindex recordings in python
3219 The following recordings-related functions
3220 (@pxref{Process Record and Replay}) are available in the @code{gdb}
3223 @defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
3224 Start a recording using the given @var{method} and @var{format}. If
3225 no @var{format} is given, the default format for the recording method
3226 is used. If no @var{method} is given, the default method will be used.
3227 Returns a @code{gdb.Record} object on success. Throw an exception on
3230 The following strings can be passed as @var{method}:
3236 @code{"btrace"}: Possible values for @var{format}: @code{"pt"},
3237 @code{"bts"} or leave out for default format.
3241 @defun gdb.current_recording ()
3242 Access a currently running recording. Return a @code{gdb.Record}
3243 object on success. Return @code{None} if no recording is currently
3247 @defun gdb.stop_recording ()
3248 Stop the current recording. Throw an exception if no recording is
3249 currently active. All record objects become invalid after this call.
3252 A @code{gdb.Record} object has the following attributes:
3254 @defvar Record.method
3255 A string with the current recording method, e.g.@: @code{full} or
3259 @defvar Record.format
3260 A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
3264 @defvar Record.begin
3265 A method specific instruction object representing the first instruction
3270 A method specific instruction object representing the current
3271 instruction, that is not actually part of the recording.
3274 @defvar Record.replay_position
3275 The instruction representing the current replay position. If there is
3276 no replay active, this will be @code{None}.
3279 @defvar Record.instruction_history
3280 A list with all recorded instructions.
3283 @defvar Record.function_call_history
3284 A list with all recorded function call segments.
3287 A @code{gdb.Record} object has the following methods:
3289 @defun Record.goto (instruction)
3290 Move the replay position to the given @var{instruction}.
3293 The common @code{gdb.Instruction} class that recording method specific
3294 instruction objects inherit from, has the following attributes:
3296 @defvar Instruction.pc
3297 An integer representing this instruction's address.
3300 @defvar Instruction.data
3301 A buffer with the raw instruction data. In Python 3, the return value is a
3302 @code{memoryview} object.
3305 @defvar Instruction.decoded
3306 A human readable string with the disassembled instruction.
3309 @defvar Instruction.size
3310 The size of the instruction in bytes.
3313 Additionally @code{gdb.RecordInstruction} has the following attributes:
3315 @defvar RecordInstruction.number
3316 An integer identifying this instruction. @code{number} corresponds to
3317 the numbers seen in @code{record instruction-history}
3318 (@pxref{Process Record and Replay}).
3321 @defvar RecordInstruction.sal
3322 A @code{gdb.Symtab_and_line} object representing the associated symtab
3323 and line of this instruction. May be @code{None} if no debug information is
3327 @defvar RecordInstruction.is_speculative
3328 A boolean indicating whether the instruction was executed speculatively.
3331 If an error occured during recording or decoding a recording, this error is
3332 represented by a @code{gdb.RecordGap} object in the instruction list. It has
3333 the following attributes:
3335 @defvar RecordGap.number
3336 An integer identifying this gap. @code{number} corresponds to the numbers seen
3337 in @code{record instruction-history} (@pxref{Process Record and Replay}).
3340 @defvar RecordGap.error_code
3341 A numerical representation of the reason for the gap. The value is specific to
3342 the current recording method.
3345 @defvar RecordGap.error_string
3346 A human readable string with the reason for the gap.
3349 A @code{gdb.RecordFunctionSegment} object has the following attributes:
3351 @defvar RecordFunctionSegment.number
3352 An integer identifying this function segment. @code{number} corresponds to
3353 the numbers seen in @code{record function-call-history}
3354 (@pxref{Process Record and Replay}).
3357 @defvar RecordFunctionSegment.symbol
3358 A @code{gdb.Symbol} object representing the associated symbol. May be
3359 @code{None} if no debug information is available.
3362 @defvar RecordFunctionSegment.level
3363 An integer representing the function call's stack level. May be
3364 @code{None} if the function call is a gap.
3367 @defvar RecordFunctionSegment.instructions
3368 A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
3369 associated with this function call.
3372 @defvar RecordFunctionSegment.up
3373 A @code{gdb.RecordFunctionSegment} object representing the caller's
3374 function segment. If the call has not been recorded, this will be the
3375 function segment to which control returns. If neither the call nor the
3376 return have been recorded, this will be @code{None}.
3379 @defvar RecordFunctionSegment.prev
3380 A @code{gdb.RecordFunctionSegment} object representing the previous
3381 segment of this function call. May be @code{None}.
3384 @defvar RecordFunctionSegment.next
3385 A @code{gdb.RecordFunctionSegment} object representing the next segment of
3386 this function call. May be @code{None}.
3389 The following example demonstrates the usage of these objects and
3390 functions to create a function that will rewind a record to the last
3391 time a function in a different file was executed. This would typically
3392 be used to track the execution of user provided callback functions in a
3393 library which typically are not visible in a back trace.
3397 rec = gdb.current_recording ()
3401 insn = rec.instruction_history
3406 position = insn.index (rec.replay_position)
3410 filename = insn[position].sal.symtab.fullname ()
3414 for i in reversed (insn[:position]):
3416 current = i.sal.symtab.fullname ()
3420 if filename == current:
3427 Another possible application is to write a function that counts the
3428 number of code executions in a given line range. This line range can
3429 contain parts of functions or span across several functions and is not
3430 limited to be contiguous.
3433 def countrange (filename, linerange):
3436 def filter_only (file_name):
3437 for call in gdb.current_recording ().function_call_history:
3439 if file_name in call.symbol.symtab.fullname ():
3444 for c in filter_only (filename):
3445 for i in c.instructions:
3447 if i.sal.line in linerange:
3456 @node Commands In Python
3457 @subsubsection Commands In Python
3459 @cindex commands in python
3460 @cindex python commands
3461 You can implement new @value{GDBN} CLI commands in Python. A CLI
3462 command is implemented using an instance of the @code{gdb.Command}
3463 class, most commonly using a subclass.
3465 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
3466 The object initializer for @code{Command} registers the new command
3467 with @value{GDBN}. This initializer is normally invoked from the
3468 subclass' own @code{__init__} method.
3470 @var{name} is the name of the command. If @var{name} consists of
3471 multiple words, then the initial words are looked for as prefix
3472 commands. In this case, if one of the prefix commands does not exist,
3473 an exception is raised.
3475 There is no support for multi-line commands.
3477 @var{command_class} should be one of the @samp{COMMAND_} constants
3478 defined below. This argument tells @value{GDBN} how to categorize the
3479 new command in the help system.
3481 @var{completer_class} is an optional argument. If given, it should be
3482 one of the @samp{COMPLETE_} constants defined below. This argument
3483 tells @value{GDBN} how to perform completion for this command. If not
3484 given, @value{GDBN} will attempt to complete using the object's
3485 @code{complete} method (see below); if no such method is found, an
3486 error will occur when completion is attempted.
3488 @var{prefix} is an optional argument. If @code{True}, then the new
3489 command is a prefix command; sub-commands of this command may be
3492 The help text for the new command is taken from the Python
3493 documentation string for the command's class, if there is one. If no
3494 documentation string is provided, the default value ``This command is
3495 not documented.'' is used.
3498 @cindex don't repeat Python command
3499 @defun Command.dont_repeat ()
3500 By default, a @value{GDBN} command is repeated when the user enters a
3501 blank line at the command prompt. A command can suppress this
3502 behavior by invoking the @code{dont_repeat} method. This is similar
3503 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
3506 @defun Command.invoke (argument, from_tty)
3507 This method is called by @value{GDBN} when this command is invoked.
3509 @var{argument} is a string. It is the argument to the command, after
3510 leading and trailing whitespace has been stripped.
3512 @var{from_tty} is a boolean argument. When true, this means that the
3513 command was entered by the user at the terminal; when false it means
3514 that the command came from elsewhere.
3516 If this method throws an exception, it is turned into a @value{GDBN}
3517 @code{error} call. Otherwise, the return value is ignored.
3519 @findex gdb.string_to_argv
3520 To break @var{argument} up into an argv-like string use
3521 @code{gdb.string_to_argv}. This function behaves identically to
3522 @value{GDBN}'s internal argument lexer @code{buildargv}.
3523 It is recommended to use this for consistency.
3524 Arguments are separated by spaces and may be quoted.
3528 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
3529 ['1', '2 "3', '4 "5', "6 '7"]
3534 @cindex completion of Python commands
3535 @defun Command.complete (text, word)
3536 This method is called by @value{GDBN} when the user attempts
3537 completion on this command. All forms of completion are handled by
3538 this method, that is, the @key{TAB} and @key{M-?} key bindings
3539 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
3542 The arguments @var{text} and @var{word} are both strings; @var{text}
3543 holds the complete command line up to the cursor's location, while
3544 @var{word} holds the last word of the command line; this is computed
3545 using a word-breaking heuristic.
3547 The @code{complete} method can return several values:
3550 If the return value is a sequence, the contents of the sequence are
3551 used as the completions. It is up to @code{complete} to ensure that the
3552 contents actually do complete the word. A zero-length sequence is
3553 allowed, it means that there were no completions available. Only
3554 string elements of the sequence are used; other elements in the
3555 sequence are ignored.
3558 If the return value is one of the @samp{COMPLETE_} constants defined
3559 below, then the corresponding @value{GDBN}-internal completion
3560 function is invoked, and its result is used.
3563 All other results are treated as though there were no available
3568 When a new command is registered, it must be declared as a member of
3569 some general class of commands. This is used to classify top-level
3570 commands in the on-line help system; note that prefix commands are not
3571 listed under their own category but rather that of their top-level
3572 command. The available classifications are represented by constants
3573 defined in the @code{gdb} module:
3576 @findex COMMAND_NONE
3577 @findex gdb.COMMAND_NONE
3578 @item gdb.COMMAND_NONE
3579 The command does not belong to any particular class. A command in
3580 this category will not be displayed in any of the help categories.
3582 @findex COMMAND_RUNNING
3583 @findex gdb.COMMAND_RUNNING
3584 @item gdb.COMMAND_RUNNING
3585 The command is related to running the inferior. For example,
3586 @code{start}, @code{step}, and @code{continue} are in this category.
3587 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
3588 commands in this category.
3590 @findex COMMAND_DATA
3591 @findex gdb.COMMAND_DATA
3592 @item gdb.COMMAND_DATA
3593 The command is related to data or variables. For example,
3594 @code{call}, @code{find}, and @code{print} are in this category. Type
3595 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
3598 @findex COMMAND_STACK
3599 @findex gdb.COMMAND_STACK
3600 @item gdb.COMMAND_STACK
3601 The command has to do with manipulation of the stack. For example,
3602 @code{backtrace}, @code{frame}, and @code{return} are in this
3603 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
3604 list of commands in this category.
3606 @findex COMMAND_FILES
3607 @findex gdb.COMMAND_FILES
3608 @item gdb.COMMAND_FILES
3609 This class is used for file-related commands. For example,
3610 @code{file}, @code{list} and @code{section} are in this category.
3611 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
3612 commands in this category.
3614 @findex COMMAND_SUPPORT
3615 @findex gdb.COMMAND_SUPPORT
3616 @item gdb.COMMAND_SUPPORT
3617 This should be used for ``support facilities'', generally meaning
3618 things that are useful to the user when interacting with @value{GDBN},
3619 but not related to the state of the inferior. For example,
3620 @code{help}, @code{make}, and @code{shell} are in this category. Type
3621 @kbd{help support} at the @value{GDBN} prompt to see a list of
3622 commands in this category.
3624 @findex COMMAND_STATUS
3625 @findex gdb.COMMAND_STATUS
3626 @item gdb.COMMAND_STATUS
3627 The command is an @samp{info}-related command, that is, related to the
3628 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
3629 and @code{show} are in this category. Type @kbd{help status} at the
3630 @value{GDBN} prompt to see a list of commands in this category.
3632 @findex COMMAND_BREAKPOINTS
3633 @findex gdb.COMMAND_BREAKPOINTS
3634 @item gdb.COMMAND_BREAKPOINTS
3635 The command has to do with breakpoints. For example, @code{break},
3636 @code{clear}, and @code{delete} are in this category. Type @kbd{help
3637 breakpoints} at the @value{GDBN} prompt to see a list of commands in
3640 @findex COMMAND_TRACEPOINTS
3641 @findex gdb.COMMAND_TRACEPOINTS
3642 @item gdb.COMMAND_TRACEPOINTS
3643 The command has to do with tracepoints. For example, @code{trace},
3644 @code{actions}, and @code{tfind} are in this category. Type
3645 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
3646 commands in this category.
3648 @findex COMMAND_USER
3649 @findex gdb.COMMAND_USER
3650 @item gdb.COMMAND_USER
3651 The command is a general purpose command for the user, and typically
3652 does not fit in one of the other categories.
3653 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
3654 a list of commands in this category, as well as the list of gdb macros
3655 (@pxref{Sequences}).
3657 @findex COMMAND_OBSCURE
3658 @findex gdb.COMMAND_OBSCURE
3659 @item gdb.COMMAND_OBSCURE
3660 The command is only used in unusual circumstances, or is not of
3661 general interest to users. For example, @code{checkpoint},
3662 @code{fork}, and @code{stop} are in this category. Type @kbd{help
3663 obscure} at the @value{GDBN} prompt to see a list of commands in this
3666 @findex COMMAND_MAINTENANCE
3667 @findex gdb.COMMAND_MAINTENANCE
3668 @item gdb.COMMAND_MAINTENANCE
3669 The command is only useful to @value{GDBN} maintainers. The
3670 @code{maintenance} and @code{flushregs} commands are in this category.
3671 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
3672 commands in this category.
3675 A new command can use a predefined completion function, either by
3676 specifying it via an argument at initialization, or by returning it
3677 from the @code{complete} method. These predefined completion
3678 constants are all defined in the @code{gdb} module:
3681 @vindex COMPLETE_NONE
3682 @item gdb.COMPLETE_NONE
3683 This constant means that no completion should be done.
3685 @vindex COMPLETE_FILENAME
3686 @item gdb.COMPLETE_FILENAME
3687 This constant means that filename completion should be performed.
3689 @vindex COMPLETE_LOCATION
3690 @item gdb.COMPLETE_LOCATION
3691 This constant means that location completion should be done.
3692 @xref{Specify Location}.
3694 @vindex COMPLETE_COMMAND
3695 @item gdb.COMPLETE_COMMAND
3696 This constant means that completion should examine @value{GDBN}
3699 @vindex COMPLETE_SYMBOL
3700 @item gdb.COMPLETE_SYMBOL
3701 This constant means that completion should be done using symbol names
3704 @vindex COMPLETE_EXPRESSION
3705 @item gdb.COMPLETE_EXPRESSION
3706 This constant means that completion should be done on expressions.
3707 Often this means completing on symbol names, but some language
3708 parsers also have support for completing on field names.
3711 The following code snippet shows how a trivial CLI command can be
3712 implemented in Python:
3715 class HelloWorld (gdb.Command):
3716 """Greet the whole world."""
3718 def __init__ (self):
3719 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
3721 def invoke (self, arg, from_tty):
3722 print "Hello, World!"
3727 The last line instantiates the class, and is necessary to trigger the
3728 registration of the command with @value{GDBN}. Depending on how the
3729 Python code is read into @value{GDBN}, you may need to import the
3730 @code{gdb} module explicitly.
3732 @node Parameters In Python
3733 @subsubsection Parameters In Python
3735 @cindex parameters in python
3736 @cindex python parameters
3737 @tindex gdb.Parameter
3739 You can implement new @value{GDBN} parameters using Python. A new
3740 parameter is implemented as an instance of the @code{gdb.Parameter}
3743 Parameters are exposed to the user via the @code{set} and
3744 @code{show} commands. @xref{Help}.
3746 There are many parameters that already exist and can be set in
3747 @value{GDBN}. Two examples are: @code{set follow fork} and
3748 @code{set charset}. Setting these parameters influences certain
3749 behavior in @value{GDBN}. Similarly, you can define parameters that
3750 can be used to influence behavior in custom Python scripts and commands.
3752 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
3753 The object initializer for @code{Parameter} registers the new
3754 parameter with @value{GDBN}. This initializer is normally invoked
3755 from the subclass' own @code{__init__} method.
3757 @var{name} is the name of the new parameter. If @var{name} consists
3758 of multiple words, then the initial words are looked for as prefix
3759 parameters. An example of this can be illustrated with the
3760 @code{set print} set of parameters. If @var{name} is
3761 @code{print foo}, then @code{print} will be searched as the prefix
3762 parameter. In this case the parameter can subsequently be accessed in
3763 @value{GDBN} as @code{set print foo}.
3765 If @var{name} consists of multiple words, and no prefix parameter group
3766 can be found, an exception is raised.
3768 @var{command-class} should be one of the @samp{COMMAND_} constants
3769 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
3770 categorize the new parameter in the help system.
3772 @var{parameter-class} should be one of the @samp{PARAM_} constants
3773 defined below. This argument tells @value{GDBN} the type of the new
3774 parameter; this information is used for input validation and
3777 If @var{parameter-class} is @code{PARAM_ENUM}, then
3778 @var{enum-sequence} must be a sequence of strings. These strings
3779 represent the possible values for the parameter.
3781 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
3782 of a fourth argument will cause an exception to be thrown.
3784 The help text for the new parameter is taken from the Python
3785 documentation string for the parameter's class, if there is one. If
3786 there is no documentation string, a default value is used.
3789 @defvar Parameter.set_doc
3790 If this attribute exists, and is a string, then its value is used as
3791 the help text for this parameter's @code{set} command. The value is
3792 examined when @code{Parameter.__init__} is invoked; subsequent changes
3796 @defvar Parameter.show_doc
3797 If this attribute exists, and is a string, then its value is used as
3798 the help text for this parameter's @code{show} command. The value is
3799 examined when @code{Parameter.__init__} is invoked; subsequent changes
3803 @defvar Parameter.value
3804 The @code{value} attribute holds the underlying value of the
3805 parameter. It can be read and assigned to just as any other
3806 attribute. @value{GDBN} does validation when assignments are made.
3809 There are two methods that may be implemented in any @code{Parameter}
3812 @defun Parameter.get_set_string (self)
3813 If this method exists, @value{GDBN} will call it when a
3814 @var{parameter}'s value has been changed via the @code{set} API (for
3815 example, @kbd{set foo off}). The @code{value} attribute has already
3816 been populated with the new value and may be used in output. This
3817 method must return a string. If the returned string is not empty,
3818 @value{GDBN} will present it to the user.
3821 @defun Parameter.get_show_string (self, svalue)
3822 @value{GDBN} will call this method when a @var{parameter}'s
3823 @code{show} API has been invoked (for example, @kbd{show foo}). The
3824 argument @code{svalue} receives the string representation of the
3825 current value. This method must return a string.
3828 When a new parameter is defined, its type must be specified. The
3829 available types are represented by constants defined in the @code{gdb}
3833 @findex PARAM_BOOLEAN
3834 @findex gdb.PARAM_BOOLEAN
3835 @item gdb.PARAM_BOOLEAN
3836 The value is a plain boolean. The Python boolean values, @code{True}
3837 and @code{False} are the only valid values.
3839 @findex PARAM_AUTO_BOOLEAN
3840 @findex gdb.PARAM_AUTO_BOOLEAN
3841 @item gdb.PARAM_AUTO_BOOLEAN
3842 The value has three possible states: true, false, and @samp{auto}. In
3843 Python, true and false are represented using boolean constants, and
3844 @samp{auto} is represented using @code{None}.
3846 @findex PARAM_UINTEGER
3847 @findex gdb.PARAM_UINTEGER
3848 @item gdb.PARAM_UINTEGER
3849 The value is an unsigned integer. The value of 0 should be
3850 interpreted to mean ``unlimited''.
3852 @findex PARAM_INTEGER
3853 @findex gdb.PARAM_INTEGER
3854 @item gdb.PARAM_INTEGER
3855 The value is a signed integer. The value of 0 should be interpreted
3856 to mean ``unlimited''.
3858 @findex PARAM_STRING
3859 @findex gdb.PARAM_STRING
3860 @item gdb.PARAM_STRING
3861 The value is a string. When the user modifies the string, any escape
3862 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
3863 translated into corresponding characters and encoded into the current
3866 @findex PARAM_STRING_NOESCAPE
3867 @findex gdb.PARAM_STRING_NOESCAPE
3868 @item gdb.PARAM_STRING_NOESCAPE
3869 The value is a string. When the user modifies the string, escapes are
3870 passed through untranslated.
3872 @findex PARAM_OPTIONAL_FILENAME
3873 @findex gdb.PARAM_OPTIONAL_FILENAME
3874 @item gdb.PARAM_OPTIONAL_FILENAME
3875 The value is a either a filename (a string), or @code{None}.
3877 @findex PARAM_FILENAME
3878 @findex gdb.PARAM_FILENAME
3879 @item gdb.PARAM_FILENAME
3880 The value is a filename. This is just like
3881 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
3883 @findex PARAM_ZINTEGER
3884 @findex gdb.PARAM_ZINTEGER
3885 @item gdb.PARAM_ZINTEGER
3886 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
3887 is interpreted as itself.
3889 @findex PARAM_ZUINTEGER
3890 @findex gdb.PARAM_ZUINTEGER
3891 @item gdb.PARAM_ZUINTEGER
3892 The value is an unsigned integer. This is like @code{PARAM_INTEGER},
3893 except 0 is interpreted as itself, and the value cannot be negative.
3895 @findex PARAM_ZUINTEGER_UNLIMITED
3896 @findex gdb.PARAM_ZUINTEGER_UNLIMITED
3897 @item gdb.PARAM_ZUINTEGER_UNLIMITED
3898 The value is a signed integer. This is like @code{PARAM_ZUINTEGER},
3899 except the special value -1 should be interpreted to mean
3900 ``unlimited''. Other negative values are not allowed.
3903 @findex gdb.PARAM_ENUM
3904 @item gdb.PARAM_ENUM
3905 The value is a string, which must be one of a collection string
3906 constants provided when the parameter is created.
3909 @node Functions In Python
3910 @subsubsection Writing new convenience functions
3912 @cindex writing convenience functions
3913 @cindex convenience functions in python
3914 @cindex python convenience functions
3915 @tindex gdb.Function
3917 You can implement new convenience functions (@pxref{Convenience Vars})
3918 in Python. A convenience function is an instance of a subclass of the
3919 class @code{gdb.Function}.
3921 @defun Function.__init__ (name)
3922 The initializer for @code{Function} registers the new function with
3923 @value{GDBN}. The argument @var{name} is the name of the function,
3924 a string. The function will be visible to the user as a convenience
3925 variable of type @code{internal function}, whose name is the same as
3926 the given @var{name}.
3928 The documentation for the new function is taken from the documentation
3929 string for the new class.
3932 @defun Function.invoke (@var{*args})
3933 When a convenience function is evaluated, its arguments are converted
3934 to instances of @code{gdb.Value}, and then the function's
3935 @code{invoke} method is called. Note that @value{GDBN} does not
3936 predetermine the arity of convenience functions. Instead, all
3937 available arguments are passed to @code{invoke}, following the
3938 standard Python calling convention. In particular, a convenience
3939 function can have default values for parameters without ill effect.
3941 The return value of this method is used as its value in the enclosing
3942 expression. If an ordinary Python value is returned, it is converted
3943 to a @code{gdb.Value} following the usual rules.
3946 The following code snippet shows how a trivial convenience function can
3947 be implemented in Python:
3950 class Greet (gdb.Function):
3951 """Return string to greet someone.
3952 Takes a name as argument."""
3954 def __init__ (self):
3955 super (Greet, self).__init__ ("greet")
3957 def invoke (self, name):
3958 return "Hello, %s!" % name.string ()
3963 The last line instantiates the class, and is necessary to trigger the
3964 registration of the function with @value{GDBN}. Depending on how the
3965 Python code is read into @value{GDBN}, you may need to import the
3966 @code{gdb} module explicitly.
3968 Now you can use the function in an expression:
3971 (gdb) print $greet("Bob")
3975 @node Progspaces In Python
3976 @subsubsection Program Spaces In Python
3978 @cindex progspaces in python
3979 @tindex gdb.Progspace
3981 A program space, or @dfn{progspace}, represents a symbolic view
3982 of an address space.
3983 It consists of all of the objfiles of the program.
3984 @xref{Objfiles In Python}.
3985 @xref{Inferiors and Programs, program spaces}, for more details
3986 about program spaces.
3988 The following progspace-related functions are available in the
3991 @findex gdb.current_progspace
3992 @defun gdb.current_progspace ()
3993 This function returns the program space of the currently selected inferior.
3994 @xref{Inferiors and Programs}.
3997 @findex gdb.progspaces
3998 @defun gdb.progspaces ()
3999 Return a sequence of all the progspaces currently known to @value{GDBN}.
4002 Each progspace is represented by an instance of the @code{gdb.Progspace}
4005 @defvar Progspace.filename
4006 The file name of the progspace as a string.
4009 @defvar Progspace.pretty_printers
4010 The @code{pretty_printers} attribute is a list of functions. It is
4011 used to look up pretty-printers. A @code{Value} is passed to each
4012 function in order; if the function returns @code{None}, then the
4013 search continues. Otherwise, the return value should be an object
4014 which is used to format the value. @xref{Pretty Printing API}, for more
4018 @defvar Progspace.type_printers
4019 The @code{type_printers} attribute is a list of type printer objects.
4020 @xref{Type Printing API}, for more information.
4023 @defvar Progspace.frame_filters
4024 The @code{frame_filters} attribute is a dictionary of frame filter
4025 objects. @xref{Frame Filter API}, for more information.
4028 One may add arbitrary attributes to @code{gdb.Progspace} objects
4029 in the usual Python way.
4030 This is useful if, for example, one needs to do some extra record keeping
4031 associated with the program space.
4033 In this contrived example, we want to perform some processing when
4034 an objfile with a certain symbol is loaded, but we only want to do
4035 this once because it is expensive. To achieve this we record the results
4036 with the program space because we can't predict when the desired objfile
4041 def clear_objfiles_handler(event):
4042 event.progspace.expensive_computation = None
4043 def expensive(symbol):
4044 """A mock routine to perform an "expensive" computation on symbol."""
4045 print "Computing the answer to the ultimate question ..."
4047 def new_objfile_handler(event):
4048 objfile = event.new_objfile
4049 progspace = objfile.progspace
4050 if not hasattr(progspace, 'expensive_computation') or \
4051 progspace.expensive_computation is None:
4052 # We use 'main' for the symbol to keep the example simple.
4053 # Note: There's no current way to constrain the lookup
4055 symbol = gdb.lookup_global_symbol('main')
4056 if symbol is not None:
4057 progspace.expensive_computation = expensive(symbol)
4058 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
4059 gdb.events.new_objfile.connect(new_objfile_handler)
4061 (gdb) file /tmp/hello
4062 Reading symbols from /tmp/hello...done.
4063 Computing the answer to the ultimate question ...
4064 (gdb) python print gdb.current_progspace().expensive_computation
4067 Starting program: /tmp/hello
4069 [Inferior 1 (process 4242) exited normally]
4072 @node Objfiles In Python
4073 @subsubsection Objfiles In Python
4075 @cindex objfiles in python
4078 @value{GDBN} loads symbols for an inferior from various
4079 symbol-containing files (@pxref{Files}). These include the primary
4080 executable file, any shared libraries used by the inferior, and any
4081 separate debug info files (@pxref{Separate Debug Files}).
4082 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
4084 The following objfile-related functions are available in the
4087 @findex gdb.current_objfile
4088 @defun gdb.current_objfile ()
4089 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
4090 sets the ``current objfile'' to the corresponding objfile. This
4091 function returns the current objfile. If there is no current objfile,
4092 this function returns @code{None}.
4095 @findex gdb.objfiles
4096 @defun gdb.objfiles ()
4097 Return a sequence of all the objfiles current known to @value{GDBN}.
4098 @xref{Objfiles In Python}.
4101 @findex gdb.lookup_objfile
4102 @defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
4103 Look up @var{name}, a file name or build ID, in the list of objfiles
4104 for the current program space (@pxref{Progspaces In Python}).
4105 If the objfile is not found throw the Python @code{ValueError} exception.
4107 If @var{name} is a relative file name, then it will match any
4108 source file name with the same trailing components. For example, if
4109 @var{name} is @samp{gcc/expr.c}, then it will match source file
4110 name of @file{/build/trunk/gcc/expr.c}, but not
4111 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
4113 If @var{by_build_id} is provided and is @code{True} then @var{name}
4114 is the build ID of the objfile. Otherwise, @var{name} is a file name.
4115 This is supported only on some operating systems, notably those which use
4116 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4117 about this feature, see the description of the @option{--build-id}
4118 command-line option in @ref{Options, , Command Line Options, ld,
4122 Each objfile is represented by an instance of the @code{gdb.Objfile}
4125 @defvar Objfile.filename
4126 The file name of the objfile as a string, with symbolic links resolved.
4128 The value is @code{None} if the objfile is no longer valid.
4129 See the @code{gdb.Objfile.is_valid} method, described below.
4132 @defvar Objfile.username
4133 The file name of the objfile as specified by the user as a string.
4135 The value is @code{None} if the objfile is no longer valid.
4136 See the @code{gdb.Objfile.is_valid} method, described below.
4139 @defvar Objfile.owner
4140 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
4141 object that debug info is being provided for.
4142 Otherwise this is @code{None}.
4143 Separate debug info objfiles are added with the
4144 @code{gdb.Objfile.add_separate_debug_file} method, described below.
4147 @defvar Objfile.build_id
4148 The build ID of the objfile as a string.
4149 If the objfile does not have a build ID then the value is @code{None}.
4151 This is supported only on some operating systems, notably those which use
4152 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4153 about this feature, see the description of the @option{--build-id}
4154 command-line option in @ref{Options, , Command Line Options, ld,
4158 @defvar Objfile.progspace
4159 The containing program space of the objfile as a @code{gdb.Progspace}
4160 object. @xref{Progspaces In Python}.
4163 @defvar Objfile.pretty_printers
4164 The @code{pretty_printers} attribute is a list of functions. It is
4165 used to look up pretty-printers. A @code{Value} is passed to each
4166 function in order; if the function returns @code{None}, then the
4167 search continues. Otherwise, the return value should be an object
4168 which is used to format the value. @xref{Pretty Printing API}, for more
4172 @defvar Objfile.type_printers
4173 The @code{type_printers} attribute is a list of type printer objects.
4174 @xref{Type Printing API}, for more information.
4177 @defvar Objfile.frame_filters
4178 The @code{frame_filters} attribute is a dictionary of frame filter
4179 objects. @xref{Frame Filter API}, for more information.
4182 One may add arbitrary attributes to @code{gdb.Objfile} objects
4183 in the usual Python way.
4184 This is useful if, for example, one needs to do some extra record keeping
4185 associated with the objfile.
4187 In this contrived example we record the time when @value{GDBN}
4193 def new_objfile_handler(event):
4194 # Set the time_loaded attribute of the new objfile.
4195 event.new_objfile.time_loaded = datetime.datetime.today()
4196 gdb.events.new_objfile.connect(new_objfile_handler)
4199 Reading symbols from ./hello...done.
4200 (gdb) python print gdb.objfiles()[0].time_loaded
4201 2014-10-09 11:41:36.770345
4204 A @code{gdb.Objfile} object has the following methods:
4206 @defun Objfile.is_valid ()
4207 Returns @code{True} if the @code{gdb.Objfile} object is valid,
4208 @code{False} if not. A @code{gdb.Objfile} object can become invalid
4209 if the object file it refers to is not loaded in @value{GDBN} any
4210 longer. All other @code{gdb.Objfile} methods will throw an exception
4211 if it is invalid at the time the method is called.
4214 @defun Objfile.add_separate_debug_file (file)
4215 Add @var{file} to the list of files that @value{GDBN} will search for
4216 debug information for the objfile.
4217 This is useful when the debug info has been removed from the program
4218 and stored in a separate file. @value{GDBN} has built-in support for
4219 finding separate debug info files (@pxref{Separate Debug Files}), but if
4220 the file doesn't live in one of the standard places that @value{GDBN}
4221 searches then this function can be used to add a debug info file
4222 from a different place.
4225 @node Frames In Python
4226 @subsubsection Accessing inferior stack frames from Python
4228 @cindex frames in python
4229 When the debugged program stops, @value{GDBN} is able to analyze its call
4230 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
4231 represents a frame in the stack. A @code{gdb.Frame} object is only valid
4232 while its corresponding frame exists in the inferior's stack. If you try
4233 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
4234 exception (@pxref{Exception Handling}).
4236 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
4240 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
4244 The following frame-related functions are available in the @code{gdb} module:
4246 @findex gdb.selected_frame
4247 @defun gdb.selected_frame ()
4248 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
4251 @findex gdb.newest_frame
4252 @defun gdb.newest_frame ()
4253 Return the newest frame object for the selected thread.
4256 @defun gdb.frame_stop_reason_string (reason)
4257 Return a string explaining the reason why @value{GDBN} stopped unwinding
4258 frames, as expressed by the given @var{reason} code (an integer, see the
4259 @code{unwind_stop_reason} method further down in this section).
4262 @findex gdb.invalidate_cached_frames
4263 @defun gdb.invalidate_cached_frames
4264 @value{GDBN} internally keeps a cache of the frames that have been
4265 unwound. This function invalidates this cache.
4267 This function should not generally be called by ordinary Python code.
4268 It is documented for the sake of completeness.
4271 A @code{gdb.Frame} object has the following methods:
4273 @defun Frame.is_valid ()
4274 Returns true if the @code{gdb.Frame} object is valid, false if not.
4275 A frame object can become invalid if the frame it refers to doesn't
4276 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
4277 an exception if it is invalid at the time the method is called.
4280 @defun Frame.name ()
4281 Returns the function name of the frame, or @code{None} if it can't be
4285 @defun Frame.architecture ()
4286 Returns the @code{gdb.Architecture} object corresponding to the frame's
4287 architecture. @xref{Architectures In Python}.
4290 @defun Frame.type ()
4291 Returns the type of the frame. The value can be one of:
4293 @item gdb.NORMAL_FRAME
4294 An ordinary stack frame.
4296 @item gdb.DUMMY_FRAME
4297 A fake stack frame that was created by @value{GDBN} when performing an
4298 inferior function call.
4300 @item gdb.INLINE_FRAME
4301 A frame representing an inlined function. The function was inlined
4302 into a @code{gdb.NORMAL_FRAME} that is older than this one.
4304 @item gdb.TAILCALL_FRAME
4305 A frame representing a tail call. @xref{Tail Call Frames}.
4307 @item gdb.SIGTRAMP_FRAME
4308 A signal trampoline frame. This is the frame created by the OS when
4309 it calls into a signal handler.
4311 @item gdb.ARCH_FRAME
4312 A fake stack frame representing a cross-architecture call.
4314 @item gdb.SENTINEL_FRAME
4315 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
4320 @defun Frame.unwind_stop_reason ()
4321 Return an integer representing the reason why it's not possible to find
4322 more frames toward the outermost frame. Use
4323 @code{gdb.frame_stop_reason_string} to convert the value returned by this
4324 function to a string. The value can be one of:
4327 @item gdb.FRAME_UNWIND_NO_REASON
4328 No particular reason (older frames should be available).
4330 @item gdb.FRAME_UNWIND_NULL_ID
4331 The previous frame's analyzer returns an invalid result. This is no
4332 longer used by @value{GDBN}, and is kept only for backward
4335 @item gdb.FRAME_UNWIND_OUTERMOST
4336 This frame is the outermost.
4338 @item gdb.FRAME_UNWIND_UNAVAILABLE
4339 Cannot unwind further, because that would require knowing the
4340 values of registers or memory that have not been collected.
4342 @item gdb.FRAME_UNWIND_INNER_ID
4343 This frame ID looks like it ought to belong to a NEXT frame,
4344 but we got it for a PREV frame. Normally, this is a sign of
4345 unwinder failure. It could also indicate stack corruption.
4347 @item gdb.FRAME_UNWIND_SAME_ID
4348 This frame has the same ID as the previous one. That means
4349 that unwinding further would almost certainly give us another
4350 frame with exactly the same ID, so break the chain. Normally,
4351 this is a sign of unwinder failure. It could also indicate
4354 @item gdb.FRAME_UNWIND_NO_SAVED_PC
4355 The frame unwinder did not find any saved PC, but we needed
4356 one to unwind further.
4358 @item gdb.FRAME_UNWIND_MEMORY_ERROR
4359 The frame unwinder caused an error while trying to access memory.
4361 @item gdb.FRAME_UNWIND_FIRST_ERROR
4362 Any stop reason greater or equal to this value indicates some kind
4363 of error. This special value facilitates writing code that tests
4364 for errors in unwinding in a way that will work correctly even if
4365 the list of the other values is modified in future @value{GDBN}
4366 versions. Using it, you could write:
4368 reason = gdb.selected_frame().unwind_stop_reason ()
4369 reason_str = gdb.frame_stop_reason_string (reason)
4370 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
4371 print "An error occured: %s" % reason_str
4378 Returns the frame's resume address.
4381 @defun Frame.block ()
4382 Return the frame's code block. @xref{Blocks In Python}. If the frame
4383 does not have a block -- for example, if there is no debugging
4384 information for the code in question -- then this will throw an
4388 @defun Frame.function ()
4389 Return the symbol for the function corresponding to this frame.
4390 @xref{Symbols In Python}.
4393 @defun Frame.older ()
4394 Return the frame that called this frame.
4397 @defun Frame.newer ()
4398 Return the frame called by this frame.
4401 @defun Frame.find_sal ()
4402 Return the frame's symtab and line object.
4403 @xref{Symbol Tables In Python}.
4406 @defun Frame.read_register (register)
4407 Return the value of @var{register} in this frame. The @var{register}
4408 argument must be a string (e.g., @code{'sp'} or @code{'rax'}).
4409 Returns a @code{Gdb.Value} object. Throws an exception if @var{register}
4413 @defun Frame.read_var (variable @r{[}, block@r{]})
4414 Return the value of @var{variable} in this frame. If the optional
4415 argument @var{block} is provided, search for the variable from that
4416 block; otherwise start at the frame's current block (which is
4417 determined by the frame's current program counter). The @var{variable}
4418 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
4419 @code{gdb.Block} object.
4422 @defun Frame.select ()
4423 Set this frame to be the selected frame. @xref{Stack, ,Examining the
4427 @node Blocks In Python
4428 @subsubsection Accessing blocks from Python
4430 @cindex blocks in python
4433 In @value{GDBN}, symbols are stored in blocks. A block corresponds
4434 roughly to a scope in the source code. Blocks are organized
4435 hierarchically, and are represented individually in Python as a
4436 @code{gdb.Block}. Blocks rely on debugging information being
4439 A frame has a block. Please see @ref{Frames In Python}, for a more
4440 in-depth discussion of frames.
4442 The outermost block is known as the @dfn{global block}. The global
4443 block typically holds public global variables and functions.
4445 The block nested just inside the global block is the @dfn{static
4446 block}. The static block typically holds file-scoped variables and
4449 @value{GDBN} provides a method to get a block's superblock, but there
4450 is currently no way to examine the sub-blocks of a block, or to
4451 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
4454 Here is a short example that should help explain blocks:
4457 /* This is in the global block. */
4460 /* This is in the static block. */
4461 static int file_scope;
4463 /* 'function' is in the global block, and 'argument' is
4464 in a block nested inside of 'function'. */
4465 int function (int argument)
4467 /* 'local' is in a block inside 'function'. It may or may
4468 not be in the same block as 'argument'. */
4472 /* 'inner' is in a block whose superblock is the one holding
4476 /* If this call is expanded by the compiler, you may see
4477 a nested block here whose function is 'inline_function'
4478 and whose superblock is the one holding 'inner'. */
4484 A @code{gdb.Block} is iterable. The iterator returns the symbols
4485 (@pxref{Symbols In Python}) local to the block. Python programs
4486 should not assume that a specific block object will always contain a
4487 given symbol, since changes in @value{GDBN} features and
4488 infrastructure may cause symbols move across blocks in a symbol
4491 The following block-related functions are available in the @code{gdb}
4494 @findex gdb.block_for_pc
4495 @defun gdb.block_for_pc (pc)
4496 Return the innermost @code{gdb.Block} containing the given @var{pc}
4497 value. If the block cannot be found for the @var{pc} value specified,
4498 the function will return @code{None}.
4501 A @code{gdb.Block} object has the following methods:
4503 @defun Block.is_valid ()
4504 Returns @code{True} if the @code{gdb.Block} object is valid,
4505 @code{False} if not. A block object can become invalid if the block it
4506 refers to doesn't exist anymore in the inferior. All other
4507 @code{gdb.Block} methods will throw an exception if it is invalid at
4508 the time the method is called. The block's validity is also checked
4509 during iteration over symbols of the block.
4512 A @code{gdb.Block} object has the following attributes:
4515 The start address of the block. This attribute is not writable.
4519 One past the last address that appears in the block. This attribute
4523 @defvar Block.function
4524 The name of the block represented as a @code{gdb.Symbol}. If the
4525 block is not named, then this attribute holds @code{None}. This
4526 attribute is not writable.
4528 For ordinary function blocks, the superblock is the static block.
4529 However, you should note that it is possible for a function block to
4530 have a superblock that is not the static block -- for instance this
4531 happens for an inlined function.
4534 @defvar Block.superblock
4535 The block containing this block. If this parent block does not exist,
4536 this attribute holds @code{None}. This attribute is not writable.
4539 @defvar Block.global_block
4540 The global block associated with this block. This attribute is not
4544 @defvar Block.static_block
4545 The static block associated with this block. This attribute is not
4549 @defvar Block.is_global
4550 @code{True} if the @code{gdb.Block} object is a global block,
4551 @code{False} if not. This attribute is not
4555 @defvar Block.is_static
4556 @code{True} if the @code{gdb.Block} object is a static block,
4557 @code{False} if not. This attribute is not writable.
4560 @node Symbols In Python
4561 @subsubsection Python representation of Symbols
4563 @cindex symbols in python
4566 @value{GDBN} represents every variable, function and type as an
4567 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
4568 Similarly, Python represents these symbols in @value{GDBN} with the
4569 @code{gdb.Symbol} object.
4571 The following symbol-related functions are available in the @code{gdb}
4574 @findex gdb.lookup_symbol
4575 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
4576 This function searches for a symbol by name. The search scope can be
4577 restricted to the parameters defined in the optional domain and block
4580 @var{name} is the name of the symbol. It must be a string. The
4581 optional @var{block} argument restricts the search to symbols visible
4582 in that @var{block}. The @var{block} argument must be a
4583 @code{gdb.Block} object. If omitted, the block for the current frame
4584 is used. The optional @var{domain} argument restricts
4585 the search to the domain type. The @var{domain} argument must be a
4586 domain constant defined in the @code{gdb} module and described later
4589 The result is a tuple of two elements.
4590 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
4592 If the symbol is found, the second element is @code{True} if the symbol
4593 is a field of a method's object (e.g., @code{this} in C@t{++}),
4594 otherwise it is @code{False}.
4595 If the symbol is not found, the second element is @code{False}.
4598 @findex gdb.lookup_global_symbol
4599 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
4600 This function searches for a global symbol by name.
4601 The search scope can be restricted to by the domain argument.
4603 @var{name} is the name of the symbol. It must be a string.
4604 The optional @var{domain} argument restricts the search to the domain type.
4605 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4606 module and described later in this chapter.
4608 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4612 A @code{gdb.Symbol} object has the following attributes:
4615 The type of the symbol or @code{None} if no type is recorded.
4616 This attribute is represented as a @code{gdb.Type} object.
4617 @xref{Types In Python}. This attribute is not writable.
4620 @defvar Symbol.symtab
4621 The symbol table in which the symbol appears. This attribute is
4622 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
4623 Python}. This attribute is not writable.
4627 The line number in the source code at which the symbol was defined.
4632 The name of the symbol as a string. This attribute is not writable.
4635 @defvar Symbol.linkage_name
4636 The name of the symbol, as used by the linker (i.e., may be mangled).
4637 This attribute is not writable.
4640 @defvar Symbol.print_name
4641 The name of the symbol in a form suitable for output. This is either
4642 @code{name} or @code{linkage_name}, depending on whether the user
4643 asked @value{GDBN} to display demangled or mangled names.
4646 @defvar Symbol.addr_class
4647 The address class of the symbol. This classifies how to find the value
4648 of a symbol. Each address class is a constant defined in the
4649 @code{gdb} module and described later in this chapter.
4652 @defvar Symbol.needs_frame
4653 This is @code{True} if evaluating this symbol's value requires a frame
4654 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
4655 local variables will require a frame, but other symbols will not.
4658 @defvar Symbol.is_argument
4659 @code{True} if the symbol is an argument of a function.
4662 @defvar Symbol.is_constant
4663 @code{True} if the symbol is a constant.
4666 @defvar Symbol.is_function
4667 @code{True} if the symbol is a function or a method.
4670 @defvar Symbol.is_variable
4671 @code{True} if the symbol is a variable.
4674 A @code{gdb.Symbol} object has the following methods:
4676 @defun Symbol.is_valid ()
4677 Returns @code{True} if the @code{gdb.Symbol} object is valid,
4678 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
4679 the symbol it refers to does not exist in @value{GDBN} any longer.
4680 All other @code{gdb.Symbol} methods will throw an exception if it is
4681 invalid at the time the method is called.
4684 @defun Symbol.value (@r{[}frame@r{]})
4685 Compute the value of the symbol, as a @code{gdb.Value}. For
4686 functions, this computes the address of the function, cast to the
4687 appropriate type. If the symbol requires a frame in order to compute
4688 its value, then @var{frame} must be given. If @var{frame} is not
4689 given, or if @var{frame} is invalid, then this method will throw an
4693 The available domain categories in @code{gdb.Symbol} are represented
4694 as constants in the @code{gdb} module:
4697 @vindex SYMBOL_UNDEF_DOMAIN
4698 @item gdb.SYMBOL_UNDEF_DOMAIN
4699 This is used when a domain has not been discovered or none of the
4700 following domains apply. This usually indicates an error either
4701 in the symbol information or in @value{GDBN}'s handling of symbols.
4703 @vindex SYMBOL_VAR_DOMAIN
4704 @item gdb.SYMBOL_VAR_DOMAIN
4705 This domain contains variables, function names, typedef names and enum
4708 @vindex SYMBOL_STRUCT_DOMAIN
4709 @item gdb.SYMBOL_STRUCT_DOMAIN
4710 This domain holds struct, union and enum type names.
4712 @vindex SYMBOL_LABEL_DOMAIN
4713 @item gdb.SYMBOL_LABEL_DOMAIN
4714 This domain contains names of labels (for gotos).
4716 @vindex SYMBOL_VARIABLES_DOMAIN
4717 @item gdb.SYMBOL_VARIABLES_DOMAIN
4718 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
4719 contains everything minus functions and types.
4721 @vindex SYMBOL_FUNCTIONS_DOMAIN
4722 @item gdb.SYMBOL_FUNCTIONS_DOMAIN
4723 This domain contains all functions.
4725 @vindex SYMBOL_TYPES_DOMAIN
4726 @item gdb.SYMBOL_TYPES_DOMAIN
4727 This domain contains all types.
4730 The available address class categories in @code{gdb.Symbol} are represented
4731 as constants in the @code{gdb} module:
4734 @vindex SYMBOL_LOC_UNDEF
4735 @item gdb.SYMBOL_LOC_UNDEF
4736 If this is returned by address class, it indicates an error either in
4737 the symbol information or in @value{GDBN}'s handling of symbols.
4739 @vindex SYMBOL_LOC_CONST
4740 @item gdb.SYMBOL_LOC_CONST
4741 Value is constant int.
4743 @vindex SYMBOL_LOC_STATIC
4744 @item gdb.SYMBOL_LOC_STATIC
4745 Value is at a fixed address.
4747 @vindex SYMBOL_LOC_REGISTER
4748 @item gdb.SYMBOL_LOC_REGISTER
4749 Value is in a register.
4751 @vindex SYMBOL_LOC_ARG
4752 @item gdb.SYMBOL_LOC_ARG
4753 Value is an argument. This value is at the offset stored within the
4754 symbol inside the frame's argument list.
4756 @vindex SYMBOL_LOC_REF_ARG
4757 @item gdb.SYMBOL_LOC_REF_ARG
4758 Value address is stored in the frame's argument list. Just like
4759 @code{LOC_ARG} except that the value's address is stored at the
4760 offset, not the value itself.
4762 @vindex SYMBOL_LOC_REGPARM_ADDR
4763 @item gdb.SYMBOL_LOC_REGPARM_ADDR
4764 Value is a specified register. Just like @code{LOC_REGISTER} except
4765 the register holds the address of the argument instead of the argument
4768 @vindex SYMBOL_LOC_LOCAL
4769 @item gdb.SYMBOL_LOC_LOCAL
4770 Value is a local variable.
4772 @vindex SYMBOL_LOC_TYPEDEF
4773 @item gdb.SYMBOL_LOC_TYPEDEF
4774 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
4777 @vindex SYMBOL_LOC_BLOCK
4778 @item gdb.SYMBOL_LOC_BLOCK
4781 @vindex SYMBOL_LOC_CONST_BYTES
4782 @item gdb.SYMBOL_LOC_CONST_BYTES
4783 Value is a byte-sequence.
4785 @vindex SYMBOL_LOC_UNRESOLVED
4786 @item gdb.SYMBOL_LOC_UNRESOLVED
4787 Value is at a fixed address, but the address of the variable has to be
4788 determined from the minimal symbol table whenever the variable is
4791 @vindex SYMBOL_LOC_OPTIMIZED_OUT
4792 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
4793 The value does not actually exist in the program.
4795 @vindex SYMBOL_LOC_COMPUTED
4796 @item gdb.SYMBOL_LOC_COMPUTED
4797 The value's address is a computed location.
4800 @node Symbol Tables In Python
4801 @subsubsection Symbol table representation in Python
4803 @cindex symbol tables in python
4805 @tindex gdb.Symtab_and_line
4807 Access to symbol table data maintained by @value{GDBN} on the inferior
4808 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
4809 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
4810 from the @code{find_sal} method in @code{gdb.Frame} object.
4811 @xref{Frames In Python}.
4813 For more information on @value{GDBN}'s symbol table management, see
4814 @ref{Symbols, ,Examining the Symbol Table}, for more information.
4816 A @code{gdb.Symtab_and_line} object has the following attributes:
4818 @defvar Symtab_and_line.symtab
4819 The symbol table object (@code{gdb.Symtab}) for this frame.
4820 This attribute is not writable.
4823 @defvar Symtab_and_line.pc
4824 Indicates the start of the address range occupied by code for the
4825 current source line. This attribute is not writable.
4828 @defvar Symtab_and_line.last
4829 Indicates the end of the address range occupied by code for the current
4830 source line. This attribute is not writable.
4833 @defvar Symtab_and_line.line
4834 Indicates the current line number for this object. This
4835 attribute is not writable.
4838 A @code{gdb.Symtab_and_line} object has the following methods:
4840 @defun Symtab_and_line.is_valid ()
4841 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
4842 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
4843 invalid if the Symbol table and line object it refers to does not
4844 exist in @value{GDBN} any longer. All other
4845 @code{gdb.Symtab_and_line} methods will throw an exception if it is
4846 invalid at the time the method is called.
4849 A @code{gdb.Symtab} object has the following attributes:
4851 @defvar Symtab.filename
4852 The symbol table's source filename. This attribute is not writable.
4855 @defvar Symtab.objfile
4856 The symbol table's backing object file. @xref{Objfiles In Python}.
4857 This attribute is not writable.
4860 @defvar Symtab.producer
4861 The name and possibly version number of the program that
4862 compiled the code in the symbol table.
4863 The contents of this string is up to the compiler.
4864 If no producer information is available then @code{None} is returned.
4865 This attribute is not writable.
4868 A @code{gdb.Symtab} object has the following methods:
4870 @defun Symtab.is_valid ()
4871 Returns @code{True} if the @code{gdb.Symtab} object is valid,
4872 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
4873 the symbol table it refers to does not exist in @value{GDBN} any
4874 longer. All other @code{gdb.Symtab} methods will throw an exception
4875 if it is invalid at the time the method is called.
4878 @defun Symtab.fullname ()
4879 Return the symbol table's source absolute file name.
4882 @defun Symtab.global_block ()
4883 Return the global block of the underlying symbol table.
4884 @xref{Blocks In Python}.
4887 @defun Symtab.static_block ()
4888 Return the static block of the underlying symbol table.
4889 @xref{Blocks In Python}.
4892 @defun Symtab.linetable ()
4893 Return the line table associated with the symbol table.
4894 @xref{Line Tables In Python}.
4897 @node Line Tables In Python
4898 @subsubsection Manipulating line tables using Python
4900 @cindex line tables in python
4901 @tindex gdb.LineTable
4903 Python code can request and inspect line table information from a
4904 symbol table that is loaded in @value{GDBN}. A line table is a
4905 mapping of source lines to their executable locations in memory. To
4906 acquire the line table information for a particular symbol table, use
4907 the @code{linetable} function (@pxref{Symbol Tables In Python}).
4909 A @code{gdb.LineTable} is iterable. The iterator returns
4910 @code{LineTableEntry} objects that correspond to the source line and
4911 address for each line table entry. @code{LineTableEntry} objects have
4912 the following attributes:
4914 @defvar LineTableEntry.line
4915 The source line number for this line table entry. This number
4916 corresponds to the actual line of source. This attribute is not
4920 @defvar LineTableEntry.pc
4921 The address that is associated with the line table entry where the
4922 executable code for that source line resides in memory. This
4923 attribute is not writable.
4926 As there can be multiple addresses for a single source line, you may
4927 receive multiple @code{LineTableEntry} objects with matching
4928 @code{line} attributes, but with different @code{pc} attributes. The
4929 iterator is sorted in ascending @code{pc} order. Here is a small
4930 example illustrating iterating over a line table.
4933 symtab = gdb.selected_frame().find_sal().symtab
4934 linetable = symtab.linetable()
4935 for line in linetable:
4936 print "Line: "+str(line.line)+" Address: "+hex(line.pc)
4939 This will have the following output:
4942 Line: 33 Address: 0x4005c8L
4943 Line: 37 Address: 0x4005caL
4944 Line: 39 Address: 0x4005d2L
4945 Line: 40 Address: 0x4005f8L
4946 Line: 42 Address: 0x4005ffL
4947 Line: 44 Address: 0x400608L
4948 Line: 42 Address: 0x40060cL
4949 Line: 45 Address: 0x400615L
4952 In addition to being able to iterate over a @code{LineTable}, it also
4953 has the following direct access methods:
4955 @defun LineTable.line (line)
4956 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
4957 entries in the line table for the given @var{line}, which specifies
4958 the source code line. If there are no entries for that source code
4959 @var{line}, the Python @code{None} is returned.
4962 @defun LineTable.has_line (line)
4963 Return a Python @code{Boolean} indicating whether there is an entry in
4964 the line table for this source line. Return @code{True} if an entry
4965 is found, or @code{False} if not.
4968 @defun LineTable.source_lines ()
4969 Return a Python @code{List} of the source line numbers in the symbol
4970 table. Only lines with executable code locations are returned. The
4971 contents of the @code{List} will just be the source line entries
4972 represented as Python @code{Long} values.
4975 @node Breakpoints In Python
4976 @subsubsection Manipulating breakpoints using Python
4978 @cindex breakpoints in python
4979 @tindex gdb.Breakpoint
4981 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
4984 A breakpoint can be created using one of the two forms of the
4985 @code{gdb.Breakpoint} constructor. The first one accepts a string
4986 like one would pass to the @code{break}
4987 (@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
4988 (@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
4989 create both breakpoints and watchpoints. The second accepts separate Python
4990 arguments similar to @ref{Explicit Locations}, and can only be used to create
4993 @defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]})
4994 Create a new breakpoint according to @var{spec}, which is a string naming the
4995 location of a breakpoint, or an expression that defines a watchpoint. The
4996 string should describe a location in a format recognized by the @code{break}
4997 command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
4998 watchpoint, by the @code{watch} command
4999 (@pxref{Set Watchpoints, , Setting Watchpoints}).
5001 The optional @var{type} argument specifies the type of the breakpoint to create,
5004 The optional @var{wp_class} argument defines the class of watchpoint to create,
5005 if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
5006 defaults to @code{gdb.WP_WRITE}.
5008 The optional @var{internal} argument allows the breakpoint to become invisible
5009 to the user. The breakpoint will neither be reported when created, nor will it
5010 be listed in the output from @code{info breakpoints} (but will be listed with
5011 the @code{maint info breakpoints} command).
5013 The optional @var{temporary} argument makes the breakpoint a temporary
5014 breakpoint. Temporary breakpoints are deleted after they have been hit. Any
5015 further access to the Python breakpoint after it has been hit will result in a
5016 runtime error (as that breakpoint has now been automatically deleted).
5018 The optional @var{qualified} argument is a boolean that allows interpreting
5019 the function passed in @code{spec} as a fully-qualified name. It is equivalent
5020 to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
5021 @ref{Explicit Locations}).
5025 @defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]})
5026 This second form of creating a new breakpoint specifies the explicit
5027 location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
5028 be created in the specified source file @var{source}, at the specified
5029 @var{function}, @var{label} and @var{line}.
5031 @var{internal}, @var{temporary} and @var{qualified} have the same usage as
5032 explained previously.
5035 The available types are represented by constants defined in the @code{gdb}
5039 @vindex BP_BREAKPOINT
5040 @item gdb.BP_BREAKPOINT
5041 Normal code breakpoint.
5043 @vindex BP_WATCHPOINT
5044 @item gdb.BP_WATCHPOINT
5045 Watchpoint breakpoint.
5047 @vindex BP_HARDWARE_WATCHPOINT
5048 @item gdb.BP_HARDWARE_WATCHPOINT
5049 Hardware assisted watchpoint.
5051 @vindex BP_READ_WATCHPOINT
5052 @item gdb.BP_READ_WATCHPOINT
5053 Hardware assisted read watchpoint.
5055 @vindex BP_ACCESS_WATCHPOINT
5056 @item gdb.BP_ACCESS_WATCHPOINT
5057 Hardware assisted access watchpoint.
5060 The available watchpoint types represented by constants are defined in the
5066 Read only watchpoint.
5070 Write only watchpoint.
5074 Read/Write watchpoint.
5077 @defun Breakpoint.stop (self)
5078 The @code{gdb.Breakpoint} class can be sub-classed and, in
5079 particular, you may choose to implement the @code{stop} method.
5080 If this method is defined in a sub-class of @code{gdb.Breakpoint},
5081 it will be called when the inferior reaches any location of a
5082 breakpoint which instantiates that sub-class. If the method returns
5083 @code{True}, the inferior will be stopped at the location of the
5084 breakpoint, otherwise the inferior will continue.
5086 If there are multiple breakpoints at the same location with a
5087 @code{stop} method, each one will be called regardless of the
5088 return status of the previous. This ensures that all @code{stop}
5089 methods have a chance to execute at that location. In this scenario
5090 if one of the methods returns @code{True} but the others return
5091 @code{False}, the inferior will still be stopped.
5093 You should not alter the execution state of the inferior (i.e.@:, step,
5094 next, etc.), alter the current frame context (i.e.@:, change the current
5095 active frame), or alter, add or delete any breakpoint. As a general
5096 rule, you should not alter any data within @value{GDBN} or the inferior
5099 Example @code{stop} implementation:
5102 class MyBreakpoint (gdb.Breakpoint):
5104 inf_val = gdb.parse_and_eval("foo")
5111 @defun Breakpoint.is_valid ()
5112 Return @code{True} if this @code{Breakpoint} object is valid,
5113 @code{False} otherwise. A @code{Breakpoint} object can become invalid
5114 if the user deletes the breakpoint. In this case, the object still
5115 exists, but the underlying breakpoint does not. In the cases of
5116 watchpoint scope, the watchpoint remains valid even if execution of the
5117 inferior leaves the scope of that watchpoint.
5120 @defun Breakpoint.delete ()
5121 Permanently deletes the @value{GDBN} breakpoint. This also
5122 invalidates the Python @code{Breakpoint} object. Any further access
5123 to this object's attributes or methods will raise an error.
5126 @defvar Breakpoint.enabled
5127 This attribute is @code{True} if the breakpoint is enabled, and
5128 @code{False} otherwise. This attribute is writable. You can use it to enable
5129 or disable the breakpoint.
5132 @defvar Breakpoint.silent
5133 This attribute is @code{True} if the breakpoint is silent, and
5134 @code{False} otherwise. This attribute is writable.
5136 Note that a breakpoint can also be silent if it has commands and the
5137 first command is @code{silent}. This is not reported by the
5138 @code{silent} attribute.
5141 @defvar Breakpoint.pending
5142 This attribute is @code{True} if the breakpoint is pending, and
5143 @code{False} otherwise. @xref{Set Breaks}. This attribute is
5147 @anchor{python_breakpoint_thread}
5148 @defvar Breakpoint.thread
5149 If the breakpoint is thread-specific, this attribute holds the
5150 thread's global id. If the breakpoint is not thread-specific, this
5151 attribute is @code{None}. This attribute is writable.
5154 @defvar Breakpoint.task
5155 If the breakpoint is Ada task-specific, this attribute holds the Ada task
5156 id. If the breakpoint is not task-specific (or the underlying
5157 language is not Ada), this attribute is @code{None}. This attribute
5161 @defvar Breakpoint.ignore_count
5162 This attribute holds the ignore count for the breakpoint, an integer.
5163 This attribute is writable.
5166 @defvar Breakpoint.number
5167 This attribute holds the breakpoint's number --- the identifier used by
5168 the user to manipulate the breakpoint. This attribute is not writable.
5171 @defvar Breakpoint.type
5172 This attribute holds the breakpoint's type --- the identifier used to
5173 determine the actual breakpoint type or use-case. This attribute is not
5177 @defvar Breakpoint.visible
5178 This attribute tells whether the breakpoint is visible to the user
5179 when set, or when the @samp{info breakpoints} command is run. This
5180 attribute is not writable.
5183 @defvar Breakpoint.temporary
5184 This attribute indicates whether the breakpoint was created as a
5185 temporary breakpoint. Temporary breakpoints are automatically deleted
5186 after that breakpoint has been hit. Access to this attribute, and all
5187 other attributes and functions other than the @code{is_valid}
5188 function, will result in an error after the breakpoint has been hit
5189 (as it has been automatically deleted). This attribute is not
5193 @defvar Breakpoint.hit_count
5194 This attribute holds the hit count for the breakpoint, an integer.
5195 This attribute is writable, but currently it can only be set to zero.
5198 @defvar Breakpoint.location
5199 This attribute holds the location of the breakpoint, as specified by
5200 the user. It is a string. If the breakpoint does not have a location
5201 (that is, it is a watchpoint) the attribute's value is @code{None}. This
5202 attribute is not writable.
5205 @defvar Breakpoint.expression
5206 This attribute holds a breakpoint expression, as specified by
5207 the user. It is a string. If the breakpoint does not have an
5208 expression (the breakpoint is not a watchpoint) the attribute's value
5209 is @code{None}. This attribute is not writable.
5212 @defvar Breakpoint.condition
5213 This attribute holds the condition of the breakpoint, as specified by
5214 the user. It is a string. If there is no condition, this attribute's
5215 value is @code{None}. This attribute is writable.
5218 @defvar Breakpoint.commands
5219 This attribute holds the commands attached to the breakpoint. If
5220 there are commands, this attribute's value is a string holding all the
5221 commands, separated by newlines. If there are no commands, this
5222 attribute is @code{None}. This attribute is writable.
5225 @node Finish Breakpoints in Python
5226 @subsubsection Finish Breakpoints
5228 @cindex python finish breakpoints
5229 @tindex gdb.FinishBreakpoint
5231 A finish breakpoint is a temporary breakpoint set at the return address of
5232 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
5233 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
5234 and deleted when the execution will run out of the breakpoint scope (i.e.@:
5235 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
5236 Finish breakpoints are thread specific and must be create with the right
5239 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
5240 Create a finish breakpoint at the return address of the @code{gdb.Frame}
5241 object @var{frame}. If @var{frame} is not provided, this defaults to the
5242 newest frame. The optional @var{internal} argument allows the breakpoint to
5243 become invisible to the user. @xref{Breakpoints In Python}, for further
5244 details about this argument.
5247 @defun FinishBreakpoint.out_of_scope (self)
5248 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
5249 @code{return} command, @dots{}), a function may not properly terminate, and
5250 thus never hit the finish breakpoint. When @value{GDBN} notices such a
5251 situation, the @code{out_of_scope} callback will be triggered.
5253 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
5257 class MyFinishBreakpoint (gdb.FinishBreakpoint)
5259 print "normal finish"
5262 def out_of_scope ():
5263 print "abnormal finish"
5267 @defvar FinishBreakpoint.return_value
5268 When @value{GDBN} is stopped at a finish breakpoint and the frame
5269 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
5270 attribute will contain a @code{gdb.Value} object corresponding to the return
5271 value of the function. The value will be @code{None} if the function return
5272 type is @code{void} or if the return value was not computable. This attribute
5276 @node Lazy Strings In Python
5277 @subsubsection Python representation of lazy strings
5279 @cindex lazy strings in python
5280 @tindex gdb.LazyString
5282 A @dfn{lazy string} is a string whose contents is not retrieved or
5283 encoded until it is needed.
5285 A @code{gdb.LazyString} is represented in @value{GDBN} as an
5286 @code{address} that points to a region of memory, an @code{encoding}
5287 that will be used to encode that region of memory, and a @code{length}
5288 to delimit the region of memory that represents the string. The
5289 difference between a @code{gdb.LazyString} and a string wrapped within
5290 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
5291 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
5292 retrieved and encoded during printing, while a @code{gdb.Value}
5293 wrapping a string is immediately retrieved and encoded on creation.
5295 A @code{gdb.LazyString} object has the following functions:
5297 @defun LazyString.value ()
5298 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
5299 will point to the string in memory, but will lose all the delayed
5300 retrieval, encoding and handling that @value{GDBN} applies to a
5301 @code{gdb.LazyString}.
5304 @defvar LazyString.address
5305 This attribute holds the address of the string. This attribute is not
5309 @defvar LazyString.length
5310 This attribute holds the length of the string in characters. If the
5311 length is -1, then the string will be fetched and encoded up to the
5312 first null of appropriate width. This attribute is not writable.
5315 @defvar LazyString.encoding
5316 This attribute holds the encoding that will be applied to the string
5317 when the string is printed by @value{GDBN}. If the encoding is not
5318 set, or contains an empty string, then @value{GDBN} will select the
5319 most appropriate encoding when the string is printed. This attribute
5323 @defvar LazyString.type
5324 This attribute holds the type that is represented by the lazy string's
5325 type. For a lazy string this is a pointer or array type. To
5326 resolve this to the lazy string's character type, use the type's
5327 @code{target} method. @xref{Types In Python}. This attribute is not
5331 @node Architectures In Python
5332 @subsubsection Python representation of architectures
5333 @cindex Python architectures
5335 @value{GDBN} uses architecture specific parameters and artifacts in a
5336 number of its various computations. An architecture is represented
5337 by an instance of the @code{gdb.Architecture} class.
5339 A @code{gdb.Architecture} class has the following methods:
5341 @defun Architecture.name ()
5342 Return the name (string value) of the architecture.
5345 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
5346 Return a list of disassembled instructions starting from the memory
5347 address @var{start_pc}. The optional arguments @var{end_pc} and
5348 @var{count} determine the number of instructions in the returned list.
5349 If both the optional arguments @var{end_pc} and @var{count} are
5350 specified, then a list of at most @var{count} disassembled instructions
5351 whose start address falls in the closed memory address interval from
5352 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
5353 specified, but @var{count} is specified, then @var{count} number of
5354 instructions starting from the address @var{start_pc} are returned. If
5355 @var{count} is not specified but @var{end_pc} is specified, then all
5356 instructions whose start address falls in the closed memory address
5357 interval from @var{start_pc} to @var{end_pc} are returned. If neither
5358 @var{end_pc} nor @var{count} are specified, then a single instruction at
5359 @var{start_pc} is returned. For all of these cases, each element of the
5360 returned list is a Python @code{dict} with the following string keys:
5365 The value corresponding to this key is a Python long integer capturing
5366 the memory address of the instruction.
5369 The value corresponding to this key is a string value which represents
5370 the instruction with assembly language mnemonics. The assembly
5371 language flavor used is the same as that specified by the current CLI
5372 variable @code{disassembly-flavor}. @xref{Machine Code}.
5375 The value corresponding to this key is the length (integer value) of the
5376 instruction in bytes.
5381 @node Python Auto-loading
5382 @subsection Python Auto-loading
5383 @cindex Python auto-loading
5385 When a new object file is read (for example, due to the @code{file}
5386 command, or because the inferior has loaded a shared library),
5387 @value{GDBN} will look for Python support scripts in several ways:
5388 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
5389 @xref{Auto-loading extensions}.
5391 The auto-loading feature is useful for supplying application-specific
5392 debugging commands and scripts.
5394 Auto-loading can be enabled or disabled,
5395 and the list of auto-loaded scripts can be printed.
5398 @anchor{set auto-load python-scripts}
5399 @kindex set auto-load python-scripts
5400 @item set auto-load python-scripts [on|off]
5401 Enable or disable the auto-loading of Python scripts.
5403 @anchor{show auto-load python-scripts}
5404 @kindex show auto-load python-scripts
5405 @item show auto-load python-scripts
5406 Show whether auto-loading of Python scripts is enabled or disabled.
5408 @anchor{info auto-load python-scripts}
5409 @kindex info auto-load python-scripts
5410 @cindex print list of auto-loaded Python scripts
5411 @item info auto-load python-scripts [@var{regexp}]
5412 Print the list of all Python scripts that @value{GDBN} auto-loaded.
5414 Also printed is the list of Python scripts that were mentioned in
5415 the @code{.debug_gdb_scripts} section and were either not found
5416 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
5417 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
5418 This is useful because their names are not printed when @value{GDBN}
5419 tries to load them and fails. There may be many of them, and printing
5420 an error message for each one is problematic.
5422 If @var{regexp} is supplied only Python scripts with matching names are printed.
5427 (gdb) info auto-load python-scripts
5429 Yes py-section-script.py
5430 full name: /tmp/py-section-script.py
5431 No my-foo-pretty-printers.py
5435 When reading an auto-loaded file or script, @value{GDBN} sets the
5436 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
5437 function (@pxref{Objfiles In Python}). This can be useful for
5438 registering objfile-specific pretty-printers and frame-filters.
5440 @node Python modules
5441 @subsection Python modules
5442 @cindex python modules
5444 @value{GDBN} comes with several modules to assist writing Python code.
5447 * gdb.printing:: Building and registering pretty-printers.
5448 * gdb.types:: Utilities for working with types.
5449 * gdb.prompt:: Utilities for prompt value substitution.
5453 @subsubsection gdb.printing
5454 @cindex gdb.printing
5456 This module provides a collection of utilities for working with
5460 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
5461 This class specifies the API that makes @samp{info pretty-printer},
5462 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
5463 Pretty-printers should generally inherit from this class.
5465 @item SubPrettyPrinter (@var{name})
5466 For printers that handle multiple types, this class specifies the
5467 corresponding API for the subprinters.
5469 @item RegexpCollectionPrettyPrinter (@var{name})
5470 Utility class for handling multiple printers, all recognized via
5471 regular expressions.
5472 @xref{Writing a Pretty-Printer}, for an example.
5474 @item FlagEnumerationPrinter (@var{name})
5475 A pretty-printer which handles printing of @code{enum} values. Unlike
5476 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
5477 work properly when there is some overlap between the enumeration
5478 constants. The argument @var{name} is the name of the printer and
5479 also the name of the @code{enum} type to look up.
5481 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
5482 Register @var{printer} with the pretty-printer list of @var{obj}.
5483 If @var{replace} is @code{True} then any existing copy of the printer
5484 is replaced. Otherwise a @code{RuntimeError} exception is raised
5485 if a printer with the same name already exists.
5489 @subsubsection gdb.types
5492 This module provides a collection of utilities for working with
5493 @code{gdb.Type} objects.
5496 @item get_basic_type (@var{type})
5497 Return @var{type} with const and volatile qualifiers stripped,
5498 and with typedefs and C@t{++} references converted to the underlying type.
5503 typedef const int const_int;
5505 const_int& foo_ref (foo);
5506 int main () @{ return 0; @}
5513 (gdb) python import gdb.types
5514 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
5515 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
5519 @item has_field (@var{type}, @var{field})
5520 Return @code{True} if @var{type}, assumed to be a type with fields
5521 (e.g., a structure or union), has field @var{field}.
5523 @item make_enum_dict (@var{enum_type})
5524 Return a Python @code{dictionary} type produced from @var{enum_type}.
5526 @item deep_items (@var{type})
5527 Returns a Python iterator similar to the standard
5528 @code{gdb.Type.iteritems} method, except that the iterator returned
5529 by @code{deep_items} will recursively traverse anonymous struct or
5530 union fields. For example:
5544 Then in @value{GDBN}:
5546 (@value{GDBP}) python import gdb.types
5547 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
5548 (@value{GDBP}) python print struct_a.keys ()
5550 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
5551 @{['a', 'b0', 'b1']@}
5554 @item get_type_recognizers ()
5555 Return a list of the enabled type recognizers for the current context.
5556 This is called by @value{GDBN} during the type-printing process
5557 (@pxref{Type Printing API}).
5559 @item apply_type_recognizers (recognizers, type_obj)
5560 Apply the type recognizers, @var{recognizers}, to the type object
5561 @var{type_obj}. If any recognizer returns a string, return that
5562 string. Otherwise, return @code{None}. This is called by
5563 @value{GDBN} during the type-printing process (@pxref{Type Printing
5566 @item register_type_printer (locus, printer)
5567 This is a convenience function to register a type printer
5568 @var{printer}. The printer must implement the type printer protocol.
5569 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
5570 the printer is registered with that objfile; a @code{gdb.Progspace},
5571 in which case the printer is registered with that progspace; or
5572 @code{None}, in which case the printer is registered globally.
5575 This is a base class that implements the type printer protocol. Type
5576 printers are encouraged, but not required, to derive from this class.
5577 It defines a constructor:
5579 @defmethod TypePrinter __init__ (self, name)
5580 Initialize the type printer with the given name. The new printer
5581 starts in the enabled state.
5587 @subsubsection gdb.prompt
5590 This module provides a method for prompt value-substitution.
5593 @item substitute_prompt (@var{string})
5594 Return @var{string} with escape sequences substituted by values. Some
5595 escape sequences take arguments. You can specify arguments inside
5596 ``@{@}'' immediately following the escape sequence.
5598 The escape sequences you can pass to this function are:
5602 Substitute a backslash.
5604 Substitute an ESC character.
5606 Substitute the selected frame; an argument names a frame parameter.
5608 Substitute a newline.
5610 Substitute a parameter's value; the argument names the parameter.
5612 Substitute a carriage return.
5614 Substitute the selected thread; an argument names a thread parameter.
5616 Substitute the version of GDB.
5618 Substitute the current working directory.
5620 Begin a sequence of non-printing characters. These sequences are
5621 typically used with the ESC character, and are not counted in the string
5622 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
5623 blue-colored ``(gdb)'' prompt where the length is five.
5625 End a sequence of non-printing characters.
5631 substitute_prompt (``frame: \f,
5632 print arguments: \p@{print frame-arguments@}'')
5635 @exdent will return the string:
5638 "frame: main, print arguments: scalars"