1 @c Copyright (C) 2008-2017 Free Software Foundation, Inc.
2 @c Permission is granted to copy, distribute and/or modify this document
3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
4 @c any later version published by the Free Software Foundation; with the
5 @c Invariant Sections being ``Free Software'' and ``Free Software Needs
6 @c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
7 @c and with the Back-Cover Texts as in (a) below.
9 @c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
10 @c this GNU Manual. Buying copies from GNU Press supports the FSF in
11 @c developing GNU and promoting software freedom.''
14 @section Extending @value{GDBN} using Python
15 @cindex python scripting
16 @cindex scripting with python
18 You can extend @value{GDBN} using the @uref{http://www.python.org/,
19 Python programming language}. This feature is available only if
20 @value{GDBN} was configured using @option{--with-python}.
22 @cindex python directory
23 Python scripts used by @value{GDBN} should be installed in
24 @file{@var{data-directory}/python}, where @var{data-directory} is
25 the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
26 This directory, known as the @dfn{python directory},
27 is automatically added to the Python Search Path in order to allow
28 the Python interpreter to locate all scripts installed at this location.
30 Additionally, @value{GDBN} commands and convenience functions which
31 are written in Python and are located in the
32 @file{@var{data-directory}/python/gdb/command} or
33 @file{@var{data-directory}/python/gdb/function} directories are
34 automatically imported when @value{GDBN} starts.
37 * Python Commands:: Accessing Python from @value{GDBN}.
38 * Python API:: Accessing @value{GDBN} from Python.
39 * Python Auto-loading:: Automatically loading Python code.
40 * Python modules:: Python modules provided by @value{GDBN}.
44 @subsection Python Commands
45 @cindex python commands
46 @cindex commands to access python
48 @value{GDBN} provides two commands for accessing the Python interpreter,
49 and one related setting:
52 @kindex python-interactive
54 @item python-interactive @r{[}@var{command}@r{]}
55 @itemx pi @r{[}@var{command}@r{]}
56 Without an argument, the @code{python-interactive} command can be used
57 to start an interactive Python prompt. To return to @value{GDBN},
58 type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
60 Alternatively, a single-line Python command can be given as an
61 argument and evaluated. If the command is an expression, the result
62 will be printed; otherwise, nothing will be printed. For example:
65 (@value{GDBP}) python-interactive 2 + 3
71 @item python @r{[}@var{command}@r{]}
72 @itemx py @r{[}@var{command}@r{]}
73 The @code{python} command can be used to evaluate Python code.
75 If given an argument, the @code{python} command will evaluate the
76 argument as a Python command. For example:
79 (@value{GDBP}) python print 23
83 If you do not provide an argument to @code{python}, it will act as a
84 multi-line command, like @code{define}. In this case, the Python
85 script is made up of subsequent command lines, given after the
86 @code{python} command. This command list is terminated using a line
87 containing @code{end}. For example:
92 End with a line saying just "end".
98 @kindex set python print-stack
99 @item set python print-stack
100 By default, @value{GDBN} will print only the message component of a
101 Python exception when an error occurs in a Python script. This can be
102 controlled using @code{set python print-stack}: if @code{full}, then
103 full Python stack printing is enabled; if @code{none}, then Python stack
104 and message printing is disabled; if @code{message}, the default, only
105 the message component of the error is printed.
108 It is also possible to execute a Python script from the @value{GDBN}
112 @item source @file{script-name}
113 The script name must end with @samp{.py} and @value{GDBN} must be configured
114 to recognize the script language based on filename extension using
115 the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
117 @item python execfile ("script-name")
118 This method is based on the @code{execfile} Python built-in function,
119 and thus is always available.
123 @subsection Python API
125 @cindex programming in python
127 You can get quick online help for @value{GDBN}'s Python API by issuing
128 the command @w{@kbd{python help (gdb)}}.
130 Functions and methods which have two or more optional arguments allow
131 them to be specified using keyword syntax. This allows passing some
132 optional arguments while skipping others. Example:
133 @w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
136 * Basic Python:: Basic Python Functions.
137 * Exception Handling:: How Python exceptions are translated.
138 * Values From Inferior:: Python representation of values.
139 * Types In Python:: Python representation of types.
140 * Pretty Printing API:: Pretty-printing values.
141 * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
142 * Writing a Pretty-Printer:: Writing a Pretty-Printer.
143 * Type Printing API:: Pretty-printing types.
144 * Frame Filter API:: Filtering Frames.
145 * Frame Decorator API:: Decorating Frames.
146 * Writing a Frame Filter:: Writing a Frame Filter.
147 * Unwinding Frames in Python:: Writing frame unwinder.
148 * Xmethods In Python:: Adding and replacing methods of C++ classes.
149 * Xmethod API:: Xmethod types.
150 * Writing an Xmethod:: Writing an xmethod.
151 * Inferiors In Python:: Python representation of inferiors (processes)
152 * Events In Python:: Listening for events from @value{GDBN}.
153 * Threads In Python:: Accessing inferior threads from Python.
154 * Recordings In Python:: Accessing recordings from Python.
155 * Commands In Python:: Implementing new commands in Python.
156 * Parameters In Python:: Adding new @value{GDBN} parameters.
157 * Functions In Python:: Writing new convenience functions.
158 * Progspaces In Python:: Program spaces.
159 * Objfiles In Python:: Object files.
160 * Frames In Python:: Accessing inferior stack frames from Python.
161 * Blocks In Python:: Accessing blocks from Python.
162 * Symbols In Python:: Python representation of symbols.
163 * Symbol Tables In Python:: Python representation of symbol tables.
164 * Line Tables In Python:: Python representation of line tables.
165 * Breakpoints In Python:: Manipulating breakpoints using Python.
166 * Finish Breakpoints in Python:: Setting Breakpoints on function return
168 * Lazy Strings In Python:: Python representation of lazy strings.
169 * Architectures In Python:: Python representation of architectures.
173 @subsubsection Basic Python
175 @cindex python stdout
176 @cindex python pagination
177 At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
178 @code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
179 A Python program which outputs to one of these streams may have its
180 output interrupted by the user (@pxref{Screen Size}). In this
181 situation, a Python @code{KeyboardInterrupt} exception is thrown.
183 Some care must be taken when writing Python code to run in
184 @value{GDBN}. Two things worth noting in particular:
188 @value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
189 Python code must not override these, or even change the options using
190 @code{sigaction}. If your program changes the handling of these
191 signals, @value{GDBN} will most likely stop working correctly. Note
192 that it is unfortunately common for GUI toolkits to install a
193 @code{SIGCHLD} handler.
196 @value{GDBN} takes care to mark its internal file descriptors as
197 close-on-exec. However, this cannot be done in a thread-safe way on
198 all platforms. Your Python programs should be aware of this and
199 should both create new file descriptors with the close-on-exec flag
200 set and arrange to close unneeded file descriptors before starting a
204 @cindex python functions
205 @cindex python module
207 @value{GDBN} introduces a new Python module, named @code{gdb}. All
208 methods and classes added by @value{GDBN} are placed in this module.
209 @value{GDBN} automatically @code{import}s the @code{gdb} module for
210 use in all scripts evaluated by the @code{python} command.
212 @findex gdb.PYTHONDIR
213 @defvar gdb.PYTHONDIR
214 A string containing the python directory (@pxref{Python}).
218 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
219 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
220 If a GDB exception happens while @var{command} runs, it is
221 translated as described in @ref{Exception Handling,,Exception Handling}.
223 The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
224 command as having originated from the user invoking it interactively.
225 It must be a boolean value. If omitted, it defaults to @code{False}.
227 By default, any output produced by @var{command} is sent to
228 @value{GDBN}'s standard output (and to the log output if logging is
229 turned on). If the @var{to_string} parameter is
230 @code{True}, then output will be collected by @code{gdb.execute} and
231 returned as a string. The default is @code{False}, in which case the
232 return value is @code{None}. If @var{to_string} is @code{True}, the
233 @value{GDBN} virtual terminal will be temporarily set to unlimited width
234 and height, and its pagination will be disabled; @pxref{Screen Size}.
237 @findex gdb.breakpoints
238 @defun gdb.breakpoints ()
239 Return a sequence holding all of @value{GDBN}'s breakpoints.
240 @xref{Breakpoints In Python}, for more information. In @value{GDBN}
241 version 7.11 and earlier, this function returned @code{None} if there
242 were no breakpoints. This peculiarity was subsequently fixed, and now
243 @code{gdb.breakpoints} returns an empty sequence in this case.
246 @defun gdb.rbreak (regex @r{[}, minsyms @r{[}, throttle, @r{[}, symtabs @r{]]]})
247 Return a Python list holding a collection of newly set
248 @code{gdb.Breakpoint} objects matching function names defined by the
249 @var{regex} pattern. If the @var{minsyms} keyword is @code{True}, all
250 system functions (those not explicitly defined in the inferior) will
251 also be included in the match. The @var{throttle} keyword takes an
252 integer that defines the maximum number of pattern matches for
253 functions matched by the @var{regex} pattern. If the number of
254 matches exceeds the integer value of @var{throttle}, a
255 @code{RuntimeError} will be raised and no breakpoints will be created.
256 If @var{throttle} is not defined then there is no imposed limit on the
257 maximum number of matches and breakpoints to be created. The
258 @var{symtabs} keyword takes a Python iterable that yields a collection
259 of @code{gdb.Symtab} objects and will restrict the search to those
260 functions only contained within the @code{gdb.Symtab} objects.
263 @findex gdb.parameter
264 @defun gdb.parameter (parameter)
265 Return the value of a @value{GDBN} @var{parameter} given by its name,
266 a string; the parameter name string may contain spaces if the parameter has a
267 multi-part name. For example, @samp{print object} is a valid
270 If the named parameter does not exist, this function throws a
271 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
272 parameter's value is converted to a Python value of the appropriate
277 @defun gdb.history (number)
278 Return a value from @value{GDBN}'s value history (@pxref{Value
279 History}). The @var{number} argument indicates which history element to return.
280 If @var{number} is negative, then @value{GDBN} will take its absolute value
281 and count backward from the last element (i.e., the most recent element) to
282 find the value to return. If @var{number} is zero, then @value{GDBN} will
283 return the most recent element. If the element specified by @var{number}
284 doesn't exist in the value history, a @code{gdb.error} exception will be
287 If no exception is raised, the return value is always an instance of
288 @code{gdb.Value} (@pxref{Values From Inferior}).
291 @findex gdb.parse_and_eval
292 @defun gdb.parse_and_eval (expression)
293 Parse @var{expression}, which must be a string, as an expression in
294 the current language, evaluate it, and return the result as a
297 This function can be useful when implementing a new command
298 (@pxref{Commands In Python}), as it provides a way to parse the
299 command's argument as an expression. It is also useful simply to
300 compute values, for example, it is the only way to get the value of a
301 convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
304 @findex gdb.find_pc_line
305 @defun gdb.find_pc_line (pc)
306 Return the @code{gdb.Symtab_and_line} object corresponding to the
307 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
308 value of @var{pc} is passed as an argument, then the @code{symtab} and
309 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
310 will be @code{None} and 0 respectively.
313 @findex gdb.post_event
314 @defun gdb.post_event (event)
315 Put @var{event}, a callable object taking no arguments, into
316 @value{GDBN}'s internal event queue. This callable will be invoked at
317 some later point, during @value{GDBN}'s event processing. Events
318 posted using @code{post_event} will be run in the order in which they
319 were posted; however, there is no way to know when they will be
320 processed relative to other events inside @value{GDBN}.
322 @value{GDBN} is not thread-safe. If your Python program uses multiple
323 threads, you must be careful to only call @value{GDBN}-specific
324 functions in the @value{GDBN} thread. @code{post_event} ensures
328 (@value{GDBP}) python
332 > def __init__(self, message):
333 > self.message = message;
334 > def __call__(self):
335 > gdb.write(self.message)
337 >class MyThread1 (threading.Thread):
339 > gdb.post_event(Writer("Hello "))
341 >class MyThread2 (threading.Thread):
343 > gdb.post_event(Writer("World\n"))
348 (@value{GDBP}) Hello World
353 @defun gdb.write (string @r{[}, stream{]})
354 Print a string to @value{GDBN}'s paginated output stream. The
355 optional @var{stream} determines the stream to print to. The default
356 stream is @value{GDBN}'s standard output stream. Possible stream
363 @value{GDBN}'s standard output stream.
368 @value{GDBN}'s standard error stream.
373 @value{GDBN}'s log stream (@pxref{Logging Output}).
376 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
377 call this function and will automatically direct the output to the
383 Flush the buffer of a @value{GDBN} paginated stream so that the
384 contents are displayed immediately. @value{GDBN} will flush the
385 contents of a stream automatically when it encounters a newline in the
386 buffer. The optional @var{stream} determines the stream to flush. The
387 default stream is @value{GDBN}'s standard output stream. Possible
394 @value{GDBN}'s standard output stream.
399 @value{GDBN}'s standard error stream.
404 @value{GDBN}'s log stream (@pxref{Logging Output}).
408 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
409 call this function for the relevant stream.
412 @findex gdb.target_charset
413 @defun gdb.target_charset ()
414 Return the name of the current target character set (@pxref{Character
415 Sets}). This differs from @code{gdb.parameter('target-charset')} in
416 that @samp{auto} is never returned.
419 @findex gdb.target_wide_charset
420 @defun gdb.target_wide_charset ()
421 Return the name of the current target wide character set
422 (@pxref{Character Sets}). This differs from
423 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
427 @findex gdb.solib_name
428 @defun gdb.solib_name (address)
429 Return the name of the shared library holding the given @var{address}
430 as a string, or @code{None}.
433 @findex gdb.decode_line
434 @defun gdb.decode_line @r{[}expression@r{]}
435 Return locations of the line specified by @var{expression}, or of the
436 current line if no argument was given. This function returns a Python
437 tuple containing two elements. The first element contains a string
438 holding any unparsed section of @var{expression} (or @code{None} if
439 the expression has been fully parsed). The second element contains
440 either @code{None} or another tuple that contains all the locations
441 that match the expression represented as @code{gdb.Symtab_and_line}
442 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
443 provided, it is decoded the way that @value{GDBN}'s inbuilt
444 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
447 @defun gdb.prompt_hook (current_prompt)
450 If @var{prompt_hook} is callable, @value{GDBN} will call the method
451 assigned to this operation before a prompt is displayed by
454 The parameter @code{current_prompt} contains the current @value{GDBN}
455 prompt. This method must return a Python string, or @code{None}. If
456 a string is returned, the @value{GDBN} prompt will be set to that
457 string. If @code{None} is returned, @value{GDBN} will continue to use
460 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
461 such as those used by readline for command input, and annotation
462 related prompts are prohibited from being changed.
465 @node Exception Handling
466 @subsubsection Exception Handling
467 @cindex python exceptions
468 @cindex exceptions, python
470 When executing the @code{python} command, Python exceptions
471 uncaught within the Python code are translated to calls to
472 @value{GDBN} error-reporting mechanism. If the command that called
473 @code{python} does not handle the error, @value{GDBN} will
474 terminate it and print an error message containing the Python
475 exception name, the associated value, and the Python call stack
476 backtrace at the point where the exception was raised. Example:
479 (@value{GDBP}) python print foo
480 Traceback (most recent call last):
481 File "<string>", line 1, in <module>
482 NameError: name 'foo' is not defined
485 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
486 Python code are converted to Python exceptions. The type of the
487 Python exception depends on the error.
491 This is the base class for most exceptions generated by @value{GDBN}.
492 It is derived from @code{RuntimeError}, for compatibility with earlier
493 versions of @value{GDBN}.
495 If an error occurring in @value{GDBN} does not fit into some more
496 specific category, then the generated exception will have this type.
498 @item gdb.MemoryError
499 This is a subclass of @code{gdb.error} which is thrown when an
500 operation tried to access invalid memory in the inferior.
502 @item KeyboardInterrupt
503 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
504 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
507 In all cases, your exception handler will see the @value{GDBN} error
508 message as its value and the Python call stack backtrace at the Python
509 statement closest to where the @value{GDBN} error occured as the
513 When implementing @value{GDBN} commands in Python via @code{gdb.Command},
514 it is useful to be able to throw an exception that doesn't cause a
515 traceback to be printed. For example, the user may have invoked the
516 command incorrectly. Use the @code{gdb.GdbError} exception
517 to handle this case. Example:
521 >class HelloWorld (gdb.Command):
522 > """Greet the whole world."""
523 > def __init__ (self):
524 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
525 > def invoke (self, args, from_tty):
526 > argv = gdb.string_to_argv (args)
527 > if len (argv) != 0:
528 > raise gdb.GdbError ("hello-world takes no arguments")
529 > print "Hello, World!"
533 hello-world takes no arguments
536 @node Values From Inferior
537 @subsubsection Values From Inferior
538 @cindex values from inferior, with Python
539 @cindex python, working with values from inferior
541 @cindex @code{gdb.Value}
542 @value{GDBN} provides values it obtains from the inferior program in
543 an object of type @code{gdb.Value}. @value{GDBN} uses this object
544 for its internal bookkeeping of the inferior's values, and for
545 fetching values when necessary.
547 Inferior values that are simple scalars can be used directly in
548 Python expressions that are valid for the value's data type. Here's
549 an example for an integer or floating-point value @code{some_val}:
556 As result of this, @code{bar} will also be a @code{gdb.Value} object
557 whose values are of the same type as those of @code{some_val}. Valid
558 Python operations can also be performed on @code{gdb.Value} objects
559 representing a @code{struct} or @code{class} object. For such cases,
560 the overloaded operator (if present), is used to perform the operation.
561 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
562 representing instances of a @code{class} which overloads the @code{+}
563 operator, then one can use the @code{+} operator in their Python script
571 The result of the operation @code{val3} is also a @code{gdb.Value}
572 object corresponding to the value returned by the overloaded @code{+}
573 operator. In general, overloaded operators are invoked for the
574 following operations: @code{+} (binary addition), @code{-} (binary
575 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
576 @code{>>}, @code{|}, @code{&}, @code{^}.
578 Inferior values that are structures or instances of some class can
579 be accessed using the Python @dfn{dictionary syntax}. For example, if
580 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
581 can access its @code{foo} element with:
584 bar = some_val['foo']
587 @cindex getting structure elements using gdb.Field objects as subscripts
588 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
589 elements can also be accessed by using @code{gdb.Field} objects as
590 subscripts (@pxref{Types In Python}, for more information on
591 @code{gdb.Field} objects). For example, if @code{foo_field} is a
592 @code{gdb.Field} object corresponding to element @code{foo} of the above
593 structure, then @code{bar} can also be accessed as follows:
596 bar = some_val[foo_field]
599 A @code{gdb.Value} that represents a function can be executed via
600 inferior function call. Any arguments provided to the call must match
601 the function's prototype, and must be provided in the order specified
604 For example, @code{some_val} is a @code{gdb.Value} instance
605 representing a function that takes two integers as arguments. To
606 execute this function, call it like so:
609 result = some_val (10,20)
612 Any values returned from a function call will be stored as a
615 The following attributes are provided:
617 @defvar Value.address
618 If this object is addressable, this read-only attribute holds a
619 @code{gdb.Value} object representing the address. Otherwise,
620 this attribute holds @code{None}.
623 @cindex optimized out value in Python
624 @defvar Value.is_optimized_out
625 This read-only boolean attribute is true if the compiler optimized out
626 this value, thus it is not available for fetching from the inferior.
630 The type of this @code{gdb.Value}. The value of this attribute is a
631 @code{gdb.Type} object (@pxref{Types In Python}).
634 @defvar Value.dynamic_type
635 The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time
636 type information (@acronym{RTTI}) to determine the dynamic type of the
637 value. If this value is of class type, it will return the class in
638 which the value is embedded, if any. If this value is of pointer or
639 reference to a class type, it will compute the dynamic type of the
640 referenced object, and return a pointer or reference to that type,
641 respectively. In all other cases, it will return the value's static
644 Note that this feature will only work when debugging a C@t{++} program
645 that includes @acronym{RTTI} for the object in question. Otherwise,
646 it will just return the static type of the value as in @kbd{ptype foo}
647 (@pxref{Symbols, ptype}).
650 @defvar Value.is_lazy
651 The value of this read-only boolean attribute is @code{True} if this
652 @code{gdb.Value} has not yet been fetched from the inferior.
653 @value{GDBN} does not fetch values until necessary, for efficiency.
657 myval = gdb.parse_and_eval ('somevar')
660 The value of @code{somevar} is not fetched at this time. It will be
661 fetched when the value is needed, or when the @code{fetch_lazy}
665 The following methods are provided:
667 @defun Value.__init__ (@var{val})
668 Many Python values can be converted directly to a @code{gdb.Value} via
669 this object initializer. Specifically:
673 A Python boolean is converted to the boolean type from the current
677 A Python integer is converted to the C @code{long} type for the
678 current architecture.
681 A Python long is converted to the C @code{long long} type for the
682 current architecture.
685 A Python float is converted to the C @code{double} type for the
686 current architecture.
689 A Python string is converted to a target string in the current target
690 language using the current target encoding.
691 If a character cannot be represented in the current target encoding,
692 then an exception is thrown.
694 @item @code{gdb.Value}
695 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
697 @item @code{gdb.LazyString}
698 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
699 Python}), then the lazy string's @code{value} method is called, and
704 @defun Value.cast (type)
705 Return a new instance of @code{gdb.Value} that is the result of
706 casting this instance to the type described by @var{type}, which must
707 be a @code{gdb.Type} object. If the cast cannot be performed for some
708 reason, this method throws an exception.
711 @defun Value.dereference ()
712 For pointer data types, this method returns a new @code{gdb.Value} object
713 whose contents is the object pointed to by the pointer. For example, if
714 @code{foo} is a C pointer to an @code{int}, declared in your C program as
721 then you can use the corresponding @code{gdb.Value} to access what
722 @code{foo} points to like this:
725 bar = foo.dereference ()
728 The result @code{bar} will be a @code{gdb.Value} object holding the
729 value pointed to by @code{foo}.
731 A similar function @code{Value.referenced_value} exists which also
732 returns @code{gdb.Value} objects corresonding to the values pointed to
733 by pointer values (and additionally, values referenced by reference
734 values). However, the behavior of @code{Value.dereference}
735 differs from @code{Value.referenced_value} by the fact that the
736 behavior of @code{Value.dereference} is identical to applying the C
737 unary operator @code{*} on a given value. For example, consider a
738 reference to a pointer @code{ptrref}, declared in your C@t{++} program
746 intptr &ptrref = ptr;
749 Though @code{ptrref} is a reference value, one can apply the method
750 @code{Value.dereference} to the @code{gdb.Value} object corresponding
751 to it and obtain a @code{gdb.Value} which is identical to that
752 corresponding to @code{val}. However, if you apply the method
753 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
754 object identical to that corresponding to @code{ptr}.
757 py_ptrref = gdb.parse_and_eval ("ptrref")
758 py_val = py_ptrref.dereference ()
759 py_ptr = py_ptrref.referenced_value ()
762 The @code{gdb.Value} object @code{py_val} is identical to that
763 corresponding to @code{val}, and @code{py_ptr} is identical to that
764 corresponding to @code{ptr}. In general, @code{Value.dereference} can
765 be applied whenever the C unary operator @code{*} can be applied
766 to the corresponding C value. For those cases where applying both
767 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
768 the results obtained need not be identical (as we have seen in the above
769 example). The results are however identical when applied on
770 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
771 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
774 @defun Value.referenced_value ()
775 For pointer or reference data types, this method returns a new
776 @code{gdb.Value} object corresponding to the value referenced by the
777 pointer/reference value. For pointer data types,
778 @code{Value.dereference} and @code{Value.referenced_value} produce
779 identical results. The difference between these methods is that
780 @code{Value.dereference} cannot get the values referenced by reference
781 values. For example, consider a reference to an @code{int}, declared
782 in your C@t{++} program as
790 then applying @code{Value.dereference} to the @code{gdb.Value} object
791 corresponding to @code{ref} will result in an error, while applying
792 @code{Value.referenced_value} will result in a @code{gdb.Value} object
793 identical to that corresponding to @code{val}.
796 py_ref = gdb.parse_and_eval ("ref")
797 er_ref = py_ref.dereference () # Results in error
798 py_val = py_ref.referenced_value () # Returns the referenced value
801 The @code{gdb.Value} object @code{py_val} is identical to that
802 corresponding to @code{val}.
805 @defun Value.reference_value ()
806 Return a @code{gdb.Value} object which is a reference to the value
807 encapsulated by this instance.
810 @defun Value.const_value ()
811 Return a @code{gdb.Value} object which is a @code{const} version of the
812 value encapsulated by this instance.
815 @defun Value.dynamic_cast (type)
816 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
817 operator were used. Consult a C@t{++} reference for details.
820 @defun Value.reinterpret_cast (type)
821 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
822 operator were used. Consult a C@t{++} reference for details.
825 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
826 If this @code{gdb.Value} represents a string, then this method
827 converts the contents to a Python string. Otherwise, this method will
830 Values are interpreted as strings according to the rules of the
831 current language. If the optional length argument is given, the
832 string will be converted to that length, and will include any embedded
833 zeroes that the string may contain. Otherwise, for languages
834 where the string is zero-terminated, the entire string will be
837 For example, in C-like languages, a value is a string if it is a pointer
838 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
841 If the optional @var{encoding} argument is given, it must be a string
842 naming the encoding of the string in the @code{gdb.Value}, such as
843 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
844 the same encodings as the corresponding argument to Python's
845 @code{string.decode} method, and the Python codec machinery will be used
846 to convert the string. If @var{encoding} is not given, or if
847 @var{encoding} is the empty string, then either the @code{target-charset}
848 (@pxref{Character Sets}) will be used, or a language-specific encoding
849 will be used, if the current language is able to supply one.
851 The optional @var{errors} argument is the same as the corresponding
852 argument to Python's @code{string.decode} method.
854 If the optional @var{length} argument is given, the string will be
855 fetched and converted to the given length.
858 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
859 If this @code{gdb.Value} represents a string, then this method
860 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
861 In Python}). Otherwise, this method will throw an exception.
863 If the optional @var{encoding} argument is given, it must be a string
864 naming the encoding of the @code{gdb.LazyString}. Some examples are:
865 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
866 @var{encoding} argument is an encoding that @value{GDBN} does
867 recognize, @value{GDBN} will raise an error.
869 When a lazy string is printed, the @value{GDBN} encoding machinery is
870 used to convert the string during printing. If the optional
871 @var{encoding} argument is not provided, or is an empty string,
872 @value{GDBN} will automatically select the encoding most suitable for
873 the string type. For further information on encoding in @value{GDBN}
874 please see @ref{Character Sets}.
876 If the optional @var{length} argument is given, the string will be
877 fetched and encoded to the length of characters specified. If
878 the @var{length} argument is not provided, the string will be fetched
879 and encoded until a null of appropriate width is found.
882 @defun Value.fetch_lazy ()
883 If the @code{gdb.Value} object is currently a lazy value
884 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
885 fetched from the inferior. Any errors that occur in the process
886 will produce a Python exception.
888 If the @code{gdb.Value} object is not a lazy value, this method
891 This method does not return a value.
895 @node Types In Python
896 @subsubsection Types In Python
897 @cindex types in Python
898 @cindex Python, working with types
901 @value{GDBN} represents types from the inferior using the class
904 The following type-related functions are available in the @code{gdb}
907 @findex gdb.lookup_type
908 @defun gdb.lookup_type (name @r{[}, block@r{]})
909 This function looks up a type by its @var{name}, which must be a string.
911 If @var{block} is given, then @var{name} is looked up in that scope.
912 Otherwise, it is searched for globally.
914 Ordinarily, this function will return an instance of @code{gdb.Type}.
915 If the named type cannot be found, it will throw an exception.
918 If the type is a structure or class type, or an enum type, the fields
919 of that type can be accessed using the Python @dfn{dictionary syntax}.
920 For example, if @code{some_type} is a @code{gdb.Type} instance holding
921 a structure type, you can access its @code{foo} field with:
924 bar = some_type['foo']
927 @code{bar} will be a @code{gdb.Field} object; see below under the
928 description of the @code{Type.fields} method for a description of the
929 @code{gdb.Field} class.
931 An instance of @code{Type} has the following attributes:
934 The type code for this type. The type code will be one of the
935 @code{TYPE_CODE_} constants defined below.
939 The name of this type. If this type has no name, then @code{None}
944 The size of this type, in target @code{char} units. Usually, a
945 target's @code{char} type will be an 8-bit byte. However, on some
946 unusual platforms, this type may have a different size.
950 The tag name for this type. The tag name is the name after
951 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
952 languages have this concept. If this type has no tag name, then
953 @code{None} is returned.
956 The following methods are provided:
958 @defun Type.fields ()
959 For structure and union types, this method returns the fields. Range
960 types have two fields, the minimum and maximum values. Enum types
961 have one field per enum constant. Function and method types have one
962 field per parameter. The base types of C@t{++} classes are also
963 represented as fields. If the type has no fields, or does not fit
964 into one of these categories, an empty sequence will be returned.
966 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
969 This attribute is not available for @code{enum} or @code{static}
970 (as in C@t{++}) fields. The value is the position, counting
971 in bits, from the start of the containing type.
974 This attribute is only available for @code{enum} fields, and its value
975 is the enumeration member's integer representation.
978 The name of the field, or @code{None} for anonymous fields.
981 This is @code{True} if the field is artificial, usually meaning that
982 it was provided by the compiler and not the user. This attribute is
983 always provided, and is @code{False} if the field is not artificial.
986 This is @code{True} if the field represents a base class of a C@t{++}
987 structure. This attribute is always provided, and is @code{False}
988 if the field is not a base class of the type that is the argument of
989 @code{fields}, or if that type was not a C@t{++} class.
992 If the field is packed, or is a bitfield, then this will have a
993 non-zero value, which is the size of the field in bits. Otherwise,
994 this will be zero; in this case the field's size is given by its type.
997 The type of the field. This is usually an instance of @code{Type},
998 but it can be @code{None} in some situations.
1001 The type which contains this field. This is an instance of
1006 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
1007 Return a new @code{gdb.Type} object which represents an array of this
1008 type. If one argument is given, it is the inclusive upper bound of
1009 the array; in this case the lower bound is zero. If two arguments are
1010 given, the first argument is the lower bound of the array, and the
1011 second argument is the upper bound of the array. An array's length
1012 must not be negative, but the bounds can be.
1015 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
1016 Return a new @code{gdb.Type} object which represents a vector of this
1017 type. If one argument is given, it is the inclusive upper bound of
1018 the vector; in this case the lower bound is zero. If two arguments are
1019 given, the first argument is the lower bound of the vector, and the
1020 second argument is the upper bound of the vector. A vector's length
1021 must not be negative, but the bounds can be.
1023 The difference between an @code{array} and a @code{vector} is that
1024 arrays behave like in C: when used in expressions they decay to a pointer
1025 to the first element whereas vectors are treated as first class values.
1028 @defun Type.const ()
1029 Return a new @code{gdb.Type} object which represents a
1030 @code{const}-qualified variant of this type.
1033 @defun Type.volatile ()
1034 Return a new @code{gdb.Type} object which represents a
1035 @code{volatile}-qualified variant of this type.
1038 @defun Type.unqualified ()
1039 Return a new @code{gdb.Type} object which represents an unqualified
1040 variant of this type. That is, the result is neither @code{const} nor
1044 @defun Type.range ()
1045 Return a Python @code{Tuple} object that contains two elements: the
1046 low bound of the argument type and the high bound of that type. If
1047 the type does not have a range, @value{GDBN} will raise a
1048 @code{gdb.error} exception (@pxref{Exception Handling}).
1051 @defun Type.reference ()
1052 Return a new @code{gdb.Type} object which represents a reference to this
1056 @defun Type.pointer ()
1057 Return a new @code{gdb.Type} object which represents a pointer to this
1061 @defun Type.strip_typedefs ()
1062 Return a new @code{gdb.Type} that represents the real type,
1063 after removing all layers of typedefs.
1066 @defun Type.target ()
1067 Return a new @code{gdb.Type} object which represents the target type
1070 For a pointer type, the target type is the type of the pointed-to
1071 object. For an array type (meaning C-like arrays), the target type is
1072 the type of the elements of the array. For a function or method type,
1073 the target type is the type of the return value. For a complex type,
1074 the target type is the type of the elements. For a typedef, the
1075 target type is the aliased type.
1077 If the type does not have a target, this method will throw an
1081 @defun Type.template_argument (n @r{[}, block@r{]})
1082 If this @code{gdb.Type} is an instantiation of a template, this will
1083 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1084 value of the @var{n}th template argument (indexed starting at 0).
1086 If this @code{gdb.Type} is not a template type, or if the type has fewer
1087 than @var{n} template arguments, this will throw an exception.
1088 Ordinarily, only C@t{++} code will have template types.
1090 If @var{block} is given, then @var{name} is looked up in that scope.
1091 Otherwise, it is searched for globally.
1094 @defun Type.optimized_out ()
1095 Return @code{gdb.Value} instance of this type whose value is optimized
1096 out. This allows a frame decorator to indicate that the value of an
1097 argument or a local variable is not known.
1100 Each type has a code, which indicates what category this type falls
1101 into. The available type categories are represented by constants
1102 defined in the @code{gdb} module:
1105 @vindex TYPE_CODE_PTR
1106 @item gdb.TYPE_CODE_PTR
1107 The type is a pointer.
1109 @vindex TYPE_CODE_ARRAY
1110 @item gdb.TYPE_CODE_ARRAY
1111 The type is an array.
1113 @vindex TYPE_CODE_STRUCT
1114 @item gdb.TYPE_CODE_STRUCT
1115 The type is a structure.
1117 @vindex TYPE_CODE_UNION
1118 @item gdb.TYPE_CODE_UNION
1119 The type is a union.
1121 @vindex TYPE_CODE_ENUM
1122 @item gdb.TYPE_CODE_ENUM
1123 The type is an enum.
1125 @vindex TYPE_CODE_FLAGS
1126 @item gdb.TYPE_CODE_FLAGS
1127 A bit flags type, used for things such as status registers.
1129 @vindex TYPE_CODE_FUNC
1130 @item gdb.TYPE_CODE_FUNC
1131 The type is a function.
1133 @vindex TYPE_CODE_INT
1134 @item gdb.TYPE_CODE_INT
1135 The type is an integer type.
1137 @vindex TYPE_CODE_FLT
1138 @item gdb.TYPE_CODE_FLT
1139 A floating point type.
1141 @vindex TYPE_CODE_VOID
1142 @item gdb.TYPE_CODE_VOID
1143 The special type @code{void}.
1145 @vindex TYPE_CODE_SET
1146 @item gdb.TYPE_CODE_SET
1149 @vindex TYPE_CODE_RANGE
1150 @item gdb.TYPE_CODE_RANGE
1151 A range type, that is, an integer type with bounds.
1153 @vindex TYPE_CODE_STRING
1154 @item gdb.TYPE_CODE_STRING
1155 A string type. Note that this is only used for certain languages with
1156 language-defined string types; C strings are not represented this way.
1158 @vindex TYPE_CODE_BITSTRING
1159 @item gdb.TYPE_CODE_BITSTRING
1160 A string of bits. It is deprecated.
1162 @vindex TYPE_CODE_ERROR
1163 @item gdb.TYPE_CODE_ERROR
1164 An unknown or erroneous type.
1166 @vindex TYPE_CODE_METHOD
1167 @item gdb.TYPE_CODE_METHOD
1168 A method type, as found in C@t{++}.
1170 @vindex TYPE_CODE_METHODPTR
1171 @item gdb.TYPE_CODE_METHODPTR
1172 A pointer-to-member-function.
1174 @vindex TYPE_CODE_MEMBERPTR
1175 @item gdb.TYPE_CODE_MEMBERPTR
1176 A pointer-to-member.
1178 @vindex TYPE_CODE_REF
1179 @item gdb.TYPE_CODE_REF
1182 @vindex TYPE_CODE_RVALUE_REF
1183 @item gdb.TYPE_CODE_RVALUE_REF
1184 A C@t{++}11 rvalue reference type.
1186 @vindex TYPE_CODE_CHAR
1187 @item gdb.TYPE_CODE_CHAR
1190 @vindex TYPE_CODE_BOOL
1191 @item gdb.TYPE_CODE_BOOL
1194 @vindex TYPE_CODE_COMPLEX
1195 @item gdb.TYPE_CODE_COMPLEX
1196 A complex float type.
1198 @vindex TYPE_CODE_TYPEDEF
1199 @item gdb.TYPE_CODE_TYPEDEF
1200 A typedef to some other type.
1202 @vindex TYPE_CODE_NAMESPACE
1203 @item gdb.TYPE_CODE_NAMESPACE
1204 A C@t{++} namespace.
1206 @vindex TYPE_CODE_DECFLOAT
1207 @item gdb.TYPE_CODE_DECFLOAT
1208 A decimal floating point type.
1210 @vindex TYPE_CODE_INTERNAL_FUNCTION
1211 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1212 A function internal to @value{GDBN}. This is the type used to represent
1213 convenience functions.
1216 Further support for types is provided in the @code{gdb.types}
1217 Python module (@pxref{gdb.types}).
1219 @node Pretty Printing API
1220 @subsubsection Pretty Printing API
1221 @cindex python pretty printing api
1223 An example output is provided (@pxref{Pretty Printing}).
1225 A pretty-printer is just an object that holds a value and implements a
1226 specific interface, defined here.
1228 @defun pretty_printer.children (self)
1229 @value{GDBN} will call this method on a pretty-printer to compute the
1230 children of the pretty-printer's value.
1232 This method must return an object conforming to the Python iterator
1233 protocol. Each item returned by the iterator must be a tuple holding
1234 two elements. The first element is the ``name'' of the child; the
1235 second element is the child's value. The value can be any Python
1236 object which is convertible to a @value{GDBN} value.
1238 This method is optional. If it does not exist, @value{GDBN} will act
1239 as though the value has no children.
1242 @defun pretty_printer.display_hint (self)
1243 The CLI may call this method and use its result to change the
1244 formatting of a value. The result will also be supplied to an MI
1245 consumer as a @samp{displayhint} attribute of the variable being
1248 This method is optional. If it does exist, this method must return a
1251 Some display hints are predefined by @value{GDBN}:
1255 Indicate that the object being printed is ``array-like''. The CLI
1256 uses this to respect parameters such as @code{set print elements} and
1257 @code{set print array}.
1260 Indicate that the object being printed is ``map-like'', and that the
1261 children of this value can be assumed to alternate between keys and
1265 Indicate that the object being printed is ``string-like''. If the
1266 printer's @code{to_string} method returns a Python string of some
1267 kind, then @value{GDBN} will call its internal language-specific
1268 string-printing function to format the string. For the CLI this means
1269 adding quotation marks, possibly escaping some characters, respecting
1270 @code{set print elements}, and the like.
1274 @defun pretty_printer.to_string (self)
1275 @value{GDBN} will call this method to display the string
1276 representation of the value passed to the object's constructor.
1278 When printing from the CLI, if the @code{to_string} method exists,
1279 then @value{GDBN} will prepend its result to the values returned by
1280 @code{children}. Exactly how this formatting is done is dependent on
1281 the display hint, and may change as more hints are added. Also,
1282 depending on the print settings (@pxref{Print Settings}), the CLI may
1283 print just the result of @code{to_string} in a stack trace, omitting
1284 the result of @code{children}.
1286 If this method returns a string, it is printed verbatim.
1288 Otherwise, if this method returns an instance of @code{gdb.Value},
1289 then @value{GDBN} prints this value. This may result in a call to
1290 another pretty-printer.
1292 If instead the method returns a Python value which is convertible to a
1293 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1294 the resulting value. Again, this may result in a call to another
1295 pretty-printer. Python scalars (integers, floats, and booleans) and
1296 strings are convertible to @code{gdb.Value}; other types are not.
1298 Finally, if this method returns @code{None} then no further operations
1299 are peformed in this method and nothing is printed.
1301 If the result is not one of these types, an exception is raised.
1304 @value{GDBN} provides a function which can be used to look up the
1305 default pretty-printer for a @code{gdb.Value}:
1307 @findex gdb.default_visualizer
1308 @defun gdb.default_visualizer (value)
1309 This function takes a @code{gdb.Value} object as an argument. If a
1310 pretty-printer for this value exists, then it is returned. If no such
1311 printer exists, then this returns @code{None}.
1314 @node Selecting Pretty-Printers
1315 @subsubsection Selecting Pretty-Printers
1316 @cindex selecting python pretty-printers
1318 The Python list @code{gdb.pretty_printers} contains an array of
1319 functions or callable objects that have been registered via addition
1320 as a pretty-printer. Printers in this list are called @code{global}
1321 printers, they're available when debugging all inferiors.
1322 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1323 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1326 Each function on these lists is passed a single @code{gdb.Value}
1327 argument and should return a pretty-printer object conforming to the
1328 interface definition above (@pxref{Pretty Printing API}). If a function
1329 cannot create a pretty-printer for the value, it should return
1332 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1333 @code{gdb.Objfile} in the current program space and iteratively calls
1334 each enabled lookup routine in the list for that @code{gdb.Objfile}
1335 until it receives a pretty-printer object.
1336 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1337 searches the pretty-printer list of the current program space,
1338 calling each enabled function until an object is returned.
1339 After these lists have been exhausted, it tries the global
1340 @code{gdb.pretty_printers} list, again calling each enabled function until an
1343 The order in which the objfiles are searched is not specified. For a
1344 given list, functions are always invoked from the head of the list,
1345 and iterated over sequentially until the end of the list, or a printer
1348 For various reasons a pretty-printer may not work.
1349 For example, the underlying data structure may have changed and
1350 the pretty-printer is out of date.
1352 The consequences of a broken pretty-printer are severe enough that
1353 @value{GDBN} provides support for enabling and disabling individual
1354 printers. For example, if @code{print frame-arguments} is on,
1355 a backtrace can become highly illegible if any argument is printed
1356 with a broken printer.
1358 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1359 attribute to the registered function or callable object. If this attribute
1360 is present and its value is @code{False}, the printer is disabled, otherwise
1361 the printer is enabled.
1363 @node Writing a Pretty-Printer
1364 @subsubsection Writing a Pretty-Printer
1365 @cindex writing a pretty-printer
1367 A pretty-printer consists of two parts: a lookup function to detect
1368 if the type is supported, and the printer itself.
1370 Here is an example showing how a @code{std::string} printer might be
1371 written. @xref{Pretty Printing API}, for details on the API this class
1375 class StdStringPrinter(object):
1376 "Print a std::string"
1378 def __init__(self, val):
1381 def to_string(self):
1382 return self.val['_M_dataplus']['_M_p']
1384 def display_hint(self):
1388 And here is an example showing how a lookup function for the printer
1389 example above might be written.
1392 def str_lookup_function(val):
1393 lookup_tag = val.type.tag
1394 if lookup_tag == None:
1396 regex = re.compile("^std::basic_string<char,.*>$")
1397 if regex.match(lookup_tag):
1398 return StdStringPrinter(val)
1402 The example lookup function extracts the value's type, and attempts to
1403 match it to a type that it can pretty-print. If it is a type the
1404 printer can pretty-print, it will return a printer object. If not, it
1405 returns @code{None}.
1407 We recommend that you put your core pretty-printers into a Python
1408 package. If your pretty-printers are for use with a library, we
1409 further recommend embedding a version number into the package name.
1410 This practice will enable @value{GDBN} to load multiple versions of
1411 your pretty-printers at the same time, because they will have
1414 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1415 can be evaluated multiple times without changing its meaning. An
1416 ideal auto-load file will consist solely of @code{import}s of your
1417 printer modules, followed by a call to a register pretty-printers with
1418 the current objfile.
1420 Taken as a whole, this approach will scale nicely to multiple
1421 inferiors, each potentially using a different library version.
1422 Embedding a version number in the Python package name will ensure that
1423 @value{GDBN} is able to load both sets of printers simultaneously.
1424 Then, because the search for pretty-printers is done by objfile, and
1425 because your auto-loaded code took care to register your library's
1426 printers with a specific objfile, @value{GDBN} will find the correct
1427 printers for the specific version of the library used by each
1430 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1431 this code might appear in @code{gdb.libstdcxx.v6}:
1434 def register_printers(objfile):
1435 objfile.pretty_printers.append(str_lookup_function)
1439 And then the corresponding contents of the auto-load file would be:
1442 import gdb.libstdcxx.v6
1443 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1446 The previous example illustrates a basic pretty-printer.
1447 There are a few things that can be improved on.
1448 The printer doesn't have a name, making it hard to identify in a
1449 list of installed printers. The lookup function has a name, but
1450 lookup functions can have arbitrary, even identical, names.
1452 Second, the printer only handles one type, whereas a library typically has
1453 several types. One could install a lookup function for each desired type
1454 in the library, but one could also have a single lookup function recognize
1455 several types. The latter is the conventional way this is handled.
1456 If a pretty-printer can handle multiple data types, then its
1457 @dfn{subprinters} are the printers for the individual data types.
1459 The @code{gdb.printing} module provides a formal way of solving these
1460 problems (@pxref{gdb.printing}).
1461 Here is another example that handles multiple types.
1463 These are the types we are going to pretty-print:
1466 struct foo @{ int a, b; @};
1467 struct bar @{ struct foo x, y; @};
1470 Here are the printers:
1474 """Print a foo object."""
1476 def __init__(self, val):
1479 def to_string(self):
1480 return ("a=<" + str(self.val["a"]) +
1481 "> b=<" + str(self.val["b"]) + ">")
1484 """Print a bar object."""
1486 def __init__(self, val):
1489 def to_string(self):
1490 return ("x=<" + str(self.val["x"]) +
1491 "> y=<" + str(self.val["y"]) + ">")
1494 This example doesn't need a lookup function, that is handled by the
1495 @code{gdb.printing} module. Instead a function is provided to build up
1496 the object that handles the lookup.
1501 def build_pretty_printer():
1502 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1504 pp.add_printer('foo', '^foo$', fooPrinter)
1505 pp.add_printer('bar', '^bar$', barPrinter)
1509 And here is the autoload support:
1514 gdb.printing.register_pretty_printer(
1515 gdb.current_objfile(),
1516 my_library.build_pretty_printer())
1519 Finally, when this printer is loaded into @value{GDBN}, here is the
1520 corresponding output of @samp{info pretty-printer}:
1523 (gdb) info pretty-printer
1530 @node Type Printing API
1531 @subsubsection Type Printing API
1532 @cindex type printing API for Python
1534 @value{GDBN} provides a way for Python code to customize type display.
1535 This is mainly useful for substituting canonical typedef names for
1538 @cindex type printer
1539 A @dfn{type printer} is just a Python object conforming to a certain
1540 protocol. A simple base class implementing the protocol is provided;
1541 see @ref{gdb.types}. A type printer must supply at least:
1543 @defivar type_printer enabled
1544 A boolean which is True if the printer is enabled, and False
1545 otherwise. This is manipulated by the @code{enable type-printer}
1546 and @code{disable type-printer} commands.
1549 @defivar type_printer name
1550 The name of the type printer. This must be a string. This is used by
1551 the @code{enable type-printer} and @code{disable type-printer}
1555 @defmethod type_printer instantiate (self)
1556 This is called by @value{GDBN} at the start of type-printing. It is
1557 only called if the type printer is enabled. This method must return a
1558 new object that supplies a @code{recognize} method, as described below.
1562 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1563 will compute a list of type recognizers. This is done by iterating
1564 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1565 followed by the per-progspace type printers (@pxref{Progspaces In
1566 Python}), and finally the global type printers.
1568 @value{GDBN} will call the @code{instantiate} method of each enabled
1569 type printer. If this method returns @code{None}, then the result is
1570 ignored; otherwise, it is appended to the list of recognizers.
1572 Then, when @value{GDBN} is going to display a type name, it iterates
1573 over the list of recognizers. For each one, it calls the recognition
1574 function, stopping if the function returns a non-@code{None} value.
1575 The recognition function is defined as:
1577 @defmethod type_recognizer recognize (self, type)
1578 If @var{type} is not recognized, return @code{None}. Otherwise,
1579 return a string which is to be printed as the name of @var{type}.
1580 The @var{type} argument will be an instance of @code{gdb.Type}
1581 (@pxref{Types In Python}).
1584 @value{GDBN} uses this two-pass approach so that type printers can
1585 efficiently cache information without holding on to it too long. For
1586 example, it can be convenient to look up type information in a type
1587 printer and hold it for a recognizer's lifetime; if a single pass were
1588 done then type printers would have to make use of the event system in
1589 order to avoid holding information that could become stale as the
1592 @node Frame Filter API
1593 @subsubsection Filtering Frames.
1594 @cindex frame filters api
1596 Frame filters are Python objects that manipulate the visibility of a
1597 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1600 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1601 commands (@pxref{GDB/MI}), those that return a collection of frames
1602 are affected. The commands that work with frame filters are:
1604 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1605 @code{-stack-list-frames}
1606 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1607 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1608 -stack-list-variables command}), @code{-stack-list-arguments}
1609 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1610 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1611 -stack-list-locals command}).
1613 A frame filter works by taking an iterator as an argument, applying
1614 actions to the contents of that iterator, and returning another
1615 iterator (or, possibly, the same iterator it was provided in the case
1616 where the filter does not perform any operations). Typically, frame
1617 filters utilize tools such as the Python's @code{itertools} module to
1618 work with and create new iterators from the source iterator.
1619 Regardless of how a filter chooses to apply actions, it must not alter
1620 the underlying @value{GDBN} frame or frames, or attempt to alter the
1621 call-stack within @value{GDBN}. This preserves data integrity within
1622 @value{GDBN}. Frame filters are executed on a priority basis and care
1623 should be taken that some frame filters may have been executed before,
1624 and that some frame filters will be executed after.
1626 An important consideration when designing frame filters, and well
1627 worth reflecting upon, is that frame filters should avoid unwinding
1628 the call stack if possible. Some stacks can run very deep, into the
1629 tens of thousands in some cases. To search every frame when a frame
1630 filter executes may be too expensive at that step. The frame filter
1631 cannot know how many frames it has to iterate over, and it may have to
1632 iterate through them all. This ends up duplicating effort as
1633 @value{GDBN} performs this iteration when it prints the frames. If
1634 the filter can defer unwinding frames until frame decorators are
1635 executed, after the last filter has executed, it should. @xref{Frame
1636 Decorator API}, for more information on decorators. Also, there are
1637 examples for both frame decorators and filters in later chapters.
1638 @xref{Writing a Frame Filter}, for more information.
1640 The Python dictionary @code{gdb.frame_filters} contains key/object
1641 pairings that comprise a frame filter. Frame filters in this
1642 dictionary are called @code{global} frame filters, and they are
1643 available when debugging all inferiors. These frame filters must
1644 register with the dictionary directly. In addition to the
1645 @code{global} dictionary, there are other dictionaries that are loaded
1646 with different inferiors via auto-loading (@pxref{Python
1647 Auto-loading}). The two other areas where frame filter dictionaries
1648 can be found are: @code{gdb.Progspace} which contains a
1649 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1650 object which also contains a @code{frame_filters} dictionary
1653 When a command is executed from @value{GDBN} that is compatible with
1654 frame filters, @value{GDBN} combines the @code{global},
1655 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1656 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1657 several frames, and thus several object files, might be in use.
1658 @value{GDBN} then prunes any frame filter whose @code{enabled}
1659 attribute is @code{False}. This pruned list is then sorted according
1660 to the @code{priority} attribute in each filter.
1662 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1663 creates an iterator which wraps each frame in the call stack in a
1664 @code{FrameDecorator} object, and calls each filter in order. The
1665 output from the previous filter will always be the input to the next
1668 Frame filters have a mandatory interface which each frame filter must
1669 implement, defined here:
1671 @defun FrameFilter.filter (iterator)
1672 @value{GDBN} will call this method on a frame filter when it has
1673 reached the order in the priority list for that filter.
1675 For example, if there are four frame filters:
1686 The order that the frame filters will be called is:
1689 Filter3 -> Filter2 -> Filter1 -> Filter4
1692 Note that the output from @code{Filter3} is passed to the input of
1693 @code{Filter2}, and so on.
1695 This @code{filter} method is passed a Python iterator. This iterator
1696 contains a sequence of frame decorators that wrap each
1697 @code{gdb.Frame}, or a frame decorator that wraps another frame
1698 decorator. The first filter that is executed in the sequence of frame
1699 filters will receive an iterator entirely comprised of default
1700 @code{FrameDecorator} objects. However, after each frame filter is
1701 executed, the previous frame filter may have wrapped some or all of
1702 the frame decorators with their own frame decorator. As frame
1703 decorators must also conform to a mandatory interface, these
1704 decorators can be assumed to act in a uniform manner (@pxref{Frame
1707 This method must return an object conforming to the Python iterator
1708 protocol. Each item in the iterator must be an object conforming to
1709 the frame decorator interface. If a frame filter does not wish to
1710 perform any operations on this iterator, it should return that
1713 This method is not optional. If it does not exist, @value{GDBN} will
1714 raise and print an error.
1717 @defvar FrameFilter.name
1718 The @code{name} attribute must be Python string which contains the
1719 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1720 Management}). This attribute may contain any combination of letters
1721 or numbers. Care should be taken to ensure that it is unique. This
1722 attribute is mandatory.
1725 @defvar FrameFilter.enabled
1726 The @code{enabled} attribute must be Python boolean. This attribute
1727 indicates to @value{GDBN} whether the frame filter is enabled, and
1728 should be considered when frame filters are executed. If
1729 @code{enabled} is @code{True}, then the frame filter will be executed
1730 when any of the backtrace commands detailed earlier in this chapter
1731 are executed. If @code{enabled} is @code{False}, then the frame
1732 filter will not be executed. This attribute is mandatory.
1735 @defvar FrameFilter.priority
1736 The @code{priority} attribute must be Python integer. This attribute
1737 controls the order of execution in relation to other frame filters.
1738 There are no imposed limits on the range of @code{priority} other than
1739 it must be a valid integer. The higher the @code{priority} attribute,
1740 the sooner the frame filter will be executed in relation to other
1741 frame filters. Although @code{priority} can be negative, it is
1742 recommended practice to assume zero is the lowest priority that a
1743 frame filter can be assigned. Frame filters that have the same
1744 priority are executed in unsorted order in that priority slot. This
1745 attribute is mandatory.
1748 @node Frame Decorator API
1749 @subsubsection Decorating Frames.
1750 @cindex frame decorator api
1752 Frame decorators are sister objects to frame filters (@pxref{Frame
1753 Filter API}). Frame decorators are applied by a frame filter and can
1754 only be used in conjunction with frame filters.
1756 The purpose of a frame decorator is to customize the printed content
1757 of each @code{gdb.Frame} in commands where frame filters are executed.
1758 This concept is called decorating a frame. Frame decorators decorate
1759 a @code{gdb.Frame} with Python code contained within each API call.
1760 This separates the actual data contained in a @code{gdb.Frame} from
1761 the decorated data produced by a frame decorator. This abstraction is
1762 necessary to maintain integrity of the data contained in each
1765 Frame decorators have a mandatory interface, defined below.
1767 @value{GDBN} already contains a frame decorator called
1768 @code{FrameDecorator}. This contains substantial amounts of
1769 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
1770 recommended that other frame decorators inherit and extend this
1771 object, and only to override the methods needed.
1773 @defun FrameDecorator.elided (self)
1775 The @code{elided} method groups frames together in a hierarchical
1776 system. An example would be an interpreter, where multiple low-level
1777 frames make up a single call in the interpreted language. In this
1778 example, the frame filter would elide the low-level frames and present
1779 a single high-level frame, representing the call in the interpreted
1780 language, to the user.
1782 The @code{elided} function must return an iterable and this iterable
1783 must contain the frames that are being elided wrapped in a suitable
1784 frame decorator. If no frames are being elided this function may
1785 return an empty iterable, or @code{None}. Elided frames are indented
1786 from normal frames in a @code{CLI} backtrace, or in the case of
1787 @code{GDB/MI}, are placed in the @code{children} field of the eliding
1790 It is the frame filter's task to also filter out the elided frames from
1791 the source iterator. This will avoid printing the frame twice.
1794 @defun FrameDecorator.function (self)
1796 This method returns the name of the function in the frame that is to
1799 This method must return a Python string describing the function, or
1802 If this function returns @code{None}, @value{GDBN} will not print any
1803 data for this field.
1806 @defun FrameDecorator.address (self)
1808 This method returns the address of the frame that is to be printed.
1810 This method must return a Python numeric integer type of sufficient
1811 size to describe the address of the frame, or @code{None}.
1813 If this function returns a @code{None}, @value{GDBN} will not print
1814 any data for this field.
1817 @defun FrameDecorator.filename (self)
1819 This method returns the filename and path associated with this frame.
1821 This method must return a Python string containing the filename and
1822 the path to the object file backing the frame, or @code{None}.
1824 If this function returns a @code{None}, @value{GDBN} will not print
1825 any data for this field.
1828 @defun FrameDecorator.line (self):
1830 This method returns the line number associated with the current
1831 position within the function addressed by this frame.
1833 This method must return a Python integer type, or @code{None}.
1835 If this function returns a @code{None}, @value{GDBN} will not print
1836 any data for this field.
1839 @defun FrameDecorator.frame_args (self)
1842 This method must return an iterable, or @code{None}. Returning an
1843 empty iterable, or @code{None} means frame arguments will not be
1844 printed for this frame. This iterable must contain objects that
1845 implement two methods, described here.
1847 This object must implement a @code{argument} method which takes a
1848 single @code{self} parameter and must return a @code{gdb.Symbol}
1849 (@pxref{Symbols In Python}), or a Python string. The object must also
1850 implement a @code{value} method which takes a single @code{self}
1851 parameter and must return a @code{gdb.Value} (@pxref{Values From
1852 Inferior}), a Python value, or @code{None}. If the @code{value}
1853 method returns @code{None}, and the @code{argument} method returns a
1854 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
1855 the @code{gdb.Symbol} automatically.
1860 class SymValueWrapper():
1862 def __init__(self, symbol, value):
1872 class SomeFrameDecorator()
1875 def frame_args(self):
1878 block = self.inferior_frame.block()
1882 # Iterate over all symbols in a block. Only add
1883 # symbols that are arguments.
1885 if not sym.is_argument:
1887 args.append(SymValueWrapper(sym,None))
1889 # Add example synthetic argument.
1890 args.append(SymValueWrapper(``foo'', 42))
1896 @defun FrameDecorator.frame_locals (self)
1898 This method must return an iterable or @code{None}. Returning an
1899 empty iterable, or @code{None} means frame local arguments will not be
1900 printed for this frame.
1902 The object interface, the description of the various strategies for
1903 reading frame locals, and the example are largely similar to those
1904 described in the @code{frame_args} function, (@pxref{frame_args,,The
1905 frame filter frame_args function}). Below is a modified example:
1908 class SomeFrameDecorator()
1911 def frame_locals(self):
1914 block = self.inferior_frame.block()
1918 # Iterate over all symbols in a block. Add all
1919 # symbols, except arguments.
1923 vars.append(SymValueWrapper(sym,None))
1925 # Add an example of a synthetic local variable.
1926 vars.append(SymValueWrapper(``bar'', 99))
1932 @defun FrameDecorator.inferior_frame (self):
1934 This method must return the underlying @code{gdb.Frame} that this
1935 frame decorator is decorating. @value{GDBN} requires the underlying
1936 frame for internal frame information to determine how to print certain
1937 values when printing a frame.
1940 @node Writing a Frame Filter
1941 @subsubsection Writing a Frame Filter
1942 @cindex writing a frame filter
1944 There are three basic elements that a frame filter must implement: it
1945 must correctly implement the documented interface (@pxref{Frame Filter
1946 API}), it must register itself with @value{GDBN}, and finally, it must
1947 decide if it is to work on the data provided by @value{GDBN}. In all
1948 cases, whether it works on the iterator or not, each frame filter must
1949 return an iterator. A bare-bones frame filter follows the pattern in
1950 the following example.
1955 class FrameFilter():
1958 # Frame filter attribute creation.
1960 # 'name' is the name of the filter that GDB will display.
1962 # 'priority' is the priority of the filter relative to other
1965 # 'enabled' is a boolean that indicates whether this filter is
1966 # enabled and should be executed.
1972 # Register this frame filter with the global frame_filters
1974 gdb.frame_filters[self.name] = self
1976 def filter(self, frame_iter):
1977 # Just return the iterator.
1981 The frame filter in the example above implements the three
1982 requirements for all frame filters. It implements the API, self
1983 registers, and makes a decision on the iterator (in this case, it just
1984 returns the iterator untouched).
1986 The first step is attribute creation and assignment, and as shown in
1987 the comments the filter assigns the following attributes: @code{name},
1988 @code{priority} and whether the filter should be enabled with the
1989 @code{enabled} attribute.
1991 The second step is registering the frame filter with the dictionary or
1992 dictionaries that the frame filter has interest in. As shown in the
1993 comments, this filter just registers itself with the global dictionary
1994 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
1995 is a dictionary that is initialized in the @code{gdb} module when
1996 @value{GDBN} starts. What dictionary a filter registers with is an
1997 important consideration. Generally, if a filter is specific to a set
1998 of code, it should be registered either in the @code{objfile} or
1999 @code{progspace} dictionaries as they are specific to the program
2000 currently loaded in @value{GDBN}. The global dictionary is always
2001 present in @value{GDBN} and is never unloaded. Any filters registered
2002 with the global dictionary will exist until @value{GDBN} exits. To
2003 avoid filters that may conflict, it is generally better to register
2004 frame filters against the dictionaries that more closely align with
2005 the usage of the filter currently in question. @xref{Python
2006 Auto-loading}, for further information on auto-loading Python scripts.
2008 @value{GDBN} takes a hands-off approach to frame filter registration,
2009 therefore it is the frame filter's responsibility to ensure
2010 registration has occurred, and that any exceptions are handled
2011 appropriately. In particular, you may wish to handle exceptions
2012 relating to Python dictionary key uniqueness. It is mandatory that
2013 the dictionary key is the same as frame filter's @code{name}
2014 attribute. When a user manages frame filters (@pxref{Frame Filter
2015 Management}), the names @value{GDBN} will display are those contained
2016 in the @code{name} attribute.
2018 The final step of this example is the implementation of the
2019 @code{filter} method. As shown in the example comments, we define the
2020 @code{filter} method and note that the method must take an iterator,
2021 and also must return an iterator. In this bare-bones example, the
2022 frame filter is not very useful as it just returns the iterator
2023 untouched. However this is a valid operation for frame filters that
2024 have the @code{enabled} attribute set, but decide not to operate on
2027 In the next example, the frame filter operates on all frames and
2028 utilizes a frame decorator to perform some work on the frames.
2029 @xref{Frame Decorator API}, for further information on the frame
2030 decorator interface.
2032 This example works on inlined frames. It highlights frames which are
2033 inlined by tagging them with an ``[inlined]'' tag. By applying a
2034 frame decorator to all frames with the Python @code{itertools imap}
2035 method, the example defers actions to the frame decorator. Frame
2036 decorators are only processed when @value{GDBN} prints the backtrace.
2038 This introduces a new decision making topic: whether to perform
2039 decision making operations at the filtering step, or at the printing
2040 step. In this example's approach, it does not perform any filtering
2041 decisions at the filtering step beyond mapping a frame decorator to
2042 each frame. This allows the actual decision making to be performed
2043 when each frame is printed. This is an important consideration, and
2044 well worth reflecting upon when designing a frame filter. An issue
2045 that frame filters should avoid is unwinding the stack if possible.
2046 Some stacks can run very deep, into the tens of thousands in some
2047 cases. To search every frame to determine if it is inlined ahead of
2048 time may be too expensive at the filtering step. The frame filter
2049 cannot know how many frames it has to iterate over, and it would have
2050 to iterate through them all. This ends up duplicating effort as
2051 @value{GDBN} performs this iteration when it prints the frames.
2053 In this example decision making can be deferred to the printing step.
2054 As each frame is printed, the frame decorator can examine each frame
2055 in turn when @value{GDBN} iterates. From a performance viewpoint,
2056 this is the most appropriate decision to make as it avoids duplicating
2057 the effort that the printing step would undertake anyway. Also, if
2058 there are many frame filters unwinding the stack during filtering, it
2059 can substantially delay the printing of the backtrace which will
2060 result in large memory usage, and a poor user experience.
2063 class InlineFilter():
2066 self.name = "InlinedFrameFilter"
2069 gdb.frame_filters[self.name] = self
2071 def filter(self, frame_iter):
2072 frame_iter = itertools.imap(InlinedFrameDecorator,
2077 This frame filter is somewhat similar to the earlier example, except
2078 that the @code{filter} method applies a frame decorator object called
2079 @code{InlinedFrameDecorator} to each element in the iterator. The
2080 @code{imap} Python method is light-weight. It does not proactively
2081 iterate over the iterator, but rather creates a new iterator which
2082 wraps the existing one.
2084 Below is the frame decorator for this example.
2087 class InlinedFrameDecorator(FrameDecorator):
2089 def __init__(self, fobj):
2090 super(InlinedFrameDecorator, self).__init__(fobj)
2093 frame = fobj.inferior_frame()
2094 name = str(frame.name())
2096 if frame.type() == gdb.INLINE_FRAME:
2097 name = name + " [inlined]"
2102 This frame decorator only defines and overrides the @code{function}
2103 method. It lets the supplied @code{FrameDecorator}, which is shipped
2104 with @value{GDBN}, perform the other work associated with printing
2107 The combination of these two objects create this output from a
2111 #0 0x004004e0 in bar () at inline.c:11
2112 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2113 #2 0x00400566 in main () at inline.c:31
2116 So in the case of this example, a frame decorator is applied to all
2117 frames, regardless of whether they may be inlined or not. As
2118 @value{GDBN} iterates over the iterator produced by the frame filters,
2119 @value{GDBN} executes each frame decorator which then makes a decision
2120 on what to print in the @code{function} callback. Using a strategy
2121 like this is a way to defer decisions on the frame content to printing
2124 @subheading Eliding Frames
2126 It might be that the above example is not desirable for representing
2127 inlined frames, and a hierarchical approach may be preferred. If we
2128 want to hierarchically represent frames, the @code{elided} frame
2129 decorator interface might be preferable.
2131 This example approaches the issue with the @code{elided} method. This
2132 example is quite long, but very simplistic. It is out-of-scope for
2133 this section to write a complete example that comprehensively covers
2134 all approaches of finding and printing inlined frames. However, this
2135 example illustrates the approach an author might use.
2137 This example comprises of three sections.
2140 class InlineFrameFilter():
2143 self.name = "InlinedFrameFilter"
2146 gdb.frame_filters[self.name] = self
2148 def filter(self, frame_iter):
2149 return ElidingInlineIterator(frame_iter)
2152 This frame filter is very similar to the other examples. The only
2153 difference is this frame filter is wrapping the iterator provided to
2154 it (@code{frame_iter}) with a custom iterator called
2155 @code{ElidingInlineIterator}. This again defers actions to when
2156 @value{GDBN} prints the backtrace, as the iterator is not traversed
2159 The iterator for this example is as follows. It is in this section of
2160 the example where decisions are made on the content of the backtrace.
2163 class ElidingInlineIterator:
2164 def __init__(self, ii):
2165 self.input_iterator = ii
2171 frame = next(self.input_iterator)
2173 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2177 eliding_frame = next(self.input_iterator)
2178 except StopIteration:
2180 return ElidingFrameDecorator(eliding_frame, [frame])
2183 This iterator implements the Python iterator protocol. When the
2184 @code{next} function is called (when @value{GDBN} prints each frame),
2185 the iterator checks if this frame decorator, @code{frame}, is wrapping
2186 an inlined frame. If it is not, it returns the existing frame decorator
2187 untouched. If it is wrapping an inlined frame, it assumes that the
2188 inlined frame was contained within the next oldest frame,
2189 @code{eliding_frame}, which it fetches. It then creates and returns a
2190 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2191 elided frame, and the eliding frame.
2194 class ElidingInlineDecorator(FrameDecorator):
2196 def __init__(self, frame, elided_frames):
2197 super(ElidingInlineDecorator, self).__init__(frame)
2199 self.elided_frames = elided_frames
2202 return iter(self.elided_frames)
2205 This frame decorator overrides one function and returns the inlined
2206 frame in the @code{elided} method. As before it lets
2207 @code{FrameDecorator} do the rest of the work involved in printing
2208 this frame. This produces the following output.
2211 #0 0x004004e0 in bar () at inline.c:11
2212 #2 0x00400529 in main () at inline.c:25
2213 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2216 In that output, @code{max} which has been inlined into @code{main} is
2217 printed hierarchically. Another approach would be to combine the
2218 @code{function} method, and the @code{elided} method to both print a
2219 marker in the inlined frame, and also show the hierarchical
2222 @node Unwinding Frames in Python
2223 @subsubsection Unwinding Frames in Python
2224 @cindex unwinding frames in Python
2226 In @value{GDBN} terminology ``unwinding'' is the process of finding
2227 the previous frame (that is, caller's) from the current one. An
2228 unwinder has three methods. The first one checks if it can handle
2229 given frame (``sniff'' it). For the frames it can sniff an unwinder
2230 provides two additional methods: it can return frame's ID, and it can
2231 fetch registers from the previous frame. A running @value{GDBN}
2232 mantains a list of the unwinders and calls each unwinder's sniffer in
2233 turn until it finds the one that recognizes the current frame. There
2234 is an API to register an unwinder.
2236 The unwinders that come with @value{GDBN} handle standard frames.
2237 However, mixed language applications (for example, an application
2238 running Java Virtual Machine) sometimes use frame layouts that cannot
2239 be handled by the @value{GDBN} unwinders. You can write Python code
2240 that can handle such custom frames.
2242 You implement a frame unwinder in Python as a class with which has two
2243 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2244 a single method @code{__call__}, which examines a given frame and
2245 returns an object (an instance of @code{gdb.UnwindInfo class)}
2246 describing it. If an unwinder does not recognize a frame, it should
2247 return @code{None}. The code in @value{GDBN} that enables writing
2248 unwinders in Python uses this object to return frame's ID and previous
2249 frame registers when @value{GDBN} core asks for them.
2251 @subheading Unwinder Input
2253 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2254 provides a method to read frame's registers:
2256 @defun PendingFrame.read_register (reg)
2257 This method returns the contents of the register @var{regn} in the
2258 frame as a @code{gdb.Value} object. @var{reg} can be either a
2259 register number or a register name; the values are platform-specific.
2260 They are usually found in the corresponding
2261 @file{@var{platform}-tdep.h} file in the @value{GDBN} source tree.
2264 It also provides a factory method to create a @code{gdb.UnwindInfo}
2265 instance to be returned to @value{GDBN}:
2267 @defun PendingFrame.create_unwind_info (frame_id)
2268 Returns a new @code{gdb.UnwindInfo} instance identified by given
2269 @var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2270 using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2271 determine which function will be used, as follows:
2274 @item sp, pc, special
2275 @code{frame_id_build_special (@var{frame_id}.sp, @var{frame_id}.pc, @var{frame_id}.special)}
2278 @code{frame_id_build (@var{frame_id}.sp, @var{frame_id}.pc)}
2280 This is the most common case.
2283 @code{frame_id_build_wild (@var{frame_id}.sp)}
2285 The attribute values should be @code{gdb.Value}
2289 @subheading Unwinder Output: UnwindInfo
2291 Use @code{PendingFrame.create_unwind_info} method described above to
2292 create a @code{gdb.UnwindInfo} instance. Use the following method to
2293 specify caller registers that have been saved in this frame:
2295 @defun gdb.UnwindInfo.add_saved_register (reg, value)
2296 @var{reg} identifies the register. It can be a number or a name, just
2297 as for the @code{PendingFrame.read_register} method above.
2298 @var{value} is a register value (a @code{gdb.Value} object).
2301 @subheading Unwinder Skeleton Code
2303 @value{GDBN} comes with the module containing the base @code{Unwinder}
2304 class. Derive your unwinder class from it and structure the code as
2308 from gdb.unwinders import Unwinder
2310 class FrameId(object):
2311 def __init__(self, sp, pc):
2316 class MyUnwinder(Unwinder):
2318 supe(MyUnwinder, self).__init___(<expects unwinder name argument>)
2320 def __call__(pending_frame):
2321 if not <we recognize frame>:
2323 # Create UnwindInfo. Usually the frame is identified by the stack
2324 # pointer and the program counter.
2325 sp = pending_frame.read_register(<SP number>)
2326 pc = pending_frame.read_register(<PC number>)
2327 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2329 # Find the values of the registers in the caller's frame and
2330 # save them in the result:
2331 unwind_info.add_saved_register(<register>, <value>)
2334 # Return the result:
2339 @subheading Registering a Unwinder
2341 An object file, a program space, and the @value{GDBN} proper can have
2342 unwinders registered with it.
2344 The @code{gdb.unwinders} module provides the function to register a
2347 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2348 @var{locus} is specifies an object file or a program space to which
2349 @var{unwinder} is added. Passing @code{None} or @code{gdb} adds
2350 @var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
2351 added @var{unwinder} will be called before any other unwinder from the
2352 same locus. Two unwinders in the same locus cannot have the same
2353 name. An attempt to add a unwinder with already existing name raises
2354 an exception unless @var{replace} is @code{True}, in which case the
2355 old unwinder is deleted.
2358 @subheading Unwinder Precedence
2360 @value{GDBN} first calls the unwinders from all the object files in no
2361 particular order, then the unwinders from the current program space,
2362 and finally the unwinders from @value{GDBN}.
2364 @node Xmethods In Python
2365 @subsubsection Xmethods In Python
2366 @cindex xmethods in Python
2368 @dfn{Xmethods} are additional methods or replacements for existing
2369 methods of a C@t{++} class. This feature is useful for those cases
2370 where a method defined in C@t{++} source code could be inlined or
2371 optimized out by the compiler, making it unavailable to @value{GDBN}.
2372 For such cases, one can define an xmethod to serve as a replacement
2373 for the method defined in the C@t{++} source code. @value{GDBN} will
2374 then invoke the xmethod, instead of the C@t{++} method, to
2375 evaluate expressions. One can also use xmethods when debugging
2376 with core files. Moreover, when debugging live programs, invoking an
2377 xmethod need not involve running the inferior (which can potentially
2378 perturb its state). Hence, even if the C@t{++} method is available, it
2379 is better to use its replacement xmethod if one is defined.
2381 The xmethods feature in Python is available via the concepts of an
2382 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2383 implement an xmethod, one has to implement a matcher and a
2384 corresponding worker for it (more than one worker can be
2385 implemented, each catering to a different overloaded instance of the
2386 method). Internally, @value{GDBN} invokes the @code{match} method of a
2387 matcher to match the class type and method name. On a match, the
2388 @code{match} method returns a list of matching @emph{worker} objects.
2389 Each worker object typically corresponds to an overloaded instance of
2390 the xmethod. They implement a @code{get_arg_types} method which
2391 returns a sequence of types corresponding to the arguments the xmethod
2392 requires. @value{GDBN} uses this sequence of types to perform
2393 overload resolution and picks a winning xmethod worker. A winner
2394 is also selected from among the methods @value{GDBN} finds in the
2395 C@t{++} source code. Next, the winning xmethod worker and the
2396 winning C@t{++} method are compared to select an overall winner. In
2397 case of a tie between a xmethod worker and a C@t{++} method, the
2398 xmethod worker is selected as the winner. That is, if a winning
2399 xmethod worker is found to be equivalent to the winning C@t{++}
2400 method, then the xmethod worker is treated as a replacement for
2401 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2402 method. If the winning xmethod worker is the overall winner, then
2403 the corresponding xmethod is invoked via the @code{__call__} method
2404 of the worker object.
2406 If one wants to implement an xmethod as a replacement for an
2407 existing C@t{++} method, then they have to implement an equivalent
2408 xmethod which has exactly the same name and takes arguments of
2409 exactly the same type as the C@t{++} method. If the user wants to
2410 invoke the C@t{++} method even though a replacement xmethod is
2411 available for that method, then they can disable the xmethod.
2413 @xref{Xmethod API}, for API to implement xmethods in Python.
2414 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2417 @subsubsection Xmethod API
2420 The @value{GDBN} Python API provides classes, interfaces and functions
2421 to implement, register and manipulate xmethods.
2422 @xref{Xmethods In Python}.
2424 An xmethod matcher should be an instance of a class derived from
2425 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2426 object with similar interface and attributes. An instance of
2427 @code{XMethodMatcher} has the following attributes:
2430 The name of the matcher.
2434 A boolean value indicating whether the matcher is enabled or disabled.
2438 A list of named methods managed by the matcher. Each object in the list
2439 is an instance of the class @code{XMethod} defined in the module
2440 @code{gdb.xmethod}, or any object with the following attributes:
2445 Name of the xmethod which should be unique for each xmethod
2446 managed by the matcher.
2449 A boolean value indicating whether the xmethod is enabled or
2454 The class @code{XMethod} is a convenience class with same
2455 attributes as above along with the following constructor:
2457 @defun XMethod.__init__ (self, name)
2458 Constructs an enabled xmethod with name @var{name}.
2463 The @code{XMethodMatcher} class has the following methods:
2465 @defun XMethodMatcher.__init__ (self, name)
2466 Constructs an enabled xmethod matcher with name @var{name}. The
2467 @code{methods} attribute is initialized to @code{None}.
2470 @defun XMethodMatcher.match (self, class_type, method_name)
2471 Derived classes should override this method. It should return a
2472 xmethod worker object (or a sequence of xmethod worker
2473 objects) matching the @var{class_type} and @var{method_name}.
2474 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2475 is a string value. If the matcher manages named methods as listed in
2476 its @code{methods} attribute, then only those worker objects whose
2477 corresponding entries in the @code{methods} list are enabled should be
2481 An xmethod worker should be an instance of a class derived from
2482 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
2483 or support the following interface:
2485 @defun XMethodWorker.get_arg_types (self)
2486 This method returns a sequence of @code{gdb.Type} objects corresponding
2487 to the arguments that the xmethod takes. It can return an empty
2488 sequence or @code{None} if the xmethod does not take any arguments.
2489 If the xmethod takes a single argument, then a single
2490 @code{gdb.Type} object corresponding to it can be returned.
2493 @defun XMethodWorker.get_result_type (self, *args)
2494 This method returns a @code{gdb.Type} object representing the type
2495 of the result of invoking this xmethod.
2496 The @var{args} argument is the same tuple of arguments that would be
2497 passed to the @code{__call__} method of this worker.
2500 @defun XMethodWorker.__call__ (self, *args)
2501 This is the method which does the @emph{work} of the xmethod. The
2502 @var{args} arguments is the tuple of arguments to the xmethod. Each
2503 element in this tuple is a gdb.Value object. The first element is
2504 always the @code{this} pointer value.
2507 For @value{GDBN} to lookup xmethods, the xmethod matchers
2508 should be registered using the following function defined in the module
2511 @defun register_xmethod_matcher (locus, matcher, replace=False)
2512 The @code{matcher} is registered with @code{locus}, replacing an
2513 existing matcher with the same name as @code{matcher} if
2514 @code{replace} is @code{True}. @code{locus} can be a
2515 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
2516 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
2517 @code{None}. If it is @code{None}, then @code{matcher} is registered
2521 @node Writing an Xmethod
2522 @subsubsection Writing an Xmethod
2523 @cindex writing xmethods in Python
2525 Implementing xmethods in Python will require implementing xmethod
2526 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2527 the following C@t{++} class:
2533 MyClass (int a) : a_(a) @{ @}
2535 int geta (void) @{ return a_; @}
2536 int operator+ (int b);
2543 MyClass::operator+ (int b)
2550 Let us define two xmethods for the class @code{MyClass}, one
2551 replacing the method @code{geta}, and another adding an overloaded
2552 flavor of @code{operator+} which takes a @code{MyClass} argument (the
2553 C@t{++} code above already has an overloaded @code{operator+}
2554 which takes an @code{int} argument). The xmethod matcher can be
2558 class MyClass_geta(gdb.xmethod.XMethod):
2560 gdb.xmethod.XMethod.__init__(self, 'geta')
2562 def get_worker(self, method_name):
2563 if method_name == 'geta':
2564 return MyClassWorker_geta()
2567 class MyClass_sum(gdb.xmethod.XMethod):
2569 gdb.xmethod.XMethod.__init__(self, 'sum')
2571 def get_worker(self, method_name):
2572 if method_name == 'operator+':
2573 return MyClassWorker_plus()
2576 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2578 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2579 # List of methods 'managed' by this matcher
2580 self.methods = [MyClass_geta(), MyClass_sum()]
2582 def match(self, class_type, method_name):
2583 if class_type.tag != 'MyClass':
2586 for method in self.methods:
2588 worker = method.get_worker(method_name)
2590 workers.append(worker)
2596 Notice that the @code{match} method of @code{MyClassMatcher} returns
2597 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
2598 method, and a worker object of type @code{MyClassWorker_plus} for the
2599 @code{operator+} method. This is done indirectly via helper classes
2600 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
2601 @code{methods} attribute in a matcher as it is optional. However, if a
2602 matcher manages more than one xmethod, it is a good practice to list the
2603 xmethods in the @code{methods} attribute of the matcher. This will then
2604 facilitate enabling and disabling individual xmethods via the
2605 @code{enable/disable} commands. Notice also that a worker object is
2606 returned only if the corresponding entry in the @code{methods} attribute
2607 of the matcher is enabled.
2609 The implementation of the worker classes returned by the matcher setup
2610 above is as follows:
2613 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
2614 def get_arg_types(self):
2617 def get_result_type(self, obj):
2618 return gdb.lookup_type('int')
2620 def __call__(self, obj):
2624 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
2625 def get_arg_types(self):
2626 return gdb.lookup_type('MyClass')
2628 def get_result_type(self, obj):
2629 return gdb.lookup_type('int')
2631 def __call__(self, obj, other):
2632 return obj['a_'] + other['a_']
2635 For @value{GDBN} to actually lookup a xmethod, it has to be
2636 registered with it. The matcher defined above is registered with
2637 @value{GDBN} globally as follows:
2640 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
2643 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
2651 then, after loading the Python script defining the xmethod matchers
2652 and workers into @code{GDBN}, invoking the method @code{geta} or using
2653 the operator @code{+} on @code{obj} will invoke the xmethods
2664 Consider another example with a C++ template class:
2671 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
2672 ~MyTemplate () @{ delete [] data_; @}
2674 int footprint (void)
2676 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
2685 Let us implement an xmethod for the above class which serves as a
2686 replacement for the @code{footprint} method. The full code listing
2687 of the xmethod workers and xmethod matchers is as follows:
2690 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
2691 def __init__(self, class_type):
2692 self.class_type = class_type
2694 def get_arg_types(self):
2697 def get_result_type(self):
2698 return gdb.lookup_type('int')
2700 def __call__(self, obj):
2701 return (self.class_type.sizeof +
2703 self.class_type.template_argument(0).sizeof)
2706 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
2708 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
2710 def match(self, class_type, method_name):
2711 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
2713 method_name == 'footprint'):
2714 return MyTemplateWorker_footprint(class_type)
2717 Notice that, in this example, we have not used the @code{methods}
2718 attribute of the matcher as the matcher manages only one xmethod. The
2719 user can enable/disable this xmethod by enabling/disabling the matcher
2722 @node Inferiors In Python
2723 @subsubsection Inferiors In Python
2724 @cindex inferiors in Python
2726 @findex gdb.Inferior
2727 Programs which are being run under @value{GDBN} are called inferiors
2728 (@pxref{Inferiors and Programs}). Python scripts can access
2729 information about and manipulate inferiors controlled by @value{GDBN}
2730 via objects of the @code{gdb.Inferior} class.
2732 The following inferior-related functions are available in the @code{gdb}
2735 @defun gdb.inferiors ()
2736 Return a tuple containing all inferior objects.
2739 @defun gdb.selected_inferior ()
2740 Return an object representing the current inferior.
2743 A @code{gdb.Inferior} object has the following attributes:
2745 @defvar Inferior.num
2746 ID of inferior, as assigned by GDB.
2749 @defvar Inferior.pid
2750 Process ID of the inferior, as assigned by the underlying operating
2754 @defvar Inferior.was_attached
2755 Boolean signaling whether the inferior was created using `attach', or
2756 started by @value{GDBN} itself.
2759 A @code{gdb.Inferior} object has the following methods:
2761 @defun Inferior.is_valid ()
2762 Returns @code{True} if the @code{gdb.Inferior} object is valid,
2763 @code{False} if not. A @code{gdb.Inferior} object will become invalid
2764 if the inferior no longer exists within @value{GDBN}. All other
2765 @code{gdb.Inferior} methods will throw an exception if it is invalid
2766 at the time the method is called.
2769 @defun Inferior.threads ()
2770 This method returns a tuple holding all the threads which are valid
2771 when it is called. If there are no valid threads, the method will
2772 return an empty tuple.
2775 @findex Inferior.read_memory
2776 @defun Inferior.read_memory (address, length)
2777 Read @var{length} addressable memory units from the inferior, starting at
2778 @var{address}. Returns a buffer object, which behaves much like an array
2779 or a string. It can be modified and given to the
2780 @code{Inferior.write_memory} function. In Python 3, the return
2781 value is a @code{memoryview} object.
2784 @findex Inferior.write_memory
2785 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
2786 Write the contents of @var{buffer} to the inferior, starting at
2787 @var{address}. The @var{buffer} parameter must be a Python object
2788 which supports the buffer protocol, i.e., a string, an array or the
2789 object returned from @code{Inferior.read_memory}. If given, @var{length}
2790 determines the number of addressable memory units from @var{buffer} to be
2794 @findex gdb.search_memory
2795 @defun Inferior.search_memory (address, length, pattern)
2796 Search a region of the inferior memory starting at @var{address} with
2797 the given @var{length} using the search pattern supplied in
2798 @var{pattern}. The @var{pattern} parameter must be a Python object
2799 which supports the buffer protocol, i.e., a string, an array or the
2800 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
2801 containing the address where the pattern was found, or @code{None} if
2802 the pattern could not be found.
2805 @findex Inferior.thread_from_thread_handle
2806 @defun Inferior.thread_from_thread_handle (thread_handle)
2807 Return the thread object corresponding to @var{thread_handle}, a thread
2808 library specific data structure such as @code{pthread_t} for pthreads
2809 library implementations.
2812 @node Events In Python
2813 @subsubsection Events In Python
2814 @cindex inferior events in Python
2816 @value{GDBN} provides a general event facility so that Python code can be
2817 notified of various state changes, particularly changes that occur in
2820 An @dfn{event} is just an object that describes some state change. The
2821 type of the object and its attributes will vary depending on the details
2822 of the change. All the existing events are described below.
2824 In order to be notified of an event, you must register an event handler
2825 with an @dfn{event registry}. An event registry is an object in the
2826 @code{gdb.events} module which dispatches particular events. A registry
2827 provides methods to register and unregister event handlers:
2829 @defun EventRegistry.connect (object)
2830 Add the given callable @var{object} to the registry. This object will be
2831 called when an event corresponding to this registry occurs.
2834 @defun EventRegistry.disconnect (object)
2835 Remove the given @var{object} from the registry. Once removed, the object
2836 will no longer receive notifications of events.
2842 def exit_handler (event):
2843 print "event type: exit"
2844 print "exit code: %d" % (event.exit_code)
2846 gdb.events.exited.connect (exit_handler)
2849 In the above example we connect our handler @code{exit_handler} to the
2850 registry @code{events.exited}. Once connected, @code{exit_handler} gets
2851 called when the inferior exits. The argument @dfn{event} in this example is
2852 of type @code{gdb.ExitedEvent}. As you can see in the example the
2853 @code{ExitedEvent} object has an attribute which indicates the exit code of
2856 The following is a listing of the event registries that are available and
2857 details of the events they emit:
2862 Emits @code{gdb.ThreadEvent}.
2864 Some events can be thread specific when @value{GDBN} is running in non-stop
2865 mode. When represented in Python, these events all extend
2866 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
2867 events which are emitted by this or other modules might extend this event.
2868 Examples of these events are @code{gdb.BreakpointEvent} and
2869 @code{gdb.ContinueEvent}.
2871 @defvar ThreadEvent.inferior_thread
2872 In non-stop mode this attribute will be set to the specific thread which was
2873 involved in the emitted event. Otherwise, it will be set to @code{None}.
2876 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
2878 This event indicates that the inferior has been continued after a stop. For
2879 inherited attribute refer to @code{gdb.ThreadEvent} above.
2882 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
2883 @code{events.ExitedEvent} has two attributes:
2884 @defvar ExitedEvent.exit_code
2885 An integer representing the exit code, if available, which the inferior
2886 has returned. (The exit code could be unavailable if, for example,
2887 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
2888 the attribute does not exist.
2890 @defvar ExitedEvent.inferior
2891 A reference to the inferior which triggered the @code{exited} event.
2895 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
2897 Indicates that the inferior has stopped. All events emitted by this registry
2898 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
2899 will indicate the stopped thread when @value{GDBN} is running in non-stop
2900 mode. Refer to @code{gdb.ThreadEvent} above for more details.
2902 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
2904 This event indicates that the inferior or one of its threads has received as
2905 signal. @code{gdb.SignalEvent} has the following attributes:
2907 @defvar SignalEvent.stop_signal
2908 A string representing the signal received by the inferior. A list of possible
2909 signal values can be obtained by running the command @code{info signals} in
2910 the @value{GDBN} command prompt.
2913 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
2915 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
2916 been hit, and has the following attributes:
2918 @defvar BreakpointEvent.breakpoints
2919 A sequence containing references to all the breakpoints (type
2920 @code{gdb.Breakpoint}) that were hit.
2921 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
2923 @defvar BreakpointEvent.breakpoint
2924 A reference to the first breakpoint that was hit.
2925 This function is maintained for backward compatibility and is now deprecated
2926 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
2929 @item events.new_objfile
2930 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
2931 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
2933 @defvar NewObjFileEvent.new_objfile
2934 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
2935 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
2938 @item events.clear_objfiles
2939 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
2940 files for a program space has been reset.
2941 @code{gdb.ClearObjFilesEvent} has one attribute:
2943 @defvar ClearObjFilesEvent.progspace
2944 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
2945 been cleared. @xref{Progspaces In Python}.
2948 @item events.inferior_call_pre
2949 Emits @code{gdb.InferiorCallPreEvent} which indicates that a function in
2950 the inferior is about to be called.
2952 @defvar InferiorCallPreEvent.ptid
2953 The thread in which the call will be run.
2956 @defvar InferiorCallPreEvent.address
2957 The location of the function to be called.
2960 @item events.inferior_call_post
2961 Emits @code{gdb.InferiorCallPostEvent} which indicates that a function in
2962 the inferior has returned.
2964 @defvar InferiorCallPostEvent.ptid
2965 The thread in which the call was run.
2968 @defvar InferiorCallPostEvent.address
2969 The location of the function that was called.
2972 @item events.memory_changed
2973 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
2974 inferior has been modified by the @value{GDBN} user, for instance via a
2975 command like @w{@code{set *addr = value}}. The event has the following
2978 @defvar MemoryChangedEvent.address
2979 The start address of the changed region.
2982 @defvar MemoryChangedEvent.length
2983 Length in bytes of the changed region.
2986 @item events.register_changed
2987 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
2988 inferior has been modified by the @value{GDBN} user.
2990 @defvar RegisterChangedEvent.frame
2991 A gdb.Frame object representing the frame in which the register was modified.
2993 @defvar RegisterChangedEvent.regnum
2994 Denotes which register was modified.
2997 @item events.breakpoint_created
2998 This is emitted when a new breakpoint has been created. The argument
2999 that is passed is the new @code{gdb.Breakpoint} object.
3001 @item events.breakpoint_modified
3002 This is emitted when a breakpoint has been modified in some way. The
3003 argument that is passed is the new @code{gdb.Breakpoint} object.
3005 @item events.breakpoint_deleted
3006 This is emitted when a breakpoint has been deleted. The argument that
3007 is passed is the @code{gdb.Breakpoint} object. When this event is
3008 emitted, the @code{gdb.Breakpoint} object will already be in its
3009 invalid state; that is, the @code{is_valid} method will return
3012 @item events.before_prompt
3013 This event carries no payload. It is emitted each time @value{GDBN}
3014 presents a prompt to the user.
3016 @item events.new_inferior
3017 This is emitted when a new inferior is created. Note that the
3018 inferior is not necessarily running; in fact, it may not even have an
3019 associated executable.
3021 The event is of type @code{gdb.NewInferiorEvent}. This has a single
3024 @defvar NewInferiorEvent.inferior
3025 The new inferior, a @code{gdb.Inferior} object.
3028 @item events.inferior_deleted
3029 This is emitted when an inferior has been deleted. Note that this is
3030 not the same as process exit; it is notified when the inferior itself
3031 is removed, say via @code{remove-inferiors}.
3033 The event is of type @code{gdb.InferiorDeletedEvent}. This has a single
3036 @defvar NewInferiorEvent.inferior
3037 The inferior that is being removed, a @code{gdb.Inferior} object.
3040 @item events.new_thread
3041 This is emitted when @value{GDBN} notices a new thread. The event is of
3042 type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}.
3043 This has a single attribute:
3045 @defvar NewThreadEvent.inferior_thread
3051 @node Threads In Python
3052 @subsubsection Threads In Python
3053 @cindex threads in python
3055 @findex gdb.InferiorThread
3056 Python scripts can access information about, and manipulate inferior threads
3057 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
3059 The following thread-related functions are available in the @code{gdb}
3062 @findex gdb.selected_thread
3063 @defun gdb.selected_thread ()
3064 This function returns the thread object for the selected thread. If there
3065 is no selected thread, this will return @code{None}.
3068 A @code{gdb.InferiorThread} object has the following attributes:
3070 @defvar InferiorThread.name
3071 The name of the thread. If the user specified a name using
3072 @code{thread name}, then this returns that name. Otherwise, if an
3073 OS-supplied name is available, then it is returned. Otherwise, this
3074 returns @code{None}.
3076 This attribute can be assigned to. The new value must be a string
3077 object, which sets the new name, or @code{None}, which removes any
3078 user-specified thread name.
3081 @defvar InferiorThread.num
3082 The per-inferior number of the thread, as assigned by GDB.
3085 @defvar InferiorThread.global_num
3086 The global ID of the thread, as assigned by GDB. You can use this to
3087 make Python breakpoints thread-specific, for example
3088 (@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
3091 @defvar InferiorThread.ptid
3092 ID of the thread, as assigned by the operating system. This attribute is a
3093 tuple containing three integers. The first is the Process ID (PID); the second
3094 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
3095 Either the LWPID or TID may be 0, which indicates that the operating system
3096 does not use that identifier.
3099 @defvar InferiorThread.inferior
3100 The inferior this thread belongs to. This attribute is represented as
3101 a @code{gdb.Inferior} object. This attribute is not writable.
3104 A @code{gdb.InferiorThread} object has the following methods:
3106 @defun InferiorThread.is_valid ()
3107 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
3108 @code{False} if not. A @code{gdb.InferiorThread} object will become
3109 invalid if the thread exits, or the inferior that the thread belongs
3110 is deleted. All other @code{gdb.InferiorThread} methods will throw an
3111 exception if it is invalid at the time the method is called.
3114 @defun InferiorThread.switch ()
3115 This changes @value{GDBN}'s currently selected thread to the one represented
3119 @defun InferiorThread.is_stopped ()
3120 Return a Boolean indicating whether the thread is stopped.
3123 @defun InferiorThread.is_running ()
3124 Return a Boolean indicating whether the thread is running.
3127 @defun InferiorThread.is_exited ()
3128 Return a Boolean indicating whether the thread is exited.
3131 @node Recordings In Python
3132 @subsubsection Recordings In Python
3133 @cindex recordings in python
3135 The following recordings-related functions
3136 (@pxref{Process Record and Replay}) are available in the @code{gdb}
3139 @defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
3140 Start a recording using the given @var{method} and @var{format}. If
3141 no @var{format} is given, the default format for the recording method
3142 is used. If no @var{method} is given, the default method will be used.
3143 Returns a @code{gdb.Record} object on success. Throw an exception on
3146 The following strings can be passed as @var{method}:
3152 @code{"btrace"}: Possible values for @var{format}: @code{"pt"},
3153 @code{"bts"} or leave out for default format.
3157 @defun gdb.current_recording ()
3158 Access a currently running recording. Return a @code{gdb.Record}
3159 object on success. Return @code{None} if no recording is currently
3163 @defun gdb.stop_recording ()
3164 Stop the current recording. Throw an exception if no recording is
3165 currently active. All record objects become invalid after this call.
3168 A @code{gdb.Record} object has the following attributes:
3170 @defvar Record.method
3171 A string with the current recording method, e.g.@: @code{full} or
3175 @defvar Record.format
3176 A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
3180 @defvar Record.begin
3181 A method specific instruction object representing the first instruction
3186 A method specific instruction object representing the current
3187 instruction, that is not actually part of the recording.
3190 @defvar Record.replay_position
3191 The instruction representing the current replay position. If there is
3192 no replay active, this will be @code{None}.
3195 @defvar Record.instruction_history
3196 A list with all recorded instructions.
3199 @defvar Record.function_call_history
3200 A list with all recorded function call segments.
3203 A @code{gdb.Record} object has the following methods:
3205 @defun Record.goto (instruction)
3206 Move the replay position to the given @var{instruction}.
3209 The common @code{gdb.Instruction} class that recording method specific
3210 instruction objects inherit from, has the following attributes:
3212 @defvar Instruction.pc
3213 An integer representing this instruction's address.
3216 @defvar Instruction.data
3217 A buffer with the raw instruction data. In Python 3, the return value is a
3218 @code{memoryview} object.
3221 @defvar Instruction.decoded
3222 A human readable string with the disassembled instruction.
3225 @defvar Instruction.size
3226 The size of the instruction in bytes.
3229 Additionally @code{gdb.RecordInstruction} has the following attributes:
3231 @defvar RecordInstruction.number
3232 An integer identifying this instruction. @code{number} corresponds to
3233 the numbers seen in @code{record instruction-history}
3234 (@pxref{Process Record and Replay}).
3237 @defvar RecordInstruction.sal
3238 A @code{gdb.Symtab_and_line} object representing the associated symtab
3239 and line of this instruction. May be @code{None} if no debug information is
3243 @defvar RecordInstruction.is_speculative
3244 A boolean indicating whether the instruction was executed speculatively.
3247 If an error occured during recording or decoding a recording, this error is
3248 represented by a @code{gdb.RecordGap} object in the instruction list. It has
3249 the following attributes:
3251 @defvar RecordGap.number
3252 An integer identifying this gap. @code{number} corresponds to the numbers seen
3253 in @code{record instruction-history} (@pxref{Process Record and Replay}).
3256 @defvar RecordGap.error_code
3257 A numerical representation of the reason for the gap. The value is specific to
3258 the current recording method.
3261 @defvar RecordGap.error_string
3262 A human readable string with the reason for the gap.
3265 A @code{gdb.RecordFunctionSegment} object has the following attributes:
3267 @defvar RecordFunctionSegment.number
3268 An integer identifying this function segment. @code{number} corresponds to
3269 the numbers seen in @code{record function-call-history}
3270 (@pxref{Process Record and Replay}).
3273 @defvar RecordFunctionSegment.symbol
3274 A @code{gdb.Symbol} object representing the associated symbol. May be
3275 @code{None} if no debug information is available.
3278 @defvar RecordFunctionSegment.level
3279 An integer representing the function call's stack level. May be
3280 @code{None} if the function call is a gap.
3283 @defvar RecordFunctionSegment.instructions
3284 A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
3285 associated with this function call.
3288 @defvar RecordFunctionSegment.up
3289 A @code{gdb.RecordFunctionSegment} object representing the caller's
3290 function segment. If the call has not been recorded, this will be the
3291 function segment to which control returns. If neither the call nor the
3292 return have been recorded, this will be @code{None}.
3295 @defvar RecordFunctionSegment.prev
3296 A @code{gdb.RecordFunctionSegment} object representing the previous
3297 segment of this function call. May be @code{None}.
3300 @defvar RecordFunctionSegment.next
3301 A @code{gdb.RecordFunctionSegment} object representing the next segment of
3302 this function call. May be @code{None}.
3305 The following example demonstrates the usage of these objects and
3306 functions to create a function that will rewind a record to the last
3307 time a function in a different file was executed. This would typically
3308 be used to track the execution of user provided callback functions in a
3309 library which typically are not visible in a back trace.
3313 rec = gdb.current_recording ()
3317 insn = rec.instruction_history
3322 position = insn.index (rec.replay_position)
3326 filename = insn[position].sal.symtab.fullname ()
3330 for i in reversed (insn[:position]):
3332 current = i.sal.symtab.fullname ()
3336 if filename == current:
3343 Another possible application is to write a function that counts the
3344 number of code executions in a given line range. This line range can
3345 contain parts of functions or span across several functions and is not
3346 limited to be contiguous.
3349 def countrange (filename, linerange):
3352 def filter_only (file_name):
3353 for call in gdb.current_recording ().function_call_history:
3355 if file_name in call.symbol.symtab.fullname ():
3360 for c in filter_only (filename):
3361 for i in c.instructions:
3363 if i.sal.line in linerange:
3372 @node Commands In Python
3373 @subsubsection Commands In Python
3375 @cindex commands in python
3376 @cindex python commands
3377 You can implement new @value{GDBN} CLI commands in Python. A CLI
3378 command is implemented using an instance of the @code{gdb.Command}
3379 class, most commonly using a subclass.
3381 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
3382 The object initializer for @code{Command} registers the new command
3383 with @value{GDBN}. This initializer is normally invoked from the
3384 subclass' own @code{__init__} method.
3386 @var{name} is the name of the command. If @var{name} consists of
3387 multiple words, then the initial words are looked for as prefix
3388 commands. In this case, if one of the prefix commands does not exist,
3389 an exception is raised.
3391 There is no support for multi-line commands.
3393 @var{command_class} should be one of the @samp{COMMAND_} constants
3394 defined below. This argument tells @value{GDBN} how to categorize the
3395 new command in the help system.
3397 @var{completer_class} is an optional argument. If given, it should be
3398 one of the @samp{COMPLETE_} constants defined below. This argument
3399 tells @value{GDBN} how to perform completion for this command. If not
3400 given, @value{GDBN} will attempt to complete using the object's
3401 @code{complete} method (see below); if no such method is found, an
3402 error will occur when completion is attempted.
3404 @var{prefix} is an optional argument. If @code{True}, then the new
3405 command is a prefix command; sub-commands of this command may be
3408 The help text for the new command is taken from the Python
3409 documentation string for the command's class, if there is one. If no
3410 documentation string is provided, the default value ``This command is
3411 not documented.'' is used.
3414 @cindex don't repeat Python command
3415 @defun Command.dont_repeat ()
3416 By default, a @value{GDBN} command is repeated when the user enters a
3417 blank line at the command prompt. A command can suppress this
3418 behavior by invoking the @code{dont_repeat} method. This is similar
3419 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
3422 @defun Command.invoke (argument, from_tty)
3423 This method is called by @value{GDBN} when this command is invoked.
3425 @var{argument} is a string. It is the argument to the command, after
3426 leading and trailing whitespace has been stripped.
3428 @var{from_tty} is a boolean argument. When true, this means that the
3429 command was entered by the user at the terminal; when false it means
3430 that the command came from elsewhere.
3432 If this method throws an exception, it is turned into a @value{GDBN}
3433 @code{error} call. Otherwise, the return value is ignored.
3435 @findex gdb.string_to_argv
3436 To break @var{argument} up into an argv-like string use
3437 @code{gdb.string_to_argv}. This function behaves identically to
3438 @value{GDBN}'s internal argument lexer @code{buildargv}.
3439 It is recommended to use this for consistency.
3440 Arguments are separated by spaces and may be quoted.
3444 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
3445 ['1', '2 "3', '4 "5', "6 '7"]
3450 @cindex completion of Python commands
3451 @defun Command.complete (text, word)
3452 This method is called by @value{GDBN} when the user attempts
3453 completion on this command. All forms of completion are handled by
3454 this method, that is, the @key{TAB} and @key{M-?} key bindings
3455 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
3458 The arguments @var{text} and @var{word} are both strings; @var{text}
3459 holds the complete command line up to the cursor's location, while
3460 @var{word} holds the last word of the command line; this is computed
3461 using a word-breaking heuristic.
3463 The @code{complete} method can return several values:
3466 If the return value is a sequence, the contents of the sequence are
3467 used as the completions. It is up to @code{complete} to ensure that the
3468 contents actually do complete the word. A zero-length sequence is
3469 allowed, it means that there were no completions available. Only
3470 string elements of the sequence are used; other elements in the
3471 sequence are ignored.
3474 If the return value is one of the @samp{COMPLETE_} constants defined
3475 below, then the corresponding @value{GDBN}-internal completion
3476 function is invoked, and its result is used.
3479 All other results are treated as though there were no available
3484 When a new command is registered, it must be declared as a member of
3485 some general class of commands. This is used to classify top-level
3486 commands in the on-line help system; note that prefix commands are not
3487 listed under their own category but rather that of their top-level
3488 command. The available classifications are represented by constants
3489 defined in the @code{gdb} module:
3492 @findex COMMAND_NONE
3493 @findex gdb.COMMAND_NONE
3494 @item gdb.COMMAND_NONE
3495 The command does not belong to any particular class. A command in
3496 this category will not be displayed in any of the help categories.
3498 @findex COMMAND_RUNNING
3499 @findex gdb.COMMAND_RUNNING
3500 @item gdb.COMMAND_RUNNING
3501 The command is related to running the inferior. For example,
3502 @code{start}, @code{step}, and @code{continue} are in this category.
3503 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
3504 commands in this category.
3506 @findex COMMAND_DATA
3507 @findex gdb.COMMAND_DATA
3508 @item gdb.COMMAND_DATA
3509 The command is related to data or variables. For example,
3510 @code{call}, @code{find}, and @code{print} are in this category. Type
3511 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
3514 @findex COMMAND_STACK
3515 @findex gdb.COMMAND_STACK
3516 @item gdb.COMMAND_STACK
3517 The command has to do with manipulation of the stack. For example,
3518 @code{backtrace}, @code{frame}, and @code{return} are in this
3519 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
3520 list of commands in this category.
3522 @findex COMMAND_FILES
3523 @findex gdb.COMMAND_FILES
3524 @item gdb.COMMAND_FILES
3525 This class is used for file-related commands. For example,
3526 @code{file}, @code{list} and @code{section} are in this category.
3527 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
3528 commands in this category.
3530 @findex COMMAND_SUPPORT
3531 @findex gdb.COMMAND_SUPPORT
3532 @item gdb.COMMAND_SUPPORT
3533 This should be used for ``support facilities'', generally meaning
3534 things that are useful to the user when interacting with @value{GDBN},
3535 but not related to the state of the inferior. For example,
3536 @code{help}, @code{make}, and @code{shell} are in this category. Type
3537 @kbd{help support} at the @value{GDBN} prompt to see a list of
3538 commands in this category.
3540 @findex COMMAND_STATUS
3541 @findex gdb.COMMAND_STATUS
3542 @item gdb.COMMAND_STATUS
3543 The command is an @samp{info}-related command, that is, related to the
3544 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
3545 and @code{show} are in this category. Type @kbd{help status} at the
3546 @value{GDBN} prompt to see a list of commands in this category.
3548 @findex COMMAND_BREAKPOINTS
3549 @findex gdb.COMMAND_BREAKPOINTS
3550 @item gdb.COMMAND_BREAKPOINTS
3551 The command has to do with breakpoints. For example, @code{break},
3552 @code{clear}, and @code{delete} are in this category. Type @kbd{help
3553 breakpoints} at the @value{GDBN} prompt to see a list of commands in
3556 @findex COMMAND_TRACEPOINTS
3557 @findex gdb.COMMAND_TRACEPOINTS
3558 @item gdb.COMMAND_TRACEPOINTS
3559 The command has to do with tracepoints. For example, @code{trace},
3560 @code{actions}, and @code{tfind} are in this category. Type
3561 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
3562 commands in this category.
3564 @findex COMMAND_USER
3565 @findex gdb.COMMAND_USER
3566 @item gdb.COMMAND_USER
3567 The command is a general purpose command for the user, and typically
3568 does not fit in one of the other categories.
3569 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
3570 a list of commands in this category, as well as the list of gdb macros
3571 (@pxref{Sequences}).
3573 @findex COMMAND_OBSCURE
3574 @findex gdb.COMMAND_OBSCURE
3575 @item gdb.COMMAND_OBSCURE
3576 The command is only used in unusual circumstances, or is not of
3577 general interest to users. For example, @code{checkpoint},
3578 @code{fork}, and @code{stop} are in this category. Type @kbd{help
3579 obscure} at the @value{GDBN} prompt to see a list of commands in this
3582 @findex COMMAND_MAINTENANCE
3583 @findex gdb.COMMAND_MAINTENANCE
3584 @item gdb.COMMAND_MAINTENANCE
3585 The command is only useful to @value{GDBN} maintainers. The
3586 @code{maintenance} and @code{flushregs} commands are in this category.
3587 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
3588 commands in this category.
3591 A new command can use a predefined completion function, either by
3592 specifying it via an argument at initialization, or by returning it
3593 from the @code{complete} method. These predefined completion
3594 constants are all defined in the @code{gdb} module:
3597 @vindex COMPLETE_NONE
3598 @item gdb.COMPLETE_NONE
3599 This constant means that no completion should be done.
3601 @vindex COMPLETE_FILENAME
3602 @item gdb.COMPLETE_FILENAME
3603 This constant means that filename completion should be performed.
3605 @vindex COMPLETE_LOCATION
3606 @item gdb.COMPLETE_LOCATION
3607 This constant means that location completion should be done.
3608 @xref{Specify Location}.
3610 @vindex COMPLETE_COMMAND
3611 @item gdb.COMPLETE_COMMAND
3612 This constant means that completion should examine @value{GDBN}
3615 @vindex COMPLETE_SYMBOL
3616 @item gdb.COMPLETE_SYMBOL
3617 This constant means that completion should be done using symbol names
3620 @vindex COMPLETE_EXPRESSION
3621 @item gdb.COMPLETE_EXPRESSION
3622 This constant means that completion should be done on expressions.
3623 Often this means completing on symbol names, but some language
3624 parsers also have support for completing on field names.
3627 The following code snippet shows how a trivial CLI command can be
3628 implemented in Python:
3631 class HelloWorld (gdb.Command):
3632 """Greet the whole world."""
3634 def __init__ (self):
3635 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
3637 def invoke (self, arg, from_tty):
3638 print "Hello, World!"
3643 The last line instantiates the class, and is necessary to trigger the
3644 registration of the command with @value{GDBN}. Depending on how the
3645 Python code is read into @value{GDBN}, you may need to import the
3646 @code{gdb} module explicitly.
3648 @node Parameters In Python
3649 @subsubsection Parameters In Python
3651 @cindex parameters in python
3652 @cindex python parameters
3653 @tindex gdb.Parameter
3655 You can implement new @value{GDBN} parameters using Python. A new
3656 parameter is implemented as an instance of the @code{gdb.Parameter}
3659 Parameters are exposed to the user via the @code{set} and
3660 @code{show} commands. @xref{Help}.
3662 There are many parameters that already exist and can be set in
3663 @value{GDBN}. Two examples are: @code{set follow fork} and
3664 @code{set charset}. Setting these parameters influences certain
3665 behavior in @value{GDBN}. Similarly, you can define parameters that
3666 can be used to influence behavior in custom Python scripts and commands.
3668 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
3669 The object initializer for @code{Parameter} registers the new
3670 parameter with @value{GDBN}. This initializer is normally invoked
3671 from the subclass' own @code{__init__} method.
3673 @var{name} is the name of the new parameter. If @var{name} consists
3674 of multiple words, then the initial words are looked for as prefix
3675 parameters. An example of this can be illustrated with the
3676 @code{set print} set of parameters. If @var{name} is
3677 @code{print foo}, then @code{print} will be searched as the prefix
3678 parameter. In this case the parameter can subsequently be accessed in
3679 @value{GDBN} as @code{set print foo}.
3681 If @var{name} consists of multiple words, and no prefix parameter group
3682 can be found, an exception is raised.
3684 @var{command-class} should be one of the @samp{COMMAND_} constants
3685 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
3686 categorize the new parameter in the help system.
3688 @var{parameter-class} should be one of the @samp{PARAM_} constants
3689 defined below. This argument tells @value{GDBN} the type of the new
3690 parameter; this information is used for input validation and
3693 If @var{parameter-class} is @code{PARAM_ENUM}, then
3694 @var{enum-sequence} must be a sequence of strings. These strings
3695 represent the possible values for the parameter.
3697 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
3698 of a fourth argument will cause an exception to be thrown.
3700 The help text for the new parameter is taken from the Python
3701 documentation string for the parameter's class, if there is one. If
3702 there is no documentation string, a default value is used.
3705 @defvar Parameter.set_doc
3706 If this attribute exists, and is a string, then its value is used as
3707 the help text for this parameter's @code{set} command. The value is
3708 examined when @code{Parameter.__init__} is invoked; subsequent changes
3712 @defvar Parameter.show_doc
3713 If this attribute exists, and is a string, then its value is used as
3714 the help text for this parameter's @code{show} command. The value is
3715 examined when @code{Parameter.__init__} is invoked; subsequent changes
3719 @defvar Parameter.value
3720 The @code{value} attribute holds the underlying value of the
3721 parameter. It can be read and assigned to just as any other
3722 attribute. @value{GDBN} does validation when assignments are made.
3725 There are two methods that should be implemented in any
3726 @code{Parameter} class. These are:
3728 @defun Parameter.get_set_string (self)
3729 @value{GDBN} will call this method when a @var{parameter}'s value has
3730 been changed via the @code{set} API (for example, @kbd{set foo off}).
3731 The @code{value} attribute has already been populated with the new
3732 value and may be used in output. This method must return a string.
3735 @defun Parameter.get_show_string (self, svalue)
3736 @value{GDBN} will call this method when a @var{parameter}'s
3737 @code{show} API has been invoked (for example, @kbd{show foo}). The
3738 argument @code{svalue} receives the string representation of the
3739 current value. This method must return a string.
3742 When a new parameter is defined, its type must be specified. The
3743 available types are represented by constants defined in the @code{gdb}
3747 @findex PARAM_BOOLEAN
3748 @findex gdb.PARAM_BOOLEAN
3749 @item gdb.PARAM_BOOLEAN
3750 The value is a plain boolean. The Python boolean values, @code{True}
3751 and @code{False} are the only valid values.
3753 @findex PARAM_AUTO_BOOLEAN
3754 @findex gdb.PARAM_AUTO_BOOLEAN
3755 @item gdb.PARAM_AUTO_BOOLEAN
3756 The value has three possible states: true, false, and @samp{auto}. In
3757 Python, true and false are represented using boolean constants, and
3758 @samp{auto} is represented using @code{None}.
3760 @findex PARAM_UINTEGER
3761 @findex gdb.PARAM_UINTEGER
3762 @item gdb.PARAM_UINTEGER
3763 The value is an unsigned integer. The value of 0 should be
3764 interpreted to mean ``unlimited''.
3766 @findex PARAM_INTEGER
3767 @findex gdb.PARAM_INTEGER
3768 @item gdb.PARAM_INTEGER
3769 The value is a signed integer. The value of 0 should be interpreted
3770 to mean ``unlimited''.
3772 @findex PARAM_STRING
3773 @findex gdb.PARAM_STRING
3774 @item gdb.PARAM_STRING
3775 The value is a string. When the user modifies the string, any escape
3776 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
3777 translated into corresponding characters and encoded into the current
3780 @findex PARAM_STRING_NOESCAPE
3781 @findex gdb.PARAM_STRING_NOESCAPE
3782 @item gdb.PARAM_STRING_NOESCAPE
3783 The value is a string. When the user modifies the string, escapes are
3784 passed through untranslated.
3786 @findex PARAM_OPTIONAL_FILENAME
3787 @findex gdb.PARAM_OPTIONAL_FILENAME
3788 @item gdb.PARAM_OPTIONAL_FILENAME
3789 The value is a either a filename (a string), or @code{None}.
3791 @findex PARAM_FILENAME
3792 @findex gdb.PARAM_FILENAME
3793 @item gdb.PARAM_FILENAME
3794 The value is a filename. This is just like
3795 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
3797 @findex PARAM_ZINTEGER
3798 @findex gdb.PARAM_ZINTEGER
3799 @item gdb.PARAM_ZINTEGER
3800 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
3801 is interpreted as itself.
3804 @findex gdb.PARAM_ENUM
3805 @item gdb.PARAM_ENUM
3806 The value is a string, which must be one of a collection string
3807 constants provided when the parameter is created.
3810 @node Functions In Python
3811 @subsubsection Writing new convenience functions
3813 @cindex writing convenience functions
3814 @cindex convenience functions in python
3815 @cindex python convenience functions
3816 @tindex gdb.Function
3818 You can implement new convenience functions (@pxref{Convenience Vars})
3819 in Python. A convenience function is an instance of a subclass of the
3820 class @code{gdb.Function}.
3822 @defun Function.__init__ (name)
3823 The initializer for @code{Function} registers the new function with
3824 @value{GDBN}. The argument @var{name} is the name of the function,
3825 a string. The function will be visible to the user as a convenience
3826 variable of type @code{internal function}, whose name is the same as
3827 the given @var{name}.
3829 The documentation for the new function is taken from the documentation
3830 string for the new class.
3833 @defun Function.invoke (@var{*args})
3834 When a convenience function is evaluated, its arguments are converted
3835 to instances of @code{gdb.Value}, and then the function's
3836 @code{invoke} method is called. Note that @value{GDBN} does not
3837 predetermine the arity of convenience functions. Instead, all
3838 available arguments are passed to @code{invoke}, following the
3839 standard Python calling convention. In particular, a convenience
3840 function can have default values for parameters without ill effect.
3842 The return value of this method is used as its value in the enclosing
3843 expression. If an ordinary Python value is returned, it is converted
3844 to a @code{gdb.Value} following the usual rules.
3847 The following code snippet shows how a trivial convenience function can
3848 be implemented in Python:
3851 class Greet (gdb.Function):
3852 """Return string to greet someone.
3853 Takes a name as argument."""
3855 def __init__ (self):
3856 super (Greet, self).__init__ ("greet")
3858 def invoke (self, name):
3859 return "Hello, %s!" % name.string ()
3864 The last line instantiates the class, and is necessary to trigger the
3865 registration of the function with @value{GDBN}. Depending on how the
3866 Python code is read into @value{GDBN}, you may need to import the
3867 @code{gdb} module explicitly.
3869 Now you can use the function in an expression:
3872 (gdb) print $greet("Bob")
3876 @node Progspaces In Python
3877 @subsubsection Program Spaces In Python
3879 @cindex progspaces in python
3880 @tindex gdb.Progspace
3882 A program space, or @dfn{progspace}, represents a symbolic view
3883 of an address space.
3884 It consists of all of the objfiles of the program.
3885 @xref{Objfiles In Python}.
3886 @xref{Inferiors and Programs, program spaces}, for more details
3887 about program spaces.
3889 The following progspace-related functions are available in the
3892 @findex gdb.current_progspace
3893 @defun gdb.current_progspace ()
3894 This function returns the program space of the currently selected inferior.
3895 @xref{Inferiors and Programs}.
3898 @findex gdb.progspaces
3899 @defun gdb.progspaces ()
3900 Return a sequence of all the progspaces currently known to @value{GDBN}.
3903 Each progspace is represented by an instance of the @code{gdb.Progspace}
3906 @defvar Progspace.filename
3907 The file name of the progspace as a string.
3910 @defvar Progspace.pretty_printers
3911 The @code{pretty_printers} attribute is a list of functions. It is
3912 used to look up pretty-printers. A @code{Value} is passed to each
3913 function in order; if the function returns @code{None}, then the
3914 search continues. Otherwise, the return value should be an object
3915 which is used to format the value. @xref{Pretty Printing API}, for more
3919 @defvar Progspace.type_printers
3920 The @code{type_printers} attribute is a list of type printer objects.
3921 @xref{Type Printing API}, for more information.
3924 @defvar Progspace.frame_filters
3925 The @code{frame_filters} attribute is a dictionary of frame filter
3926 objects. @xref{Frame Filter API}, for more information.
3929 One may add arbitrary attributes to @code{gdb.Progspace} objects
3930 in the usual Python way.
3931 This is useful if, for example, one needs to do some extra record keeping
3932 associated with the program space.
3934 In this contrived example, we want to perform some processing when
3935 an objfile with a certain symbol is loaded, but we only want to do
3936 this once because it is expensive. To achieve this we record the results
3937 with the program space because we can't predict when the desired objfile
3942 def clear_objfiles_handler(event):
3943 event.progspace.expensive_computation = None
3944 def expensive(symbol):
3945 """A mock routine to perform an "expensive" computation on symbol."""
3946 print "Computing the answer to the ultimate question ..."
3948 def new_objfile_handler(event):
3949 objfile = event.new_objfile
3950 progspace = objfile.progspace
3951 if not hasattr(progspace, 'expensive_computation') or \
3952 progspace.expensive_computation is None:
3953 # We use 'main' for the symbol to keep the example simple.
3954 # Note: There's no current way to constrain the lookup
3956 symbol = gdb.lookup_global_symbol('main')
3957 if symbol is not None:
3958 progspace.expensive_computation = expensive(symbol)
3959 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
3960 gdb.events.new_objfile.connect(new_objfile_handler)
3962 (gdb) file /tmp/hello
3963 Reading symbols from /tmp/hello...done.
3964 Computing the answer to the ultimate question ...
3965 (gdb) python print gdb.current_progspace().expensive_computation
3968 Starting program: /tmp/hello
3970 [Inferior 1 (process 4242) exited normally]
3973 @node Objfiles In Python
3974 @subsubsection Objfiles In Python
3976 @cindex objfiles in python
3979 @value{GDBN} loads symbols for an inferior from various
3980 symbol-containing files (@pxref{Files}). These include the primary
3981 executable file, any shared libraries used by the inferior, and any
3982 separate debug info files (@pxref{Separate Debug Files}).
3983 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
3985 The following objfile-related functions are available in the
3988 @findex gdb.current_objfile
3989 @defun gdb.current_objfile ()
3990 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
3991 sets the ``current objfile'' to the corresponding objfile. This
3992 function returns the current objfile. If there is no current objfile,
3993 this function returns @code{None}.
3996 @findex gdb.objfiles
3997 @defun gdb.objfiles ()
3998 Return a sequence of all the objfiles current known to @value{GDBN}.
3999 @xref{Objfiles In Python}.
4002 @findex gdb.lookup_objfile
4003 @defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
4004 Look up @var{name}, a file name or build ID, in the list of objfiles
4005 for the current program space (@pxref{Progspaces In Python}).
4006 If the objfile is not found throw the Python @code{ValueError} exception.
4008 If @var{name} is a relative file name, then it will match any
4009 source file name with the same trailing components. For example, if
4010 @var{name} is @samp{gcc/expr.c}, then it will match source file
4011 name of @file{/build/trunk/gcc/expr.c}, but not
4012 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
4014 If @var{by_build_id} is provided and is @code{True} then @var{name}
4015 is the build ID of the objfile. Otherwise, @var{name} is a file name.
4016 This is supported only on some operating systems, notably those which use
4017 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4018 about this feature, see the description of the @option{--build-id}
4019 command-line option in @ref{Options, , Command Line Options, ld.info,
4023 Each objfile is represented by an instance of the @code{gdb.Objfile}
4026 @defvar Objfile.filename
4027 The file name of the objfile as a string, with symbolic links resolved.
4029 The value is @code{None} if the objfile is no longer valid.
4030 See the @code{gdb.Objfile.is_valid} method, described below.
4033 @defvar Objfile.username
4034 The file name of the objfile as specified by the user as a string.
4036 The value is @code{None} if the objfile is no longer valid.
4037 See the @code{gdb.Objfile.is_valid} method, described below.
4040 @defvar Objfile.owner
4041 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
4042 object that debug info is being provided for.
4043 Otherwise this is @code{None}.
4044 Separate debug info objfiles are added with the
4045 @code{gdb.Objfile.add_separate_debug_file} method, described below.
4048 @defvar Objfile.build_id
4049 The build ID of the objfile as a string.
4050 If the objfile does not have a build ID then the value is @code{None}.
4052 This is supported only on some operating systems, notably those which use
4053 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4054 about this feature, see the description of the @option{--build-id}
4055 command-line option in @ref{Options, , Command Line Options, ld.info,
4059 @defvar Objfile.progspace
4060 The containing program space of the objfile as a @code{gdb.Progspace}
4061 object. @xref{Progspaces In Python}.
4064 @defvar Objfile.pretty_printers
4065 The @code{pretty_printers} attribute is a list of functions. It is
4066 used to look up pretty-printers. A @code{Value} is passed to each
4067 function in order; if the function returns @code{None}, then the
4068 search continues. Otherwise, the return value should be an object
4069 which is used to format the value. @xref{Pretty Printing API}, for more
4073 @defvar Objfile.type_printers
4074 The @code{type_printers} attribute is a list of type printer objects.
4075 @xref{Type Printing API}, for more information.
4078 @defvar Objfile.frame_filters
4079 The @code{frame_filters} attribute is a dictionary of frame filter
4080 objects. @xref{Frame Filter API}, for more information.
4083 One may add arbitrary attributes to @code{gdb.Objfile} objects
4084 in the usual Python way.
4085 This is useful if, for example, one needs to do some extra record keeping
4086 associated with the objfile.
4088 In this contrived example we record the time when @value{GDBN}
4094 def new_objfile_handler(event):
4095 # Set the time_loaded attribute of the new objfile.
4096 event.new_objfile.time_loaded = datetime.datetime.today()
4097 gdb.events.new_objfile.connect(new_objfile_handler)
4100 Reading symbols from ./hello...done.
4101 (gdb) python print gdb.objfiles()[0].time_loaded
4102 2014-10-09 11:41:36.770345
4105 A @code{gdb.Objfile} object has the following methods:
4107 @defun Objfile.is_valid ()
4108 Returns @code{True} if the @code{gdb.Objfile} object is valid,
4109 @code{False} if not. A @code{gdb.Objfile} object can become invalid
4110 if the object file it refers to is not loaded in @value{GDBN} any
4111 longer. All other @code{gdb.Objfile} methods will throw an exception
4112 if it is invalid at the time the method is called.
4115 @defun Objfile.add_separate_debug_file (file)
4116 Add @var{file} to the list of files that @value{GDBN} will search for
4117 debug information for the objfile.
4118 This is useful when the debug info has been removed from the program
4119 and stored in a separate file. @value{GDBN} has built-in support for
4120 finding separate debug info files (@pxref{Separate Debug Files}), but if
4121 the file doesn't live in one of the standard places that @value{GDBN}
4122 searches then this function can be used to add a debug info file
4123 from a different place.
4126 @node Frames In Python
4127 @subsubsection Accessing inferior stack frames from Python.
4129 @cindex frames in python
4130 When the debugged program stops, @value{GDBN} is able to analyze its call
4131 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
4132 represents a frame in the stack. A @code{gdb.Frame} object is only valid
4133 while its corresponding frame exists in the inferior's stack. If you try
4134 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
4135 exception (@pxref{Exception Handling}).
4137 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
4141 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
4145 The following frame-related functions are available in the @code{gdb} module:
4147 @findex gdb.selected_frame
4148 @defun gdb.selected_frame ()
4149 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
4152 @findex gdb.newest_frame
4153 @defun gdb.newest_frame ()
4154 Return the newest frame object for the selected thread.
4157 @defun gdb.frame_stop_reason_string (reason)
4158 Return a string explaining the reason why @value{GDBN} stopped unwinding
4159 frames, as expressed by the given @var{reason} code (an integer, see the
4160 @code{unwind_stop_reason} method further down in this section).
4163 @findex gdb.invalidate_cached_frames
4164 @defun gdb.invalidate_cached_frames
4165 @value{GDBN} internally keeps a cache of the frames that have been
4166 unwound. This function invalidates this cache.
4168 This function should not generally be called by ordinary Python code.
4169 It is documented for the sake of completeness.
4172 A @code{gdb.Frame} object has the following methods:
4174 @defun Frame.is_valid ()
4175 Returns true if the @code{gdb.Frame} object is valid, false if not.
4176 A frame object can become invalid if the frame it refers to doesn't
4177 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
4178 an exception if it is invalid at the time the method is called.
4181 @defun Frame.name ()
4182 Returns the function name of the frame, or @code{None} if it can't be
4186 @defun Frame.architecture ()
4187 Returns the @code{gdb.Architecture} object corresponding to the frame's
4188 architecture. @xref{Architectures In Python}.
4191 @defun Frame.type ()
4192 Returns the type of the frame. The value can be one of:
4194 @item gdb.NORMAL_FRAME
4195 An ordinary stack frame.
4197 @item gdb.DUMMY_FRAME
4198 A fake stack frame that was created by @value{GDBN} when performing an
4199 inferior function call.
4201 @item gdb.INLINE_FRAME
4202 A frame representing an inlined function. The function was inlined
4203 into a @code{gdb.NORMAL_FRAME} that is older than this one.
4205 @item gdb.TAILCALL_FRAME
4206 A frame representing a tail call. @xref{Tail Call Frames}.
4208 @item gdb.SIGTRAMP_FRAME
4209 A signal trampoline frame. This is the frame created by the OS when
4210 it calls into a signal handler.
4212 @item gdb.ARCH_FRAME
4213 A fake stack frame representing a cross-architecture call.
4215 @item gdb.SENTINEL_FRAME
4216 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
4221 @defun Frame.unwind_stop_reason ()
4222 Return an integer representing the reason why it's not possible to find
4223 more frames toward the outermost frame. Use
4224 @code{gdb.frame_stop_reason_string} to convert the value returned by this
4225 function to a string. The value can be one of:
4228 @item gdb.FRAME_UNWIND_NO_REASON
4229 No particular reason (older frames should be available).
4231 @item gdb.FRAME_UNWIND_NULL_ID
4232 The previous frame's analyzer returns an invalid result. This is no
4233 longer used by @value{GDBN}, and is kept only for backward
4236 @item gdb.FRAME_UNWIND_OUTERMOST
4237 This frame is the outermost.
4239 @item gdb.FRAME_UNWIND_UNAVAILABLE
4240 Cannot unwind further, because that would require knowing the
4241 values of registers or memory that have not been collected.
4243 @item gdb.FRAME_UNWIND_INNER_ID
4244 This frame ID looks like it ought to belong to a NEXT frame,
4245 but we got it for a PREV frame. Normally, this is a sign of
4246 unwinder failure. It could also indicate stack corruption.
4248 @item gdb.FRAME_UNWIND_SAME_ID
4249 This frame has the same ID as the previous one. That means
4250 that unwinding further would almost certainly give us another
4251 frame with exactly the same ID, so break the chain. Normally,
4252 this is a sign of unwinder failure. It could also indicate
4255 @item gdb.FRAME_UNWIND_NO_SAVED_PC
4256 The frame unwinder did not find any saved PC, but we needed
4257 one to unwind further.
4259 @item gdb.FRAME_UNWIND_MEMORY_ERROR
4260 The frame unwinder caused an error while trying to access memory.
4262 @item gdb.FRAME_UNWIND_FIRST_ERROR
4263 Any stop reason greater or equal to this value indicates some kind
4264 of error. This special value facilitates writing code that tests
4265 for errors in unwinding in a way that will work correctly even if
4266 the list of the other values is modified in future @value{GDBN}
4267 versions. Using it, you could write:
4269 reason = gdb.selected_frame().unwind_stop_reason ()
4270 reason_str = gdb.frame_stop_reason_string (reason)
4271 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
4272 print "An error occured: %s" % reason_str
4279 Returns the frame's resume address.
4282 @defun Frame.block ()
4283 Return the frame's code block. @xref{Blocks In Python}.
4286 @defun Frame.function ()
4287 Return the symbol for the function corresponding to this frame.
4288 @xref{Symbols In Python}.
4291 @defun Frame.older ()
4292 Return the frame that called this frame.
4295 @defun Frame.newer ()
4296 Return the frame called by this frame.
4299 @defun Frame.find_sal ()
4300 Return the frame's symtab and line object.
4301 @xref{Symbol Tables In Python}.
4304 @defun Frame.read_register (register)
4305 Return the value of @var{register} in this frame. The @var{register}
4306 argument must be a string (e.g., @code{'sp'} or @code{'rax'}).
4307 Returns a @code{Gdb.Value} object. Throws an exception if @var{register}
4311 @defun Frame.read_var (variable @r{[}, block@r{]})
4312 Return the value of @var{variable} in this frame. If the optional
4313 argument @var{block} is provided, search for the variable from that
4314 block; otherwise start at the frame's current block (which is
4315 determined by the frame's current program counter). The @var{variable}
4316 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
4317 @code{gdb.Block} object.
4320 @defun Frame.select ()
4321 Set this frame to be the selected frame. @xref{Stack, ,Examining the
4325 @node Blocks In Python
4326 @subsubsection Accessing blocks from Python.
4328 @cindex blocks in python
4331 In @value{GDBN}, symbols are stored in blocks. A block corresponds
4332 roughly to a scope in the source code. Blocks are organized
4333 hierarchically, and are represented individually in Python as a
4334 @code{gdb.Block}. Blocks rely on debugging information being
4337 A frame has a block. Please see @ref{Frames In Python}, for a more
4338 in-depth discussion of frames.
4340 The outermost block is known as the @dfn{global block}. The global
4341 block typically holds public global variables and functions.
4343 The block nested just inside the global block is the @dfn{static
4344 block}. The static block typically holds file-scoped variables and
4347 @value{GDBN} provides a method to get a block's superblock, but there
4348 is currently no way to examine the sub-blocks of a block, or to
4349 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
4352 Here is a short example that should help explain blocks:
4355 /* This is in the global block. */
4358 /* This is in the static block. */
4359 static int file_scope;
4361 /* 'function' is in the global block, and 'argument' is
4362 in a block nested inside of 'function'. */
4363 int function (int argument)
4365 /* 'local' is in a block inside 'function'. It may or may
4366 not be in the same block as 'argument'. */
4370 /* 'inner' is in a block whose superblock is the one holding
4374 /* If this call is expanded by the compiler, you may see
4375 a nested block here whose function is 'inline_function'
4376 and whose superblock is the one holding 'inner'. */
4382 A @code{gdb.Block} is iterable. The iterator returns the symbols
4383 (@pxref{Symbols In Python}) local to the block. Python programs
4384 should not assume that a specific block object will always contain a
4385 given symbol, since changes in @value{GDBN} features and
4386 infrastructure may cause symbols move across blocks in a symbol
4389 The following block-related functions are available in the @code{gdb}
4392 @findex gdb.block_for_pc
4393 @defun gdb.block_for_pc (pc)
4394 Return the innermost @code{gdb.Block} containing the given @var{pc}
4395 value. If the block cannot be found for the @var{pc} value specified,
4396 the function will return @code{None}.
4399 A @code{gdb.Block} object has the following methods:
4401 @defun Block.is_valid ()
4402 Returns @code{True} if the @code{gdb.Block} object is valid,
4403 @code{False} if not. A block object can become invalid if the block it
4404 refers to doesn't exist anymore in the inferior. All other
4405 @code{gdb.Block} methods will throw an exception if it is invalid at
4406 the time the method is called. The block's validity is also checked
4407 during iteration over symbols of the block.
4410 A @code{gdb.Block} object has the following attributes:
4413 The start address of the block. This attribute is not writable.
4417 The end address of the block. This attribute is not writable.
4420 @defvar Block.function
4421 The name of the block represented as a @code{gdb.Symbol}. If the
4422 block is not named, then this attribute holds @code{None}. This
4423 attribute is not writable.
4425 For ordinary function blocks, the superblock is the static block.
4426 However, you should note that it is possible for a function block to
4427 have a superblock that is not the static block -- for instance this
4428 happens for an inlined function.
4431 @defvar Block.superblock
4432 The block containing this block. If this parent block does not exist,
4433 this attribute holds @code{None}. This attribute is not writable.
4436 @defvar Block.global_block
4437 The global block associated with this block. This attribute is not
4441 @defvar Block.static_block
4442 The static block associated with this block. This attribute is not
4446 @defvar Block.is_global
4447 @code{True} if the @code{gdb.Block} object is a global block,
4448 @code{False} if not. This attribute is not
4452 @defvar Block.is_static
4453 @code{True} if the @code{gdb.Block} object is a static block,
4454 @code{False} if not. This attribute is not writable.
4457 @node Symbols In Python
4458 @subsubsection Python representation of Symbols.
4460 @cindex symbols in python
4463 @value{GDBN} represents every variable, function and type as an
4464 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
4465 Similarly, Python represents these symbols in @value{GDBN} with the
4466 @code{gdb.Symbol} object.
4468 The following symbol-related functions are available in the @code{gdb}
4471 @findex gdb.lookup_symbol
4472 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
4473 This function searches for a symbol by name. The search scope can be
4474 restricted to the parameters defined in the optional domain and block
4477 @var{name} is the name of the symbol. It must be a string. The
4478 optional @var{block} argument restricts the search to symbols visible
4479 in that @var{block}. The @var{block} argument must be a
4480 @code{gdb.Block} object. If omitted, the block for the current frame
4481 is used. The optional @var{domain} argument restricts
4482 the search to the domain type. The @var{domain} argument must be a
4483 domain constant defined in the @code{gdb} module and described later
4486 The result is a tuple of two elements.
4487 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
4489 If the symbol is found, the second element is @code{True} if the symbol
4490 is a field of a method's object (e.g., @code{this} in C@t{++}),
4491 otherwise it is @code{False}.
4492 If the symbol is not found, the second element is @code{False}.
4495 @findex gdb.lookup_global_symbol
4496 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
4497 This function searches for a global symbol by name.
4498 The search scope can be restricted to by the domain argument.
4500 @var{name} is the name of the symbol. It must be a string.
4501 The optional @var{domain} argument restricts the search to the domain type.
4502 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4503 module and described later in this chapter.
4505 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4509 A @code{gdb.Symbol} object has the following attributes:
4512 The type of the symbol or @code{None} if no type is recorded.
4513 This attribute is represented as a @code{gdb.Type} object.
4514 @xref{Types In Python}. This attribute is not writable.
4517 @defvar Symbol.symtab
4518 The symbol table in which the symbol appears. This attribute is
4519 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
4520 Python}. This attribute is not writable.
4524 The line number in the source code at which the symbol was defined.
4529 The name of the symbol as a string. This attribute is not writable.
4532 @defvar Symbol.linkage_name
4533 The name of the symbol, as used by the linker (i.e., may be mangled).
4534 This attribute is not writable.
4537 @defvar Symbol.print_name
4538 The name of the symbol in a form suitable for output. This is either
4539 @code{name} or @code{linkage_name}, depending on whether the user
4540 asked @value{GDBN} to display demangled or mangled names.
4543 @defvar Symbol.addr_class
4544 The address class of the symbol. This classifies how to find the value
4545 of a symbol. Each address class is a constant defined in the
4546 @code{gdb} module and described later in this chapter.
4549 @defvar Symbol.needs_frame
4550 This is @code{True} if evaluating this symbol's value requires a frame
4551 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
4552 local variables will require a frame, but other symbols will not.
4555 @defvar Symbol.is_argument
4556 @code{True} if the symbol is an argument of a function.
4559 @defvar Symbol.is_constant
4560 @code{True} if the symbol is a constant.
4563 @defvar Symbol.is_function
4564 @code{True} if the symbol is a function or a method.
4567 @defvar Symbol.is_variable
4568 @code{True} if the symbol is a variable.
4571 A @code{gdb.Symbol} object has the following methods:
4573 @defun Symbol.is_valid ()
4574 Returns @code{True} if the @code{gdb.Symbol} object is valid,
4575 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
4576 the symbol it refers to does not exist in @value{GDBN} any longer.
4577 All other @code{gdb.Symbol} methods will throw an exception if it is
4578 invalid at the time the method is called.
4581 @defun Symbol.value (@r{[}frame@r{]})
4582 Compute the value of the symbol, as a @code{gdb.Value}. For
4583 functions, this computes the address of the function, cast to the
4584 appropriate type. If the symbol requires a frame in order to compute
4585 its value, then @var{frame} must be given. If @var{frame} is not
4586 given, or if @var{frame} is invalid, then this method will throw an
4590 The available domain categories in @code{gdb.Symbol} are represented
4591 as constants in the @code{gdb} module:
4594 @vindex SYMBOL_UNDEF_DOMAIN
4595 @item gdb.SYMBOL_UNDEF_DOMAIN
4596 This is used when a domain has not been discovered or none of the
4597 following domains apply. This usually indicates an error either
4598 in the symbol information or in @value{GDBN}'s handling of symbols.
4600 @vindex SYMBOL_VAR_DOMAIN
4601 @item gdb.SYMBOL_VAR_DOMAIN
4602 This domain contains variables, function names, typedef names and enum
4605 @vindex SYMBOL_STRUCT_DOMAIN
4606 @item gdb.SYMBOL_STRUCT_DOMAIN
4607 This domain holds struct, union and enum type names.
4609 @vindex SYMBOL_LABEL_DOMAIN
4610 @item gdb.SYMBOL_LABEL_DOMAIN
4611 This domain contains names of labels (for gotos).
4613 @vindex SYMBOL_VARIABLES_DOMAIN
4614 @item gdb.SYMBOL_VARIABLES_DOMAIN
4615 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
4616 contains everything minus functions and types.
4618 @vindex SYMBOL_FUNCTIONS_DOMAIN
4619 @item gdb.SYMBOL_FUNCTIONS_DOMAIN
4620 This domain contains all functions.
4622 @vindex SYMBOL_TYPES_DOMAIN
4623 @item gdb.SYMBOL_TYPES_DOMAIN
4624 This domain contains all types.
4627 The available address class categories in @code{gdb.Symbol} are represented
4628 as constants in the @code{gdb} module:
4631 @vindex SYMBOL_LOC_UNDEF
4632 @item gdb.SYMBOL_LOC_UNDEF
4633 If this is returned by address class, it indicates an error either in
4634 the symbol information or in @value{GDBN}'s handling of symbols.
4636 @vindex SYMBOL_LOC_CONST
4637 @item gdb.SYMBOL_LOC_CONST
4638 Value is constant int.
4640 @vindex SYMBOL_LOC_STATIC
4641 @item gdb.SYMBOL_LOC_STATIC
4642 Value is at a fixed address.
4644 @vindex SYMBOL_LOC_REGISTER
4645 @item gdb.SYMBOL_LOC_REGISTER
4646 Value is in a register.
4648 @vindex SYMBOL_LOC_ARG
4649 @item gdb.SYMBOL_LOC_ARG
4650 Value is an argument. This value is at the offset stored within the
4651 symbol inside the frame's argument list.
4653 @vindex SYMBOL_LOC_REF_ARG
4654 @item gdb.SYMBOL_LOC_REF_ARG
4655 Value address is stored in the frame's argument list. Just like
4656 @code{LOC_ARG} except that the value's address is stored at the
4657 offset, not the value itself.
4659 @vindex SYMBOL_LOC_REGPARM_ADDR
4660 @item gdb.SYMBOL_LOC_REGPARM_ADDR
4661 Value is a specified register. Just like @code{LOC_REGISTER} except
4662 the register holds the address of the argument instead of the argument
4665 @vindex SYMBOL_LOC_LOCAL
4666 @item gdb.SYMBOL_LOC_LOCAL
4667 Value is a local variable.
4669 @vindex SYMBOL_LOC_TYPEDEF
4670 @item gdb.SYMBOL_LOC_TYPEDEF
4671 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
4674 @vindex SYMBOL_LOC_BLOCK
4675 @item gdb.SYMBOL_LOC_BLOCK
4678 @vindex SYMBOL_LOC_CONST_BYTES
4679 @item gdb.SYMBOL_LOC_CONST_BYTES
4680 Value is a byte-sequence.
4682 @vindex SYMBOL_LOC_UNRESOLVED
4683 @item gdb.SYMBOL_LOC_UNRESOLVED
4684 Value is at a fixed address, but the address of the variable has to be
4685 determined from the minimal symbol table whenever the variable is
4688 @vindex SYMBOL_LOC_OPTIMIZED_OUT
4689 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
4690 The value does not actually exist in the program.
4692 @vindex SYMBOL_LOC_COMPUTED
4693 @item gdb.SYMBOL_LOC_COMPUTED
4694 The value's address is a computed location.
4697 @node Symbol Tables In Python
4698 @subsubsection Symbol table representation in Python.
4700 @cindex symbol tables in python
4702 @tindex gdb.Symtab_and_line
4704 Access to symbol table data maintained by @value{GDBN} on the inferior
4705 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
4706 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
4707 from the @code{find_sal} method in @code{gdb.Frame} object.
4708 @xref{Frames In Python}.
4710 For more information on @value{GDBN}'s symbol table management, see
4711 @ref{Symbols, ,Examining the Symbol Table}, for more information.
4713 A @code{gdb.Symtab_and_line} object has the following attributes:
4715 @defvar Symtab_and_line.symtab
4716 The symbol table object (@code{gdb.Symtab}) for this frame.
4717 This attribute is not writable.
4720 @defvar Symtab_and_line.pc
4721 Indicates the start of the address range occupied by code for the
4722 current source line. This attribute is not writable.
4725 @defvar Symtab_and_line.last
4726 Indicates the end of the address range occupied by code for the current
4727 source line. This attribute is not writable.
4730 @defvar Symtab_and_line.line
4731 Indicates the current line number for this object. This
4732 attribute is not writable.
4735 A @code{gdb.Symtab_and_line} object has the following methods:
4737 @defun Symtab_and_line.is_valid ()
4738 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
4739 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
4740 invalid if the Symbol table and line object it refers to does not
4741 exist in @value{GDBN} any longer. All other
4742 @code{gdb.Symtab_and_line} methods will throw an exception if it is
4743 invalid at the time the method is called.
4746 A @code{gdb.Symtab} object has the following attributes:
4748 @defvar Symtab.filename
4749 The symbol table's source filename. This attribute is not writable.
4752 @defvar Symtab.objfile
4753 The symbol table's backing object file. @xref{Objfiles In Python}.
4754 This attribute is not writable.
4757 @defvar Symtab.producer
4758 The name and possibly version number of the program that
4759 compiled the code in the symbol table.
4760 The contents of this string is up to the compiler.
4761 If no producer information is available then @code{None} is returned.
4762 This attribute is not writable.
4765 A @code{gdb.Symtab} object has the following methods:
4767 @defun Symtab.is_valid ()
4768 Returns @code{True} if the @code{gdb.Symtab} object is valid,
4769 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
4770 the symbol table it refers to does not exist in @value{GDBN} any
4771 longer. All other @code{gdb.Symtab} methods will throw an exception
4772 if it is invalid at the time the method is called.
4775 @defun Symtab.fullname ()
4776 Return the symbol table's source absolute file name.
4779 @defun Symtab.global_block ()
4780 Return the global block of the underlying symbol table.
4781 @xref{Blocks In Python}.
4784 @defun Symtab.static_block ()
4785 Return the static block of the underlying symbol table.
4786 @xref{Blocks In Python}.
4789 @defun Symtab.linetable ()
4790 Return the line table associated with the symbol table.
4791 @xref{Line Tables In Python}.
4794 @node Line Tables In Python
4795 @subsubsection Manipulating line tables using Python
4797 @cindex line tables in python
4798 @tindex gdb.LineTable
4800 Python code can request and inspect line table information from a
4801 symbol table that is loaded in @value{GDBN}. A line table is a
4802 mapping of source lines to their executable locations in memory. To
4803 acquire the line table information for a particular symbol table, use
4804 the @code{linetable} function (@pxref{Symbol Tables In Python}).
4806 A @code{gdb.LineTable} is iterable. The iterator returns
4807 @code{LineTableEntry} objects that correspond to the source line and
4808 address for each line table entry. @code{LineTableEntry} objects have
4809 the following attributes:
4811 @defvar LineTableEntry.line
4812 The source line number for this line table entry. This number
4813 corresponds to the actual line of source. This attribute is not
4817 @defvar LineTableEntry.pc
4818 The address that is associated with the line table entry where the
4819 executable code for that source line resides in memory. This
4820 attribute is not writable.
4823 As there can be multiple addresses for a single source line, you may
4824 receive multiple @code{LineTableEntry} objects with matching
4825 @code{line} attributes, but with different @code{pc} attributes. The
4826 iterator is sorted in ascending @code{pc} order. Here is a small
4827 example illustrating iterating over a line table.
4830 symtab = gdb.selected_frame().find_sal().symtab
4831 linetable = symtab.linetable()
4832 for line in linetable:
4833 print "Line: "+str(line.line)+" Address: "+hex(line.pc)
4836 This will have the following output:
4839 Line: 33 Address: 0x4005c8L
4840 Line: 37 Address: 0x4005caL
4841 Line: 39 Address: 0x4005d2L
4842 Line: 40 Address: 0x4005f8L
4843 Line: 42 Address: 0x4005ffL
4844 Line: 44 Address: 0x400608L
4845 Line: 42 Address: 0x40060cL
4846 Line: 45 Address: 0x400615L
4849 In addition to being able to iterate over a @code{LineTable}, it also
4850 has the following direct access methods:
4852 @defun LineTable.line (line)
4853 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
4854 entries in the line table for the given @var{line}, which specifies
4855 the source code line. If there are no entries for that source code
4856 @var{line}, the Python @code{None} is returned.
4859 @defun LineTable.has_line (line)
4860 Return a Python @code{Boolean} indicating whether there is an entry in
4861 the line table for this source line. Return @code{True} if an entry
4862 is found, or @code{False} if not.
4865 @defun LineTable.source_lines ()
4866 Return a Python @code{List} of the source line numbers in the symbol
4867 table. Only lines with executable code locations are returned. The
4868 contents of the @code{List} will just be the source line entries
4869 represented as Python @code{Long} values.
4872 @node Breakpoints In Python
4873 @subsubsection Manipulating breakpoints using Python
4875 @cindex breakpoints in python
4876 @tindex gdb.Breakpoint
4878 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
4881 A breakpoint can be created using one of the two forms of the
4882 @code{gdb.Breakpoint} constructor. The first one accepts a string
4883 like one would pass to the @code{break}
4884 (@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
4885 (@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
4886 create both breakpoints and watchpoints. The second accepts separate Python
4887 arguments similar to @ref{Explicit Locations}, and can only be used to create
4890 @defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]})
4891 Create a new breakpoint according to @var{spec}, which is a string naming the
4892 location of a breakpoint, or an expression that defines a watchpoint. The
4893 string should describe a location in a format recognized by the @code{break}
4894 command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
4895 watchpoint, by the @code{watch} command
4896 (@pxref{Set Watchpoints, , Setting Watchpoints}).
4898 The optional @var{type} argument specifies the type of the breakpoint to create,
4901 The optional @var{wp_class} argument defines the class of watchpoint to create,
4902 if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
4903 defaults to @code{gdb.WP_WRITE}.
4905 The optional @var{internal} argument allows the breakpoint to become invisible
4906 to the user. The breakpoint will neither be reported when created, nor will it
4907 be listed in the output from @code{info breakpoints} (but will be listed with
4908 the @code{maint info breakpoints} command).
4910 The optional @var{temporary} argument makes the breakpoint a temporary
4911 breakpoint. Temporary breakpoints are deleted after they have been hit. Any
4912 further access to the Python breakpoint after it has been hit will result in a
4913 runtime error (as that breakpoint has now been automatically deleted).
4915 The optional @var{qualified} argument is a boolean that allows interpreting
4916 the function passed in @code{spec} as a fully-qualified name. It is equivalent
4917 to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
4918 @ref{Explicit Locations}).
4922 @defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]})
4923 This second form of creating a new breakpoint specifies the explicit
4924 location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
4925 be created in the specified source file @var{source}, at the specified
4926 @var{function}, @var{label} and @var{line}.
4928 @var{internal}, @var{temporary} and @var{qualified} have the same usage as
4929 explained previously.
4932 The available types are represented by constants defined in the @code{gdb}
4936 @vindex BP_BREAKPOINT
4937 @item gdb.BP_BREAKPOINT
4938 Normal code breakpoint.
4940 @vindex BP_WATCHPOINT
4941 @item gdb.BP_WATCHPOINT
4942 Watchpoint breakpoint.
4944 @vindex BP_HARDWARE_WATCHPOINT
4945 @item gdb.BP_HARDWARE_WATCHPOINT
4946 Hardware assisted watchpoint.
4948 @vindex BP_READ_WATCHPOINT
4949 @item gdb.BP_READ_WATCHPOINT
4950 Hardware assisted read watchpoint.
4952 @vindex BP_ACCESS_WATCHPOINT
4953 @item gdb.BP_ACCESS_WATCHPOINT
4954 Hardware assisted access watchpoint.
4957 The available watchpoint types represented by constants are defined in the
4963 Read only watchpoint.
4967 Write only watchpoint.
4971 Read/Write watchpoint.
4974 @defun Breakpoint.stop (self)
4975 The @code{gdb.Breakpoint} class can be sub-classed and, in
4976 particular, you may choose to implement the @code{stop} method.
4977 If this method is defined in a sub-class of @code{gdb.Breakpoint},
4978 it will be called when the inferior reaches any location of a
4979 breakpoint which instantiates that sub-class. If the method returns
4980 @code{True}, the inferior will be stopped at the location of the
4981 breakpoint, otherwise the inferior will continue.
4983 If there are multiple breakpoints at the same location with a
4984 @code{stop} method, each one will be called regardless of the
4985 return status of the previous. This ensures that all @code{stop}
4986 methods have a chance to execute at that location. In this scenario
4987 if one of the methods returns @code{True} but the others return
4988 @code{False}, the inferior will still be stopped.
4990 You should not alter the execution state of the inferior (i.e.@:, step,
4991 next, etc.), alter the current frame context (i.e.@:, change the current
4992 active frame), or alter, add or delete any breakpoint. As a general
4993 rule, you should not alter any data within @value{GDBN} or the inferior
4996 Example @code{stop} implementation:
4999 class MyBreakpoint (gdb.Breakpoint):
5001 inf_val = gdb.parse_and_eval("foo")
5008 @defun Breakpoint.is_valid ()
5009 Return @code{True} if this @code{Breakpoint} object is valid,
5010 @code{False} otherwise. A @code{Breakpoint} object can become invalid
5011 if the user deletes the breakpoint. In this case, the object still
5012 exists, but the underlying breakpoint does not. In the cases of
5013 watchpoint scope, the watchpoint remains valid even if execution of the
5014 inferior leaves the scope of that watchpoint.
5017 @defun Breakpoint.delete ()
5018 Permanently deletes the @value{GDBN} breakpoint. This also
5019 invalidates the Python @code{Breakpoint} object. Any further access
5020 to this object's attributes or methods will raise an error.
5023 @defvar Breakpoint.enabled
5024 This attribute is @code{True} if the breakpoint is enabled, and
5025 @code{False} otherwise. This attribute is writable. You can use it to enable
5026 or disable the breakpoint.
5029 @defvar Breakpoint.silent
5030 This attribute is @code{True} if the breakpoint is silent, and
5031 @code{False} otherwise. This attribute is writable.
5033 Note that a breakpoint can also be silent if it has commands and the
5034 first command is @code{silent}. This is not reported by the
5035 @code{silent} attribute.
5038 @defvar Breakpoint.pending
5039 This attribute is @code{True} if the breakpoint is pending, and
5040 @code{False} otherwise. @xref{Set Breaks}. This attribute is
5044 @anchor{python_breakpoint_thread}
5045 @defvar Breakpoint.thread
5046 If the breakpoint is thread-specific, this attribute holds the
5047 thread's global id. If the breakpoint is not thread-specific, this
5048 attribute is @code{None}. This attribute is writable.
5051 @defvar Breakpoint.task
5052 If the breakpoint is Ada task-specific, this attribute holds the Ada task
5053 id. If the breakpoint is not task-specific (or the underlying
5054 language is not Ada), this attribute is @code{None}. This attribute
5058 @defvar Breakpoint.ignore_count
5059 This attribute holds the ignore count for the breakpoint, an integer.
5060 This attribute is writable.
5063 @defvar Breakpoint.number
5064 This attribute holds the breakpoint's number --- the identifier used by
5065 the user to manipulate the breakpoint. This attribute is not writable.
5068 @defvar Breakpoint.type
5069 This attribute holds the breakpoint's type --- the identifier used to
5070 determine the actual breakpoint type or use-case. This attribute is not
5074 @defvar Breakpoint.visible
5075 This attribute tells whether the breakpoint is visible to the user
5076 when set, or when the @samp{info breakpoints} command is run. This
5077 attribute is not writable.
5080 @defvar Breakpoint.temporary
5081 This attribute indicates whether the breakpoint was created as a
5082 temporary breakpoint. Temporary breakpoints are automatically deleted
5083 after that breakpoint has been hit. Access to this attribute, and all
5084 other attributes and functions other than the @code{is_valid}
5085 function, will result in an error after the breakpoint has been hit
5086 (as it has been automatically deleted). This attribute is not
5090 @defvar Breakpoint.hit_count
5091 This attribute holds the hit count for the breakpoint, an integer.
5092 This attribute is writable, but currently it can only be set to zero.
5095 @defvar Breakpoint.location
5096 This attribute holds the location of the breakpoint, as specified by
5097 the user. It is a string. If the breakpoint does not have a location
5098 (that is, it is a watchpoint) the attribute's value is @code{None}. This
5099 attribute is not writable.
5102 @defvar Breakpoint.expression
5103 This attribute holds a breakpoint expression, as specified by
5104 the user. It is a string. If the breakpoint does not have an
5105 expression (the breakpoint is not a watchpoint) the attribute's value
5106 is @code{None}. This attribute is not writable.
5109 @defvar Breakpoint.condition
5110 This attribute holds the condition of the breakpoint, as specified by
5111 the user. It is a string. If there is no condition, this attribute's
5112 value is @code{None}. This attribute is writable.
5115 @defvar Breakpoint.commands
5116 This attribute holds the commands attached to the breakpoint. If
5117 there are commands, this attribute's value is a string holding all the
5118 commands, separated by newlines. If there are no commands, this
5119 attribute is @code{None}. This attribute is not writable.
5122 @node Finish Breakpoints in Python
5123 @subsubsection Finish Breakpoints
5125 @cindex python finish breakpoints
5126 @tindex gdb.FinishBreakpoint
5128 A finish breakpoint is a temporary breakpoint set at the return address of
5129 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
5130 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
5131 and deleted when the execution will run out of the breakpoint scope (i.e.@:
5132 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
5133 Finish breakpoints are thread specific and must be create with the right
5136 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
5137 Create a finish breakpoint at the return address of the @code{gdb.Frame}
5138 object @var{frame}. If @var{frame} is not provided, this defaults to the
5139 newest frame. The optional @var{internal} argument allows the breakpoint to
5140 become invisible to the user. @xref{Breakpoints In Python}, for further
5141 details about this argument.
5144 @defun FinishBreakpoint.out_of_scope (self)
5145 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
5146 @code{return} command, @dots{}), a function may not properly terminate, and
5147 thus never hit the finish breakpoint. When @value{GDBN} notices such a
5148 situation, the @code{out_of_scope} callback will be triggered.
5150 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
5154 class MyFinishBreakpoint (gdb.FinishBreakpoint)
5156 print "normal finish"
5159 def out_of_scope ():
5160 print "abnormal finish"
5164 @defvar FinishBreakpoint.return_value
5165 When @value{GDBN} is stopped at a finish breakpoint and the frame
5166 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
5167 attribute will contain a @code{gdb.Value} object corresponding to the return
5168 value of the function. The value will be @code{None} if the function return
5169 type is @code{void} or if the return value was not computable. This attribute
5173 @node Lazy Strings In Python
5174 @subsubsection Python representation of lazy strings.
5176 @cindex lazy strings in python
5177 @tindex gdb.LazyString
5179 A @dfn{lazy string} is a string whose contents is not retrieved or
5180 encoded until it is needed.
5182 A @code{gdb.LazyString} is represented in @value{GDBN} as an
5183 @code{address} that points to a region of memory, an @code{encoding}
5184 that will be used to encode that region of memory, and a @code{length}
5185 to delimit the region of memory that represents the string. The
5186 difference between a @code{gdb.LazyString} and a string wrapped within
5187 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
5188 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
5189 retrieved and encoded during printing, while a @code{gdb.Value}
5190 wrapping a string is immediately retrieved and encoded on creation.
5192 A @code{gdb.LazyString} object has the following functions:
5194 @defun LazyString.value ()
5195 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
5196 will point to the string in memory, but will lose all the delayed
5197 retrieval, encoding and handling that @value{GDBN} applies to a
5198 @code{gdb.LazyString}.
5201 @defvar LazyString.address
5202 This attribute holds the address of the string. This attribute is not
5206 @defvar LazyString.length
5207 This attribute holds the length of the string in characters. If the
5208 length is -1, then the string will be fetched and encoded up to the
5209 first null of appropriate width. This attribute is not writable.
5212 @defvar LazyString.encoding
5213 This attribute holds the encoding that will be applied to the string
5214 when the string is printed by @value{GDBN}. If the encoding is not
5215 set, or contains an empty string, then @value{GDBN} will select the
5216 most appropriate encoding when the string is printed. This attribute
5220 @defvar LazyString.type
5221 This attribute holds the type that is represented by the lazy string's
5222 type. For a lazy string this is a pointer or array type. To
5223 resolve this to the lazy string's character type, use the type's
5224 @code{target} method. @xref{Types In Python}. This attribute is not
5228 @node Architectures In Python
5229 @subsubsection Python representation of architectures
5230 @cindex Python architectures
5232 @value{GDBN} uses architecture specific parameters and artifacts in a
5233 number of its various computations. An architecture is represented
5234 by an instance of the @code{gdb.Architecture} class.
5236 A @code{gdb.Architecture} class has the following methods:
5238 @defun Architecture.name ()
5239 Return the name (string value) of the architecture.
5242 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
5243 Return a list of disassembled instructions starting from the memory
5244 address @var{start_pc}. The optional arguments @var{end_pc} and
5245 @var{count} determine the number of instructions in the returned list.
5246 If both the optional arguments @var{end_pc} and @var{count} are
5247 specified, then a list of at most @var{count} disassembled instructions
5248 whose start address falls in the closed memory address interval from
5249 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
5250 specified, but @var{count} is specified, then @var{count} number of
5251 instructions starting from the address @var{start_pc} are returned. If
5252 @var{count} is not specified but @var{end_pc} is specified, then all
5253 instructions whose start address falls in the closed memory address
5254 interval from @var{start_pc} to @var{end_pc} are returned. If neither
5255 @var{end_pc} nor @var{count} are specified, then a single instruction at
5256 @var{start_pc} is returned. For all of these cases, each element of the
5257 returned list is a Python @code{dict} with the following string keys:
5262 The value corresponding to this key is a Python long integer capturing
5263 the memory address of the instruction.
5266 The value corresponding to this key is a string value which represents
5267 the instruction with assembly language mnemonics. The assembly
5268 language flavor used is the same as that specified by the current CLI
5269 variable @code{disassembly-flavor}. @xref{Machine Code}.
5272 The value corresponding to this key is the length (integer value) of the
5273 instruction in bytes.
5278 @node Python Auto-loading
5279 @subsection Python Auto-loading
5280 @cindex Python auto-loading
5282 When a new object file is read (for example, due to the @code{file}
5283 command, or because the inferior has loaded a shared library),
5284 @value{GDBN} will look for Python support scripts in several ways:
5285 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
5286 @xref{Auto-loading extensions}.
5288 The auto-loading feature is useful for supplying application-specific
5289 debugging commands and scripts.
5291 Auto-loading can be enabled or disabled,
5292 and the list of auto-loaded scripts can be printed.
5295 @anchor{set auto-load python-scripts}
5296 @kindex set auto-load python-scripts
5297 @item set auto-load python-scripts [on|off]
5298 Enable or disable the auto-loading of Python scripts.
5300 @anchor{show auto-load python-scripts}
5301 @kindex show auto-load python-scripts
5302 @item show auto-load python-scripts
5303 Show whether auto-loading of Python scripts is enabled or disabled.
5305 @anchor{info auto-load python-scripts}
5306 @kindex info auto-load python-scripts
5307 @cindex print list of auto-loaded Python scripts
5308 @item info auto-load python-scripts [@var{regexp}]
5309 Print the list of all Python scripts that @value{GDBN} auto-loaded.
5311 Also printed is the list of Python scripts that were mentioned in
5312 the @code{.debug_gdb_scripts} section and were either not found
5313 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
5314 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
5315 This is useful because their names are not printed when @value{GDBN}
5316 tries to load them and fails. There may be many of them, and printing
5317 an error message for each one is problematic.
5319 If @var{regexp} is supplied only Python scripts with matching names are printed.
5324 (gdb) info auto-load python-scripts
5326 Yes py-section-script.py
5327 full name: /tmp/py-section-script.py
5328 No my-foo-pretty-printers.py
5332 When reading an auto-loaded file or script, @value{GDBN} sets the
5333 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
5334 function (@pxref{Objfiles In Python}). This can be useful for
5335 registering objfile-specific pretty-printers and frame-filters.
5337 @node Python modules
5338 @subsection Python modules
5339 @cindex python modules
5341 @value{GDBN} comes with several modules to assist writing Python code.
5344 * gdb.printing:: Building and registering pretty-printers.
5345 * gdb.types:: Utilities for working with types.
5346 * gdb.prompt:: Utilities for prompt value substitution.
5350 @subsubsection gdb.printing
5351 @cindex gdb.printing
5353 This module provides a collection of utilities for working with
5357 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
5358 This class specifies the API that makes @samp{info pretty-printer},
5359 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
5360 Pretty-printers should generally inherit from this class.
5362 @item SubPrettyPrinter (@var{name})
5363 For printers that handle multiple types, this class specifies the
5364 corresponding API for the subprinters.
5366 @item RegexpCollectionPrettyPrinter (@var{name})
5367 Utility class for handling multiple printers, all recognized via
5368 regular expressions.
5369 @xref{Writing a Pretty-Printer}, for an example.
5371 @item FlagEnumerationPrinter (@var{name})
5372 A pretty-printer which handles printing of @code{enum} values. Unlike
5373 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
5374 work properly when there is some overlap between the enumeration
5375 constants. The argument @var{name} is the name of the printer and
5376 also the name of the @code{enum} type to look up.
5378 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
5379 Register @var{printer} with the pretty-printer list of @var{obj}.
5380 If @var{replace} is @code{True} then any existing copy of the printer
5381 is replaced. Otherwise a @code{RuntimeError} exception is raised
5382 if a printer with the same name already exists.
5386 @subsubsection gdb.types
5389 This module provides a collection of utilities for working with
5390 @code{gdb.Type} objects.
5393 @item get_basic_type (@var{type})
5394 Return @var{type} with const and volatile qualifiers stripped,
5395 and with typedefs and C@t{++} references converted to the underlying type.
5400 typedef const int const_int;
5402 const_int& foo_ref (foo);
5403 int main () @{ return 0; @}
5410 (gdb) python import gdb.types
5411 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
5412 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
5416 @item has_field (@var{type}, @var{field})
5417 Return @code{True} if @var{type}, assumed to be a type with fields
5418 (e.g., a structure or union), has field @var{field}.
5420 @item make_enum_dict (@var{enum_type})
5421 Return a Python @code{dictionary} type produced from @var{enum_type}.
5423 @item deep_items (@var{type})
5424 Returns a Python iterator similar to the standard
5425 @code{gdb.Type.iteritems} method, except that the iterator returned
5426 by @code{deep_items} will recursively traverse anonymous struct or
5427 union fields. For example:
5441 Then in @value{GDBN}:
5443 (@value{GDBP}) python import gdb.types
5444 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
5445 (@value{GDBP}) python print struct_a.keys ()
5447 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
5448 @{['a', 'b0', 'b1']@}
5451 @item get_type_recognizers ()
5452 Return a list of the enabled type recognizers for the current context.
5453 This is called by @value{GDBN} during the type-printing process
5454 (@pxref{Type Printing API}).
5456 @item apply_type_recognizers (recognizers, type_obj)
5457 Apply the type recognizers, @var{recognizers}, to the type object
5458 @var{type_obj}. If any recognizer returns a string, return that
5459 string. Otherwise, return @code{None}. This is called by
5460 @value{GDBN} during the type-printing process (@pxref{Type Printing
5463 @item register_type_printer (locus, printer)
5464 This is a convenience function to register a type printer
5465 @var{printer}. The printer must implement the type printer protocol.
5466 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
5467 the printer is registered with that objfile; a @code{gdb.Progspace},
5468 in which case the printer is registered with that progspace; or
5469 @code{None}, in which case the printer is registered globally.
5472 This is a base class that implements the type printer protocol. Type
5473 printers are encouraged, but not required, to derive from this class.
5474 It defines a constructor:
5476 @defmethod TypePrinter __init__ (self, name)
5477 Initialize the type printer with the given name. The new printer
5478 starts in the enabled state.
5484 @subsubsection gdb.prompt
5487 This module provides a method for prompt value-substitution.
5490 @item substitute_prompt (@var{string})
5491 Return @var{string} with escape sequences substituted by values. Some
5492 escape sequences take arguments. You can specify arguments inside
5493 ``@{@}'' immediately following the escape sequence.
5495 The escape sequences you can pass to this function are:
5499 Substitute a backslash.
5501 Substitute an ESC character.
5503 Substitute the selected frame; an argument names a frame parameter.
5505 Substitute a newline.
5507 Substitute a parameter's value; the argument names the parameter.
5509 Substitute a carriage return.
5511 Substitute the selected thread; an argument names a thread parameter.
5513 Substitute the version of GDB.
5515 Substitute the current working directory.
5517 Begin a sequence of non-printing characters. These sequences are
5518 typically used with the ESC character, and are not counted in the string
5519 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
5520 blue-colored ``(gdb)'' prompt where the length is five.
5522 End a sequence of non-printing characters.
5528 substitute_prompt (``frame: \f,
5529 print arguments: \p@{print frame-arguments@}'')
5532 @exdent will return the string:
5535 "frame: main, print arguments: scalars"