1 @c Copyright (C) 2008-2018 Free Software Foundation, Inc.
2 @c Permission is granted to copy, distribute and/or modify this document
3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
4 @c any later version published by the Free Software Foundation; with the
5 @c Invariant Sections being ``Free Software'' and ``Free Software Needs
6 @c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
7 @c and with the Back-Cover Texts as in (a) below.
9 @c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
10 @c this GNU Manual. Buying copies from GNU Press supports the FSF in
11 @c developing GNU and promoting software freedom.''
14 @section Extending @value{GDBN} using Python
15 @cindex python scripting
16 @cindex scripting with python
18 You can extend @value{GDBN} using the @uref{http://www.python.org/,
19 Python programming language}. This feature is available only if
20 @value{GDBN} was configured using @option{--with-python}.
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.convenience_variable
292 @defun gdb.convenience_variable (name)
293 Return the value of the convenience variable (@pxref{Convenience
294 Vars}) named @var{name}. @var{name} must be a string. The name
295 should not include the @samp{$} that is used to mark a convenience
296 variable in an expression. If the convenience variable does not
297 exist, then @code{None} is returned.
300 @findex gdb.set_convenience_variable
301 @defun gdb.set_convenience_variable (name, value)
302 Set the value of the convenience variable (@pxref{Convenience Vars})
303 named @var{name}. @var{name} must be a string. The name should not
304 include the @samp{$} that is used to mark a convenience variable in an
305 expression. If @var{value} is @code{None}, then the convenience
306 variable is removed. Otherwise, if @var{value} is not a
307 @code{gdb.Value} (@pxref{Values From Inferior}), it is is converted
308 using the @code{gdb.Value} constructor.
311 @findex gdb.parse_and_eval
312 @defun gdb.parse_and_eval (expression)
313 Parse @var{expression}, which must be a string, as an expression in
314 the current language, evaluate it, and return the result as a
317 This function can be useful when implementing a new command
318 (@pxref{Commands In Python}), as it provides a way to parse the
319 command's argument as an expression. It is also useful simply to
323 @findex gdb.find_pc_line
324 @defun gdb.find_pc_line (pc)
325 Return the @code{gdb.Symtab_and_line} object corresponding to the
326 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
327 value of @var{pc} is passed as an argument, then the @code{symtab} and
328 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
329 will be @code{None} and 0 respectively.
332 @findex gdb.post_event
333 @defun gdb.post_event (event)
334 Put @var{event}, a callable object taking no arguments, into
335 @value{GDBN}'s internal event queue. This callable will be invoked at
336 some later point, during @value{GDBN}'s event processing. Events
337 posted using @code{post_event} will be run in the order in which they
338 were posted; however, there is no way to know when they will be
339 processed relative to other events inside @value{GDBN}.
341 @value{GDBN} is not thread-safe. If your Python program uses multiple
342 threads, you must be careful to only call @value{GDBN}-specific
343 functions in the @value{GDBN} thread. @code{post_event} ensures
347 (@value{GDBP}) python
351 > def __init__(self, message):
352 > self.message = message;
353 > def __call__(self):
354 > gdb.write(self.message)
356 >class MyThread1 (threading.Thread):
358 > gdb.post_event(Writer("Hello "))
360 >class MyThread2 (threading.Thread):
362 > gdb.post_event(Writer("World\n"))
367 (@value{GDBP}) Hello World
372 @defun gdb.write (string @r{[}, stream{]})
373 Print a string to @value{GDBN}'s paginated output stream. The
374 optional @var{stream} determines the stream to print to. The default
375 stream is @value{GDBN}'s standard output stream. Possible stream
382 @value{GDBN}'s standard output stream.
387 @value{GDBN}'s standard error stream.
392 @value{GDBN}'s log stream (@pxref{Logging Output}).
395 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
396 call this function and will automatically direct the output to the
402 Flush the buffer of a @value{GDBN} paginated stream so that the
403 contents are displayed immediately. @value{GDBN} will flush the
404 contents of a stream automatically when it encounters a newline in the
405 buffer. The optional @var{stream} determines the stream to flush. The
406 default stream is @value{GDBN}'s standard output stream. Possible
413 @value{GDBN}'s standard output stream.
418 @value{GDBN}'s standard error stream.
423 @value{GDBN}'s log stream (@pxref{Logging Output}).
427 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
428 call this function for the relevant stream.
431 @findex gdb.target_charset
432 @defun gdb.target_charset ()
433 Return the name of the current target character set (@pxref{Character
434 Sets}). This differs from @code{gdb.parameter('target-charset')} in
435 that @samp{auto} is never returned.
438 @findex gdb.target_wide_charset
439 @defun gdb.target_wide_charset ()
440 Return the name of the current target wide character set
441 (@pxref{Character Sets}). This differs from
442 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
446 @findex gdb.solib_name
447 @defun gdb.solib_name (address)
448 Return the name of the shared library holding the given @var{address}
449 as a string, or @code{None}.
452 @findex gdb.decode_line
453 @defun gdb.decode_line @r{[}expression@r{]}
454 Return locations of the line specified by @var{expression}, or of the
455 current line if no argument was given. This function returns a Python
456 tuple containing two elements. The first element contains a string
457 holding any unparsed section of @var{expression} (or @code{None} if
458 the expression has been fully parsed). The second element contains
459 either @code{None} or another tuple that contains all the locations
460 that match the expression represented as @code{gdb.Symtab_and_line}
461 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
462 provided, it is decoded the way that @value{GDBN}'s inbuilt
463 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
466 @defun gdb.prompt_hook (current_prompt)
469 If @var{prompt_hook} is callable, @value{GDBN} will call the method
470 assigned to this operation before a prompt is displayed by
473 The parameter @code{current_prompt} contains the current @value{GDBN}
474 prompt. This method must return a Python string, or @code{None}. If
475 a string is returned, the @value{GDBN} prompt will be set to that
476 string. If @code{None} is returned, @value{GDBN} will continue to use
479 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
480 such as those used by readline for command input, and annotation
481 related prompts are prohibited from being changed.
484 @node Exception Handling
485 @subsubsection Exception Handling
486 @cindex python exceptions
487 @cindex exceptions, python
489 When executing the @code{python} command, Python exceptions
490 uncaught within the Python code are translated to calls to
491 @value{GDBN} error-reporting mechanism. If the command that called
492 @code{python} does not handle the error, @value{GDBN} will
493 terminate it and print an error message containing the Python
494 exception name, the associated value, and the Python call stack
495 backtrace at the point where the exception was raised. Example:
498 (@value{GDBP}) python print foo
499 Traceback (most recent call last):
500 File "<string>", line 1, in <module>
501 NameError: name 'foo' is not defined
504 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
505 Python code are converted to Python exceptions. The type of the
506 Python exception depends on the error.
510 This is the base class for most exceptions generated by @value{GDBN}.
511 It is derived from @code{RuntimeError}, for compatibility with earlier
512 versions of @value{GDBN}.
514 If an error occurring in @value{GDBN} does not fit into some more
515 specific category, then the generated exception will have this type.
517 @item gdb.MemoryError
518 This is a subclass of @code{gdb.error} which is thrown when an
519 operation tried to access invalid memory in the inferior.
521 @item KeyboardInterrupt
522 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
523 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
526 In all cases, your exception handler will see the @value{GDBN} error
527 message as its value and the Python call stack backtrace at the Python
528 statement closest to where the @value{GDBN} error occured as the
532 When implementing @value{GDBN} commands in Python via
533 @code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
534 to be able to throw an exception that doesn't cause a traceback to be
535 printed. For example, the user may have invoked the command
536 incorrectly. @value{GDBN} provides a special exception class that can
537 be used for this purpose.
541 When thrown from a command or function, this exception will cause the
542 command or function to fail, but the Python stack will not be
543 displayed. @value{GDBN} does not throw this exception itself, but
544 rather recognizes it when thrown from user Python code. Example:
548 >class HelloWorld (gdb.Command):
549 > """Greet the whole world."""
550 > def __init__ (self):
551 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
552 > def invoke (self, args, from_tty):
553 > argv = gdb.string_to_argv (args)
554 > if len (argv) != 0:
555 > raise gdb.GdbError ("hello-world takes no arguments")
556 > print "Hello, World!"
560 hello-world takes no arguments
564 @node Values From Inferior
565 @subsubsection Values From Inferior
566 @cindex values from inferior, with Python
567 @cindex python, working with values from inferior
569 @cindex @code{gdb.Value}
570 @value{GDBN} provides values it obtains from the inferior program in
571 an object of type @code{gdb.Value}. @value{GDBN} uses this object
572 for its internal bookkeeping of the inferior's values, and for
573 fetching values when necessary.
575 Inferior values that are simple scalars can be used directly in
576 Python expressions that are valid for the value's data type. Here's
577 an example for an integer or floating-point value @code{some_val}:
584 As result of this, @code{bar} will also be a @code{gdb.Value} object
585 whose values are of the same type as those of @code{some_val}. Valid
586 Python operations can also be performed on @code{gdb.Value} objects
587 representing a @code{struct} or @code{class} object. For such cases,
588 the overloaded operator (if present), is used to perform the operation.
589 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
590 representing instances of a @code{class} which overloads the @code{+}
591 operator, then one can use the @code{+} operator in their Python script
599 The result of the operation @code{val3} is also a @code{gdb.Value}
600 object corresponding to the value returned by the overloaded @code{+}
601 operator. In general, overloaded operators are invoked for the
602 following operations: @code{+} (binary addition), @code{-} (binary
603 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
604 @code{>>}, @code{|}, @code{&}, @code{^}.
606 Inferior values that are structures or instances of some class can
607 be accessed using the Python @dfn{dictionary syntax}. For example, if
608 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
609 can access its @code{foo} element with:
612 bar = some_val['foo']
615 @cindex getting structure elements using gdb.Field objects as subscripts
616 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
617 elements can also be accessed by using @code{gdb.Field} objects as
618 subscripts (@pxref{Types In Python}, for more information on
619 @code{gdb.Field} objects). For example, if @code{foo_field} is a
620 @code{gdb.Field} object corresponding to element @code{foo} of the above
621 structure, then @code{bar} can also be accessed as follows:
624 bar = some_val[foo_field]
627 A @code{gdb.Value} that represents a function can be executed via
628 inferior function call. Any arguments provided to the call must match
629 the function's prototype, and must be provided in the order specified
632 For example, @code{some_val} is a @code{gdb.Value} instance
633 representing a function that takes two integers as arguments. To
634 execute this function, call it like so:
637 result = some_val (10,20)
640 Any values returned from a function call will be stored as a
643 The following attributes are provided:
645 @defvar Value.address
646 If this object is addressable, this read-only attribute holds a
647 @code{gdb.Value} object representing the address. Otherwise,
648 this attribute holds @code{None}.
651 @cindex optimized out value in Python
652 @defvar Value.is_optimized_out
653 This read-only boolean attribute is true if the compiler optimized out
654 this value, thus it is not available for fetching from the inferior.
658 The type of this @code{gdb.Value}. The value of this attribute is a
659 @code{gdb.Type} object (@pxref{Types In Python}).
662 @defvar Value.dynamic_type
663 The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time
664 type information (@acronym{RTTI}) to determine the dynamic type of the
665 value. If this value is of class type, it will return the class in
666 which the value is embedded, if any. If this value is of pointer or
667 reference to a class type, it will compute the dynamic type of the
668 referenced object, and return a pointer or reference to that type,
669 respectively. In all other cases, it will return the value's static
672 Note that this feature will only work when debugging a C@t{++} program
673 that includes @acronym{RTTI} for the object in question. Otherwise,
674 it will just return the static type of the value as in @kbd{ptype foo}
675 (@pxref{Symbols, ptype}).
678 @defvar Value.is_lazy
679 The value of this read-only boolean attribute is @code{True} if this
680 @code{gdb.Value} has not yet been fetched from the inferior.
681 @value{GDBN} does not fetch values until necessary, for efficiency.
685 myval = gdb.parse_and_eval ('somevar')
688 The value of @code{somevar} is not fetched at this time. It will be
689 fetched when the value is needed, or when the @code{fetch_lazy}
693 The following methods are provided:
695 @defun Value.__init__ (@var{val})
696 Many Python values can be converted directly to a @code{gdb.Value} via
697 this object initializer. Specifically:
701 A Python boolean is converted to the boolean type from the current
705 A Python integer is converted to the C @code{long} type for the
706 current architecture.
709 A Python long is converted to the C @code{long long} type for the
710 current architecture.
713 A Python float is converted to the C @code{double} type for the
714 current architecture.
717 A Python string is converted to a target string in the current target
718 language using the current target encoding.
719 If a character cannot be represented in the current target encoding,
720 then an exception is thrown.
722 @item @code{gdb.Value}
723 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
725 @item @code{gdb.LazyString}
726 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
727 Python}), then the lazy string's @code{value} method is called, and
732 @defun Value.cast (type)
733 Return a new instance of @code{gdb.Value} that is the result of
734 casting this instance to the type described by @var{type}, which must
735 be a @code{gdb.Type} object. If the cast cannot be performed for some
736 reason, this method throws an exception.
739 @defun Value.dereference ()
740 For pointer data types, this method returns a new @code{gdb.Value} object
741 whose contents is the object pointed to by the pointer. For example, if
742 @code{foo} is a C pointer to an @code{int}, declared in your C program as
749 then you can use the corresponding @code{gdb.Value} to access what
750 @code{foo} points to like this:
753 bar = foo.dereference ()
756 The result @code{bar} will be a @code{gdb.Value} object holding the
757 value pointed to by @code{foo}.
759 A similar function @code{Value.referenced_value} exists which also
760 returns @code{gdb.Value} objects corresonding to the values pointed to
761 by pointer values (and additionally, values referenced by reference
762 values). However, the behavior of @code{Value.dereference}
763 differs from @code{Value.referenced_value} by the fact that the
764 behavior of @code{Value.dereference} is identical to applying the C
765 unary operator @code{*} on a given value. For example, consider a
766 reference to a pointer @code{ptrref}, declared in your C@t{++} program
774 intptr &ptrref = ptr;
777 Though @code{ptrref} is a reference value, one can apply the method
778 @code{Value.dereference} to the @code{gdb.Value} object corresponding
779 to it and obtain a @code{gdb.Value} which is identical to that
780 corresponding to @code{val}. However, if you apply the method
781 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
782 object identical to that corresponding to @code{ptr}.
785 py_ptrref = gdb.parse_and_eval ("ptrref")
786 py_val = py_ptrref.dereference ()
787 py_ptr = py_ptrref.referenced_value ()
790 The @code{gdb.Value} object @code{py_val} is identical to that
791 corresponding to @code{val}, and @code{py_ptr} is identical to that
792 corresponding to @code{ptr}. In general, @code{Value.dereference} can
793 be applied whenever the C unary operator @code{*} can be applied
794 to the corresponding C value. For those cases where applying both
795 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
796 the results obtained need not be identical (as we have seen in the above
797 example). The results are however identical when applied on
798 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
799 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
802 @defun Value.referenced_value ()
803 For pointer or reference data types, this method returns a new
804 @code{gdb.Value} object corresponding to the value referenced by the
805 pointer/reference value. For pointer data types,
806 @code{Value.dereference} and @code{Value.referenced_value} produce
807 identical results. The difference between these methods is that
808 @code{Value.dereference} cannot get the values referenced by reference
809 values. For example, consider a reference to an @code{int}, declared
810 in your C@t{++} program as
818 then applying @code{Value.dereference} to the @code{gdb.Value} object
819 corresponding to @code{ref} will result in an error, while applying
820 @code{Value.referenced_value} will result in a @code{gdb.Value} object
821 identical to that corresponding to @code{val}.
824 py_ref = gdb.parse_and_eval ("ref")
825 er_ref = py_ref.dereference () # Results in error
826 py_val = py_ref.referenced_value () # Returns the referenced value
829 The @code{gdb.Value} object @code{py_val} is identical to that
830 corresponding to @code{val}.
833 @defun Value.reference_value ()
834 Return a @code{gdb.Value} object which is a reference to the value
835 encapsulated by this instance.
838 @defun Value.const_value ()
839 Return a @code{gdb.Value} object which is a @code{const} version of the
840 value encapsulated by this instance.
843 @defun Value.dynamic_cast (type)
844 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
845 operator were used. Consult a C@t{++} reference for details.
848 @defun Value.reinterpret_cast (type)
849 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
850 operator were used. Consult a C@t{++} reference for details.
853 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
854 If this @code{gdb.Value} represents a string, then this method
855 converts the contents to a Python string. Otherwise, this method will
858 Values are interpreted as strings according to the rules of the
859 current language. If the optional length argument is given, the
860 string will be converted to that length, and will include any embedded
861 zeroes that the string may contain. Otherwise, for languages
862 where the string is zero-terminated, the entire string will be
865 For example, in C-like languages, a value is a string if it is a pointer
866 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
869 If the optional @var{encoding} argument is given, it must be a string
870 naming the encoding of the string in the @code{gdb.Value}, such as
871 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
872 the same encodings as the corresponding argument to Python's
873 @code{string.decode} method, and the Python codec machinery will be used
874 to convert the string. If @var{encoding} is not given, or if
875 @var{encoding} is the empty string, then either the @code{target-charset}
876 (@pxref{Character Sets}) will be used, or a language-specific encoding
877 will be used, if the current language is able to supply one.
879 The optional @var{errors} argument is the same as the corresponding
880 argument to Python's @code{string.decode} method.
882 If the optional @var{length} argument is given, the string will be
883 fetched and converted to the given length.
886 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
887 If this @code{gdb.Value} represents a string, then this method
888 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
889 In Python}). Otherwise, this method will throw an exception.
891 If the optional @var{encoding} argument is given, it must be a string
892 naming the encoding of the @code{gdb.LazyString}. Some examples are:
893 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
894 @var{encoding} argument is an encoding that @value{GDBN} does
895 recognize, @value{GDBN} will raise an error.
897 When a lazy string is printed, the @value{GDBN} encoding machinery is
898 used to convert the string during printing. If the optional
899 @var{encoding} argument is not provided, or is an empty string,
900 @value{GDBN} will automatically select the encoding most suitable for
901 the string type. For further information on encoding in @value{GDBN}
902 please see @ref{Character Sets}.
904 If the optional @var{length} argument is given, the string will be
905 fetched and encoded to the length of characters specified. If
906 the @var{length} argument is not provided, the string will be fetched
907 and encoded until a null of appropriate width is found.
910 @defun Value.fetch_lazy ()
911 If the @code{gdb.Value} object is currently a lazy value
912 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
913 fetched from the inferior. Any errors that occur in the process
914 will produce a Python exception.
916 If the @code{gdb.Value} object is not a lazy value, this method
919 This method does not return a value.
923 @node Types In Python
924 @subsubsection Types In Python
925 @cindex types in Python
926 @cindex Python, working with types
929 @value{GDBN} represents types from the inferior using the class
932 The following type-related functions are available in the @code{gdb}
935 @findex gdb.lookup_type
936 @defun gdb.lookup_type (name @r{[}, block@r{]})
937 This function looks up a type by its @var{name}, which must be a string.
939 If @var{block} is given, then @var{name} is looked up in that scope.
940 Otherwise, it is searched for globally.
942 Ordinarily, this function will return an instance of @code{gdb.Type}.
943 If the named type cannot be found, it will throw an exception.
946 If the type is a structure or class type, or an enum type, the fields
947 of that type can be accessed using the Python @dfn{dictionary syntax}.
948 For example, if @code{some_type} is a @code{gdb.Type} instance holding
949 a structure type, you can access its @code{foo} field with:
952 bar = some_type['foo']
955 @code{bar} will be a @code{gdb.Field} object; see below under the
956 description of the @code{Type.fields} method for a description of the
957 @code{gdb.Field} class.
959 An instance of @code{Type} has the following attributes:
962 The alignment of this type, in bytes. Type alignment comes from the
963 debugging information; if it was not specified, then @value{GDBN} will
964 use the relevant ABI to try to determine the alignment. In some
965 cases, even this is not possible, and zero will be returned.
969 The type code for this type. The type code will be one of the
970 @code{TYPE_CODE_} constants defined below.
974 The name of this type. If this type has no name, then @code{None}
979 The size of this type, in target @code{char} units. Usually, a
980 target's @code{char} type will be an 8-bit byte. However, on some
981 unusual platforms, this type may have a different size.
985 The tag name for this type. The tag name is the name after
986 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
987 languages have this concept. If this type has no tag name, then
988 @code{None} is returned.
991 The following methods are provided:
993 @defun Type.fields ()
994 For structure and union types, this method returns the fields. Range
995 types have two fields, the minimum and maximum values. Enum types
996 have one field per enum constant. Function and method types have one
997 field per parameter. The base types of C@t{++} classes are also
998 represented as fields. If the type has no fields, or does not fit
999 into one of these categories, an empty sequence will be returned.
1001 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
1004 This attribute is not available for @code{enum} or @code{static}
1005 (as in C@t{++}) fields. The value is the position, counting
1006 in bits, from the start of the containing type.
1009 This attribute is only available for @code{enum} fields, and its value
1010 is the enumeration member's integer representation.
1013 The name of the field, or @code{None} for anonymous fields.
1016 This is @code{True} if the field is artificial, usually meaning that
1017 it was provided by the compiler and not the user. This attribute is
1018 always provided, and is @code{False} if the field is not artificial.
1021 This is @code{True} if the field represents a base class of a C@t{++}
1022 structure. This attribute is always provided, and is @code{False}
1023 if the field is not a base class of the type that is the argument of
1024 @code{fields}, or if that type was not a C@t{++} class.
1027 If the field is packed, or is a bitfield, then this will have a
1028 non-zero value, which is the size of the field in bits. Otherwise,
1029 this will be zero; in this case the field's size is given by its type.
1032 The type of the field. This is usually an instance of @code{Type},
1033 but it can be @code{None} in some situations.
1036 The type which contains this field. This is an instance of
1041 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
1042 Return a new @code{gdb.Type} object which represents an array of this
1043 type. If one argument is given, it is the inclusive upper bound of
1044 the array; in this case the lower bound is zero. If two arguments are
1045 given, the first argument is the lower bound of the array, and the
1046 second argument is the upper bound of the array. An array's length
1047 must not be negative, but the bounds can be.
1050 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
1051 Return a new @code{gdb.Type} object which represents a vector of this
1052 type. If one argument is given, it is the inclusive upper bound of
1053 the vector; in this case the lower bound is zero. If two arguments are
1054 given, the first argument is the lower bound of the vector, and the
1055 second argument is the upper bound of the vector. A vector's length
1056 must not be negative, but the bounds can be.
1058 The difference between an @code{array} and a @code{vector} is that
1059 arrays behave like in C: when used in expressions they decay to a pointer
1060 to the first element whereas vectors are treated as first class values.
1063 @defun Type.const ()
1064 Return a new @code{gdb.Type} object which represents a
1065 @code{const}-qualified variant of this type.
1068 @defun Type.volatile ()
1069 Return a new @code{gdb.Type} object which represents a
1070 @code{volatile}-qualified variant of this type.
1073 @defun Type.unqualified ()
1074 Return a new @code{gdb.Type} object which represents an unqualified
1075 variant of this type. That is, the result is neither @code{const} nor
1079 @defun Type.range ()
1080 Return a Python @code{Tuple} object that contains two elements: the
1081 low bound of the argument type and the high bound of that type. If
1082 the type does not have a range, @value{GDBN} will raise a
1083 @code{gdb.error} exception (@pxref{Exception Handling}).
1086 @defun Type.reference ()
1087 Return a new @code{gdb.Type} object which represents a reference to this
1091 @defun Type.pointer ()
1092 Return a new @code{gdb.Type} object which represents a pointer to this
1096 @defun Type.strip_typedefs ()
1097 Return a new @code{gdb.Type} that represents the real type,
1098 after removing all layers of typedefs.
1101 @defun Type.target ()
1102 Return a new @code{gdb.Type} object which represents the target type
1105 For a pointer type, the target type is the type of the pointed-to
1106 object. For an array type (meaning C-like arrays), the target type is
1107 the type of the elements of the array. For a function or method type,
1108 the target type is the type of the return value. For a complex type,
1109 the target type is the type of the elements. For a typedef, the
1110 target type is the aliased type.
1112 If the type does not have a target, this method will throw an
1116 @defun Type.template_argument (n @r{[}, block@r{]})
1117 If this @code{gdb.Type} is an instantiation of a template, this will
1118 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1119 value of the @var{n}th template argument (indexed starting at 0).
1121 If this @code{gdb.Type} is not a template type, or if the type has fewer
1122 than @var{n} template arguments, this will throw an exception.
1123 Ordinarily, only C@t{++} code will have template types.
1125 If @var{block} is given, then @var{name} is looked up in that scope.
1126 Otherwise, it is searched for globally.
1129 @defun Type.optimized_out ()
1130 Return @code{gdb.Value} instance of this type whose value is optimized
1131 out. This allows a frame decorator to indicate that the value of an
1132 argument or a local variable is not known.
1135 Each type has a code, which indicates what category this type falls
1136 into. The available type categories are represented by constants
1137 defined in the @code{gdb} module:
1140 @vindex TYPE_CODE_PTR
1141 @item gdb.TYPE_CODE_PTR
1142 The type is a pointer.
1144 @vindex TYPE_CODE_ARRAY
1145 @item gdb.TYPE_CODE_ARRAY
1146 The type is an array.
1148 @vindex TYPE_CODE_STRUCT
1149 @item gdb.TYPE_CODE_STRUCT
1150 The type is a structure.
1152 @vindex TYPE_CODE_UNION
1153 @item gdb.TYPE_CODE_UNION
1154 The type is a union.
1156 @vindex TYPE_CODE_ENUM
1157 @item gdb.TYPE_CODE_ENUM
1158 The type is an enum.
1160 @vindex TYPE_CODE_FLAGS
1161 @item gdb.TYPE_CODE_FLAGS
1162 A bit flags type, used for things such as status registers.
1164 @vindex TYPE_CODE_FUNC
1165 @item gdb.TYPE_CODE_FUNC
1166 The type is a function.
1168 @vindex TYPE_CODE_INT
1169 @item gdb.TYPE_CODE_INT
1170 The type is an integer type.
1172 @vindex TYPE_CODE_FLT
1173 @item gdb.TYPE_CODE_FLT
1174 A floating point type.
1176 @vindex TYPE_CODE_VOID
1177 @item gdb.TYPE_CODE_VOID
1178 The special type @code{void}.
1180 @vindex TYPE_CODE_SET
1181 @item gdb.TYPE_CODE_SET
1184 @vindex TYPE_CODE_RANGE
1185 @item gdb.TYPE_CODE_RANGE
1186 A range type, that is, an integer type with bounds.
1188 @vindex TYPE_CODE_STRING
1189 @item gdb.TYPE_CODE_STRING
1190 A string type. Note that this is only used for certain languages with
1191 language-defined string types; C strings are not represented this way.
1193 @vindex TYPE_CODE_BITSTRING
1194 @item gdb.TYPE_CODE_BITSTRING
1195 A string of bits. It is deprecated.
1197 @vindex TYPE_CODE_ERROR
1198 @item gdb.TYPE_CODE_ERROR
1199 An unknown or erroneous type.
1201 @vindex TYPE_CODE_METHOD
1202 @item gdb.TYPE_CODE_METHOD
1203 A method type, as found in C@t{++}.
1205 @vindex TYPE_CODE_METHODPTR
1206 @item gdb.TYPE_CODE_METHODPTR
1207 A pointer-to-member-function.
1209 @vindex TYPE_CODE_MEMBERPTR
1210 @item gdb.TYPE_CODE_MEMBERPTR
1211 A pointer-to-member.
1213 @vindex TYPE_CODE_REF
1214 @item gdb.TYPE_CODE_REF
1217 @vindex TYPE_CODE_RVALUE_REF
1218 @item gdb.TYPE_CODE_RVALUE_REF
1219 A C@t{++}11 rvalue reference type.
1221 @vindex TYPE_CODE_CHAR
1222 @item gdb.TYPE_CODE_CHAR
1225 @vindex TYPE_CODE_BOOL
1226 @item gdb.TYPE_CODE_BOOL
1229 @vindex TYPE_CODE_COMPLEX
1230 @item gdb.TYPE_CODE_COMPLEX
1231 A complex float type.
1233 @vindex TYPE_CODE_TYPEDEF
1234 @item gdb.TYPE_CODE_TYPEDEF
1235 A typedef to some other type.
1237 @vindex TYPE_CODE_NAMESPACE
1238 @item gdb.TYPE_CODE_NAMESPACE
1239 A C@t{++} namespace.
1241 @vindex TYPE_CODE_DECFLOAT
1242 @item gdb.TYPE_CODE_DECFLOAT
1243 A decimal floating point type.
1245 @vindex TYPE_CODE_INTERNAL_FUNCTION
1246 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1247 A function internal to @value{GDBN}. This is the type used to represent
1248 convenience functions.
1251 Further support for types is provided in the @code{gdb.types}
1252 Python module (@pxref{gdb.types}).
1254 @node Pretty Printing API
1255 @subsubsection Pretty Printing API
1256 @cindex python pretty printing api
1258 An example output is provided (@pxref{Pretty Printing}).
1260 A pretty-printer is just an object that holds a value and implements a
1261 specific interface, defined here.
1263 @defun pretty_printer.children (self)
1264 @value{GDBN} will call this method on a pretty-printer to compute the
1265 children of the pretty-printer's value.
1267 This method must return an object conforming to the Python iterator
1268 protocol. Each item returned by the iterator must be a tuple holding
1269 two elements. The first element is the ``name'' of the child; the
1270 second element is the child's value. The value can be any Python
1271 object which is convertible to a @value{GDBN} value.
1273 This method is optional. If it does not exist, @value{GDBN} will act
1274 as though the value has no children.
1277 @defun pretty_printer.display_hint (self)
1278 The CLI may call this method and use its result to change the
1279 formatting of a value. The result will also be supplied to an MI
1280 consumer as a @samp{displayhint} attribute of the variable being
1283 This method is optional. If it does exist, this method must return a
1286 Some display hints are predefined by @value{GDBN}:
1290 Indicate that the object being printed is ``array-like''. The CLI
1291 uses this to respect parameters such as @code{set print elements} and
1292 @code{set print array}.
1295 Indicate that the object being printed is ``map-like'', and that the
1296 children of this value can be assumed to alternate between keys and
1300 Indicate that the object being printed is ``string-like''. If the
1301 printer's @code{to_string} method returns a Python string of some
1302 kind, then @value{GDBN} will call its internal language-specific
1303 string-printing function to format the string. For the CLI this means
1304 adding quotation marks, possibly escaping some characters, respecting
1305 @code{set print elements}, and the like.
1309 @defun pretty_printer.to_string (self)
1310 @value{GDBN} will call this method to display the string
1311 representation of the value passed to the object's constructor.
1313 When printing from the CLI, if the @code{to_string} method exists,
1314 then @value{GDBN} will prepend its result to the values returned by
1315 @code{children}. Exactly how this formatting is done is dependent on
1316 the display hint, and may change as more hints are added. Also,
1317 depending on the print settings (@pxref{Print Settings}), the CLI may
1318 print just the result of @code{to_string} in a stack trace, omitting
1319 the result of @code{children}.
1321 If this method returns a string, it is printed verbatim.
1323 Otherwise, if this method returns an instance of @code{gdb.Value},
1324 then @value{GDBN} prints this value. This may result in a call to
1325 another pretty-printer.
1327 If instead the method returns a Python value which is convertible to a
1328 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1329 the resulting value. Again, this may result in a call to another
1330 pretty-printer. Python scalars (integers, floats, and booleans) and
1331 strings are convertible to @code{gdb.Value}; other types are not.
1333 Finally, if this method returns @code{None} then no further operations
1334 are peformed in this method and nothing is printed.
1336 If the result is not one of these types, an exception is raised.
1339 @value{GDBN} provides a function which can be used to look up the
1340 default pretty-printer for a @code{gdb.Value}:
1342 @findex gdb.default_visualizer
1343 @defun gdb.default_visualizer (value)
1344 This function takes a @code{gdb.Value} object as an argument. If a
1345 pretty-printer for this value exists, then it is returned. If no such
1346 printer exists, then this returns @code{None}.
1349 @node Selecting Pretty-Printers
1350 @subsubsection Selecting Pretty-Printers
1351 @cindex selecting python pretty-printers
1353 The Python list @code{gdb.pretty_printers} contains an array of
1354 functions or callable objects that have been registered via addition
1355 as a pretty-printer. Printers in this list are called @code{global}
1356 printers, they're available when debugging all inferiors.
1357 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1358 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1361 Each function on these lists is passed a single @code{gdb.Value}
1362 argument and should return a pretty-printer object conforming to the
1363 interface definition above (@pxref{Pretty Printing API}). If a function
1364 cannot create a pretty-printer for the value, it should return
1367 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1368 @code{gdb.Objfile} in the current program space and iteratively calls
1369 each enabled lookup routine in the list for that @code{gdb.Objfile}
1370 until it receives a pretty-printer object.
1371 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1372 searches the pretty-printer list of the current program space,
1373 calling each enabled function until an object is returned.
1374 After these lists have been exhausted, it tries the global
1375 @code{gdb.pretty_printers} list, again calling each enabled function until an
1378 The order in which the objfiles are searched is not specified. For a
1379 given list, functions are always invoked from the head of the list,
1380 and iterated over sequentially until the end of the list, or a printer
1383 For various reasons a pretty-printer may not work.
1384 For example, the underlying data structure may have changed and
1385 the pretty-printer is out of date.
1387 The consequences of a broken pretty-printer are severe enough that
1388 @value{GDBN} provides support for enabling and disabling individual
1389 printers. For example, if @code{print frame-arguments} is on,
1390 a backtrace can become highly illegible if any argument is printed
1391 with a broken printer.
1393 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1394 attribute to the registered function or callable object. If this attribute
1395 is present and its value is @code{False}, the printer is disabled, otherwise
1396 the printer is enabled.
1398 @node Writing a Pretty-Printer
1399 @subsubsection Writing a Pretty-Printer
1400 @cindex writing a pretty-printer
1402 A pretty-printer consists of two parts: a lookup function to detect
1403 if the type is supported, and the printer itself.
1405 Here is an example showing how a @code{std::string} printer might be
1406 written. @xref{Pretty Printing API}, for details on the API this class
1410 class StdStringPrinter(object):
1411 "Print a std::string"
1413 def __init__(self, val):
1416 def to_string(self):
1417 return self.val['_M_dataplus']['_M_p']
1419 def display_hint(self):
1423 And here is an example showing how a lookup function for the printer
1424 example above might be written.
1427 def str_lookup_function(val):
1428 lookup_tag = val.type.tag
1429 if lookup_tag == None:
1431 regex = re.compile("^std::basic_string<char,.*>$")
1432 if regex.match(lookup_tag):
1433 return StdStringPrinter(val)
1437 The example lookup function extracts the value's type, and attempts to
1438 match it to a type that it can pretty-print. If it is a type the
1439 printer can pretty-print, it will return a printer object. If not, it
1440 returns @code{None}.
1442 We recommend that you put your core pretty-printers into a Python
1443 package. If your pretty-printers are for use with a library, we
1444 further recommend embedding a version number into the package name.
1445 This practice will enable @value{GDBN} to load multiple versions of
1446 your pretty-printers at the same time, because they will have
1449 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1450 can be evaluated multiple times without changing its meaning. An
1451 ideal auto-load file will consist solely of @code{import}s of your
1452 printer modules, followed by a call to a register pretty-printers with
1453 the current objfile.
1455 Taken as a whole, this approach will scale nicely to multiple
1456 inferiors, each potentially using a different library version.
1457 Embedding a version number in the Python package name will ensure that
1458 @value{GDBN} is able to load both sets of printers simultaneously.
1459 Then, because the search for pretty-printers is done by objfile, and
1460 because your auto-loaded code took care to register your library's
1461 printers with a specific objfile, @value{GDBN} will find the correct
1462 printers for the specific version of the library used by each
1465 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1466 this code might appear in @code{gdb.libstdcxx.v6}:
1469 def register_printers(objfile):
1470 objfile.pretty_printers.append(str_lookup_function)
1474 And then the corresponding contents of the auto-load file would be:
1477 import gdb.libstdcxx.v6
1478 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1481 The previous example illustrates a basic pretty-printer.
1482 There are a few things that can be improved on.
1483 The printer doesn't have a name, making it hard to identify in a
1484 list of installed printers. The lookup function has a name, but
1485 lookup functions can have arbitrary, even identical, names.
1487 Second, the printer only handles one type, whereas a library typically has
1488 several types. One could install a lookup function for each desired type
1489 in the library, but one could also have a single lookup function recognize
1490 several types. The latter is the conventional way this is handled.
1491 If a pretty-printer can handle multiple data types, then its
1492 @dfn{subprinters} are the printers for the individual data types.
1494 The @code{gdb.printing} module provides a formal way of solving these
1495 problems (@pxref{gdb.printing}).
1496 Here is another example that handles multiple types.
1498 These are the types we are going to pretty-print:
1501 struct foo @{ int a, b; @};
1502 struct bar @{ struct foo x, y; @};
1505 Here are the printers:
1509 """Print a foo object."""
1511 def __init__(self, val):
1514 def to_string(self):
1515 return ("a=<" + str(self.val["a"]) +
1516 "> b=<" + str(self.val["b"]) + ">")
1519 """Print a bar object."""
1521 def __init__(self, val):
1524 def to_string(self):
1525 return ("x=<" + str(self.val["x"]) +
1526 "> y=<" + str(self.val["y"]) + ">")
1529 This example doesn't need a lookup function, that is handled by the
1530 @code{gdb.printing} module. Instead a function is provided to build up
1531 the object that handles the lookup.
1536 def build_pretty_printer():
1537 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1539 pp.add_printer('foo', '^foo$', fooPrinter)
1540 pp.add_printer('bar', '^bar$', barPrinter)
1544 And here is the autoload support:
1549 gdb.printing.register_pretty_printer(
1550 gdb.current_objfile(),
1551 my_library.build_pretty_printer())
1554 Finally, when this printer is loaded into @value{GDBN}, here is the
1555 corresponding output of @samp{info pretty-printer}:
1558 (gdb) info pretty-printer
1565 @node Type Printing API
1566 @subsubsection Type Printing API
1567 @cindex type printing API for Python
1569 @value{GDBN} provides a way for Python code to customize type display.
1570 This is mainly useful for substituting canonical typedef names for
1573 @cindex type printer
1574 A @dfn{type printer} is just a Python object conforming to a certain
1575 protocol. A simple base class implementing the protocol is provided;
1576 see @ref{gdb.types}. A type printer must supply at least:
1578 @defivar type_printer enabled
1579 A boolean which is True if the printer is enabled, and False
1580 otherwise. This is manipulated by the @code{enable type-printer}
1581 and @code{disable type-printer} commands.
1584 @defivar type_printer name
1585 The name of the type printer. This must be a string. This is used by
1586 the @code{enable type-printer} and @code{disable type-printer}
1590 @defmethod type_printer instantiate (self)
1591 This is called by @value{GDBN} at the start of type-printing. It is
1592 only called if the type printer is enabled. This method must return a
1593 new object that supplies a @code{recognize} method, as described below.
1597 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1598 will compute a list of type recognizers. This is done by iterating
1599 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1600 followed by the per-progspace type printers (@pxref{Progspaces In
1601 Python}), and finally the global type printers.
1603 @value{GDBN} will call the @code{instantiate} method of each enabled
1604 type printer. If this method returns @code{None}, then the result is
1605 ignored; otherwise, it is appended to the list of recognizers.
1607 Then, when @value{GDBN} is going to display a type name, it iterates
1608 over the list of recognizers. For each one, it calls the recognition
1609 function, stopping if the function returns a non-@code{None} value.
1610 The recognition function is defined as:
1612 @defmethod type_recognizer recognize (self, type)
1613 If @var{type} is not recognized, return @code{None}. Otherwise,
1614 return a string which is to be printed as the name of @var{type}.
1615 The @var{type} argument will be an instance of @code{gdb.Type}
1616 (@pxref{Types In Python}).
1619 @value{GDBN} uses this two-pass approach so that type printers can
1620 efficiently cache information without holding on to it too long. For
1621 example, it can be convenient to look up type information in a type
1622 printer and hold it for a recognizer's lifetime; if a single pass were
1623 done then type printers would have to make use of the event system in
1624 order to avoid holding information that could become stale as the
1627 @node Frame Filter API
1628 @subsubsection Filtering Frames
1629 @cindex frame filters api
1631 Frame filters are Python objects that manipulate the visibility of a
1632 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1635 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1636 commands (@pxref{GDB/MI}), those that return a collection of frames
1637 are affected. The commands that work with frame filters are:
1639 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1640 @code{-stack-list-frames}
1641 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1642 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1643 -stack-list-variables command}), @code{-stack-list-arguments}
1644 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1645 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1646 -stack-list-locals command}).
1648 A frame filter works by taking an iterator as an argument, applying
1649 actions to the contents of that iterator, and returning another
1650 iterator (or, possibly, the same iterator it was provided in the case
1651 where the filter does not perform any operations). Typically, frame
1652 filters utilize tools such as the Python's @code{itertools} module to
1653 work with and create new iterators from the source iterator.
1654 Regardless of how a filter chooses to apply actions, it must not alter
1655 the underlying @value{GDBN} frame or frames, or attempt to alter the
1656 call-stack within @value{GDBN}. This preserves data integrity within
1657 @value{GDBN}. Frame filters are executed on a priority basis and care
1658 should be taken that some frame filters may have been executed before,
1659 and that some frame filters will be executed after.
1661 An important consideration when designing frame filters, and well
1662 worth reflecting upon, is that frame filters should avoid unwinding
1663 the call stack if possible. Some stacks can run very deep, into the
1664 tens of thousands in some cases. To search every frame when a frame
1665 filter executes may be too expensive at that step. The frame filter
1666 cannot know how many frames it has to iterate over, and it may have to
1667 iterate through them all. This ends up duplicating effort as
1668 @value{GDBN} performs this iteration when it prints the frames. If
1669 the filter can defer unwinding frames until frame decorators are
1670 executed, after the last filter has executed, it should. @xref{Frame
1671 Decorator API}, for more information on decorators. Also, there are
1672 examples for both frame decorators and filters in later chapters.
1673 @xref{Writing a Frame Filter}, for more information.
1675 The Python dictionary @code{gdb.frame_filters} contains key/object
1676 pairings that comprise a frame filter. Frame filters in this
1677 dictionary are called @code{global} frame filters, and they are
1678 available when debugging all inferiors. These frame filters must
1679 register with the dictionary directly. In addition to the
1680 @code{global} dictionary, there are other dictionaries that are loaded
1681 with different inferiors via auto-loading (@pxref{Python
1682 Auto-loading}). The two other areas where frame filter dictionaries
1683 can be found are: @code{gdb.Progspace} which contains a
1684 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1685 object which also contains a @code{frame_filters} dictionary
1688 When a command is executed from @value{GDBN} that is compatible with
1689 frame filters, @value{GDBN} combines the @code{global},
1690 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1691 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1692 several frames, and thus several object files, might be in use.
1693 @value{GDBN} then prunes any frame filter whose @code{enabled}
1694 attribute is @code{False}. This pruned list is then sorted according
1695 to the @code{priority} attribute in each filter.
1697 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1698 creates an iterator which wraps each frame in the call stack in a
1699 @code{FrameDecorator} object, and calls each filter in order. The
1700 output from the previous filter will always be the input to the next
1703 Frame filters have a mandatory interface which each frame filter must
1704 implement, defined here:
1706 @defun FrameFilter.filter (iterator)
1707 @value{GDBN} will call this method on a frame filter when it has
1708 reached the order in the priority list for that filter.
1710 For example, if there are four frame filters:
1721 The order that the frame filters will be called is:
1724 Filter3 -> Filter2 -> Filter1 -> Filter4
1727 Note that the output from @code{Filter3} is passed to the input of
1728 @code{Filter2}, and so on.
1730 This @code{filter} method is passed a Python iterator. This iterator
1731 contains a sequence of frame decorators that wrap each
1732 @code{gdb.Frame}, or a frame decorator that wraps another frame
1733 decorator. The first filter that is executed in the sequence of frame
1734 filters will receive an iterator entirely comprised of default
1735 @code{FrameDecorator} objects. However, after each frame filter is
1736 executed, the previous frame filter may have wrapped some or all of
1737 the frame decorators with their own frame decorator. As frame
1738 decorators must also conform to a mandatory interface, these
1739 decorators can be assumed to act in a uniform manner (@pxref{Frame
1742 This method must return an object conforming to the Python iterator
1743 protocol. Each item in the iterator must be an object conforming to
1744 the frame decorator interface. If a frame filter does not wish to
1745 perform any operations on this iterator, it should return that
1748 This method is not optional. If it does not exist, @value{GDBN} will
1749 raise and print an error.
1752 @defvar FrameFilter.name
1753 The @code{name} attribute must be Python string which contains the
1754 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1755 Management}). This attribute may contain any combination of letters
1756 or numbers. Care should be taken to ensure that it is unique. This
1757 attribute is mandatory.
1760 @defvar FrameFilter.enabled
1761 The @code{enabled} attribute must be Python boolean. This attribute
1762 indicates to @value{GDBN} whether the frame filter is enabled, and
1763 should be considered when frame filters are executed. If
1764 @code{enabled} is @code{True}, then the frame filter will be executed
1765 when any of the backtrace commands detailed earlier in this chapter
1766 are executed. If @code{enabled} is @code{False}, then the frame
1767 filter will not be executed. This attribute is mandatory.
1770 @defvar FrameFilter.priority
1771 The @code{priority} attribute must be Python integer. This attribute
1772 controls the order of execution in relation to other frame filters.
1773 There are no imposed limits on the range of @code{priority} other than
1774 it must be a valid integer. The higher the @code{priority} attribute,
1775 the sooner the frame filter will be executed in relation to other
1776 frame filters. Although @code{priority} can be negative, it is
1777 recommended practice to assume zero is the lowest priority that a
1778 frame filter can be assigned. Frame filters that have the same
1779 priority are executed in unsorted order in that priority slot. This
1780 attribute is mandatory. 100 is a good default priority.
1783 @node Frame Decorator API
1784 @subsubsection Decorating Frames
1785 @cindex frame decorator api
1787 Frame decorators are sister objects to frame filters (@pxref{Frame
1788 Filter API}). Frame decorators are applied by a frame filter and can
1789 only be used in conjunction with frame filters.
1791 The purpose of a frame decorator is to customize the printed content
1792 of each @code{gdb.Frame} in commands where frame filters are executed.
1793 This concept is called decorating a frame. Frame decorators decorate
1794 a @code{gdb.Frame} with Python code contained within each API call.
1795 This separates the actual data contained in a @code{gdb.Frame} from
1796 the decorated data produced by a frame decorator. This abstraction is
1797 necessary to maintain integrity of the data contained in each
1800 Frame decorators have a mandatory interface, defined below.
1802 @value{GDBN} already contains a frame decorator called
1803 @code{FrameDecorator}. This contains substantial amounts of
1804 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
1805 recommended that other frame decorators inherit and extend this
1806 object, and only to override the methods needed.
1808 @tindex gdb.FrameDecorator
1809 @code{FrameDecorator} is defined in the Python module
1810 @code{gdb.FrameDecorator}, so your code can import it like:
1812 from gdb.FrameDecorator import FrameDecorator
1815 @defun FrameDecorator.elided (self)
1817 The @code{elided} method groups frames together in a hierarchical
1818 system. An example would be an interpreter, where multiple low-level
1819 frames make up a single call in the interpreted language. In this
1820 example, the frame filter would elide the low-level frames and present
1821 a single high-level frame, representing the call in the interpreted
1822 language, to the user.
1824 The @code{elided} function must return an iterable and this iterable
1825 must contain the frames that are being elided wrapped in a suitable
1826 frame decorator. If no frames are being elided this function may
1827 return an empty iterable, or @code{None}. Elided frames are indented
1828 from normal frames in a @code{CLI} backtrace, or in the case of
1829 @code{GDB/MI}, are placed in the @code{children} field of the eliding
1832 It is the frame filter's task to also filter out the elided frames from
1833 the source iterator. This will avoid printing the frame twice.
1836 @defun FrameDecorator.function (self)
1838 This method returns the name of the function in the frame that is to
1841 This method must return a Python string describing the function, or
1844 If this function returns @code{None}, @value{GDBN} will not print any
1845 data for this field.
1848 @defun FrameDecorator.address (self)
1850 This method returns the address of the frame that is to be printed.
1852 This method must return a Python numeric integer type of sufficient
1853 size to describe the address of the frame, or @code{None}.
1855 If this function returns a @code{None}, @value{GDBN} will not print
1856 any data for this field.
1859 @defun FrameDecorator.filename (self)
1861 This method returns the filename and path associated with this frame.
1863 This method must return a Python string containing the filename and
1864 the path to the object file backing the frame, or @code{None}.
1866 If this function returns a @code{None}, @value{GDBN} will not print
1867 any data for this field.
1870 @defun FrameDecorator.line (self):
1872 This method returns the line number associated with the current
1873 position within the function addressed by this frame.
1875 This method must return a Python integer type, or @code{None}.
1877 If this function returns a @code{None}, @value{GDBN} will not print
1878 any data for this field.
1881 @defun FrameDecorator.frame_args (self)
1884 This method must return an iterable, or @code{None}. Returning an
1885 empty iterable, or @code{None} means frame arguments will not be
1886 printed for this frame. This iterable must contain objects that
1887 implement two methods, described here.
1889 This object must implement a @code{argument} method which takes a
1890 single @code{self} parameter and must return a @code{gdb.Symbol}
1891 (@pxref{Symbols In Python}), or a Python string. The object must also
1892 implement a @code{value} method which takes a single @code{self}
1893 parameter and must return a @code{gdb.Value} (@pxref{Values From
1894 Inferior}), a Python value, or @code{None}. If the @code{value}
1895 method returns @code{None}, and the @code{argument} method returns a
1896 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
1897 the @code{gdb.Symbol} automatically.
1902 class SymValueWrapper():
1904 def __init__(self, symbol, value):
1914 class SomeFrameDecorator()
1917 def frame_args(self):
1920 block = self.inferior_frame.block()
1924 # Iterate over all symbols in a block. Only add
1925 # symbols that are arguments.
1927 if not sym.is_argument:
1929 args.append(SymValueWrapper(sym,None))
1931 # Add example synthetic argument.
1932 args.append(SymValueWrapper(``foo'', 42))
1938 @defun FrameDecorator.frame_locals (self)
1940 This method must return an iterable or @code{None}. Returning an
1941 empty iterable, or @code{None} means frame local arguments will not be
1942 printed for this frame.
1944 The object interface, the description of the various strategies for
1945 reading frame locals, and the example are largely similar to those
1946 described in the @code{frame_args} function, (@pxref{frame_args,,The
1947 frame filter frame_args function}). Below is a modified example:
1950 class SomeFrameDecorator()
1953 def frame_locals(self):
1956 block = self.inferior_frame.block()
1960 # Iterate over all symbols in a block. Add all
1961 # symbols, except arguments.
1965 vars.append(SymValueWrapper(sym,None))
1967 # Add an example of a synthetic local variable.
1968 vars.append(SymValueWrapper(``bar'', 99))
1974 @defun FrameDecorator.inferior_frame (self):
1976 This method must return the underlying @code{gdb.Frame} that this
1977 frame decorator is decorating. @value{GDBN} requires the underlying
1978 frame for internal frame information to determine how to print certain
1979 values when printing a frame.
1982 @node Writing a Frame Filter
1983 @subsubsection Writing a Frame Filter
1984 @cindex writing a frame filter
1986 There are three basic elements that a frame filter must implement: it
1987 must correctly implement the documented interface (@pxref{Frame Filter
1988 API}), it must register itself with @value{GDBN}, and finally, it must
1989 decide if it is to work on the data provided by @value{GDBN}. In all
1990 cases, whether it works on the iterator or not, each frame filter must
1991 return an iterator. A bare-bones frame filter follows the pattern in
1992 the following example.
1997 class FrameFilter():
2000 # Frame filter attribute creation.
2002 # 'name' is the name of the filter that GDB will display.
2004 # 'priority' is the priority of the filter relative to other
2007 # 'enabled' is a boolean that indicates whether this filter is
2008 # enabled and should be executed.
2014 # Register this frame filter with the global frame_filters
2016 gdb.frame_filters[self.name] = self
2018 def filter(self, frame_iter):
2019 # Just return the iterator.
2023 The frame filter in the example above implements the three
2024 requirements for all frame filters. It implements the API, self
2025 registers, and makes a decision on the iterator (in this case, it just
2026 returns the iterator untouched).
2028 The first step is attribute creation and assignment, and as shown in
2029 the comments the filter assigns the following attributes: @code{name},
2030 @code{priority} and whether the filter should be enabled with the
2031 @code{enabled} attribute.
2033 The second step is registering the frame filter with the dictionary or
2034 dictionaries that the frame filter has interest in. As shown in the
2035 comments, this filter just registers itself with the global dictionary
2036 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
2037 is a dictionary that is initialized in the @code{gdb} module when
2038 @value{GDBN} starts. What dictionary a filter registers with is an
2039 important consideration. Generally, if a filter is specific to a set
2040 of code, it should be registered either in the @code{objfile} or
2041 @code{progspace} dictionaries as they are specific to the program
2042 currently loaded in @value{GDBN}. The global dictionary is always
2043 present in @value{GDBN} and is never unloaded. Any filters registered
2044 with the global dictionary will exist until @value{GDBN} exits. To
2045 avoid filters that may conflict, it is generally better to register
2046 frame filters against the dictionaries that more closely align with
2047 the usage of the filter currently in question. @xref{Python
2048 Auto-loading}, for further information on auto-loading Python scripts.
2050 @value{GDBN} takes a hands-off approach to frame filter registration,
2051 therefore it is the frame filter's responsibility to ensure
2052 registration has occurred, and that any exceptions are handled
2053 appropriately. In particular, you may wish to handle exceptions
2054 relating to Python dictionary key uniqueness. It is mandatory that
2055 the dictionary key is the same as frame filter's @code{name}
2056 attribute. When a user manages frame filters (@pxref{Frame Filter
2057 Management}), the names @value{GDBN} will display are those contained
2058 in the @code{name} attribute.
2060 The final step of this example is the implementation of the
2061 @code{filter} method. As shown in the example comments, we define the
2062 @code{filter} method and note that the method must take an iterator,
2063 and also must return an iterator. In this bare-bones example, the
2064 frame filter is not very useful as it just returns the iterator
2065 untouched. However this is a valid operation for frame filters that
2066 have the @code{enabled} attribute set, but decide not to operate on
2069 In the next example, the frame filter operates on all frames and
2070 utilizes a frame decorator to perform some work on the frames.
2071 @xref{Frame Decorator API}, for further information on the frame
2072 decorator interface.
2074 This example works on inlined frames. It highlights frames which are
2075 inlined by tagging them with an ``[inlined]'' tag. By applying a
2076 frame decorator to all frames with the Python @code{itertools imap}
2077 method, the example defers actions to the frame decorator. Frame
2078 decorators are only processed when @value{GDBN} prints the backtrace.
2080 This introduces a new decision making topic: whether to perform
2081 decision making operations at the filtering step, or at the printing
2082 step. In this example's approach, it does not perform any filtering
2083 decisions at the filtering step beyond mapping a frame decorator to
2084 each frame. This allows the actual decision making to be performed
2085 when each frame is printed. This is an important consideration, and
2086 well worth reflecting upon when designing a frame filter. An issue
2087 that frame filters should avoid is unwinding the stack if possible.
2088 Some stacks can run very deep, into the tens of thousands in some
2089 cases. To search every frame to determine if it is inlined ahead of
2090 time may be too expensive at the filtering step. The frame filter
2091 cannot know how many frames it has to iterate over, and it would have
2092 to iterate through them all. This ends up duplicating effort as
2093 @value{GDBN} performs this iteration when it prints the frames.
2095 In this example decision making can be deferred to the printing step.
2096 As each frame is printed, the frame decorator can examine each frame
2097 in turn when @value{GDBN} iterates. From a performance viewpoint,
2098 this is the most appropriate decision to make as it avoids duplicating
2099 the effort that the printing step would undertake anyway. Also, if
2100 there are many frame filters unwinding the stack during filtering, it
2101 can substantially delay the printing of the backtrace which will
2102 result in large memory usage, and a poor user experience.
2105 class InlineFilter():
2108 self.name = "InlinedFrameFilter"
2111 gdb.frame_filters[self.name] = self
2113 def filter(self, frame_iter):
2114 frame_iter = itertools.imap(InlinedFrameDecorator,
2119 This frame filter is somewhat similar to the earlier example, except
2120 that the @code{filter} method applies a frame decorator object called
2121 @code{InlinedFrameDecorator} to each element in the iterator. The
2122 @code{imap} Python method is light-weight. It does not proactively
2123 iterate over the iterator, but rather creates a new iterator which
2124 wraps the existing one.
2126 Below is the frame decorator for this example.
2129 class InlinedFrameDecorator(FrameDecorator):
2131 def __init__(self, fobj):
2132 super(InlinedFrameDecorator, self).__init__(fobj)
2135 frame = fobj.inferior_frame()
2136 name = str(frame.name())
2138 if frame.type() == gdb.INLINE_FRAME:
2139 name = name + " [inlined]"
2144 This frame decorator only defines and overrides the @code{function}
2145 method. It lets the supplied @code{FrameDecorator}, which is shipped
2146 with @value{GDBN}, perform the other work associated with printing
2149 The combination of these two objects create this output from a
2153 #0 0x004004e0 in bar () at inline.c:11
2154 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2155 #2 0x00400566 in main () at inline.c:31
2158 So in the case of this example, a frame decorator is applied to all
2159 frames, regardless of whether they may be inlined or not. As
2160 @value{GDBN} iterates over the iterator produced by the frame filters,
2161 @value{GDBN} executes each frame decorator which then makes a decision
2162 on what to print in the @code{function} callback. Using a strategy
2163 like this is a way to defer decisions on the frame content to printing
2166 @subheading Eliding Frames
2168 It might be that the above example is not desirable for representing
2169 inlined frames, and a hierarchical approach may be preferred. If we
2170 want to hierarchically represent frames, the @code{elided} frame
2171 decorator interface might be preferable.
2173 This example approaches the issue with the @code{elided} method. This
2174 example is quite long, but very simplistic. It is out-of-scope for
2175 this section to write a complete example that comprehensively covers
2176 all approaches of finding and printing inlined frames. However, this
2177 example illustrates the approach an author might use.
2179 This example comprises of three sections.
2182 class InlineFrameFilter():
2185 self.name = "InlinedFrameFilter"
2188 gdb.frame_filters[self.name] = self
2190 def filter(self, frame_iter):
2191 return ElidingInlineIterator(frame_iter)
2194 This frame filter is very similar to the other examples. The only
2195 difference is this frame filter is wrapping the iterator provided to
2196 it (@code{frame_iter}) with a custom iterator called
2197 @code{ElidingInlineIterator}. This again defers actions to when
2198 @value{GDBN} prints the backtrace, as the iterator is not traversed
2201 The iterator for this example is as follows. It is in this section of
2202 the example where decisions are made on the content of the backtrace.
2205 class ElidingInlineIterator:
2206 def __init__(self, ii):
2207 self.input_iterator = ii
2213 frame = next(self.input_iterator)
2215 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2219 eliding_frame = next(self.input_iterator)
2220 except StopIteration:
2222 return ElidingFrameDecorator(eliding_frame, [frame])
2225 This iterator implements the Python iterator protocol. When the
2226 @code{next} function is called (when @value{GDBN} prints each frame),
2227 the iterator checks if this frame decorator, @code{frame}, is wrapping
2228 an inlined frame. If it is not, it returns the existing frame decorator
2229 untouched. If it is wrapping an inlined frame, it assumes that the
2230 inlined frame was contained within the next oldest frame,
2231 @code{eliding_frame}, which it fetches. It then creates and returns a
2232 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2233 elided frame, and the eliding frame.
2236 class ElidingInlineDecorator(FrameDecorator):
2238 def __init__(self, frame, elided_frames):
2239 super(ElidingInlineDecorator, self).__init__(frame)
2241 self.elided_frames = elided_frames
2244 return iter(self.elided_frames)
2247 This frame decorator overrides one function and returns the inlined
2248 frame in the @code{elided} method. As before it lets
2249 @code{FrameDecorator} do the rest of the work involved in printing
2250 this frame. This produces the following output.
2253 #0 0x004004e0 in bar () at inline.c:11
2254 #2 0x00400529 in main () at inline.c:25
2255 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2258 In that output, @code{max} which has been inlined into @code{main} is
2259 printed hierarchically. Another approach would be to combine the
2260 @code{function} method, and the @code{elided} method to both print a
2261 marker in the inlined frame, and also show the hierarchical
2264 @node Unwinding Frames in Python
2265 @subsubsection Unwinding Frames in Python
2266 @cindex unwinding frames in Python
2268 In @value{GDBN} terminology ``unwinding'' is the process of finding
2269 the previous frame (that is, caller's) from the current one. An
2270 unwinder has three methods. The first one checks if it can handle
2271 given frame (``sniff'' it). For the frames it can sniff an unwinder
2272 provides two additional methods: it can return frame's ID, and it can
2273 fetch registers from the previous frame. A running @value{GDBN}
2274 mantains a list of the unwinders and calls each unwinder's sniffer in
2275 turn until it finds the one that recognizes the current frame. There
2276 is an API to register an unwinder.
2278 The unwinders that come with @value{GDBN} handle standard frames.
2279 However, mixed language applications (for example, an application
2280 running Java Virtual Machine) sometimes use frame layouts that cannot
2281 be handled by the @value{GDBN} unwinders. You can write Python code
2282 that can handle such custom frames.
2284 You implement a frame unwinder in Python as a class with which has two
2285 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2286 a single method @code{__call__}, which examines a given frame and
2287 returns an object (an instance of @code{gdb.UnwindInfo class)}
2288 describing it. If an unwinder does not recognize a frame, it should
2289 return @code{None}. The code in @value{GDBN} that enables writing
2290 unwinders in Python uses this object to return frame's ID and previous
2291 frame registers when @value{GDBN} core asks for them.
2293 An unwinder should do as little work as possible. Some otherwise
2294 innocuous operations can cause problems (even crashes, as this code is
2295 not not well-hardened yet). For example, making an inferior call from
2296 an unwinder is unadvisable, as an inferior call will reset
2297 @value{GDBN}'s stack unwinding process, potentially causing re-entrant
2300 @subheading Unwinder Input
2302 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2303 provides a method to read frame's registers:
2305 @defun PendingFrame.read_register (reg)
2306 This method returns the contents of the register @var{reg} in the
2307 frame as a @code{gdb.Value} object. @var{reg} can be either a
2308 register number or a register name; the values are platform-specific.
2309 They are usually found in the corresponding
2310 @file{@var{platform}-tdep.h} file in the @value{GDBN} source tree. If
2311 @var{reg} does not name a register for the current architecture, this
2312 method will throw an exception.
2314 Note that this method will always return a @code{gdb.Value} for a
2315 valid register name. This does not mean that the value will be valid.
2316 For example, you may request a register that an earlier unwinder could
2317 not unwind---the value will be unavailable. Instead, the
2318 @code{gdb.Value} returned from this method will be lazy; that is, its
2319 underlying bits will not be fetched until it is first used. So,
2320 attempting to use such a value will cause an exception at the point of
2323 The type of the returned @code{gdb.Value} depends on the register and
2324 the architecture. It is common for registers to have a scalar type,
2325 like @code{long long}; but many other types are possible, such as
2326 pointer, pointer-to-function, floating point or vector types.
2329 It also provides a factory method to create a @code{gdb.UnwindInfo}
2330 instance to be returned to @value{GDBN}:
2332 @defun PendingFrame.create_unwind_info (frame_id)
2333 Returns a new @code{gdb.UnwindInfo} instance identified by given
2334 @var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2335 using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2336 determine which function will be used, as follows:
2340 The frame is identified by the given stack address and PC. The stack
2341 address must be chosen so that it is constant throughout the lifetime
2342 of the frame, so a typical choice is the value of the stack pointer at
2343 the start of the function---in the DWARF standard, this would be the
2344 ``Call Frame Address''.
2346 This is the most common case by far. The other cases are documented
2347 for completeness but are only useful in specialized situations.
2349 @item sp, pc, special
2350 The frame is identified by the stack address, the PC, and a
2351 ``special'' address. The special address is used on architectures
2352 that can have frames that do not change the stack, but which are still
2353 distinct, for example the IA-64, which has a second stack for
2354 registers. Both @var{sp} and @var{special} must be constant
2355 throughout the lifetime of the frame.
2358 The frame is identified by the stack address only. Any other stack
2359 frame with a matching @var{sp} will be considered to match this frame.
2360 Inside gdb, this is called a ``wild frame''. You will never need
2364 Each attribute value should be an instance of @code{gdb.Value}.
2368 @subheading Unwinder Output: UnwindInfo
2370 Use @code{PendingFrame.create_unwind_info} method described above to
2371 create a @code{gdb.UnwindInfo} instance. Use the following method to
2372 specify caller registers that have been saved in this frame:
2374 @defun gdb.UnwindInfo.add_saved_register (reg, value)
2375 @var{reg} identifies the register. It can be a number or a name, just
2376 as for the @code{PendingFrame.read_register} method above.
2377 @var{value} is a register value (a @code{gdb.Value} object).
2380 @subheading Unwinder Skeleton Code
2382 @value{GDBN} comes with the module containing the base @code{Unwinder}
2383 class. Derive your unwinder class from it and structure the code as
2387 from gdb.unwinders import Unwinder
2389 class FrameId(object):
2390 def __init__(self, sp, pc):
2395 class MyUnwinder(Unwinder):
2397 supe(MyUnwinder, self).__init___(<expects unwinder name argument>)
2399 def __call__(pending_frame):
2400 if not <we recognize frame>:
2402 # Create UnwindInfo. Usually the frame is identified by the stack
2403 # pointer and the program counter.
2404 sp = pending_frame.read_register(<SP number>)
2405 pc = pending_frame.read_register(<PC number>)
2406 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2408 # Find the values of the registers in the caller's frame and
2409 # save them in the result:
2410 unwind_info.add_saved_register(<register>, <value>)
2413 # Return the result:
2418 @subheading Registering a Unwinder
2420 An object file, a program space, and the @value{GDBN} proper can have
2421 unwinders registered with it.
2423 The @code{gdb.unwinders} module provides the function to register a
2426 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2427 @var{locus} is specifies an object file or a program space to which
2428 @var{unwinder} is added. Passing @code{None} or @code{gdb} adds
2429 @var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
2430 added @var{unwinder} will be called before any other unwinder from the
2431 same locus. Two unwinders in the same locus cannot have the same
2432 name. An attempt to add a unwinder with already existing name raises
2433 an exception unless @var{replace} is @code{True}, in which case the
2434 old unwinder is deleted.
2437 @subheading Unwinder Precedence
2439 @value{GDBN} first calls the unwinders from all the object files in no
2440 particular order, then the unwinders from the current program space,
2441 and finally the unwinders from @value{GDBN}.
2443 @node Xmethods In Python
2444 @subsubsection Xmethods In Python
2445 @cindex xmethods in Python
2447 @dfn{Xmethods} are additional methods or replacements for existing
2448 methods of a C@t{++} class. This feature is useful for those cases
2449 where a method defined in C@t{++} source code could be inlined or
2450 optimized out by the compiler, making it unavailable to @value{GDBN}.
2451 For such cases, one can define an xmethod to serve as a replacement
2452 for the method defined in the C@t{++} source code. @value{GDBN} will
2453 then invoke the xmethod, instead of the C@t{++} method, to
2454 evaluate expressions. One can also use xmethods when debugging
2455 with core files. Moreover, when debugging live programs, invoking an
2456 xmethod need not involve running the inferior (which can potentially
2457 perturb its state). Hence, even if the C@t{++} method is available, it
2458 is better to use its replacement xmethod if one is defined.
2460 The xmethods feature in Python is available via the concepts of an
2461 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2462 implement an xmethod, one has to implement a matcher and a
2463 corresponding worker for it (more than one worker can be
2464 implemented, each catering to a different overloaded instance of the
2465 method). Internally, @value{GDBN} invokes the @code{match} method of a
2466 matcher to match the class type and method name. On a match, the
2467 @code{match} method returns a list of matching @emph{worker} objects.
2468 Each worker object typically corresponds to an overloaded instance of
2469 the xmethod. They implement a @code{get_arg_types} method which
2470 returns a sequence of types corresponding to the arguments the xmethod
2471 requires. @value{GDBN} uses this sequence of types to perform
2472 overload resolution and picks a winning xmethod worker. A winner
2473 is also selected from among the methods @value{GDBN} finds in the
2474 C@t{++} source code. Next, the winning xmethod worker and the
2475 winning C@t{++} method are compared to select an overall winner. In
2476 case of a tie between a xmethod worker and a C@t{++} method, the
2477 xmethod worker is selected as the winner. That is, if a winning
2478 xmethod worker is found to be equivalent to the winning C@t{++}
2479 method, then the xmethod worker is treated as a replacement for
2480 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2481 method. If the winning xmethod worker is the overall winner, then
2482 the corresponding xmethod is invoked via the @code{__call__} method
2483 of the worker object.
2485 If one wants to implement an xmethod as a replacement for an
2486 existing C@t{++} method, then they have to implement an equivalent
2487 xmethod which has exactly the same name and takes arguments of
2488 exactly the same type as the C@t{++} method. If the user wants to
2489 invoke the C@t{++} method even though a replacement xmethod is
2490 available for that method, then they can disable the xmethod.
2492 @xref{Xmethod API}, for API to implement xmethods in Python.
2493 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2496 @subsubsection Xmethod API
2499 The @value{GDBN} Python API provides classes, interfaces and functions
2500 to implement, register and manipulate xmethods.
2501 @xref{Xmethods In Python}.
2503 An xmethod matcher should be an instance of a class derived from
2504 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2505 object with similar interface and attributes. An instance of
2506 @code{XMethodMatcher} has the following attributes:
2509 The name of the matcher.
2513 A boolean value indicating whether the matcher is enabled or disabled.
2517 A list of named methods managed by the matcher. Each object in the list
2518 is an instance of the class @code{XMethod} defined in the module
2519 @code{gdb.xmethod}, or any object with the following attributes:
2524 Name of the xmethod which should be unique for each xmethod
2525 managed by the matcher.
2528 A boolean value indicating whether the xmethod is enabled or
2533 The class @code{XMethod} is a convenience class with same
2534 attributes as above along with the following constructor:
2536 @defun XMethod.__init__ (self, name)
2537 Constructs an enabled xmethod with name @var{name}.
2542 The @code{XMethodMatcher} class has the following methods:
2544 @defun XMethodMatcher.__init__ (self, name)
2545 Constructs an enabled xmethod matcher with name @var{name}. The
2546 @code{methods} attribute is initialized to @code{None}.
2549 @defun XMethodMatcher.match (self, class_type, method_name)
2550 Derived classes should override this method. It should return a
2551 xmethod worker object (or a sequence of xmethod worker
2552 objects) matching the @var{class_type} and @var{method_name}.
2553 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2554 is a string value. If the matcher manages named methods as listed in
2555 its @code{methods} attribute, then only those worker objects whose
2556 corresponding entries in the @code{methods} list are enabled should be
2560 An xmethod worker should be an instance of a class derived from
2561 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
2562 or support the following interface:
2564 @defun XMethodWorker.get_arg_types (self)
2565 This method returns a sequence of @code{gdb.Type} objects corresponding
2566 to the arguments that the xmethod takes. It can return an empty
2567 sequence or @code{None} if the xmethod does not take any arguments.
2568 If the xmethod takes a single argument, then a single
2569 @code{gdb.Type} object corresponding to it can be returned.
2572 @defun XMethodWorker.get_result_type (self, *args)
2573 This method returns a @code{gdb.Type} object representing the type
2574 of the result of invoking this xmethod.
2575 The @var{args} argument is the same tuple of arguments that would be
2576 passed to the @code{__call__} method of this worker.
2579 @defun XMethodWorker.__call__ (self, *args)
2580 This is the method which does the @emph{work} of the xmethod. The
2581 @var{args} arguments is the tuple of arguments to the xmethod. Each
2582 element in this tuple is a gdb.Value object. The first element is
2583 always the @code{this} pointer value.
2586 For @value{GDBN} to lookup xmethods, the xmethod matchers
2587 should be registered using the following function defined in the module
2590 @defun register_xmethod_matcher (locus, matcher, replace=False)
2591 The @code{matcher} is registered with @code{locus}, replacing an
2592 existing matcher with the same name as @code{matcher} if
2593 @code{replace} is @code{True}. @code{locus} can be a
2594 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
2595 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
2596 @code{None}. If it is @code{None}, then @code{matcher} is registered
2600 @node Writing an Xmethod
2601 @subsubsection Writing an Xmethod
2602 @cindex writing xmethods in Python
2604 Implementing xmethods in Python will require implementing xmethod
2605 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2606 the following C@t{++} class:
2612 MyClass (int a) : a_(a) @{ @}
2614 int geta (void) @{ return a_; @}
2615 int operator+ (int b);
2622 MyClass::operator+ (int b)
2629 Let us define two xmethods for the class @code{MyClass}, one
2630 replacing the method @code{geta}, and another adding an overloaded
2631 flavor of @code{operator+} which takes a @code{MyClass} argument (the
2632 C@t{++} code above already has an overloaded @code{operator+}
2633 which takes an @code{int} argument). The xmethod matcher can be
2637 class MyClass_geta(gdb.xmethod.XMethod):
2639 gdb.xmethod.XMethod.__init__(self, 'geta')
2641 def get_worker(self, method_name):
2642 if method_name == 'geta':
2643 return MyClassWorker_geta()
2646 class MyClass_sum(gdb.xmethod.XMethod):
2648 gdb.xmethod.XMethod.__init__(self, 'sum')
2650 def get_worker(self, method_name):
2651 if method_name == 'operator+':
2652 return MyClassWorker_plus()
2655 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2657 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2658 # List of methods 'managed' by this matcher
2659 self.methods = [MyClass_geta(), MyClass_sum()]
2661 def match(self, class_type, method_name):
2662 if class_type.tag != 'MyClass':
2665 for method in self.methods:
2667 worker = method.get_worker(method_name)
2669 workers.append(worker)
2675 Notice that the @code{match} method of @code{MyClassMatcher} returns
2676 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
2677 method, and a worker object of type @code{MyClassWorker_plus} for the
2678 @code{operator+} method. This is done indirectly via helper classes
2679 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
2680 @code{methods} attribute in a matcher as it is optional. However, if a
2681 matcher manages more than one xmethod, it is a good practice to list the
2682 xmethods in the @code{methods} attribute of the matcher. This will then
2683 facilitate enabling and disabling individual xmethods via the
2684 @code{enable/disable} commands. Notice also that a worker object is
2685 returned only if the corresponding entry in the @code{methods} attribute
2686 of the matcher is enabled.
2688 The implementation of the worker classes returned by the matcher setup
2689 above is as follows:
2692 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
2693 def get_arg_types(self):
2696 def get_result_type(self, obj):
2697 return gdb.lookup_type('int')
2699 def __call__(self, obj):
2703 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
2704 def get_arg_types(self):
2705 return gdb.lookup_type('MyClass')
2707 def get_result_type(self, obj):
2708 return gdb.lookup_type('int')
2710 def __call__(self, obj, other):
2711 return obj['a_'] + other['a_']
2714 For @value{GDBN} to actually lookup a xmethod, it has to be
2715 registered with it. The matcher defined above is registered with
2716 @value{GDBN} globally as follows:
2719 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
2722 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
2730 then, after loading the Python script defining the xmethod matchers
2731 and workers into @code{GDBN}, invoking the method @code{geta} or using
2732 the operator @code{+} on @code{obj} will invoke the xmethods
2743 Consider another example with a C++ template class:
2750 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
2751 ~MyTemplate () @{ delete [] data_; @}
2753 int footprint (void)
2755 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
2764 Let us implement an xmethod for the above class which serves as a
2765 replacement for the @code{footprint} method. The full code listing
2766 of the xmethod workers and xmethod matchers is as follows:
2769 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
2770 def __init__(self, class_type):
2771 self.class_type = class_type
2773 def get_arg_types(self):
2776 def get_result_type(self):
2777 return gdb.lookup_type('int')
2779 def __call__(self, obj):
2780 return (self.class_type.sizeof +
2782 self.class_type.template_argument(0).sizeof)
2785 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
2787 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
2789 def match(self, class_type, method_name):
2790 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
2792 method_name == 'footprint'):
2793 return MyTemplateWorker_footprint(class_type)
2796 Notice that, in this example, we have not used the @code{methods}
2797 attribute of the matcher as the matcher manages only one xmethod. The
2798 user can enable/disable this xmethod by enabling/disabling the matcher
2801 @node Inferiors In Python
2802 @subsubsection Inferiors In Python
2803 @cindex inferiors in Python
2805 @findex gdb.Inferior
2806 Programs which are being run under @value{GDBN} are called inferiors
2807 (@pxref{Inferiors and Programs}). Python scripts can access
2808 information about and manipulate inferiors controlled by @value{GDBN}
2809 via objects of the @code{gdb.Inferior} class.
2811 The following inferior-related functions are available in the @code{gdb}
2814 @defun gdb.inferiors ()
2815 Return a tuple containing all inferior objects.
2818 @defun gdb.selected_inferior ()
2819 Return an object representing the current inferior.
2822 A @code{gdb.Inferior} object has the following attributes:
2824 @defvar Inferior.num
2825 ID of inferior, as assigned by GDB.
2828 @defvar Inferior.pid
2829 Process ID of the inferior, as assigned by the underlying operating
2833 @defvar Inferior.was_attached
2834 Boolean signaling whether the inferior was created using `attach', or
2835 started by @value{GDBN} itself.
2838 A @code{gdb.Inferior} object has the following methods:
2840 @defun Inferior.is_valid ()
2841 Returns @code{True} if the @code{gdb.Inferior} object is valid,
2842 @code{False} if not. A @code{gdb.Inferior} object will become invalid
2843 if the inferior no longer exists within @value{GDBN}. All other
2844 @code{gdb.Inferior} methods will throw an exception if it is invalid
2845 at the time the method is called.
2848 @defun Inferior.threads ()
2849 This method returns a tuple holding all the threads which are valid
2850 when it is called. If there are no valid threads, the method will
2851 return an empty tuple.
2854 @findex Inferior.read_memory
2855 @defun Inferior.read_memory (address, length)
2856 Read @var{length} addressable memory units from the inferior, starting at
2857 @var{address}. Returns a buffer object, which behaves much like an array
2858 or a string. It can be modified and given to the
2859 @code{Inferior.write_memory} function. In Python 3, the return
2860 value is a @code{memoryview} object.
2863 @findex Inferior.write_memory
2864 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
2865 Write the contents of @var{buffer} to the inferior, starting at
2866 @var{address}. The @var{buffer} parameter must be a Python object
2867 which supports the buffer protocol, i.e., a string, an array or the
2868 object returned from @code{Inferior.read_memory}. If given, @var{length}
2869 determines the number of addressable memory units from @var{buffer} to be
2873 @findex gdb.search_memory
2874 @defun Inferior.search_memory (address, length, pattern)
2875 Search a region of the inferior memory starting at @var{address} with
2876 the given @var{length} using the search pattern supplied in
2877 @var{pattern}. The @var{pattern} parameter must be a Python object
2878 which supports the buffer protocol, i.e., a string, an array or the
2879 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
2880 containing the address where the pattern was found, or @code{None} if
2881 the pattern could not be found.
2884 @findex Inferior.thread_from_thread_handle
2885 @defun Inferior.thread_from_thread_handle (thread_handle)
2886 Return the thread object corresponding to @var{thread_handle}, a thread
2887 library specific data structure such as @code{pthread_t} for pthreads
2888 library implementations.
2891 @node Events In Python
2892 @subsubsection Events In Python
2893 @cindex inferior events in Python
2895 @value{GDBN} provides a general event facility so that Python code can be
2896 notified of various state changes, particularly changes that occur in
2899 An @dfn{event} is just an object that describes some state change. The
2900 type of the object and its attributes will vary depending on the details
2901 of the change. All the existing events are described below.
2903 In order to be notified of an event, you must register an event handler
2904 with an @dfn{event registry}. An event registry is an object in the
2905 @code{gdb.events} module which dispatches particular events. A registry
2906 provides methods to register and unregister event handlers:
2908 @defun EventRegistry.connect (object)
2909 Add the given callable @var{object} to the registry. This object will be
2910 called when an event corresponding to this registry occurs.
2913 @defun EventRegistry.disconnect (object)
2914 Remove the given @var{object} from the registry. Once removed, the object
2915 will no longer receive notifications of events.
2921 def exit_handler (event):
2922 print "event type: exit"
2923 print "exit code: %d" % (event.exit_code)
2925 gdb.events.exited.connect (exit_handler)
2928 In the above example we connect our handler @code{exit_handler} to the
2929 registry @code{events.exited}. Once connected, @code{exit_handler} gets
2930 called when the inferior exits. The argument @dfn{event} in this example is
2931 of type @code{gdb.ExitedEvent}. As you can see in the example the
2932 @code{ExitedEvent} object has an attribute which indicates the exit code of
2935 The following is a listing of the event registries that are available and
2936 details of the events they emit:
2941 Emits @code{gdb.ThreadEvent}.
2943 Some events can be thread specific when @value{GDBN} is running in non-stop
2944 mode. When represented in Python, these events all extend
2945 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
2946 events which are emitted by this or other modules might extend this event.
2947 Examples of these events are @code{gdb.BreakpointEvent} and
2948 @code{gdb.ContinueEvent}.
2950 @defvar ThreadEvent.inferior_thread
2951 In non-stop mode this attribute will be set to the specific thread which was
2952 involved in the emitted event. Otherwise, it will be set to @code{None}.
2955 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
2957 This event indicates that the inferior has been continued after a stop. For
2958 inherited attribute refer to @code{gdb.ThreadEvent} above.
2961 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
2962 @code{events.ExitedEvent} has two attributes:
2963 @defvar ExitedEvent.exit_code
2964 An integer representing the exit code, if available, which the inferior
2965 has returned. (The exit code could be unavailable if, for example,
2966 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
2967 the attribute does not exist.
2969 @defvar ExitedEvent.inferior
2970 A reference to the inferior which triggered the @code{exited} event.
2974 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
2976 Indicates that the inferior has stopped. All events emitted by this registry
2977 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
2978 will indicate the stopped thread when @value{GDBN} is running in non-stop
2979 mode. Refer to @code{gdb.ThreadEvent} above for more details.
2981 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
2983 This event indicates that the inferior or one of its threads has received as
2984 signal. @code{gdb.SignalEvent} has the following attributes:
2986 @defvar SignalEvent.stop_signal
2987 A string representing the signal received by the inferior. A list of possible
2988 signal values can be obtained by running the command @code{info signals} in
2989 the @value{GDBN} command prompt.
2992 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
2994 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
2995 been hit, and has the following attributes:
2997 @defvar BreakpointEvent.breakpoints
2998 A sequence containing references to all the breakpoints (type
2999 @code{gdb.Breakpoint}) that were hit.
3000 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
3002 @defvar BreakpointEvent.breakpoint
3003 A reference to the first breakpoint that was hit.
3004 This function is maintained for backward compatibility and is now deprecated
3005 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
3008 @item events.new_objfile
3009 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
3010 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
3012 @defvar NewObjFileEvent.new_objfile
3013 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
3014 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
3017 @item events.clear_objfiles
3018 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
3019 files for a program space has been reset.
3020 @code{gdb.ClearObjFilesEvent} has one attribute:
3022 @defvar ClearObjFilesEvent.progspace
3023 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
3024 been cleared. @xref{Progspaces In Python}.
3027 @item events.inferior_call
3028 Emits events just before and after a function in the inferior is
3029 called by @value{GDBN}. Before an inferior call, this emits an event
3030 of type @code{gdb.InferiorCallPreEvent}, and after an inferior call,
3031 this emits an event of type @code{gdb.InferiorCallPostEvent}.
3034 @tindex gdb.InferiorCallPreEvent
3035 @item @code{gdb.InferiorCallPreEvent}
3036 Indicates that a function in the inferior is about to be called.
3038 @defvar InferiorCallPreEvent.ptid
3039 The thread in which the call will be run.
3042 @defvar InferiorCallPreEvent.address
3043 The location of the function to be called.
3046 @tindex gdb.InferiorCallPostEvent
3047 @item @code{gdb.InferiorCallPostEvent}
3048 Indicates that a function in the inferior has just been called.
3050 @defvar InferiorCallPostEvent.ptid
3051 The thread in which the call was run.
3054 @defvar InferiorCallPostEvent.address
3055 The location of the function that was called.
3059 @item events.memory_changed
3060 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
3061 inferior has been modified by the @value{GDBN} user, for instance via a
3062 command like @w{@code{set *addr = value}}. The event has the following
3065 @defvar MemoryChangedEvent.address
3066 The start address of the changed region.
3069 @defvar MemoryChangedEvent.length
3070 Length in bytes of the changed region.
3073 @item events.register_changed
3074 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
3075 inferior has been modified by the @value{GDBN} user.
3077 @defvar RegisterChangedEvent.frame
3078 A gdb.Frame object representing the frame in which the register was modified.
3080 @defvar RegisterChangedEvent.regnum
3081 Denotes which register was modified.
3084 @item events.breakpoint_created
3085 This is emitted when a new breakpoint has been created. The argument
3086 that is passed is the new @code{gdb.Breakpoint} object.
3088 @item events.breakpoint_modified
3089 This is emitted when a breakpoint has been modified in some way. The
3090 argument that is passed is the new @code{gdb.Breakpoint} object.
3092 @item events.breakpoint_deleted
3093 This is emitted when a breakpoint has been deleted. The argument that
3094 is passed is the @code{gdb.Breakpoint} object. When this event is
3095 emitted, the @code{gdb.Breakpoint} object will already be in its
3096 invalid state; that is, the @code{is_valid} method will return
3099 @item events.before_prompt
3100 This event carries no payload. It is emitted each time @value{GDBN}
3101 presents a prompt to the user.
3103 @item events.new_inferior
3104 This is emitted when a new inferior is created. Note that the
3105 inferior is not necessarily running; in fact, it may not even have an
3106 associated executable.
3108 The event is of type @code{gdb.NewInferiorEvent}. This has a single
3111 @defvar NewInferiorEvent.inferior
3112 The new inferior, a @code{gdb.Inferior} object.
3115 @item events.inferior_deleted
3116 This is emitted when an inferior has been deleted. Note that this is
3117 not the same as process exit; it is notified when the inferior itself
3118 is removed, say via @code{remove-inferiors}.
3120 The event is of type @code{gdb.InferiorDeletedEvent}. This has a single
3123 @defvar NewInferiorEvent.inferior
3124 The inferior that is being removed, a @code{gdb.Inferior} object.
3127 @item events.new_thread
3128 This is emitted when @value{GDBN} notices a new thread. The event is of
3129 type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}.
3130 This has a single attribute:
3132 @defvar NewThreadEvent.inferior_thread
3138 @node Threads In Python
3139 @subsubsection Threads In Python
3140 @cindex threads in python
3142 @findex gdb.InferiorThread
3143 Python scripts can access information about, and manipulate inferior threads
3144 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
3146 The following thread-related functions are available in the @code{gdb}
3149 @findex gdb.selected_thread
3150 @defun gdb.selected_thread ()
3151 This function returns the thread object for the selected thread. If there
3152 is no selected thread, this will return @code{None}.
3155 A @code{gdb.InferiorThread} object has the following attributes:
3157 @defvar InferiorThread.name
3158 The name of the thread. If the user specified a name using
3159 @code{thread name}, then this returns that name. Otherwise, if an
3160 OS-supplied name is available, then it is returned. Otherwise, this
3161 returns @code{None}.
3163 This attribute can be assigned to. The new value must be a string
3164 object, which sets the new name, or @code{None}, which removes any
3165 user-specified thread name.
3168 @defvar InferiorThread.num
3169 The per-inferior number of the thread, as assigned by GDB.
3172 @defvar InferiorThread.global_num
3173 The global ID of the thread, as assigned by GDB. You can use this to
3174 make Python breakpoints thread-specific, for example
3175 (@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
3178 @defvar InferiorThread.ptid
3179 ID of the thread, as assigned by the operating system. This attribute is a
3180 tuple containing three integers. The first is the Process ID (PID); the second
3181 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
3182 Either the LWPID or TID may be 0, which indicates that the operating system
3183 does not use that identifier.
3186 @defvar InferiorThread.inferior
3187 The inferior this thread belongs to. This attribute is represented as
3188 a @code{gdb.Inferior} object. This attribute is not writable.
3191 A @code{gdb.InferiorThread} object has the following methods:
3193 @defun InferiorThread.is_valid ()
3194 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
3195 @code{False} if not. A @code{gdb.InferiorThread} object will become
3196 invalid if the thread exits, or the inferior that the thread belongs
3197 is deleted. All other @code{gdb.InferiorThread} methods will throw an
3198 exception if it is invalid at the time the method is called.
3201 @defun InferiorThread.switch ()
3202 This changes @value{GDBN}'s currently selected thread to the one represented
3206 @defun InferiorThread.is_stopped ()
3207 Return a Boolean indicating whether the thread is stopped.
3210 @defun InferiorThread.is_running ()
3211 Return a Boolean indicating whether the thread is running.
3214 @defun InferiorThread.is_exited ()
3215 Return a Boolean indicating whether the thread is exited.
3218 @node Recordings In Python
3219 @subsubsection Recordings In Python
3220 @cindex recordings in python
3222 The following recordings-related functions
3223 (@pxref{Process Record and Replay}) are available in the @code{gdb}
3226 @defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
3227 Start a recording using the given @var{method} and @var{format}. If
3228 no @var{format} is given, the default format for the recording method
3229 is used. If no @var{method} is given, the default method will be used.
3230 Returns a @code{gdb.Record} object on success. Throw an exception on
3233 The following strings can be passed as @var{method}:
3239 @code{"btrace"}: Possible values for @var{format}: @code{"pt"},
3240 @code{"bts"} or leave out for default format.
3244 @defun gdb.current_recording ()
3245 Access a currently running recording. Return a @code{gdb.Record}
3246 object on success. Return @code{None} if no recording is currently
3250 @defun gdb.stop_recording ()
3251 Stop the current recording. Throw an exception if no recording is
3252 currently active. All record objects become invalid after this call.
3255 A @code{gdb.Record} object has the following attributes:
3257 @defvar Record.method
3258 A string with the current recording method, e.g.@: @code{full} or
3262 @defvar Record.format
3263 A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
3267 @defvar Record.begin
3268 A method specific instruction object representing the first instruction
3273 A method specific instruction object representing the current
3274 instruction, that is not actually part of the recording.
3277 @defvar Record.replay_position
3278 The instruction representing the current replay position. If there is
3279 no replay active, this will be @code{None}.
3282 @defvar Record.instruction_history
3283 A list with all recorded instructions.
3286 @defvar Record.function_call_history
3287 A list with all recorded function call segments.
3290 A @code{gdb.Record} object has the following methods:
3292 @defun Record.goto (instruction)
3293 Move the replay position to the given @var{instruction}.
3296 The common @code{gdb.Instruction} class that recording method specific
3297 instruction objects inherit from, has the following attributes:
3299 @defvar Instruction.pc
3300 An integer representing this instruction's address.
3303 @defvar Instruction.data
3304 A buffer with the raw instruction data. In Python 3, the return value is a
3305 @code{memoryview} object.
3308 @defvar Instruction.decoded
3309 A human readable string with the disassembled instruction.
3312 @defvar Instruction.size
3313 The size of the instruction in bytes.
3316 Additionally @code{gdb.RecordInstruction} has the following attributes:
3318 @defvar RecordInstruction.number
3319 An integer identifying this instruction. @code{number} corresponds to
3320 the numbers seen in @code{record instruction-history}
3321 (@pxref{Process Record and Replay}).
3324 @defvar RecordInstruction.sal
3325 A @code{gdb.Symtab_and_line} object representing the associated symtab
3326 and line of this instruction. May be @code{None} if no debug information is
3330 @defvar RecordInstruction.is_speculative
3331 A boolean indicating whether the instruction was executed speculatively.
3334 If an error occured during recording or decoding a recording, this error is
3335 represented by a @code{gdb.RecordGap} object in the instruction list. It has
3336 the following attributes:
3338 @defvar RecordGap.number
3339 An integer identifying this gap. @code{number} corresponds to the numbers seen
3340 in @code{record instruction-history} (@pxref{Process Record and Replay}).
3343 @defvar RecordGap.error_code
3344 A numerical representation of the reason for the gap. The value is specific to
3345 the current recording method.
3348 @defvar RecordGap.error_string
3349 A human readable string with the reason for the gap.
3352 A @code{gdb.RecordFunctionSegment} object has the following attributes:
3354 @defvar RecordFunctionSegment.number
3355 An integer identifying this function segment. @code{number} corresponds to
3356 the numbers seen in @code{record function-call-history}
3357 (@pxref{Process Record and Replay}).
3360 @defvar RecordFunctionSegment.symbol
3361 A @code{gdb.Symbol} object representing the associated symbol. May be
3362 @code{None} if no debug information is available.
3365 @defvar RecordFunctionSegment.level
3366 An integer representing the function call's stack level. May be
3367 @code{None} if the function call is a gap.
3370 @defvar RecordFunctionSegment.instructions
3371 A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
3372 associated with this function call.
3375 @defvar RecordFunctionSegment.up
3376 A @code{gdb.RecordFunctionSegment} object representing the caller's
3377 function segment. If the call has not been recorded, this will be the
3378 function segment to which control returns. If neither the call nor the
3379 return have been recorded, this will be @code{None}.
3382 @defvar RecordFunctionSegment.prev
3383 A @code{gdb.RecordFunctionSegment} object representing the previous
3384 segment of this function call. May be @code{None}.
3387 @defvar RecordFunctionSegment.next
3388 A @code{gdb.RecordFunctionSegment} object representing the next segment of
3389 this function call. May be @code{None}.
3392 The following example demonstrates the usage of these objects and
3393 functions to create a function that will rewind a record to the last
3394 time a function in a different file was executed. This would typically
3395 be used to track the execution of user provided callback functions in a
3396 library which typically are not visible in a back trace.
3400 rec = gdb.current_recording ()
3404 insn = rec.instruction_history
3409 position = insn.index (rec.replay_position)
3413 filename = insn[position].sal.symtab.fullname ()
3417 for i in reversed (insn[:position]):
3419 current = i.sal.symtab.fullname ()
3423 if filename == current:
3430 Another possible application is to write a function that counts the
3431 number of code executions in a given line range. This line range can
3432 contain parts of functions or span across several functions and is not
3433 limited to be contiguous.
3436 def countrange (filename, linerange):
3439 def filter_only (file_name):
3440 for call in gdb.current_recording ().function_call_history:
3442 if file_name in call.symbol.symtab.fullname ():
3447 for c in filter_only (filename):
3448 for i in c.instructions:
3450 if i.sal.line in linerange:
3459 @node Commands In Python
3460 @subsubsection Commands In Python
3462 @cindex commands in python
3463 @cindex python commands
3464 You can implement new @value{GDBN} CLI commands in Python. A CLI
3465 command is implemented using an instance of the @code{gdb.Command}
3466 class, most commonly using a subclass.
3468 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
3469 The object initializer for @code{Command} registers the new command
3470 with @value{GDBN}. This initializer is normally invoked from the
3471 subclass' own @code{__init__} method.
3473 @var{name} is the name of the command. If @var{name} consists of
3474 multiple words, then the initial words are looked for as prefix
3475 commands. In this case, if one of the prefix commands does not exist,
3476 an exception is raised.
3478 There is no support for multi-line commands.
3480 @var{command_class} should be one of the @samp{COMMAND_} constants
3481 defined below. This argument tells @value{GDBN} how to categorize the
3482 new command in the help system.
3484 @var{completer_class} is an optional argument. If given, it should be
3485 one of the @samp{COMPLETE_} constants defined below. This argument
3486 tells @value{GDBN} how to perform completion for this command. If not
3487 given, @value{GDBN} will attempt to complete using the object's
3488 @code{complete} method (see below); if no such method is found, an
3489 error will occur when completion is attempted.
3491 @var{prefix} is an optional argument. If @code{True}, then the new
3492 command is a prefix command; sub-commands of this command may be
3495 The help text for the new command is taken from the Python
3496 documentation string for the command's class, if there is one. If no
3497 documentation string is provided, the default value ``This command is
3498 not documented.'' is used.
3501 @cindex don't repeat Python command
3502 @defun Command.dont_repeat ()
3503 By default, a @value{GDBN} command is repeated when the user enters a
3504 blank line at the command prompt. A command can suppress this
3505 behavior by invoking the @code{dont_repeat} method. This is similar
3506 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
3509 @defun Command.invoke (argument, from_tty)
3510 This method is called by @value{GDBN} when this command is invoked.
3512 @var{argument} is a string. It is the argument to the command, after
3513 leading and trailing whitespace has been stripped.
3515 @var{from_tty} is a boolean argument. When true, this means that the
3516 command was entered by the user at the terminal; when false it means
3517 that the command came from elsewhere.
3519 If this method throws an exception, it is turned into a @value{GDBN}
3520 @code{error} call. Otherwise, the return value is ignored.
3522 @findex gdb.string_to_argv
3523 To break @var{argument} up into an argv-like string use
3524 @code{gdb.string_to_argv}. This function behaves identically to
3525 @value{GDBN}'s internal argument lexer @code{buildargv}.
3526 It is recommended to use this for consistency.
3527 Arguments are separated by spaces and may be quoted.
3531 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
3532 ['1', '2 "3', '4 "5', "6 '7"]
3537 @cindex completion of Python commands
3538 @defun Command.complete (text, word)
3539 This method is called by @value{GDBN} when the user attempts
3540 completion on this command. All forms of completion are handled by
3541 this method, that is, the @key{TAB} and @key{M-?} key bindings
3542 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
3545 The arguments @var{text} and @var{word} are both strings; @var{text}
3546 holds the complete command line up to the cursor's location, while
3547 @var{word} holds the last word of the command line; this is computed
3548 using a word-breaking heuristic.
3550 The @code{complete} method can return several values:
3553 If the return value is a sequence, the contents of the sequence are
3554 used as the completions. It is up to @code{complete} to ensure that the
3555 contents actually do complete the word. A zero-length sequence is
3556 allowed, it means that there were no completions available. Only
3557 string elements of the sequence are used; other elements in the
3558 sequence are ignored.
3561 If the return value is one of the @samp{COMPLETE_} constants defined
3562 below, then the corresponding @value{GDBN}-internal completion
3563 function is invoked, and its result is used.
3566 All other results are treated as though there were no available
3571 When a new command is registered, it must be declared as a member of
3572 some general class of commands. This is used to classify top-level
3573 commands in the on-line help system; note that prefix commands are not
3574 listed under their own category but rather that of their top-level
3575 command. The available classifications are represented by constants
3576 defined in the @code{gdb} module:
3579 @findex COMMAND_NONE
3580 @findex gdb.COMMAND_NONE
3581 @item gdb.COMMAND_NONE
3582 The command does not belong to any particular class. A command in
3583 this category will not be displayed in any of the help categories.
3585 @findex COMMAND_RUNNING
3586 @findex gdb.COMMAND_RUNNING
3587 @item gdb.COMMAND_RUNNING
3588 The command is related to running the inferior. For example,
3589 @code{start}, @code{step}, and @code{continue} are in this category.
3590 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
3591 commands in this category.
3593 @findex COMMAND_DATA
3594 @findex gdb.COMMAND_DATA
3595 @item gdb.COMMAND_DATA
3596 The command is related to data or variables. For example,
3597 @code{call}, @code{find}, and @code{print} are in this category. Type
3598 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
3601 @findex COMMAND_STACK
3602 @findex gdb.COMMAND_STACK
3603 @item gdb.COMMAND_STACK
3604 The command has to do with manipulation of the stack. For example,
3605 @code{backtrace}, @code{frame}, and @code{return} are in this
3606 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
3607 list of commands in this category.
3609 @findex COMMAND_FILES
3610 @findex gdb.COMMAND_FILES
3611 @item gdb.COMMAND_FILES
3612 This class is used for file-related commands. For example,
3613 @code{file}, @code{list} and @code{section} are in this category.
3614 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
3615 commands in this category.
3617 @findex COMMAND_SUPPORT
3618 @findex gdb.COMMAND_SUPPORT
3619 @item gdb.COMMAND_SUPPORT
3620 This should be used for ``support facilities'', generally meaning
3621 things that are useful to the user when interacting with @value{GDBN},
3622 but not related to the state of the inferior. For example,
3623 @code{help}, @code{make}, and @code{shell} are in this category. Type
3624 @kbd{help support} at the @value{GDBN} prompt to see a list of
3625 commands in this category.
3627 @findex COMMAND_STATUS
3628 @findex gdb.COMMAND_STATUS
3629 @item gdb.COMMAND_STATUS
3630 The command is an @samp{info}-related command, that is, related to the
3631 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
3632 and @code{show} are in this category. Type @kbd{help status} at the
3633 @value{GDBN} prompt to see a list of commands in this category.
3635 @findex COMMAND_BREAKPOINTS
3636 @findex gdb.COMMAND_BREAKPOINTS
3637 @item gdb.COMMAND_BREAKPOINTS
3638 The command has to do with breakpoints. For example, @code{break},
3639 @code{clear}, and @code{delete} are in this category. Type @kbd{help
3640 breakpoints} at the @value{GDBN} prompt to see a list of commands in
3643 @findex COMMAND_TRACEPOINTS
3644 @findex gdb.COMMAND_TRACEPOINTS
3645 @item gdb.COMMAND_TRACEPOINTS
3646 The command has to do with tracepoints. For example, @code{trace},
3647 @code{actions}, and @code{tfind} are in this category. Type
3648 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
3649 commands in this category.
3651 @findex COMMAND_USER
3652 @findex gdb.COMMAND_USER
3653 @item gdb.COMMAND_USER
3654 The command is a general purpose command for the user, and typically
3655 does not fit in one of the other categories.
3656 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
3657 a list of commands in this category, as well as the list of gdb macros
3658 (@pxref{Sequences}).
3660 @findex COMMAND_OBSCURE
3661 @findex gdb.COMMAND_OBSCURE
3662 @item gdb.COMMAND_OBSCURE
3663 The command is only used in unusual circumstances, or is not of
3664 general interest to users. For example, @code{checkpoint},
3665 @code{fork}, and @code{stop} are in this category. Type @kbd{help
3666 obscure} at the @value{GDBN} prompt to see a list of commands in this
3669 @findex COMMAND_MAINTENANCE
3670 @findex gdb.COMMAND_MAINTENANCE
3671 @item gdb.COMMAND_MAINTENANCE
3672 The command is only useful to @value{GDBN} maintainers. The
3673 @code{maintenance} and @code{flushregs} commands are in this category.
3674 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
3675 commands in this category.
3678 A new command can use a predefined completion function, either by
3679 specifying it via an argument at initialization, or by returning it
3680 from the @code{complete} method. These predefined completion
3681 constants are all defined in the @code{gdb} module:
3684 @vindex COMPLETE_NONE
3685 @item gdb.COMPLETE_NONE
3686 This constant means that no completion should be done.
3688 @vindex COMPLETE_FILENAME
3689 @item gdb.COMPLETE_FILENAME
3690 This constant means that filename completion should be performed.
3692 @vindex COMPLETE_LOCATION
3693 @item gdb.COMPLETE_LOCATION
3694 This constant means that location completion should be done.
3695 @xref{Specify Location}.
3697 @vindex COMPLETE_COMMAND
3698 @item gdb.COMPLETE_COMMAND
3699 This constant means that completion should examine @value{GDBN}
3702 @vindex COMPLETE_SYMBOL
3703 @item gdb.COMPLETE_SYMBOL
3704 This constant means that completion should be done using symbol names
3707 @vindex COMPLETE_EXPRESSION
3708 @item gdb.COMPLETE_EXPRESSION
3709 This constant means that completion should be done on expressions.
3710 Often this means completing on symbol names, but some language
3711 parsers also have support for completing on field names.
3714 The following code snippet shows how a trivial CLI command can be
3715 implemented in Python:
3718 class HelloWorld (gdb.Command):
3719 """Greet the whole world."""
3721 def __init__ (self):
3722 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
3724 def invoke (self, arg, from_tty):
3725 print "Hello, World!"
3730 The last line instantiates the class, and is necessary to trigger the
3731 registration of the command with @value{GDBN}. Depending on how the
3732 Python code is read into @value{GDBN}, you may need to import the
3733 @code{gdb} module explicitly.
3735 @node Parameters In Python
3736 @subsubsection Parameters In Python
3738 @cindex parameters in python
3739 @cindex python parameters
3740 @tindex gdb.Parameter
3742 You can implement new @value{GDBN} parameters using Python. A new
3743 parameter is implemented as an instance of the @code{gdb.Parameter}
3746 Parameters are exposed to the user via the @code{set} and
3747 @code{show} commands. @xref{Help}.
3749 There are many parameters that already exist and can be set in
3750 @value{GDBN}. Two examples are: @code{set follow fork} and
3751 @code{set charset}. Setting these parameters influences certain
3752 behavior in @value{GDBN}. Similarly, you can define parameters that
3753 can be used to influence behavior in custom Python scripts and commands.
3755 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
3756 The object initializer for @code{Parameter} registers the new
3757 parameter with @value{GDBN}. This initializer is normally invoked
3758 from the subclass' own @code{__init__} method.
3760 @var{name} is the name of the new parameter. If @var{name} consists
3761 of multiple words, then the initial words are looked for as prefix
3762 parameters. An example of this can be illustrated with the
3763 @code{set print} set of parameters. If @var{name} is
3764 @code{print foo}, then @code{print} will be searched as the prefix
3765 parameter. In this case the parameter can subsequently be accessed in
3766 @value{GDBN} as @code{set print foo}.
3768 If @var{name} consists of multiple words, and no prefix parameter group
3769 can be found, an exception is raised.
3771 @var{command-class} should be one of the @samp{COMMAND_} constants
3772 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
3773 categorize the new parameter in the help system.
3775 @var{parameter-class} should be one of the @samp{PARAM_} constants
3776 defined below. This argument tells @value{GDBN} the type of the new
3777 parameter; this information is used for input validation and
3780 If @var{parameter-class} is @code{PARAM_ENUM}, then
3781 @var{enum-sequence} must be a sequence of strings. These strings
3782 represent the possible values for the parameter.
3784 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
3785 of a fourth argument will cause an exception to be thrown.
3787 The help text for the new parameter is taken from the Python
3788 documentation string for the parameter's class, if there is one. If
3789 there is no documentation string, a default value is used.
3792 @defvar Parameter.set_doc
3793 If this attribute exists, and is a string, then its value is used as
3794 the help text for this parameter's @code{set} command. The value is
3795 examined when @code{Parameter.__init__} is invoked; subsequent changes
3799 @defvar Parameter.show_doc
3800 If this attribute exists, and is a string, then its value is used as
3801 the help text for this parameter's @code{show} command. The value is
3802 examined when @code{Parameter.__init__} is invoked; subsequent changes
3806 @defvar Parameter.value
3807 The @code{value} attribute holds the underlying value of the
3808 parameter. It can be read and assigned to just as any other
3809 attribute. @value{GDBN} does validation when assignments are made.
3812 There are two methods that may be implemented in any @code{Parameter}
3815 @defun Parameter.get_set_string (self)
3816 If this method exists, @value{GDBN} will call it when a
3817 @var{parameter}'s value has been changed via the @code{set} API (for
3818 example, @kbd{set foo off}). The @code{value} attribute has already
3819 been populated with the new value and may be used in output. This
3820 method must return a string. If the returned string is not empty,
3821 @value{GDBN} will present it to the user.
3824 @defun Parameter.get_show_string (self, svalue)
3825 @value{GDBN} will call this method when a @var{parameter}'s
3826 @code{show} API has been invoked (for example, @kbd{show foo}). The
3827 argument @code{svalue} receives the string representation of the
3828 current value. This method must return a string.
3831 When a new parameter is defined, its type must be specified. The
3832 available types are represented by constants defined in the @code{gdb}
3836 @findex PARAM_BOOLEAN
3837 @findex gdb.PARAM_BOOLEAN
3838 @item gdb.PARAM_BOOLEAN
3839 The value is a plain boolean. The Python boolean values, @code{True}
3840 and @code{False} are the only valid values.
3842 @findex PARAM_AUTO_BOOLEAN
3843 @findex gdb.PARAM_AUTO_BOOLEAN
3844 @item gdb.PARAM_AUTO_BOOLEAN
3845 The value has three possible states: true, false, and @samp{auto}. In
3846 Python, true and false are represented using boolean constants, and
3847 @samp{auto} is represented using @code{None}.
3849 @findex PARAM_UINTEGER
3850 @findex gdb.PARAM_UINTEGER
3851 @item gdb.PARAM_UINTEGER
3852 The value is an unsigned integer. The value of 0 should be
3853 interpreted to mean ``unlimited''.
3855 @findex PARAM_INTEGER
3856 @findex gdb.PARAM_INTEGER
3857 @item gdb.PARAM_INTEGER
3858 The value is a signed integer. The value of 0 should be interpreted
3859 to mean ``unlimited''.
3861 @findex PARAM_STRING
3862 @findex gdb.PARAM_STRING
3863 @item gdb.PARAM_STRING
3864 The value is a string. When the user modifies the string, any escape
3865 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
3866 translated into corresponding characters and encoded into the current
3869 @findex PARAM_STRING_NOESCAPE
3870 @findex gdb.PARAM_STRING_NOESCAPE
3871 @item gdb.PARAM_STRING_NOESCAPE
3872 The value is a string. When the user modifies the string, escapes are
3873 passed through untranslated.
3875 @findex PARAM_OPTIONAL_FILENAME
3876 @findex gdb.PARAM_OPTIONAL_FILENAME
3877 @item gdb.PARAM_OPTIONAL_FILENAME
3878 The value is a either a filename (a string), or @code{None}.
3880 @findex PARAM_FILENAME
3881 @findex gdb.PARAM_FILENAME
3882 @item gdb.PARAM_FILENAME
3883 The value is a filename. This is just like
3884 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
3886 @findex PARAM_ZINTEGER
3887 @findex gdb.PARAM_ZINTEGER
3888 @item gdb.PARAM_ZINTEGER
3889 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
3890 is interpreted as itself.
3892 @findex PARAM_ZUINTEGER
3893 @findex gdb.PARAM_ZUINTEGER
3894 @item gdb.PARAM_ZUINTEGER
3895 The value is an unsigned integer. This is like @code{PARAM_INTEGER},
3896 except 0 is interpreted as itself, and the value cannot be negative.
3898 @findex PARAM_ZUINTEGER_UNLIMITED
3899 @findex gdb.PARAM_ZUINTEGER_UNLIMITED
3900 @item gdb.PARAM_ZUINTEGER_UNLIMITED
3901 The value is a signed integer. This is like @code{PARAM_ZUINTEGER},
3902 except the special value -1 should be interpreted to mean
3903 ``unlimited''. Other negative values are not allowed.
3906 @findex gdb.PARAM_ENUM
3907 @item gdb.PARAM_ENUM
3908 The value is a string, which must be one of a collection string
3909 constants provided when the parameter is created.
3912 @node Functions In Python
3913 @subsubsection Writing new convenience functions
3915 @cindex writing convenience functions
3916 @cindex convenience functions in python
3917 @cindex python convenience functions
3918 @tindex gdb.Function
3920 You can implement new convenience functions (@pxref{Convenience Vars})
3921 in Python. A convenience function is an instance of a subclass of the
3922 class @code{gdb.Function}.
3924 @defun Function.__init__ (name)
3925 The initializer for @code{Function} registers the new function with
3926 @value{GDBN}. The argument @var{name} is the name of the function,
3927 a string. The function will be visible to the user as a convenience
3928 variable of type @code{internal function}, whose name is the same as
3929 the given @var{name}.
3931 The documentation for the new function is taken from the documentation
3932 string for the new class.
3935 @defun Function.invoke (@var{*args})
3936 When a convenience function is evaluated, its arguments are converted
3937 to instances of @code{gdb.Value}, and then the function's
3938 @code{invoke} method is called. Note that @value{GDBN} does not
3939 predetermine the arity of convenience functions. Instead, all
3940 available arguments are passed to @code{invoke}, following the
3941 standard Python calling convention. In particular, a convenience
3942 function can have default values for parameters without ill effect.
3944 The return value of this method is used as its value in the enclosing
3945 expression. If an ordinary Python value is returned, it is converted
3946 to a @code{gdb.Value} following the usual rules.
3949 The following code snippet shows how a trivial convenience function can
3950 be implemented in Python:
3953 class Greet (gdb.Function):
3954 """Return string to greet someone.
3955 Takes a name as argument."""
3957 def __init__ (self):
3958 super (Greet, self).__init__ ("greet")
3960 def invoke (self, name):
3961 return "Hello, %s!" % name.string ()
3966 The last line instantiates the class, and is necessary to trigger the
3967 registration of the function with @value{GDBN}. Depending on how the
3968 Python code is read into @value{GDBN}, you may need to import the
3969 @code{gdb} module explicitly.
3971 Now you can use the function in an expression:
3974 (gdb) print $greet("Bob")
3978 @node Progspaces In Python
3979 @subsubsection Program Spaces In Python
3981 @cindex progspaces in python
3982 @tindex gdb.Progspace
3984 A program space, or @dfn{progspace}, represents a symbolic view
3985 of an address space.
3986 It consists of all of the objfiles of the program.
3987 @xref{Objfiles In Python}.
3988 @xref{Inferiors and Programs, program spaces}, for more details
3989 about program spaces.
3991 The following progspace-related functions are available in the
3994 @findex gdb.current_progspace
3995 @defun gdb.current_progspace ()
3996 This function returns the program space of the currently selected inferior.
3997 @xref{Inferiors and Programs}.
4000 @findex gdb.progspaces
4001 @defun gdb.progspaces ()
4002 Return a sequence of all the progspaces currently known to @value{GDBN}.
4005 Each progspace is represented by an instance of the @code{gdb.Progspace}
4008 @defvar Progspace.filename
4009 The file name of the progspace as a string.
4012 @defvar Progspace.pretty_printers
4013 The @code{pretty_printers} attribute is a list of functions. It is
4014 used to look up pretty-printers. A @code{Value} is passed to each
4015 function in order; if the function returns @code{None}, then the
4016 search continues. Otherwise, the return value should be an object
4017 which is used to format the value. @xref{Pretty Printing API}, for more
4021 @defvar Progspace.type_printers
4022 The @code{type_printers} attribute is a list of type printer objects.
4023 @xref{Type Printing API}, for more information.
4026 @defvar Progspace.frame_filters
4027 The @code{frame_filters} attribute is a dictionary of frame filter
4028 objects. @xref{Frame Filter API}, for more information.
4031 One may add arbitrary attributes to @code{gdb.Progspace} objects
4032 in the usual Python way.
4033 This is useful if, for example, one needs to do some extra record keeping
4034 associated with the program space.
4036 In this contrived example, we want to perform some processing when
4037 an objfile with a certain symbol is loaded, but we only want to do
4038 this once because it is expensive. To achieve this we record the results
4039 with the program space because we can't predict when the desired objfile
4044 def clear_objfiles_handler(event):
4045 event.progspace.expensive_computation = None
4046 def expensive(symbol):
4047 """A mock routine to perform an "expensive" computation on symbol."""
4048 print "Computing the answer to the ultimate question ..."
4050 def new_objfile_handler(event):
4051 objfile = event.new_objfile
4052 progspace = objfile.progspace
4053 if not hasattr(progspace, 'expensive_computation') or \
4054 progspace.expensive_computation is None:
4055 # We use 'main' for the symbol to keep the example simple.
4056 # Note: There's no current way to constrain the lookup
4058 symbol = gdb.lookup_global_symbol('main')
4059 if symbol is not None:
4060 progspace.expensive_computation = expensive(symbol)
4061 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
4062 gdb.events.new_objfile.connect(new_objfile_handler)
4064 (gdb) file /tmp/hello
4065 Reading symbols from /tmp/hello...done.
4066 Computing the answer to the ultimate question ...
4067 (gdb) python print gdb.current_progspace().expensive_computation
4070 Starting program: /tmp/hello
4072 [Inferior 1 (process 4242) exited normally]
4075 @node Objfiles In Python
4076 @subsubsection Objfiles In Python
4078 @cindex objfiles in python
4081 @value{GDBN} loads symbols for an inferior from various
4082 symbol-containing files (@pxref{Files}). These include the primary
4083 executable file, any shared libraries used by the inferior, and any
4084 separate debug info files (@pxref{Separate Debug Files}).
4085 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
4087 The following objfile-related functions are available in the
4090 @findex gdb.current_objfile
4091 @defun gdb.current_objfile ()
4092 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
4093 sets the ``current objfile'' to the corresponding objfile. This
4094 function returns the current objfile. If there is no current objfile,
4095 this function returns @code{None}.
4098 @findex gdb.objfiles
4099 @defun gdb.objfiles ()
4100 Return a sequence of all the objfiles current known to @value{GDBN}.
4101 @xref{Objfiles In Python}.
4104 @findex gdb.lookup_objfile
4105 @defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
4106 Look up @var{name}, a file name or build ID, in the list of objfiles
4107 for the current program space (@pxref{Progspaces In Python}).
4108 If the objfile is not found throw the Python @code{ValueError} exception.
4110 If @var{name} is a relative file name, then it will match any
4111 source file name with the same trailing components. For example, if
4112 @var{name} is @samp{gcc/expr.c}, then it will match source file
4113 name of @file{/build/trunk/gcc/expr.c}, but not
4114 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
4116 If @var{by_build_id} is provided and is @code{True} then @var{name}
4117 is the build ID of the objfile. Otherwise, @var{name} is a file name.
4118 This is supported only on some operating systems, notably those which use
4119 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4120 about this feature, see the description of the @option{--build-id}
4121 command-line option in @ref{Options, , Command Line Options, ld,
4125 Each objfile is represented by an instance of the @code{gdb.Objfile}
4128 @defvar Objfile.filename
4129 The file name of the objfile as a string, with symbolic links resolved.
4131 The value is @code{None} if the objfile is no longer valid.
4132 See the @code{gdb.Objfile.is_valid} method, described below.
4135 @defvar Objfile.username
4136 The file name of the objfile as specified by the user as a string.
4138 The value is @code{None} if the objfile is no longer valid.
4139 See the @code{gdb.Objfile.is_valid} method, described below.
4142 @defvar Objfile.owner
4143 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
4144 object that debug info is being provided for.
4145 Otherwise this is @code{None}.
4146 Separate debug info objfiles are added with the
4147 @code{gdb.Objfile.add_separate_debug_file} method, described below.
4150 @defvar Objfile.build_id
4151 The build ID of the objfile as a string.
4152 If the objfile does not have a build ID then the value is @code{None}.
4154 This is supported only on some operating systems, notably those which use
4155 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4156 about this feature, see the description of the @option{--build-id}
4157 command-line option in @ref{Options, , Command Line Options, ld,
4161 @defvar Objfile.progspace
4162 The containing program space of the objfile as a @code{gdb.Progspace}
4163 object. @xref{Progspaces In Python}.
4166 @defvar Objfile.pretty_printers
4167 The @code{pretty_printers} attribute is a list of functions. It is
4168 used to look up pretty-printers. A @code{Value} is passed to each
4169 function in order; if the function returns @code{None}, then the
4170 search continues. Otherwise, the return value should be an object
4171 which is used to format the value. @xref{Pretty Printing API}, for more
4175 @defvar Objfile.type_printers
4176 The @code{type_printers} attribute is a list of type printer objects.
4177 @xref{Type Printing API}, for more information.
4180 @defvar Objfile.frame_filters
4181 The @code{frame_filters} attribute is a dictionary of frame filter
4182 objects. @xref{Frame Filter API}, for more information.
4185 One may add arbitrary attributes to @code{gdb.Objfile} objects
4186 in the usual Python way.
4187 This is useful if, for example, one needs to do some extra record keeping
4188 associated with the objfile.
4190 In this contrived example we record the time when @value{GDBN}
4196 def new_objfile_handler(event):
4197 # Set the time_loaded attribute of the new objfile.
4198 event.new_objfile.time_loaded = datetime.datetime.today()
4199 gdb.events.new_objfile.connect(new_objfile_handler)
4202 Reading symbols from ./hello...done.
4203 (gdb) python print gdb.objfiles()[0].time_loaded
4204 2014-10-09 11:41:36.770345
4207 A @code{gdb.Objfile} object has the following methods:
4209 @defun Objfile.is_valid ()
4210 Returns @code{True} if the @code{gdb.Objfile} object is valid,
4211 @code{False} if not. A @code{gdb.Objfile} object can become invalid
4212 if the object file it refers to is not loaded in @value{GDBN} any
4213 longer. All other @code{gdb.Objfile} methods will throw an exception
4214 if it is invalid at the time the method is called.
4217 @defun Objfile.add_separate_debug_file (file)
4218 Add @var{file} to the list of files that @value{GDBN} will search for
4219 debug information for the objfile.
4220 This is useful when the debug info has been removed from the program
4221 and stored in a separate file. @value{GDBN} has built-in support for
4222 finding separate debug info files (@pxref{Separate Debug Files}), but if
4223 the file doesn't live in one of the standard places that @value{GDBN}
4224 searches then this function can be used to add a debug info file
4225 from a different place.
4228 @node Frames In Python
4229 @subsubsection Accessing inferior stack frames from Python.
4231 @cindex frames in python
4232 When the debugged program stops, @value{GDBN} is able to analyze its call
4233 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
4234 represents a frame in the stack. A @code{gdb.Frame} object is only valid
4235 while its corresponding frame exists in the inferior's stack. If you try
4236 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
4237 exception (@pxref{Exception Handling}).
4239 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
4243 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
4247 The following frame-related functions are available in the @code{gdb} module:
4249 @findex gdb.selected_frame
4250 @defun gdb.selected_frame ()
4251 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
4254 @findex gdb.newest_frame
4255 @defun gdb.newest_frame ()
4256 Return the newest frame object for the selected thread.
4259 @defun gdb.frame_stop_reason_string (reason)
4260 Return a string explaining the reason why @value{GDBN} stopped unwinding
4261 frames, as expressed by the given @var{reason} code (an integer, see the
4262 @code{unwind_stop_reason} method further down in this section).
4265 @findex gdb.invalidate_cached_frames
4266 @defun gdb.invalidate_cached_frames
4267 @value{GDBN} internally keeps a cache of the frames that have been
4268 unwound. This function invalidates this cache.
4270 This function should not generally be called by ordinary Python code.
4271 It is documented for the sake of completeness.
4274 A @code{gdb.Frame} object has the following methods:
4276 @defun Frame.is_valid ()
4277 Returns true if the @code{gdb.Frame} object is valid, false if not.
4278 A frame object can become invalid if the frame it refers to doesn't
4279 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
4280 an exception if it is invalid at the time the method is called.
4283 @defun Frame.name ()
4284 Returns the function name of the frame, or @code{None} if it can't be
4288 @defun Frame.architecture ()
4289 Returns the @code{gdb.Architecture} object corresponding to the frame's
4290 architecture. @xref{Architectures In Python}.
4293 @defun Frame.type ()
4294 Returns the type of the frame. The value can be one of:
4296 @item gdb.NORMAL_FRAME
4297 An ordinary stack frame.
4299 @item gdb.DUMMY_FRAME
4300 A fake stack frame that was created by @value{GDBN} when performing an
4301 inferior function call.
4303 @item gdb.INLINE_FRAME
4304 A frame representing an inlined function. The function was inlined
4305 into a @code{gdb.NORMAL_FRAME} that is older than this one.
4307 @item gdb.TAILCALL_FRAME
4308 A frame representing a tail call. @xref{Tail Call Frames}.
4310 @item gdb.SIGTRAMP_FRAME
4311 A signal trampoline frame. This is the frame created by the OS when
4312 it calls into a signal handler.
4314 @item gdb.ARCH_FRAME
4315 A fake stack frame representing a cross-architecture call.
4317 @item gdb.SENTINEL_FRAME
4318 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
4323 @defun Frame.unwind_stop_reason ()
4324 Return an integer representing the reason why it's not possible to find
4325 more frames toward the outermost frame. Use
4326 @code{gdb.frame_stop_reason_string} to convert the value returned by this
4327 function to a string. The value can be one of:
4330 @item gdb.FRAME_UNWIND_NO_REASON
4331 No particular reason (older frames should be available).
4333 @item gdb.FRAME_UNWIND_NULL_ID
4334 The previous frame's analyzer returns an invalid result. This is no
4335 longer used by @value{GDBN}, and is kept only for backward
4338 @item gdb.FRAME_UNWIND_OUTERMOST
4339 This frame is the outermost.
4341 @item gdb.FRAME_UNWIND_UNAVAILABLE
4342 Cannot unwind further, because that would require knowing the
4343 values of registers or memory that have not been collected.
4345 @item gdb.FRAME_UNWIND_INNER_ID
4346 This frame ID looks like it ought to belong to a NEXT frame,
4347 but we got it for a PREV frame. Normally, this is a sign of
4348 unwinder failure. It could also indicate stack corruption.
4350 @item gdb.FRAME_UNWIND_SAME_ID
4351 This frame has the same ID as the previous one. That means
4352 that unwinding further would almost certainly give us another
4353 frame with exactly the same ID, so break the chain. Normally,
4354 this is a sign of unwinder failure. It could also indicate
4357 @item gdb.FRAME_UNWIND_NO_SAVED_PC
4358 The frame unwinder did not find any saved PC, but we needed
4359 one to unwind further.
4361 @item gdb.FRAME_UNWIND_MEMORY_ERROR
4362 The frame unwinder caused an error while trying to access memory.
4364 @item gdb.FRAME_UNWIND_FIRST_ERROR
4365 Any stop reason greater or equal to this value indicates some kind
4366 of error. This special value facilitates writing code that tests
4367 for errors in unwinding in a way that will work correctly even if
4368 the list of the other values is modified in future @value{GDBN}
4369 versions. Using it, you could write:
4371 reason = gdb.selected_frame().unwind_stop_reason ()
4372 reason_str = gdb.frame_stop_reason_string (reason)
4373 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
4374 print "An error occured: %s" % reason_str
4381 Returns the frame's resume address.
4384 @defun Frame.block ()
4385 Return the frame's code block. @xref{Blocks In Python}. If the frame
4386 does not have a block -- for example, if there is no debugging
4387 information for the code in question -- then this will throw an
4391 @defun Frame.function ()
4392 Return the symbol for the function corresponding to this frame.
4393 @xref{Symbols In Python}.
4396 @defun Frame.older ()
4397 Return the frame that called this frame.
4400 @defun Frame.newer ()
4401 Return the frame called by this frame.
4404 @defun Frame.find_sal ()
4405 Return the frame's symtab and line object.
4406 @xref{Symbol Tables In Python}.
4409 @defun Frame.read_register (register)
4410 Return the value of @var{register} in this frame. The @var{register}
4411 argument must be a string (e.g., @code{'sp'} or @code{'rax'}).
4412 Returns a @code{Gdb.Value} object. Throws an exception if @var{register}
4416 @defun Frame.read_var (variable @r{[}, block@r{]})
4417 Return the value of @var{variable} in this frame. If the optional
4418 argument @var{block} is provided, search for the variable from that
4419 block; otherwise start at the frame's current block (which is
4420 determined by the frame's current program counter). The @var{variable}
4421 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
4422 @code{gdb.Block} object.
4425 @defun Frame.select ()
4426 Set this frame to be the selected frame. @xref{Stack, ,Examining the
4430 @node Blocks In Python
4431 @subsubsection Accessing blocks from Python.
4433 @cindex blocks in python
4436 In @value{GDBN}, symbols are stored in blocks. A block corresponds
4437 roughly to a scope in the source code. Blocks are organized
4438 hierarchically, and are represented individually in Python as a
4439 @code{gdb.Block}. Blocks rely on debugging information being
4442 A frame has a block. Please see @ref{Frames In Python}, for a more
4443 in-depth discussion of frames.
4445 The outermost block is known as the @dfn{global block}. The global
4446 block typically holds public global variables and functions.
4448 The block nested just inside the global block is the @dfn{static
4449 block}. The static block typically holds file-scoped variables and
4452 @value{GDBN} provides a method to get a block's superblock, but there
4453 is currently no way to examine the sub-blocks of a block, or to
4454 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
4457 Here is a short example that should help explain blocks:
4460 /* This is in the global block. */
4463 /* This is in the static block. */
4464 static int file_scope;
4466 /* 'function' is in the global block, and 'argument' is
4467 in a block nested inside of 'function'. */
4468 int function (int argument)
4470 /* 'local' is in a block inside 'function'. It may or may
4471 not be in the same block as 'argument'. */
4475 /* 'inner' is in a block whose superblock is the one holding
4479 /* If this call is expanded by the compiler, you may see
4480 a nested block here whose function is 'inline_function'
4481 and whose superblock is the one holding 'inner'. */
4487 A @code{gdb.Block} is iterable. The iterator returns the symbols
4488 (@pxref{Symbols In Python}) local to the block. Python programs
4489 should not assume that a specific block object will always contain a
4490 given symbol, since changes in @value{GDBN} features and
4491 infrastructure may cause symbols move across blocks in a symbol
4494 The following block-related functions are available in the @code{gdb}
4497 @findex gdb.block_for_pc
4498 @defun gdb.block_for_pc (pc)
4499 Return the innermost @code{gdb.Block} containing the given @var{pc}
4500 value. If the block cannot be found for the @var{pc} value specified,
4501 the function will return @code{None}.
4504 A @code{gdb.Block} object has the following methods:
4506 @defun Block.is_valid ()
4507 Returns @code{True} if the @code{gdb.Block} object is valid,
4508 @code{False} if not. A block object can become invalid if the block it
4509 refers to doesn't exist anymore in the inferior. All other
4510 @code{gdb.Block} methods will throw an exception if it is invalid at
4511 the time the method is called. The block's validity is also checked
4512 during iteration over symbols of the block.
4515 A @code{gdb.Block} object has the following attributes:
4518 The start address of the block. This attribute is not writable.
4522 One past the last address that appears in the block. This attribute
4526 @defvar Block.function
4527 The name of the block represented as a @code{gdb.Symbol}. If the
4528 block is not named, then this attribute holds @code{None}. This
4529 attribute is not writable.
4531 For ordinary function blocks, the superblock is the static block.
4532 However, you should note that it is possible for a function block to
4533 have a superblock that is not the static block -- for instance this
4534 happens for an inlined function.
4537 @defvar Block.superblock
4538 The block containing this block. If this parent block does not exist,
4539 this attribute holds @code{None}. This attribute is not writable.
4542 @defvar Block.global_block
4543 The global block associated with this block. This attribute is not
4547 @defvar Block.static_block
4548 The static block associated with this block. This attribute is not
4552 @defvar Block.is_global
4553 @code{True} if the @code{gdb.Block} object is a global block,
4554 @code{False} if not. This attribute is not
4558 @defvar Block.is_static
4559 @code{True} if the @code{gdb.Block} object is a static block,
4560 @code{False} if not. This attribute is not writable.
4563 @node Symbols In Python
4564 @subsubsection Python representation of Symbols.
4566 @cindex symbols in python
4569 @value{GDBN} represents every variable, function and type as an
4570 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
4571 Similarly, Python represents these symbols in @value{GDBN} with the
4572 @code{gdb.Symbol} object.
4574 The following symbol-related functions are available in the @code{gdb}
4577 @findex gdb.lookup_symbol
4578 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
4579 This function searches for a symbol by name. The search scope can be
4580 restricted to the parameters defined in the optional domain and block
4583 @var{name} is the name of the symbol. It must be a string. The
4584 optional @var{block} argument restricts the search to symbols visible
4585 in that @var{block}. The @var{block} argument must be a
4586 @code{gdb.Block} object. If omitted, the block for the current frame
4587 is used. The optional @var{domain} argument restricts
4588 the search to the domain type. The @var{domain} argument must be a
4589 domain constant defined in the @code{gdb} module and described later
4592 The result is a tuple of two elements.
4593 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
4595 If the symbol is found, the second element is @code{True} if the symbol
4596 is a field of a method's object (e.g., @code{this} in C@t{++}),
4597 otherwise it is @code{False}.
4598 If the symbol is not found, the second element is @code{False}.
4601 @findex gdb.lookup_global_symbol
4602 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
4603 This function searches for a global symbol by name.
4604 The search scope can be restricted to by the domain argument.
4606 @var{name} is the name of the symbol. It must be a string.
4607 The optional @var{domain} argument restricts the search to the domain type.
4608 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4609 module and described later in this chapter.
4611 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4615 A @code{gdb.Symbol} object has the following attributes:
4618 The type of the symbol or @code{None} if no type is recorded.
4619 This attribute is represented as a @code{gdb.Type} object.
4620 @xref{Types In Python}. This attribute is not writable.
4623 @defvar Symbol.symtab
4624 The symbol table in which the symbol appears. This attribute is
4625 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
4626 Python}. This attribute is not writable.
4630 The line number in the source code at which the symbol was defined.
4635 The name of the symbol as a string. This attribute is not writable.
4638 @defvar Symbol.linkage_name
4639 The name of the symbol, as used by the linker (i.e., may be mangled).
4640 This attribute is not writable.
4643 @defvar Symbol.print_name
4644 The name of the symbol in a form suitable for output. This is either
4645 @code{name} or @code{linkage_name}, depending on whether the user
4646 asked @value{GDBN} to display demangled or mangled names.
4649 @defvar Symbol.addr_class
4650 The address class of the symbol. This classifies how to find the value
4651 of a symbol. Each address class is a constant defined in the
4652 @code{gdb} module and described later in this chapter.
4655 @defvar Symbol.needs_frame
4656 This is @code{True} if evaluating this symbol's value requires a frame
4657 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
4658 local variables will require a frame, but other symbols will not.
4661 @defvar Symbol.is_argument
4662 @code{True} if the symbol is an argument of a function.
4665 @defvar Symbol.is_constant
4666 @code{True} if the symbol is a constant.
4669 @defvar Symbol.is_function
4670 @code{True} if the symbol is a function or a method.
4673 @defvar Symbol.is_variable
4674 @code{True} if the symbol is a variable.
4677 A @code{gdb.Symbol} object has the following methods:
4679 @defun Symbol.is_valid ()
4680 Returns @code{True} if the @code{gdb.Symbol} object is valid,
4681 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
4682 the symbol it refers to does not exist in @value{GDBN} any longer.
4683 All other @code{gdb.Symbol} methods will throw an exception if it is
4684 invalid at the time the method is called.
4687 @defun Symbol.value (@r{[}frame@r{]})
4688 Compute the value of the symbol, as a @code{gdb.Value}. For
4689 functions, this computes the address of the function, cast to the
4690 appropriate type. If the symbol requires a frame in order to compute
4691 its value, then @var{frame} must be given. If @var{frame} is not
4692 given, or if @var{frame} is invalid, then this method will throw an
4696 The available domain categories in @code{gdb.Symbol} are represented
4697 as constants in the @code{gdb} module:
4700 @vindex SYMBOL_UNDEF_DOMAIN
4701 @item gdb.SYMBOL_UNDEF_DOMAIN
4702 This is used when a domain has not been discovered or none of the
4703 following domains apply. This usually indicates an error either
4704 in the symbol information or in @value{GDBN}'s handling of symbols.
4706 @vindex SYMBOL_VAR_DOMAIN
4707 @item gdb.SYMBOL_VAR_DOMAIN
4708 This domain contains variables, function names, typedef names and enum
4711 @vindex SYMBOL_STRUCT_DOMAIN
4712 @item gdb.SYMBOL_STRUCT_DOMAIN
4713 This domain holds struct, union and enum type names.
4715 @vindex SYMBOL_LABEL_DOMAIN
4716 @item gdb.SYMBOL_LABEL_DOMAIN
4717 This domain contains names of labels (for gotos).
4719 @vindex SYMBOL_VARIABLES_DOMAIN
4720 @item gdb.SYMBOL_VARIABLES_DOMAIN
4721 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
4722 contains everything minus functions and types.
4724 @vindex SYMBOL_FUNCTIONS_DOMAIN
4725 @item gdb.SYMBOL_FUNCTIONS_DOMAIN
4726 This domain contains all functions.
4728 @vindex SYMBOL_TYPES_DOMAIN
4729 @item gdb.SYMBOL_TYPES_DOMAIN
4730 This domain contains all types.
4733 The available address class categories in @code{gdb.Symbol} are represented
4734 as constants in the @code{gdb} module:
4737 @vindex SYMBOL_LOC_UNDEF
4738 @item gdb.SYMBOL_LOC_UNDEF
4739 If this is returned by address class, it indicates an error either in
4740 the symbol information or in @value{GDBN}'s handling of symbols.
4742 @vindex SYMBOL_LOC_CONST
4743 @item gdb.SYMBOL_LOC_CONST
4744 Value is constant int.
4746 @vindex SYMBOL_LOC_STATIC
4747 @item gdb.SYMBOL_LOC_STATIC
4748 Value is at a fixed address.
4750 @vindex SYMBOL_LOC_REGISTER
4751 @item gdb.SYMBOL_LOC_REGISTER
4752 Value is in a register.
4754 @vindex SYMBOL_LOC_ARG
4755 @item gdb.SYMBOL_LOC_ARG
4756 Value is an argument. This value is at the offset stored within the
4757 symbol inside the frame's argument list.
4759 @vindex SYMBOL_LOC_REF_ARG
4760 @item gdb.SYMBOL_LOC_REF_ARG
4761 Value address is stored in the frame's argument list. Just like
4762 @code{LOC_ARG} except that the value's address is stored at the
4763 offset, not the value itself.
4765 @vindex SYMBOL_LOC_REGPARM_ADDR
4766 @item gdb.SYMBOL_LOC_REGPARM_ADDR
4767 Value is a specified register. Just like @code{LOC_REGISTER} except
4768 the register holds the address of the argument instead of the argument
4771 @vindex SYMBOL_LOC_LOCAL
4772 @item gdb.SYMBOL_LOC_LOCAL
4773 Value is a local variable.
4775 @vindex SYMBOL_LOC_TYPEDEF
4776 @item gdb.SYMBOL_LOC_TYPEDEF
4777 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
4780 @vindex SYMBOL_LOC_BLOCK
4781 @item gdb.SYMBOL_LOC_BLOCK
4784 @vindex SYMBOL_LOC_CONST_BYTES
4785 @item gdb.SYMBOL_LOC_CONST_BYTES
4786 Value is a byte-sequence.
4788 @vindex SYMBOL_LOC_UNRESOLVED
4789 @item gdb.SYMBOL_LOC_UNRESOLVED
4790 Value is at a fixed address, but the address of the variable has to be
4791 determined from the minimal symbol table whenever the variable is
4794 @vindex SYMBOL_LOC_OPTIMIZED_OUT
4795 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
4796 The value does not actually exist in the program.
4798 @vindex SYMBOL_LOC_COMPUTED
4799 @item gdb.SYMBOL_LOC_COMPUTED
4800 The value's address is a computed location.
4803 @node Symbol Tables In Python
4804 @subsubsection Symbol table representation in Python.
4806 @cindex symbol tables in python
4808 @tindex gdb.Symtab_and_line
4810 Access to symbol table data maintained by @value{GDBN} on the inferior
4811 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
4812 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
4813 from the @code{find_sal} method in @code{gdb.Frame} object.
4814 @xref{Frames In Python}.
4816 For more information on @value{GDBN}'s symbol table management, see
4817 @ref{Symbols, ,Examining the Symbol Table}, for more information.
4819 A @code{gdb.Symtab_and_line} object has the following attributes:
4821 @defvar Symtab_and_line.symtab
4822 The symbol table object (@code{gdb.Symtab}) for this frame.
4823 This attribute is not writable.
4826 @defvar Symtab_and_line.pc
4827 Indicates the start of the address range occupied by code for the
4828 current source line. This attribute is not writable.
4831 @defvar Symtab_and_line.last
4832 Indicates the end of the address range occupied by code for the current
4833 source line. This attribute is not writable.
4836 @defvar Symtab_and_line.line
4837 Indicates the current line number for this object. This
4838 attribute is not writable.
4841 A @code{gdb.Symtab_and_line} object has the following methods:
4843 @defun Symtab_and_line.is_valid ()
4844 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
4845 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
4846 invalid if the Symbol table and line object it refers to does not
4847 exist in @value{GDBN} any longer. All other
4848 @code{gdb.Symtab_and_line} methods will throw an exception if it is
4849 invalid at the time the method is called.
4852 A @code{gdb.Symtab} object has the following attributes:
4854 @defvar Symtab.filename
4855 The symbol table's source filename. This attribute is not writable.
4858 @defvar Symtab.objfile
4859 The symbol table's backing object file. @xref{Objfiles In Python}.
4860 This attribute is not writable.
4863 @defvar Symtab.producer
4864 The name and possibly version number of the program that
4865 compiled the code in the symbol table.
4866 The contents of this string is up to the compiler.
4867 If no producer information is available then @code{None} is returned.
4868 This attribute is not writable.
4871 A @code{gdb.Symtab} object has the following methods:
4873 @defun Symtab.is_valid ()
4874 Returns @code{True} if the @code{gdb.Symtab} object is valid,
4875 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
4876 the symbol table it refers to does not exist in @value{GDBN} any
4877 longer. All other @code{gdb.Symtab} methods will throw an exception
4878 if it is invalid at the time the method is called.
4881 @defun Symtab.fullname ()
4882 Return the symbol table's source absolute file name.
4885 @defun Symtab.global_block ()
4886 Return the global block of the underlying symbol table.
4887 @xref{Blocks In Python}.
4890 @defun Symtab.static_block ()
4891 Return the static block of the underlying symbol table.
4892 @xref{Blocks In Python}.
4895 @defun Symtab.linetable ()
4896 Return the line table associated with the symbol table.
4897 @xref{Line Tables In Python}.
4900 @node Line Tables In Python
4901 @subsubsection Manipulating line tables using Python
4903 @cindex line tables in python
4904 @tindex gdb.LineTable
4906 Python code can request and inspect line table information from a
4907 symbol table that is loaded in @value{GDBN}. A line table is a
4908 mapping of source lines to their executable locations in memory. To
4909 acquire the line table information for a particular symbol table, use
4910 the @code{linetable} function (@pxref{Symbol Tables In Python}).
4912 A @code{gdb.LineTable} is iterable. The iterator returns
4913 @code{LineTableEntry} objects that correspond to the source line and
4914 address for each line table entry. @code{LineTableEntry} objects have
4915 the following attributes:
4917 @defvar LineTableEntry.line
4918 The source line number for this line table entry. This number
4919 corresponds to the actual line of source. This attribute is not
4923 @defvar LineTableEntry.pc
4924 The address that is associated with the line table entry where the
4925 executable code for that source line resides in memory. This
4926 attribute is not writable.
4929 As there can be multiple addresses for a single source line, you may
4930 receive multiple @code{LineTableEntry} objects with matching
4931 @code{line} attributes, but with different @code{pc} attributes. The
4932 iterator is sorted in ascending @code{pc} order. Here is a small
4933 example illustrating iterating over a line table.
4936 symtab = gdb.selected_frame().find_sal().symtab
4937 linetable = symtab.linetable()
4938 for line in linetable:
4939 print "Line: "+str(line.line)+" Address: "+hex(line.pc)
4942 This will have the following output:
4945 Line: 33 Address: 0x4005c8L
4946 Line: 37 Address: 0x4005caL
4947 Line: 39 Address: 0x4005d2L
4948 Line: 40 Address: 0x4005f8L
4949 Line: 42 Address: 0x4005ffL
4950 Line: 44 Address: 0x400608L
4951 Line: 42 Address: 0x40060cL
4952 Line: 45 Address: 0x400615L
4955 In addition to being able to iterate over a @code{LineTable}, it also
4956 has the following direct access methods:
4958 @defun LineTable.line (line)
4959 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
4960 entries in the line table for the given @var{line}, which specifies
4961 the source code line. If there are no entries for that source code
4962 @var{line}, the Python @code{None} is returned.
4965 @defun LineTable.has_line (line)
4966 Return a Python @code{Boolean} indicating whether there is an entry in
4967 the line table for this source line. Return @code{True} if an entry
4968 is found, or @code{False} if not.
4971 @defun LineTable.source_lines ()
4972 Return a Python @code{List} of the source line numbers in the symbol
4973 table. Only lines with executable code locations are returned. The
4974 contents of the @code{List} will just be the source line entries
4975 represented as Python @code{Long} values.
4978 @node Breakpoints In Python
4979 @subsubsection Manipulating breakpoints using Python
4981 @cindex breakpoints in python
4982 @tindex gdb.Breakpoint
4984 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
4987 A breakpoint can be created using one of the two forms of the
4988 @code{gdb.Breakpoint} constructor. The first one accepts a string
4989 like one would pass to the @code{break}
4990 (@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
4991 (@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
4992 create both breakpoints and watchpoints. The second accepts separate Python
4993 arguments similar to @ref{Explicit Locations}, and can only be used to create
4996 @defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]})
4997 Create a new breakpoint according to @var{spec}, which is a string naming the
4998 location of a breakpoint, or an expression that defines a watchpoint. The
4999 string should describe a location in a format recognized by the @code{break}
5000 command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
5001 watchpoint, by the @code{watch} command
5002 (@pxref{Set Watchpoints, , Setting Watchpoints}).
5004 The optional @var{type} argument specifies the type of the breakpoint to create,
5007 The optional @var{wp_class} argument defines the class of watchpoint to create,
5008 if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
5009 defaults to @code{gdb.WP_WRITE}.
5011 The optional @var{internal} argument allows the breakpoint to become invisible
5012 to the user. The breakpoint will neither be reported when created, nor will it
5013 be listed in the output from @code{info breakpoints} (but will be listed with
5014 the @code{maint info breakpoints} command).
5016 The optional @var{temporary} argument makes the breakpoint a temporary
5017 breakpoint. Temporary breakpoints are deleted after they have been hit. Any
5018 further access to the Python breakpoint after it has been hit will result in a
5019 runtime error (as that breakpoint has now been automatically deleted).
5021 The optional @var{qualified} argument is a boolean that allows interpreting
5022 the function passed in @code{spec} as a fully-qualified name. It is equivalent
5023 to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
5024 @ref{Explicit Locations}).
5028 @defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]})
5029 This second form of creating a new breakpoint specifies the explicit
5030 location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
5031 be created in the specified source file @var{source}, at the specified
5032 @var{function}, @var{label} and @var{line}.
5034 @var{internal}, @var{temporary} and @var{qualified} have the same usage as
5035 explained previously.
5038 The available types are represented by constants defined in the @code{gdb}
5042 @vindex BP_BREAKPOINT
5043 @item gdb.BP_BREAKPOINT
5044 Normal code breakpoint.
5046 @vindex BP_WATCHPOINT
5047 @item gdb.BP_WATCHPOINT
5048 Watchpoint breakpoint.
5050 @vindex BP_HARDWARE_WATCHPOINT
5051 @item gdb.BP_HARDWARE_WATCHPOINT
5052 Hardware assisted watchpoint.
5054 @vindex BP_READ_WATCHPOINT
5055 @item gdb.BP_READ_WATCHPOINT
5056 Hardware assisted read watchpoint.
5058 @vindex BP_ACCESS_WATCHPOINT
5059 @item gdb.BP_ACCESS_WATCHPOINT
5060 Hardware assisted access watchpoint.
5063 The available watchpoint types represented by constants are defined in the
5069 Read only watchpoint.
5073 Write only watchpoint.
5077 Read/Write watchpoint.
5080 @defun Breakpoint.stop (self)
5081 The @code{gdb.Breakpoint} class can be sub-classed and, in
5082 particular, you may choose to implement the @code{stop} method.
5083 If this method is defined in a sub-class of @code{gdb.Breakpoint},
5084 it will be called when the inferior reaches any location of a
5085 breakpoint which instantiates that sub-class. If the method returns
5086 @code{True}, the inferior will be stopped at the location of the
5087 breakpoint, otherwise the inferior will continue.
5089 If there are multiple breakpoints at the same location with a
5090 @code{stop} method, each one will be called regardless of the
5091 return status of the previous. This ensures that all @code{stop}
5092 methods have a chance to execute at that location. In this scenario
5093 if one of the methods returns @code{True} but the others return
5094 @code{False}, the inferior will still be stopped.
5096 You should not alter the execution state of the inferior (i.e.@:, step,
5097 next, etc.), alter the current frame context (i.e.@:, change the current
5098 active frame), or alter, add or delete any breakpoint. As a general
5099 rule, you should not alter any data within @value{GDBN} or the inferior
5102 Example @code{stop} implementation:
5105 class MyBreakpoint (gdb.Breakpoint):
5107 inf_val = gdb.parse_and_eval("foo")
5114 @defun Breakpoint.is_valid ()
5115 Return @code{True} if this @code{Breakpoint} object is valid,
5116 @code{False} otherwise. A @code{Breakpoint} object can become invalid
5117 if the user deletes the breakpoint. In this case, the object still
5118 exists, but the underlying breakpoint does not. In the cases of
5119 watchpoint scope, the watchpoint remains valid even if execution of the
5120 inferior leaves the scope of that watchpoint.
5123 @defun Breakpoint.delete ()
5124 Permanently deletes the @value{GDBN} breakpoint. This also
5125 invalidates the Python @code{Breakpoint} object. Any further access
5126 to this object's attributes or methods will raise an error.
5129 @defvar Breakpoint.enabled
5130 This attribute is @code{True} if the breakpoint is enabled, and
5131 @code{False} otherwise. This attribute is writable. You can use it to enable
5132 or disable the breakpoint.
5135 @defvar Breakpoint.silent
5136 This attribute is @code{True} if the breakpoint is silent, and
5137 @code{False} otherwise. This attribute is writable.
5139 Note that a breakpoint can also be silent if it has commands and the
5140 first command is @code{silent}. This is not reported by the
5141 @code{silent} attribute.
5144 @defvar Breakpoint.pending
5145 This attribute is @code{True} if the breakpoint is pending, and
5146 @code{False} otherwise. @xref{Set Breaks}. This attribute is
5150 @anchor{python_breakpoint_thread}
5151 @defvar Breakpoint.thread
5152 If the breakpoint is thread-specific, this attribute holds the
5153 thread's global id. If the breakpoint is not thread-specific, this
5154 attribute is @code{None}. This attribute is writable.
5157 @defvar Breakpoint.task
5158 If the breakpoint is Ada task-specific, this attribute holds the Ada task
5159 id. If the breakpoint is not task-specific (or the underlying
5160 language is not Ada), this attribute is @code{None}. This attribute
5164 @defvar Breakpoint.ignore_count
5165 This attribute holds the ignore count for the breakpoint, an integer.
5166 This attribute is writable.
5169 @defvar Breakpoint.number
5170 This attribute holds the breakpoint's number --- the identifier used by
5171 the user to manipulate the breakpoint. This attribute is not writable.
5174 @defvar Breakpoint.type
5175 This attribute holds the breakpoint's type --- the identifier used to
5176 determine the actual breakpoint type or use-case. This attribute is not
5180 @defvar Breakpoint.visible
5181 This attribute tells whether the breakpoint is visible to the user
5182 when set, or when the @samp{info breakpoints} command is run. This
5183 attribute is not writable.
5186 @defvar Breakpoint.temporary
5187 This attribute indicates whether the breakpoint was created as a
5188 temporary breakpoint. Temporary breakpoints are automatically deleted
5189 after that breakpoint has been hit. Access to this attribute, and all
5190 other attributes and functions other than the @code{is_valid}
5191 function, will result in an error after the breakpoint has been hit
5192 (as it has been automatically deleted). This attribute is not
5196 @defvar Breakpoint.hit_count
5197 This attribute holds the hit count for the breakpoint, an integer.
5198 This attribute is writable, but currently it can only be set to zero.
5201 @defvar Breakpoint.location
5202 This attribute holds the location of the breakpoint, as specified by
5203 the user. It is a string. If the breakpoint does not have a location
5204 (that is, it is a watchpoint) the attribute's value is @code{None}. This
5205 attribute is not writable.
5208 @defvar Breakpoint.expression
5209 This attribute holds a breakpoint expression, as specified by
5210 the user. It is a string. If the breakpoint does not have an
5211 expression (the breakpoint is not a watchpoint) the attribute's value
5212 is @code{None}. This attribute is not writable.
5215 @defvar Breakpoint.condition
5216 This attribute holds the condition of the breakpoint, as specified by
5217 the user. It is a string. If there is no condition, this attribute's
5218 value is @code{None}. This attribute is writable.
5221 @defvar Breakpoint.commands
5222 This attribute holds the commands attached to the breakpoint. If
5223 there are commands, this attribute's value is a string holding all the
5224 commands, separated by newlines. If there are no commands, this
5225 attribute is @code{None}. This attribute is writable.
5228 @node Finish Breakpoints in Python
5229 @subsubsection Finish Breakpoints
5231 @cindex python finish breakpoints
5232 @tindex gdb.FinishBreakpoint
5234 A finish breakpoint is a temporary breakpoint set at the return address of
5235 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
5236 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
5237 and deleted when the execution will run out of the breakpoint scope (i.e.@:
5238 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
5239 Finish breakpoints are thread specific and must be create with the right
5242 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
5243 Create a finish breakpoint at the return address of the @code{gdb.Frame}
5244 object @var{frame}. If @var{frame} is not provided, this defaults to the
5245 newest frame. The optional @var{internal} argument allows the breakpoint to
5246 become invisible to the user. @xref{Breakpoints In Python}, for further
5247 details about this argument.
5250 @defun FinishBreakpoint.out_of_scope (self)
5251 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
5252 @code{return} command, @dots{}), a function may not properly terminate, and
5253 thus never hit the finish breakpoint. When @value{GDBN} notices such a
5254 situation, the @code{out_of_scope} callback will be triggered.
5256 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
5260 class MyFinishBreakpoint (gdb.FinishBreakpoint)
5262 print "normal finish"
5265 def out_of_scope ():
5266 print "abnormal finish"
5270 @defvar FinishBreakpoint.return_value
5271 When @value{GDBN} is stopped at a finish breakpoint and the frame
5272 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
5273 attribute will contain a @code{gdb.Value} object corresponding to the return
5274 value of the function. The value will be @code{None} if the function return
5275 type is @code{void} or if the return value was not computable. This attribute
5279 @node Lazy Strings In Python
5280 @subsubsection Python representation of lazy strings.
5282 @cindex lazy strings in python
5283 @tindex gdb.LazyString
5285 A @dfn{lazy string} is a string whose contents is not retrieved or
5286 encoded until it is needed.
5288 A @code{gdb.LazyString} is represented in @value{GDBN} as an
5289 @code{address} that points to a region of memory, an @code{encoding}
5290 that will be used to encode that region of memory, and a @code{length}
5291 to delimit the region of memory that represents the string. The
5292 difference between a @code{gdb.LazyString} and a string wrapped within
5293 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
5294 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
5295 retrieved and encoded during printing, while a @code{gdb.Value}
5296 wrapping a string is immediately retrieved and encoded on creation.
5298 A @code{gdb.LazyString} object has the following functions:
5300 @defun LazyString.value ()
5301 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
5302 will point to the string in memory, but will lose all the delayed
5303 retrieval, encoding and handling that @value{GDBN} applies to a
5304 @code{gdb.LazyString}.
5307 @defvar LazyString.address
5308 This attribute holds the address of the string. This attribute is not
5312 @defvar LazyString.length
5313 This attribute holds the length of the string in characters. If the
5314 length is -1, then the string will be fetched and encoded up to the
5315 first null of appropriate width. This attribute is not writable.
5318 @defvar LazyString.encoding
5319 This attribute holds the encoding that will be applied to the string
5320 when the string is printed by @value{GDBN}. If the encoding is not
5321 set, or contains an empty string, then @value{GDBN} will select the
5322 most appropriate encoding when the string is printed. This attribute
5326 @defvar LazyString.type
5327 This attribute holds the type that is represented by the lazy string's
5328 type. For a lazy string this is a pointer or array type. To
5329 resolve this to the lazy string's character type, use the type's
5330 @code{target} method. @xref{Types In Python}. This attribute is not
5334 @node Architectures In Python
5335 @subsubsection Python representation of architectures
5336 @cindex Python architectures
5338 @value{GDBN} uses architecture specific parameters and artifacts in a
5339 number of its various computations. An architecture is represented
5340 by an instance of the @code{gdb.Architecture} class.
5342 A @code{gdb.Architecture} class has the following methods:
5344 @defun Architecture.name ()
5345 Return the name (string value) of the architecture.
5348 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
5349 Return a list of disassembled instructions starting from the memory
5350 address @var{start_pc}. The optional arguments @var{end_pc} and
5351 @var{count} determine the number of instructions in the returned list.
5352 If both the optional arguments @var{end_pc} and @var{count} are
5353 specified, then a list of at most @var{count} disassembled instructions
5354 whose start address falls in the closed memory address interval from
5355 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
5356 specified, but @var{count} is specified, then @var{count} number of
5357 instructions starting from the address @var{start_pc} are returned. If
5358 @var{count} is not specified but @var{end_pc} is specified, then all
5359 instructions whose start address falls in the closed memory address
5360 interval from @var{start_pc} to @var{end_pc} are returned. If neither
5361 @var{end_pc} nor @var{count} are specified, then a single instruction at
5362 @var{start_pc} is returned. For all of these cases, each element of the
5363 returned list is a Python @code{dict} with the following string keys:
5368 The value corresponding to this key is a Python long integer capturing
5369 the memory address of the instruction.
5372 The value corresponding to this key is a string value which represents
5373 the instruction with assembly language mnemonics. The assembly
5374 language flavor used is the same as that specified by the current CLI
5375 variable @code{disassembly-flavor}. @xref{Machine Code}.
5378 The value corresponding to this key is the length (integer value) of the
5379 instruction in bytes.
5384 @node Python Auto-loading
5385 @subsection Python Auto-loading
5386 @cindex Python auto-loading
5388 When a new object file is read (for example, due to the @code{file}
5389 command, or because the inferior has loaded a shared library),
5390 @value{GDBN} will look for Python support scripts in several ways:
5391 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
5392 @xref{Auto-loading extensions}.
5394 The auto-loading feature is useful for supplying application-specific
5395 debugging commands and scripts.
5397 Auto-loading can be enabled or disabled,
5398 and the list of auto-loaded scripts can be printed.
5401 @anchor{set auto-load python-scripts}
5402 @kindex set auto-load python-scripts
5403 @item set auto-load python-scripts [on|off]
5404 Enable or disable the auto-loading of Python scripts.
5406 @anchor{show auto-load python-scripts}
5407 @kindex show auto-load python-scripts
5408 @item show auto-load python-scripts
5409 Show whether auto-loading of Python scripts is enabled or disabled.
5411 @anchor{info auto-load python-scripts}
5412 @kindex info auto-load python-scripts
5413 @cindex print list of auto-loaded Python scripts
5414 @item info auto-load python-scripts [@var{regexp}]
5415 Print the list of all Python scripts that @value{GDBN} auto-loaded.
5417 Also printed is the list of Python scripts that were mentioned in
5418 the @code{.debug_gdb_scripts} section and were either not found
5419 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
5420 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
5421 This is useful because their names are not printed when @value{GDBN}
5422 tries to load them and fails. There may be many of them, and printing
5423 an error message for each one is problematic.
5425 If @var{regexp} is supplied only Python scripts with matching names are printed.
5430 (gdb) info auto-load python-scripts
5432 Yes py-section-script.py
5433 full name: /tmp/py-section-script.py
5434 No my-foo-pretty-printers.py
5438 When reading an auto-loaded file or script, @value{GDBN} sets the
5439 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
5440 function (@pxref{Objfiles In Python}). This can be useful for
5441 registering objfile-specific pretty-printers and frame-filters.
5443 @node Python modules
5444 @subsection Python modules
5445 @cindex python modules
5447 @value{GDBN} comes with several modules to assist writing Python code.
5450 * gdb.printing:: Building and registering pretty-printers.
5451 * gdb.types:: Utilities for working with types.
5452 * gdb.prompt:: Utilities for prompt value substitution.
5456 @subsubsection gdb.printing
5457 @cindex gdb.printing
5459 This module provides a collection of utilities for working with
5463 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
5464 This class specifies the API that makes @samp{info pretty-printer},
5465 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
5466 Pretty-printers should generally inherit from this class.
5468 @item SubPrettyPrinter (@var{name})
5469 For printers that handle multiple types, this class specifies the
5470 corresponding API for the subprinters.
5472 @item RegexpCollectionPrettyPrinter (@var{name})
5473 Utility class for handling multiple printers, all recognized via
5474 regular expressions.
5475 @xref{Writing a Pretty-Printer}, for an example.
5477 @item FlagEnumerationPrinter (@var{name})
5478 A pretty-printer which handles printing of @code{enum} values. Unlike
5479 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
5480 work properly when there is some overlap between the enumeration
5481 constants. The argument @var{name} is the name of the printer and
5482 also the name of the @code{enum} type to look up.
5484 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
5485 Register @var{printer} with the pretty-printer list of @var{obj}.
5486 If @var{replace} is @code{True} then any existing copy of the printer
5487 is replaced. Otherwise a @code{RuntimeError} exception is raised
5488 if a printer with the same name already exists.
5492 @subsubsection gdb.types
5495 This module provides a collection of utilities for working with
5496 @code{gdb.Type} objects.
5499 @item get_basic_type (@var{type})
5500 Return @var{type} with const and volatile qualifiers stripped,
5501 and with typedefs and C@t{++} references converted to the underlying type.
5506 typedef const int const_int;
5508 const_int& foo_ref (foo);
5509 int main () @{ return 0; @}
5516 (gdb) python import gdb.types
5517 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
5518 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
5522 @item has_field (@var{type}, @var{field})
5523 Return @code{True} if @var{type}, assumed to be a type with fields
5524 (e.g., a structure or union), has field @var{field}.
5526 @item make_enum_dict (@var{enum_type})
5527 Return a Python @code{dictionary} type produced from @var{enum_type}.
5529 @item deep_items (@var{type})
5530 Returns a Python iterator similar to the standard
5531 @code{gdb.Type.iteritems} method, except that the iterator returned
5532 by @code{deep_items} will recursively traverse anonymous struct or
5533 union fields. For example:
5547 Then in @value{GDBN}:
5549 (@value{GDBP}) python import gdb.types
5550 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
5551 (@value{GDBP}) python print struct_a.keys ()
5553 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
5554 @{['a', 'b0', 'b1']@}
5557 @item get_type_recognizers ()
5558 Return a list of the enabled type recognizers for the current context.
5559 This is called by @value{GDBN} during the type-printing process
5560 (@pxref{Type Printing API}).
5562 @item apply_type_recognizers (recognizers, type_obj)
5563 Apply the type recognizers, @var{recognizers}, to the type object
5564 @var{type_obj}. If any recognizer returns a string, return that
5565 string. Otherwise, return @code{None}. This is called by
5566 @value{GDBN} during the type-printing process (@pxref{Type Printing
5569 @item register_type_printer (locus, printer)
5570 This is a convenience function to register a type printer
5571 @var{printer}. The printer must implement the type printer protocol.
5572 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
5573 the printer is registered with that objfile; a @code{gdb.Progspace},
5574 in which case the printer is registered with that progspace; or
5575 @code{None}, in which case the printer is registered globally.
5578 This is a base class that implements the type printer protocol. Type
5579 printers are encouraged, but not required, to derive from this class.
5580 It defines a constructor:
5582 @defmethod TypePrinter __init__ (self, name)
5583 Initialize the type printer with the given name. The new printer
5584 starts in the enabled state.
5590 @subsubsection gdb.prompt
5593 This module provides a method for prompt value-substitution.
5596 @item substitute_prompt (@var{string})
5597 Return @var{string} with escape sequences substituted by values. Some
5598 escape sequences take arguments. You can specify arguments inside
5599 ``@{@}'' immediately following the escape sequence.
5601 The escape sequences you can pass to this function are:
5605 Substitute a backslash.
5607 Substitute an ESC character.
5609 Substitute the selected frame; an argument names a frame parameter.
5611 Substitute a newline.
5613 Substitute a parameter's value; the argument names the parameter.
5615 Substitute a carriage return.
5617 Substitute the selected thread; an argument names a thread parameter.
5619 Substitute the version of GDB.
5621 Substitute the current working directory.
5623 Begin a sequence of non-printing characters. These sequences are
5624 typically used with the ESC character, and are not counted in the string
5625 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
5626 blue-colored ``(gdb)'' prompt where the length is five.
5628 End a sequence of non-printing characters.
5634 substitute_prompt (``frame: \f,
5635 print arguments: \p@{print frame-arguments@}'')
5638 @exdent will return the string:
5641 "frame: main, print arguments: scalars"