1 @c Copyright (C) 2008-2015 Free Software Foundation, Inc.
2 @c Permission is granted to copy, distribute and/or modify this document
3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
4 @c any later version published by the Free Software Foundation; with the
5 @c Invariant Sections being ``Free Software'' and ``Free Software Needs
6 @c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
7 @c and with the Back-Cover Texts as in (a) below.
9 @c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
10 @c this GNU Manual. Buying copies from GNU Press supports the FSF in
11 @c developing GNU and promoting software freedom.''
14 @section Extending @value{GDBN} using Python
15 @cindex python scripting
16 @cindex scripting with python
18 You can extend @value{GDBN} using the @uref{http://www.python.org/,
19 Python programming language}. This feature is available only if
20 @value{GDBN} was configured using @option{--with-python}.
22 @cindex python directory
23 Python scripts used by @value{GDBN} should be installed in
24 @file{@var{data-directory}/python}, where @var{data-directory} is
25 the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
26 This directory, known as the @dfn{python directory},
27 is automatically added to the Python Search Path in order to allow
28 the Python interpreter to locate all scripts installed at this location.
30 Additionally, @value{GDBN} commands and convenience functions which
31 are written in Python and are located in the
32 @file{@var{data-directory}/python/gdb/command} or
33 @file{@var{data-directory}/python/gdb/function} directories are
34 automatically imported when @value{GDBN} starts.
37 * Python Commands:: Accessing Python from @value{GDBN}.
38 * Python API:: Accessing @value{GDBN} from Python.
39 * Python Auto-loading:: Automatically loading Python code.
40 * Python modules:: Python modules provided by @value{GDBN}.
44 @subsection Python Commands
45 @cindex python commands
46 @cindex commands to access python
48 @value{GDBN} provides two commands for accessing the Python interpreter,
49 and one related setting:
52 @kindex python-interactive
54 @item python-interactive @r{[}@var{command}@r{]}
55 @itemx pi @r{[}@var{command}@r{]}
56 Without an argument, the @code{python-interactive} command can be used
57 to start an interactive Python prompt. To return to @value{GDBN},
58 type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
60 Alternatively, a single-line Python command can be given as an
61 argument and evaluated. If the command is an expression, the result
62 will be printed; otherwise, nothing will be printed. For example:
65 (@value{GDBP}) python-interactive 2 + 3
71 @item python @r{[}@var{command}@r{]}
72 @itemx py @r{[}@var{command}@r{]}
73 The @code{python} command can be used to evaluate Python code.
75 If given an argument, the @code{python} command will evaluate the
76 argument as a Python command. For example:
79 (@value{GDBP}) python print 23
83 If you do not provide an argument to @code{python}, it will act as a
84 multi-line command, like @code{define}. In this case, the Python
85 script is made up of subsequent command lines, given after the
86 @code{python} command. This command list is terminated using a line
87 containing @code{end}. For example:
92 End with a line saying just "end".
98 @kindex set python print-stack
99 @item set python print-stack
100 By default, @value{GDBN} will print only the message component of a
101 Python exception when an error occurs in a Python script. This can be
102 controlled using @code{set python print-stack}: if @code{full}, then
103 full Python stack printing is enabled; if @code{none}, then Python stack
104 and message printing is disabled; if @code{message}, the default, only
105 the message component of the error is printed.
108 It is also possible to execute a Python script from the @value{GDBN}
112 @item source @file{script-name}
113 The script name must end with @samp{.py} and @value{GDBN} must be configured
114 to recognize the script language based on filename extension using
115 the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
117 @item python execfile ("script-name")
118 This method is based on the @code{execfile} Python built-in function,
119 and thus is always available.
123 @subsection Python API
125 @cindex programming in python
127 You can get quick online help for @value{GDBN}'s Python API by issuing
128 the command @w{@kbd{python help (gdb)}}.
130 Functions and methods which have two or more optional arguments allow
131 them to be specified using keyword syntax. This allows passing some
132 optional arguments while skipping others. Example:
133 @w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
136 * Basic Python:: Basic Python Functions.
137 * Exception Handling:: How Python exceptions are translated.
138 * Values From Inferior:: Python representation of values.
139 * Types In Python:: Python representation of types.
140 * Pretty Printing API:: Pretty-printing values.
141 * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
142 * Writing a Pretty-Printer:: Writing a Pretty-Printer.
143 * Type Printing API:: Pretty-printing types.
144 * Frame Filter API:: Filtering Frames.
145 * Frame Decorator API:: Decorating Frames.
146 * Writing a Frame Filter:: Writing a Frame Filter.
147 * Xmethods In Python:: Adding and replacing methods of C++ classes.
148 * Xmethod API:: Xmethod types.
149 * Writing an Xmethod:: Writing an xmethod.
150 * Inferiors In Python:: Python representation of inferiors (processes)
151 * Events In Python:: Listening for events from @value{GDBN}.
152 * Threads In Python:: Accessing inferior threads from Python.
153 * Commands In Python:: Implementing new commands in Python.
154 * Parameters In Python:: Adding new @value{GDBN} parameters.
155 * Functions In Python:: Writing new convenience functions.
156 * Progspaces In Python:: Program spaces.
157 * Objfiles In Python:: Object files.
158 * Frames In Python:: Accessing inferior stack frames from Python.
159 * Blocks In Python:: Accessing blocks from Python.
160 * Symbols In Python:: Python representation of symbols.
161 * Symbol Tables In Python:: Python representation of symbol tables.
162 * Line Tables In Python:: Python representation of line tables.
163 * Breakpoints In Python:: Manipulating breakpoints using Python.
164 * Finish Breakpoints in Python:: Setting Breakpoints on function return
166 * Lazy Strings In Python:: Python representation of lazy strings.
167 * Architectures In Python:: Python representation of architectures.
171 @subsubsection Basic Python
173 @cindex python stdout
174 @cindex python pagination
175 At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
176 @code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
177 A Python program which outputs to one of these streams may have its
178 output interrupted by the user (@pxref{Screen Size}). In this
179 situation, a Python @code{KeyboardInterrupt} exception is thrown.
181 Some care must be taken when writing Python code to run in
182 @value{GDBN}. Two things worth noting in particular:
186 @value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
187 Python code must not override these, or even change the options using
188 @code{sigaction}. If your program changes the handling of these
189 signals, @value{GDBN} will most likely stop working correctly. Note
190 that it is unfortunately common for GUI toolkits to install a
191 @code{SIGCHLD} handler.
194 @value{GDBN} takes care to mark its internal file descriptors as
195 close-on-exec. However, this cannot be done in a thread-safe way on
196 all platforms. Your Python programs should be aware of this and
197 should both create new file descriptors with the close-on-exec flag
198 set and arrange to close unneeded file descriptors before starting a
202 @cindex python functions
203 @cindex python module
205 @value{GDBN} introduces a new Python module, named @code{gdb}. All
206 methods and classes added by @value{GDBN} are placed in this module.
207 @value{GDBN} automatically @code{import}s the @code{gdb} module for
208 use in all scripts evaluated by the @code{python} command.
210 @findex gdb.PYTHONDIR
211 @defvar gdb.PYTHONDIR
212 A string containing the python directory (@pxref{Python}).
216 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
217 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
218 If a GDB exception happens while @var{command} runs, it is
219 translated as described in @ref{Exception Handling,,Exception Handling}.
221 The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
222 command as having originated from the user invoking it interactively.
223 It must be a boolean value. If omitted, it defaults to @code{False}.
225 By default, any output produced by @var{command} is sent to
226 @value{GDBN}'s standard output (and to the log output if logging is
227 turned on). If the @var{to_string} parameter is
228 @code{True}, then output will be collected by @code{gdb.execute} and
229 returned as a string. The default is @code{False}, in which case the
230 return value is @code{None}. If @var{to_string} is @code{True}, the
231 @value{GDBN} virtual terminal will be temporarily set to unlimited width
232 and height, and its pagination will be disabled; @pxref{Screen Size}.
235 @findex gdb.breakpoints
236 @defun gdb.breakpoints ()
237 Return a sequence holding all of @value{GDBN}'s breakpoints.
238 @xref{Breakpoints In Python}, for more information.
241 @findex gdb.parameter
242 @defun gdb.parameter (parameter)
243 Return the value of a @value{GDBN} @var{parameter} given by its name,
244 a string; the parameter name string may contain spaces if the parameter has a
245 multi-part name. For example, @samp{print object} is a valid
248 If the named parameter does not exist, this function throws a
249 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
250 parameter's value is converted to a Python value of the appropriate
255 @defun gdb.history (number)
256 Return a value from @value{GDBN}'s value history (@pxref{Value
257 History}). The @var{number} argument indicates which history element to return.
258 If @var{number} is negative, then @value{GDBN} will take its absolute value
259 and count backward from the last element (i.e., the most recent element) to
260 find the value to return. If @var{number} is zero, then @value{GDBN} will
261 return the most recent element. If the element specified by @var{number}
262 doesn't exist in the value history, a @code{gdb.error} exception will be
265 If no exception is raised, the return value is always an instance of
266 @code{gdb.Value} (@pxref{Values From Inferior}).
269 @findex gdb.parse_and_eval
270 @defun gdb.parse_and_eval (expression)
271 Parse @var{expression}, which must be a string, as an expression in
272 the current language, evaluate it, and return the result as a
275 This function can be useful when implementing a new command
276 (@pxref{Commands In Python}), as it provides a way to parse the
277 command's argument as an expression. It is also useful simply to
278 compute values, for example, it is the only way to get the value of a
279 convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
282 @findex gdb.find_pc_line
283 @defun gdb.find_pc_line (pc)
284 Return the @code{gdb.Symtab_and_line} object corresponding to the
285 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
286 value of @var{pc} is passed as an argument, then the @code{symtab} and
287 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
288 will be @code{None} and 0 respectively.
291 @findex gdb.post_event
292 @defun gdb.post_event (event)
293 Put @var{event}, a callable object taking no arguments, into
294 @value{GDBN}'s internal event queue. This callable will be invoked at
295 some later point, during @value{GDBN}'s event processing. Events
296 posted using @code{post_event} will be run in the order in which they
297 were posted; however, there is no way to know when they will be
298 processed relative to other events inside @value{GDBN}.
300 @value{GDBN} is not thread-safe. If your Python program uses multiple
301 threads, you must be careful to only call @value{GDBN}-specific
302 functions in the @value{GDBN} thread. @code{post_event} ensures
306 (@value{GDBP}) python
310 > def __init__(self, message):
311 > self.message = message;
312 > def __call__(self):
313 > gdb.write(self.message)
315 >class MyThread1 (threading.Thread):
317 > gdb.post_event(Writer("Hello "))
319 >class MyThread2 (threading.Thread):
321 > gdb.post_event(Writer("World\n"))
326 (@value{GDBP}) Hello World
331 @defun gdb.write (string @r{[}, stream{]})
332 Print a string to @value{GDBN}'s paginated output stream. The
333 optional @var{stream} determines the stream to print to. The default
334 stream is @value{GDBN}'s standard output stream. Possible stream
341 @value{GDBN}'s standard output stream.
346 @value{GDBN}'s standard error stream.
351 @value{GDBN}'s log stream (@pxref{Logging Output}).
354 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
355 call this function and will automatically direct the output to the
361 Flush the buffer of a @value{GDBN} paginated stream so that the
362 contents are displayed immediately. @value{GDBN} will flush the
363 contents of a stream automatically when it encounters a newline in the
364 buffer. The optional @var{stream} determines the stream to flush. The
365 default stream is @value{GDBN}'s standard output stream. Possible
372 @value{GDBN}'s standard output stream.
377 @value{GDBN}'s standard error stream.
382 @value{GDBN}'s log stream (@pxref{Logging Output}).
386 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
387 call this function for the relevant stream.
390 @findex gdb.target_charset
391 @defun gdb.target_charset ()
392 Return the name of the current target character set (@pxref{Character
393 Sets}). This differs from @code{gdb.parameter('target-charset')} in
394 that @samp{auto} is never returned.
397 @findex gdb.target_wide_charset
398 @defun gdb.target_wide_charset ()
399 Return the name of the current target wide character set
400 (@pxref{Character Sets}). This differs from
401 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
405 @findex gdb.solib_name
406 @defun gdb.solib_name (address)
407 Return the name of the shared library holding the given @var{address}
408 as a string, or @code{None}.
411 @findex gdb.decode_line
412 @defun gdb.decode_line @r{[}expression@r{]}
413 Return locations of the line specified by @var{expression}, or of the
414 current line if no argument was given. This function returns a Python
415 tuple containing two elements. The first element contains a string
416 holding any unparsed section of @var{expression} (or @code{None} if
417 the expression has been fully parsed). The second element contains
418 either @code{None} or another tuple that contains all the locations
419 that match the expression represented as @code{gdb.Symtab_and_line}
420 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
421 provided, it is decoded the way that @value{GDBN}'s inbuilt
422 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
425 @defun gdb.prompt_hook (current_prompt)
428 If @var{prompt_hook} is callable, @value{GDBN} will call the method
429 assigned to this operation before a prompt is displayed by
432 The parameter @code{current_prompt} contains the current @value{GDBN}
433 prompt. This method must return a Python string, or @code{None}. If
434 a string is returned, the @value{GDBN} prompt will be set to that
435 string. If @code{None} is returned, @value{GDBN} will continue to use
438 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
439 such as those used by readline for command input, and annotation
440 related prompts are prohibited from being changed.
443 @node Exception Handling
444 @subsubsection Exception Handling
445 @cindex python exceptions
446 @cindex exceptions, python
448 When executing the @code{python} command, Python exceptions
449 uncaught within the Python code are translated to calls to
450 @value{GDBN} error-reporting mechanism. If the command that called
451 @code{python} does not handle the error, @value{GDBN} will
452 terminate it and print an error message containing the Python
453 exception name, the associated value, and the Python call stack
454 backtrace at the point where the exception was raised. Example:
457 (@value{GDBP}) python print foo
458 Traceback (most recent call last):
459 File "<string>", line 1, in <module>
460 NameError: name 'foo' is not defined
463 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
464 Python code are converted to Python exceptions. The type of the
465 Python exception depends on the error.
469 This is the base class for most exceptions generated by @value{GDBN}.
470 It is derived from @code{RuntimeError}, for compatibility with earlier
471 versions of @value{GDBN}.
473 If an error occurring in @value{GDBN} does not fit into some more
474 specific category, then the generated exception will have this type.
476 @item gdb.MemoryError
477 This is a subclass of @code{gdb.error} which is thrown when an
478 operation tried to access invalid memory in the inferior.
480 @item KeyboardInterrupt
481 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
482 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
485 In all cases, your exception handler will see the @value{GDBN} error
486 message as its value and the Python call stack backtrace at the Python
487 statement closest to where the @value{GDBN} error occured as the
491 When implementing @value{GDBN} commands in Python via @code{gdb.Command},
492 it is useful to be able to throw an exception that doesn't cause a
493 traceback to be printed. For example, the user may have invoked the
494 command incorrectly. Use the @code{gdb.GdbError} exception
495 to handle this case. Example:
499 >class HelloWorld (gdb.Command):
500 > """Greet the whole world."""
501 > def __init__ (self):
502 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
503 > def invoke (self, args, from_tty):
504 > argv = gdb.string_to_argv (args)
505 > if len (argv) != 0:
506 > raise gdb.GdbError ("hello-world takes no arguments")
507 > print "Hello, World!"
511 hello-world takes no arguments
514 @node Values From Inferior
515 @subsubsection Values From Inferior
516 @cindex values from inferior, with Python
517 @cindex python, working with values from inferior
519 @cindex @code{gdb.Value}
520 @value{GDBN} provides values it obtains from the inferior program in
521 an object of type @code{gdb.Value}. @value{GDBN} uses this object
522 for its internal bookkeeping of the inferior's values, and for
523 fetching values when necessary.
525 Inferior values that are simple scalars can be used directly in
526 Python expressions that are valid for the value's data type. Here's
527 an example for an integer or floating-point value @code{some_val}:
534 As result of this, @code{bar} will also be a @code{gdb.Value} object
535 whose values are of the same type as those of @code{some_val}. Valid
536 Python operations can also be performed on @code{gdb.Value} objects
537 representing a @code{struct} or @code{class} object. For such cases,
538 the overloaded operator (if present), is used to perform the operation.
539 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
540 representing instances of a @code{class} which overloads the @code{+}
541 operator, then one can use the @code{+} operator in their Python script
549 The result of the operation @code{val3} is also a @code{gdb.Value}
550 object corresponding to the value returned by the overloaded @code{+}
551 operator. In general, overloaded operators are invoked for the
552 following operations: @code{+} (binary addition), @code{-} (binary
553 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
554 @code{>>}, @code{|}, @code{&}, @code{^}.
556 Inferior values that are structures or instances of some class can
557 be accessed using the Python @dfn{dictionary syntax}. For example, if
558 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
559 can access its @code{foo} element with:
562 bar = some_val['foo']
565 @cindex getting structure elements using gdb.Field objects as subscripts
566 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
567 elements can also be accessed by using @code{gdb.Field} objects as
568 subscripts (@pxref{Types In Python}, for more information on
569 @code{gdb.Field} objects). For example, if @code{foo_field} is a
570 @code{gdb.Field} object corresponding to element @code{foo} of the above
571 structure, then @code{bar} can also be accessed as follows:
574 bar = some_val[foo_field]
577 A @code{gdb.Value} that represents a function can be executed via
578 inferior function call. Any arguments provided to the call must match
579 the function's prototype, and must be provided in the order specified
582 For example, @code{some_val} is a @code{gdb.Value} instance
583 representing a function that takes two integers as arguments. To
584 execute this function, call it like so:
587 result = some_val (10,20)
590 Any values returned from a function call will be stored as a
593 The following attributes are provided:
595 @defvar Value.address
596 If this object is addressable, this read-only attribute holds a
597 @code{gdb.Value} object representing the address. Otherwise,
598 this attribute holds @code{None}.
601 @cindex optimized out value in Python
602 @defvar Value.is_optimized_out
603 This read-only boolean attribute is true if the compiler optimized out
604 this value, thus it is not available for fetching from the inferior.
608 The type of this @code{gdb.Value}. The value of this attribute is a
609 @code{gdb.Type} object (@pxref{Types In Python}).
612 @defvar Value.dynamic_type
613 The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time
614 type information (@acronym{RTTI}) to determine the dynamic type of the
615 value. If this value is of class type, it will return the class in
616 which the value is embedded, if any. If this value is of pointer or
617 reference to a class type, it will compute the dynamic type of the
618 referenced object, and return a pointer or reference to that type,
619 respectively. In all other cases, it will return the value's static
622 Note that this feature will only work when debugging a C@t{++} program
623 that includes @acronym{RTTI} for the object in question. Otherwise,
624 it will just return the static type of the value as in @kbd{ptype foo}
625 (@pxref{Symbols, ptype}).
628 @defvar Value.is_lazy
629 The value of this read-only boolean attribute is @code{True} if this
630 @code{gdb.Value} has not yet been fetched from the inferior.
631 @value{GDBN} does not fetch values until necessary, for efficiency.
635 myval = gdb.parse_and_eval ('somevar')
638 The value of @code{somevar} is not fetched at this time. It will be
639 fetched when the value is needed, or when the @code{fetch_lazy}
643 The following methods are provided:
645 @defun Value.__init__ (@var{val})
646 Many Python values can be converted directly to a @code{gdb.Value} via
647 this object initializer. Specifically:
651 A Python boolean is converted to the boolean type from the current
655 A Python integer is converted to the C @code{long} type for the
656 current architecture.
659 A Python long is converted to the C @code{long long} type for the
660 current architecture.
663 A Python float is converted to the C @code{double} type for the
664 current architecture.
667 A Python string is converted to a target string in the current target
668 language using the current target encoding.
669 If a character cannot be represented in the current target encoding,
670 then an exception is thrown.
672 @item @code{gdb.Value}
673 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
675 @item @code{gdb.LazyString}
676 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
677 Python}), then the lazy string's @code{value} method is called, and
682 @defun Value.cast (type)
683 Return a new instance of @code{gdb.Value} that is the result of
684 casting this instance to the type described by @var{type}, which must
685 be a @code{gdb.Type} object. If the cast cannot be performed for some
686 reason, this method throws an exception.
689 @defun Value.dereference ()
690 For pointer data types, this method returns a new @code{gdb.Value} object
691 whose contents is the object pointed to by the pointer. For example, if
692 @code{foo} is a C pointer to an @code{int}, declared in your C program as
699 then you can use the corresponding @code{gdb.Value} to access what
700 @code{foo} points to like this:
703 bar = foo.dereference ()
706 The result @code{bar} will be a @code{gdb.Value} object holding the
707 value pointed to by @code{foo}.
709 A similar function @code{Value.referenced_value} exists which also
710 returns @code{gdb.Value} objects corresonding to the values pointed to
711 by pointer values (and additionally, values referenced by reference
712 values). However, the behavior of @code{Value.dereference}
713 differs from @code{Value.referenced_value} by the fact that the
714 behavior of @code{Value.dereference} is identical to applying the C
715 unary operator @code{*} on a given value. For example, consider a
716 reference to a pointer @code{ptrref}, declared in your C@t{++} program
724 intptr &ptrref = ptr;
727 Though @code{ptrref} is a reference value, one can apply the method
728 @code{Value.dereference} to the @code{gdb.Value} object corresponding
729 to it and obtain a @code{gdb.Value} which is identical to that
730 corresponding to @code{val}. However, if you apply the method
731 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
732 object identical to that corresponding to @code{ptr}.
735 py_ptrref = gdb.parse_and_eval ("ptrref")
736 py_val = py_ptrref.dereference ()
737 py_ptr = py_ptrref.referenced_value ()
740 The @code{gdb.Value} object @code{py_val} is identical to that
741 corresponding to @code{val}, and @code{py_ptr} is identical to that
742 corresponding to @code{ptr}. In general, @code{Value.dereference} can
743 be applied whenever the C unary operator @code{*} can be applied
744 to the corresponding C value. For those cases where applying both
745 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
746 the results obtained need not be identical (as we have seen in the above
747 example). The results are however identical when applied on
748 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
749 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
752 @defun Value.referenced_value ()
753 For pointer or reference data types, this method returns a new
754 @code{gdb.Value} object corresponding to the value referenced by the
755 pointer/reference value. For pointer data types,
756 @code{Value.dereference} and @code{Value.referenced_value} produce
757 identical results. The difference between these methods is that
758 @code{Value.dereference} cannot get the values referenced by reference
759 values. For example, consider a reference to an @code{int}, declared
760 in your C@t{++} program as
768 then applying @code{Value.dereference} to the @code{gdb.Value} object
769 corresponding to @code{ref} will result in an error, while applying
770 @code{Value.referenced_value} will result in a @code{gdb.Value} object
771 identical to that corresponding to @code{val}.
774 py_ref = gdb.parse_and_eval ("ref")
775 er_ref = py_ref.dereference () # Results in error
776 py_val = py_ref.referenced_value () # Returns the referenced value
779 The @code{gdb.Value} object @code{py_val} is identical to that
780 corresponding to @code{val}.
783 @defun Value.dynamic_cast (type)
784 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
785 operator were used. Consult a C@t{++} reference for details.
788 @defun Value.reinterpret_cast (type)
789 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
790 operator were used. Consult a C@t{++} reference for details.
793 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
794 If this @code{gdb.Value} represents a string, then this method
795 converts the contents to a Python string. Otherwise, this method will
798 Values are interpreted as strings according to the rules of the
799 current language. If the optional length argument is given, the
800 string will be converted to that length, and will include any embedded
801 zeroes that the string may contain. Otherwise, for languages
802 where the string is zero-terminated, the entire string will be
805 For example, in C-like languages, a value is a string if it is a pointer
806 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
809 If the optional @var{encoding} argument is given, it must be a string
810 naming the encoding of the string in the @code{gdb.Value}, such as
811 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
812 the same encodings as the corresponding argument to Python's
813 @code{string.decode} method, and the Python codec machinery will be used
814 to convert the string. If @var{encoding} is not given, or if
815 @var{encoding} is the empty string, then either the @code{target-charset}
816 (@pxref{Character Sets}) will be used, or a language-specific encoding
817 will be used, if the current language is able to supply one.
819 The optional @var{errors} argument is the same as the corresponding
820 argument to Python's @code{string.decode} method.
822 If the optional @var{length} argument is given, the string will be
823 fetched and converted to the given length.
826 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
827 If this @code{gdb.Value} represents a string, then this method
828 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
829 In Python}). Otherwise, this method will throw an exception.
831 If the optional @var{encoding} argument is given, it must be a string
832 naming the encoding of the @code{gdb.LazyString}. Some examples are:
833 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
834 @var{encoding} argument is an encoding that @value{GDBN} does
835 recognize, @value{GDBN} will raise an error.
837 When a lazy string is printed, the @value{GDBN} encoding machinery is
838 used to convert the string during printing. If the optional
839 @var{encoding} argument is not provided, or is an empty string,
840 @value{GDBN} will automatically select the encoding most suitable for
841 the string type. For further information on encoding in @value{GDBN}
842 please see @ref{Character Sets}.
844 If the optional @var{length} argument is given, the string will be
845 fetched and encoded to the length of characters specified. If
846 the @var{length} argument is not provided, the string will be fetched
847 and encoded until a null of appropriate width is found.
850 @defun Value.fetch_lazy ()
851 If the @code{gdb.Value} object is currently a lazy value
852 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
853 fetched from the inferior. Any errors that occur in the process
854 will produce a Python exception.
856 If the @code{gdb.Value} object is not a lazy value, this method
859 This method does not return a value.
863 @node Types In Python
864 @subsubsection Types In Python
865 @cindex types in Python
866 @cindex Python, working with types
869 @value{GDBN} represents types from the inferior using the class
872 The following type-related functions are available in the @code{gdb}
875 @findex gdb.lookup_type
876 @defun gdb.lookup_type (name @r{[}, block@r{]})
877 This function looks up a type by its @var{name}, which must be a string.
879 If @var{block} is given, then @var{name} is looked up in that scope.
880 Otherwise, it is searched for globally.
882 Ordinarily, this function will return an instance of @code{gdb.Type}.
883 If the named type cannot be found, it will throw an exception.
886 If the type is a structure or class type, or an enum type, the fields
887 of that type can be accessed using the Python @dfn{dictionary syntax}.
888 For example, if @code{some_type} is a @code{gdb.Type} instance holding
889 a structure type, you can access its @code{foo} field with:
892 bar = some_type['foo']
895 @code{bar} will be a @code{gdb.Field} object; see below under the
896 description of the @code{Type.fields} method for a description of the
897 @code{gdb.Field} class.
899 An instance of @code{Type} has the following attributes:
902 The type code for this type. The type code will be one of the
903 @code{TYPE_CODE_} constants defined below.
907 The name of this type. If this type has no name, then @code{None}
912 The size of this type, in target @code{char} units. Usually, a
913 target's @code{char} type will be an 8-bit byte. However, on some
914 unusual platforms, this type may have a different size.
918 The tag name for this type. The tag name is the name after
919 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
920 languages have this concept. If this type has no tag name, then
921 @code{None} is returned.
924 The following methods are provided:
926 @defun Type.fields ()
927 For structure and union types, this method returns the fields. Range
928 types have two fields, the minimum and maximum values. Enum types
929 have one field per enum constant. Function and method types have one
930 field per parameter. The base types of C@t{++} classes are also
931 represented as fields. If the type has no fields, or does not fit
932 into one of these categories, an empty sequence will be returned.
934 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
937 This attribute is not available for @code{enum} or @code{static}
938 (as in C@t{++} or Java) fields. The value is the position, counting
939 in bits, from the start of the containing type.
942 This attribute is only available for @code{enum} fields, and its value
943 is the enumeration member's integer representation.
946 The name of the field, or @code{None} for anonymous fields.
949 This is @code{True} if the field is artificial, usually meaning that
950 it was provided by the compiler and not the user. This attribute is
951 always provided, and is @code{False} if the field is not artificial.
954 This is @code{True} if the field represents a base class of a C@t{++}
955 structure. This attribute is always provided, and is @code{False}
956 if the field is not a base class of the type that is the argument of
957 @code{fields}, or if that type was not a C@t{++} class.
960 If the field is packed, or is a bitfield, then this will have a
961 non-zero value, which is the size of the field in bits. Otherwise,
962 this will be zero; in this case the field's size is given by its type.
965 The type of the field. This is usually an instance of @code{Type},
966 but it can be @code{None} in some situations.
969 The type which contains this field. This is an instance of
974 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
975 Return a new @code{gdb.Type} object which represents an array of this
976 type. If one argument is given, it is the inclusive upper bound of
977 the array; in this case the lower bound is zero. If two arguments are
978 given, the first argument is the lower bound of the array, and the
979 second argument is the upper bound of the array. An array's length
980 must not be negative, but the bounds can be.
983 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
984 Return a new @code{gdb.Type} object which represents a vector of this
985 type. If one argument is given, it is the inclusive upper bound of
986 the vector; in this case the lower bound is zero. If two arguments are
987 given, the first argument is the lower bound of the vector, and the
988 second argument is the upper bound of the vector. A vector's length
989 must not be negative, but the bounds can be.
991 The difference between an @code{array} and a @code{vector} is that
992 arrays behave like in C: when used in expressions they decay to a pointer
993 to the first element whereas vectors are treated as first class values.
997 Return a new @code{gdb.Type} object which represents a
998 @code{const}-qualified variant of this type.
1001 @defun Type.volatile ()
1002 Return a new @code{gdb.Type} object which represents a
1003 @code{volatile}-qualified variant of this type.
1006 @defun Type.unqualified ()
1007 Return a new @code{gdb.Type} object which represents an unqualified
1008 variant of this type. That is, the result is neither @code{const} nor
1012 @defun Type.range ()
1013 Return a Python @code{Tuple} object that contains two elements: the
1014 low bound of the argument type and the high bound of that type. If
1015 the type does not have a range, @value{GDBN} will raise a
1016 @code{gdb.error} exception (@pxref{Exception Handling}).
1019 @defun Type.reference ()
1020 Return a new @code{gdb.Type} object which represents a reference to this
1024 @defun Type.pointer ()
1025 Return a new @code{gdb.Type} object which represents a pointer to this
1029 @defun Type.strip_typedefs ()
1030 Return a new @code{gdb.Type} that represents the real type,
1031 after removing all layers of typedefs.
1034 @defun Type.target ()
1035 Return a new @code{gdb.Type} object which represents the target type
1038 For a pointer type, the target type is the type of the pointed-to
1039 object. For an array type (meaning C-like arrays), the target type is
1040 the type of the elements of the array. For a function or method type,
1041 the target type is the type of the return value. For a complex type,
1042 the target type is the type of the elements. For a typedef, the
1043 target type is the aliased type.
1045 If the type does not have a target, this method will throw an
1049 @defun Type.template_argument (n @r{[}, block@r{]})
1050 If this @code{gdb.Type} is an instantiation of a template, this will
1051 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1052 value of the @var{n}th template argument (indexed starting at 0).
1054 If this @code{gdb.Type} is not a template type, or if the type has fewer
1055 than @var{n} template arguments, this will throw an exception.
1056 Ordinarily, only C@t{++} code will have template types.
1058 If @var{block} is given, then @var{name} is looked up in that scope.
1059 Otherwise, it is searched for globally.
1063 Each type has a code, which indicates what category this type falls
1064 into. The available type categories are represented by constants
1065 defined in the @code{gdb} module:
1068 @vindex TYPE_CODE_PTR
1069 @item gdb.TYPE_CODE_PTR
1070 The type is a pointer.
1072 @vindex TYPE_CODE_ARRAY
1073 @item gdb.TYPE_CODE_ARRAY
1074 The type is an array.
1076 @vindex TYPE_CODE_STRUCT
1077 @item gdb.TYPE_CODE_STRUCT
1078 The type is a structure.
1080 @vindex TYPE_CODE_UNION
1081 @item gdb.TYPE_CODE_UNION
1082 The type is a union.
1084 @vindex TYPE_CODE_ENUM
1085 @item gdb.TYPE_CODE_ENUM
1086 The type is an enum.
1088 @vindex TYPE_CODE_FLAGS
1089 @item gdb.TYPE_CODE_FLAGS
1090 A bit flags type, used for things such as status registers.
1092 @vindex TYPE_CODE_FUNC
1093 @item gdb.TYPE_CODE_FUNC
1094 The type is a function.
1096 @vindex TYPE_CODE_INT
1097 @item gdb.TYPE_CODE_INT
1098 The type is an integer type.
1100 @vindex TYPE_CODE_FLT
1101 @item gdb.TYPE_CODE_FLT
1102 A floating point type.
1104 @vindex TYPE_CODE_VOID
1105 @item gdb.TYPE_CODE_VOID
1106 The special type @code{void}.
1108 @vindex TYPE_CODE_SET
1109 @item gdb.TYPE_CODE_SET
1112 @vindex TYPE_CODE_RANGE
1113 @item gdb.TYPE_CODE_RANGE
1114 A range type, that is, an integer type with bounds.
1116 @vindex TYPE_CODE_STRING
1117 @item gdb.TYPE_CODE_STRING
1118 A string type. Note that this is only used for certain languages with
1119 language-defined string types; C strings are not represented this way.
1121 @vindex TYPE_CODE_BITSTRING
1122 @item gdb.TYPE_CODE_BITSTRING
1123 A string of bits. It is deprecated.
1125 @vindex TYPE_CODE_ERROR
1126 @item gdb.TYPE_CODE_ERROR
1127 An unknown or erroneous type.
1129 @vindex TYPE_CODE_METHOD
1130 @item gdb.TYPE_CODE_METHOD
1131 A method type, as found in C@t{++} or Java.
1133 @vindex TYPE_CODE_METHODPTR
1134 @item gdb.TYPE_CODE_METHODPTR
1135 A pointer-to-member-function.
1137 @vindex TYPE_CODE_MEMBERPTR
1138 @item gdb.TYPE_CODE_MEMBERPTR
1139 A pointer-to-member.
1141 @vindex TYPE_CODE_REF
1142 @item gdb.TYPE_CODE_REF
1145 @vindex TYPE_CODE_CHAR
1146 @item gdb.TYPE_CODE_CHAR
1149 @vindex TYPE_CODE_BOOL
1150 @item gdb.TYPE_CODE_BOOL
1153 @vindex TYPE_CODE_COMPLEX
1154 @item gdb.TYPE_CODE_COMPLEX
1155 A complex float type.
1157 @vindex TYPE_CODE_TYPEDEF
1158 @item gdb.TYPE_CODE_TYPEDEF
1159 A typedef to some other type.
1161 @vindex TYPE_CODE_NAMESPACE
1162 @item gdb.TYPE_CODE_NAMESPACE
1163 A C@t{++} namespace.
1165 @vindex TYPE_CODE_DECFLOAT
1166 @item gdb.TYPE_CODE_DECFLOAT
1167 A decimal floating point type.
1169 @vindex TYPE_CODE_INTERNAL_FUNCTION
1170 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1171 A function internal to @value{GDBN}. This is the type used to represent
1172 convenience functions.
1175 Further support for types is provided in the @code{gdb.types}
1176 Python module (@pxref{gdb.types}).
1178 @node Pretty Printing API
1179 @subsubsection Pretty Printing API
1180 @cindex python pretty printing api
1182 An example output is provided (@pxref{Pretty Printing}).
1184 A pretty-printer is just an object that holds a value and implements a
1185 specific interface, defined here.
1187 @defun pretty_printer.children (self)
1188 @value{GDBN} will call this method on a pretty-printer to compute the
1189 children of the pretty-printer's value.
1191 This method must return an object conforming to the Python iterator
1192 protocol. Each item returned by the iterator must be a tuple holding
1193 two elements. The first element is the ``name'' of the child; the
1194 second element is the child's value. The value can be any Python
1195 object which is convertible to a @value{GDBN} value.
1197 This method is optional. If it does not exist, @value{GDBN} will act
1198 as though the value has no children.
1201 @defun pretty_printer.display_hint (self)
1202 The CLI may call this method and use its result to change the
1203 formatting of a value. The result will also be supplied to an MI
1204 consumer as a @samp{displayhint} attribute of the variable being
1207 This method is optional. If it does exist, this method must return a
1210 Some display hints are predefined by @value{GDBN}:
1214 Indicate that the object being printed is ``array-like''. The CLI
1215 uses this to respect parameters such as @code{set print elements} and
1216 @code{set print array}.
1219 Indicate that the object being printed is ``map-like'', and that the
1220 children of this value can be assumed to alternate between keys and
1224 Indicate that the object being printed is ``string-like''. If the
1225 printer's @code{to_string} method returns a Python string of some
1226 kind, then @value{GDBN} will call its internal language-specific
1227 string-printing function to format the string. For the CLI this means
1228 adding quotation marks, possibly escaping some characters, respecting
1229 @code{set print elements}, and the like.
1233 @defun pretty_printer.to_string (self)
1234 @value{GDBN} will call this method to display the string
1235 representation of the value passed to the object's constructor.
1237 When printing from the CLI, if the @code{to_string} method exists,
1238 then @value{GDBN} will prepend its result to the values returned by
1239 @code{children}. Exactly how this formatting is done is dependent on
1240 the display hint, and may change as more hints are added. Also,
1241 depending on the print settings (@pxref{Print Settings}), the CLI may
1242 print just the result of @code{to_string} in a stack trace, omitting
1243 the result of @code{children}.
1245 If this method returns a string, it is printed verbatim.
1247 Otherwise, if this method returns an instance of @code{gdb.Value},
1248 then @value{GDBN} prints this value. This may result in a call to
1249 another pretty-printer.
1251 If instead the method returns a Python value which is convertible to a
1252 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1253 the resulting value. Again, this may result in a call to another
1254 pretty-printer. Python scalars (integers, floats, and booleans) and
1255 strings are convertible to @code{gdb.Value}; other types are not.
1257 Finally, if this method returns @code{None} then no further operations
1258 are peformed in this method and nothing is printed.
1260 If the result is not one of these types, an exception is raised.
1263 @value{GDBN} provides a function which can be used to look up the
1264 default pretty-printer for a @code{gdb.Value}:
1266 @findex gdb.default_visualizer
1267 @defun gdb.default_visualizer (value)
1268 This function takes a @code{gdb.Value} object as an argument. If a
1269 pretty-printer for this value exists, then it is returned. If no such
1270 printer exists, then this returns @code{None}.
1273 @node Selecting Pretty-Printers
1274 @subsubsection Selecting Pretty-Printers
1275 @cindex selecting python pretty-printers
1277 The Python list @code{gdb.pretty_printers} contains an array of
1278 functions or callable objects that have been registered via addition
1279 as a pretty-printer. Printers in this list are called @code{global}
1280 printers, they're available when debugging all inferiors.
1281 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1282 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1285 Each function on these lists is passed a single @code{gdb.Value}
1286 argument and should return a pretty-printer object conforming to the
1287 interface definition above (@pxref{Pretty Printing API}). If a function
1288 cannot create a pretty-printer for the value, it should return
1291 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1292 @code{gdb.Objfile} in the current program space and iteratively calls
1293 each enabled lookup routine in the list for that @code{gdb.Objfile}
1294 until it receives a pretty-printer object.
1295 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1296 searches the pretty-printer list of the current program space,
1297 calling each enabled function until an object is returned.
1298 After these lists have been exhausted, it tries the global
1299 @code{gdb.pretty_printers} list, again calling each enabled function until an
1302 The order in which the objfiles are searched is not specified. For a
1303 given list, functions are always invoked from the head of the list,
1304 and iterated over sequentially until the end of the list, or a printer
1307 For various reasons a pretty-printer may not work.
1308 For example, the underlying data structure may have changed and
1309 the pretty-printer is out of date.
1311 The consequences of a broken pretty-printer are severe enough that
1312 @value{GDBN} provides support for enabling and disabling individual
1313 printers. For example, if @code{print frame-arguments} is on,
1314 a backtrace can become highly illegible if any argument is printed
1315 with a broken printer.
1317 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1318 attribute to the registered function or callable object. If this attribute
1319 is present and its value is @code{False}, the printer is disabled, otherwise
1320 the printer is enabled.
1322 @node Writing a Pretty-Printer
1323 @subsubsection Writing a Pretty-Printer
1324 @cindex writing a pretty-printer
1326 A pretty-printer consists of two parts: a lookup function to detect
1327 if the type is supported, and the printer itself.
1329 Here is an example showing how a @code{std::string} printer might be
1330 written. @xref{Pretty Printing API}, for details on the API this class
1334 class StdStringPrinter(object):
1335 "Print a std::string"
1337 def __init__(self, val):
1340 def to_string(self):
1341 return self.val['_M_dataplus']['_M_p']
1343 def display_hint(self):
1347 And here is an example showing how a lookup function for the printer
1348 example above might be written.
1351 def str_lookup_function(val):
1352 lookup_tag = val.type.tag
1353 if lookup_tag == None:
1355 regex = re.compile("^std::basic_string<char,.*>$")
1356 if regex.match(lookup_tag):
1357 return StdStringPrinter(val)
1361 The example lookup function extracts the value's type, and attempts to
1362 match it to a type that it can pretty-print. If it is a type the
1363 printer can pretty-print, it will return a printer object. If not, it
1364 returns @code{None}.
1366 We recommend that you put your core pretty-printers into a Python
1367 package. If your pretty-printers are for use with a library, we
1368 further recommend embedding a version number into the package name.
1369 This practice will enable @value{GDBN} to load multiple versions of
1370 your pretty-printers at the same time, because they will have
1373 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1374 can be evaluated multiple times without changing its meaning. An
1375 ideal auto-load file will consist solely of @code{import}s of your
1376 printer modules, followed by a call to a register pretty-printers with
1377 the current objfile.
1379 Taken as a whole, this approach will scale nicely to multiple
1380 inferiors, each potentially using a different library version.
1381 Embedding a version number in the Python package name will ensure that
1382 @value{GDBN} is able to load both sets of printers simultaneously.
1383 Then, because the search for pretty-printers is done by objfile, and
1384 because your auto-loaded code took care to register your library's
1385 printers with a specific objfile, @value{GDBN} will find the correct
1386 printers for the specific version of the library used by each
1389 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1390 this code might appear in @code{gdb.libstdcxx.v6}:
1393 def register_printers(objfile):
1394 objfile.pretty_printers.append(str_lookup_function)
1398 And then the corresponding contents of the auto-load file would be:
1401 import gdb.libstdcxx.v6
1402 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1405 The previous example illustrates a basic pretty-printer.
1406 There are a few things that can be improved on.
1407 The printer doesn't have a name, making it hard to identify in a
1408 list of installed printers. The lookup function has a name, but
1409 lookup functions can have arbitrary, even identical, names.
1411 Second, the printer only handles one type, whereas a library typically has
1412 several types. One could install a lookup function for each desired type
1413 in the library, but one could also have a single lookup function recognize
1414 several types. The latter is the conventional way this is handled.
1415 If a pretty-printer can handle multiple data types, then its
1416 @dfn{subprinters} are the printers for the individual data types.
1418 The @code{gdb.printing} module provides a formal way of solving these
1419 problems (@pxref{gdb.printing}).
1420 Here is another example that handles multiple types.
1422 These are the types we are going to pretty-print:
1425 struct foo @{ int a, b; @};
1426 struct bar @{ struct foo x, y; @};
1429 Here are the printers:
1433 """Print a foo object."""
1435 def __init__(self, val):
1438 def to_string(self):
1439 return ("a=<" + str(self.val["a"]) +
1440 "> b=<" + str(self.val["b"]) + ">")
1443 """Print a bar object."""
1445 def __init__(self, val):
1448 def to_string(self):
1449 return ("x=<" + str(self.val["x"]) +
1450 "> y=<" + str(self.val["y"]) + ">")
1453 This example doesn't need a lookup function, that is handled by the
1454 @code{gdb.printing} module. Instead a function is provided to build up
1455 the object that handles the lookup.
1460 def build_pretty_printer():
1461 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1463 pp.add_printer('foo', '^foo$', fooPrinter)
1464 pp.add_printer('bar', '^bar$', barPrinter)
1468 And here is the autoload support:
1473 gdb.printing.register_pretty_printer(
1474 gdb.current_objfile(),
1475 my_library.build_pretty_printer())
1478 Finally, when this printer is loaded into @value{GDBN}, here is the
1479 corresponding output of @samp{info pretty-printer}:
1482 (gdb) info pretty-printer
1489 @node Type Printing API
1490 @subsubsection Type Printing API
1491 @cindex type printing API for Python
1493 @value{GDBN} provides a way for Python code to customize type display.
1494 This is mainly useful for substituting canonical typedef names for
1497 @cindex type printer
1498 A @dfn{type printer} is just a Python object conforming to a certain
1499 protocol. A simple base class implementing the protocol is provided;
1500 see @ref{gdb.types}. A type printer must supply at least:
1502 @defivar type_printer enabled
1503 A boolean which is True if the printer is enabled, and False
1504 otherwise. This is manipulated by the @code{enable type-printer}
1505 and @code{disable type-printer} commands.
1508 @defivar type_printer name
1509 The name of the type printer. This must be a string. This is used by
1510 the @code{enable type-printer} and @code{disable type-printer}
1514 @defmethod type_printer instantiate (self)
1515 This is called by @value{GDBN} at the start of type-printing. It is
1516 only called if the type printer is enabled. This method must return a
1517 new object that supplies a @code{recognize} method, as described below.
1521 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1522 will compute a list of type recognizers. This is done by iterating
1523 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1524 followed by the per-progspace type printers (@pxref{Progspaces In
1525 Python}), and finally the global type printers.
1527 @value{GDBN} will call the @code{instantiate} method of each enabled
1528 type printer. If this method returns @code{None}, then the result is
1529 ignored; otherwise, it is appended to the list of recognizers.
1531 Then, when @value{GDBN} is going to display a type name, it iterates
1532 over the list of recognizers. For each one, it calls the recognition
1533 function, stopping if the function returns a non-@code{None} value.
1534 The recognition function is defined as:
1536 @defmethod type_recognizer recognize (self, type)
1537 If @var{type} is not recognized, return @code{None}. Otherwise,
1538 return a string which is to be printed as the name of @var{type}.
1539 The @var{type} argument will be an instance of @code{gdb.Type}
1540 (@pxref{Types In Python}).
1543 @value{GDBN} uses this two-pass approach so that type printers can
1544 efficiently cache information without holding on to it too long. For
1545 example, it can be convenient to look up type information in a type
1546 printer and hold it for a recognizer's lifetime; if a single pass were
1547 done then type printers would have to make use of the event system in
1548 order to avoid holding information that could become stale as the
1551 @node Frame Filter API
1552 @subsubsection Filtering Frames.
1553 @cindex frame filters api
1555 Frame filters are Python objects that manipulate the visibility of a
1556 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1559 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1560 commands (@pxref{GDB/MI}), those that return a collection of frames
1561 are affected. The commands that work with frame filters are:
1563 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1564 @code{-stack-list-frames}
1565 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1566 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1567 -stack-list-variables command}), @code{-stack-list-arguments}
1568 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1569 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1570 -stack-list-locals command}).
1572 A frame filter works by taking an iterator as an argument, applying
1573 actions to the contents of that iterator, and returning another
1574 iterator (or, possibly, the same iterator it was provided in the case
1575 where the filter does not perform any operations). Typically, frame
1576 filters utilize tools such as the Python's @code{itertools} module to
1577 work with and create new iterators from the source iterator.
1578 Regardless of how a filter chooses to apply actions, it must not alter
1579 the underlying @value{GDBN} frame or frames, or attempt to alter the
1580 call-stack within @value{GDBN}. This preserves data integrity within
1581 @value{GDBN}. Frame filters are executed on a priority basis and care
1582 should be taken that some frame filters may have been executed before,
1583 and that some frame filters will be executed after.
1585 An important consideration when designing frame filters, and well
1586 worth reflecting upon, is that frame filters should avoid unwinding
1587 the call stack if possible. Some stacks can run very deep, into the
1588 tens of thousands in some cases. To search every frame when a frame
1589 filter executes may be too expensive at that step. The frame filter
1590 cannot know how many frames it has to iterate over, and it may have to
1591 iterate through them all. This ends up duplicating effort as
1592 @value{GDBN} performs this iteration when it prints the frames. If
1593 the filter can defer unwinding frames until frame decorators are
1594 executed, after the last filter has executed, it should. @xref{Frame
1595 Decorator API}, for more information on decorators. Also, there are
1596 examples for both frame decorators and filters in later chapters.
1597 @xref{Writing a Frame Filter}, for more information.
1599 The Python dictionary @code{gdb.frame_filters} contains key/object
1600 pairings that comprise a frame filter. Frame filters in this
1601 dictionary are called @code{global} frame filters, and they are
1602 available when debugging all inferiors. These frame filters must
1603 register with the dictionary directly. In addition to the
1604 @code{global} dictionary, there are other dictionaries that are loaded
1605 with different inferiors via auto-loading (@pxref{Python
1606 Auto-loading}). The two other areas where frame filter dictionaries
1607 can be found are: @code{gdb.Progspace} which contains a
1608 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1609 object which also contains a @code{frame_filters} dictionary
1612 When a command is executed from @value{GDBN} that is compatible with
1613 frame filters, @value{GDBN} combines the @code{global},
1614 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1615 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1616 several frames, and thus several object files, might be in use.
1617 @value{GDBN} then prunes any frame filter whose @code{enabled}
1618 attribute is @code{False}. This pruned list is then sorted according
1619 to the @code{priority} attribute in each filter.
1621 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1622 creates an iterator which wraps each frame in the call stack in a
1623 @code{FrameDecorator} object, and calls each filter in order. The
1624 output from the previous filter will always be the input to the next
1627 Frame filters have a mandatory interface which each frame filter must
1628 implement, defined here:
1630 @defun FrameFilter.filter (iterator)
1631 @value{GDBN} will call this method on a frame filter when it has
1632 reached the order in the priority list for that filter.
1634 For example, if there are four frame filters:
1645 The order that the frame filters will be called is:
1648 Filter3 -> Filter2 -> Filter1 -> Filter4
1651 Note that the output from @code{Filter3} is passed to the input of
1652 @code{Filter2}, and so on.
1654 This @code{filter} method is passed a Python iterator. This iterator
1655 contains a sequence of frame decorators that wrap each
1656 @code{gdb.Frame}, or a frame decorator that wraps another frame
1657 decorator. The first filter that is executed in the sequence of frame
1658 filters will receive an iterator entirely comprised of default
1659 @code{FrameDecorator} objects. However, after each frame filter is
1660 executed, the previous frame filter may have wrapped some or all of
1661 the frame decorators with their own frame decorator. As frame
1662 decorators must also conform to a mandatory interface, these
1663 decorators can be assumed to act in a uniform manner (@pxref{Frame
1666 This method must return an object conforming to the Python iterator
1667 protocol. Each item in the iterator must be an object conforming to
1668 the frame decorator interface. If a frame filter does not wish to
1669 perform any operations on this iterator, it should return that
1672 This method is not optional. If it does not exist, @value{GDBN} will
1673 raise and print an error.
1676 @defvar FrameFilter.name
1677 The @code{name} attribute must be Python string which contains the
1678 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1679 Management}). This attribute may contain any combination of letters
1680 or numbers. Care should be taken to ensure that it is unique. This
1681 attribute is mandatory.
1684 @defvar FrameFilter.enabled
1685 The @code{enabled} attribute must be Python boolean. This attribute
1686 indicates to @value{GDBN} whether the frame filter is enabled, and
1687 should be considered when frame filters are executed. If
1688 @code{enabled} is @code{True}, then the frame filter will be executed
1689 when any of the backtrace commands detailed earlier in this chapter
1690 are executed. If @code{enabled} is @code{False}, then the frame
1691 filter will not be executed. This attribute is mandatory.
1694 @defvar FrameFilter.priority
1695 The @code{priority} attribute must be Python integer. This attribute
1696 controls the order of execution in relation to other frame filters.
1697 There are no imposed limits on the range of @code{priority} other than
1698 it must be a valid integer. The higher the @code{priority} attribute,
1699 the sooner the frame filter will be executed in relation to other
1700 frame filters. Although @code{priority} can be negative, it is
1701 recommended practice to assume zero is the lowest priority that a
1702 frame filter can be assigned. Frame filters that have the same
1703 priority are executed in unsorted order in that priority slot. This
1704 attribute is mandatory.
1707 @node Frame Decorator API
1708 @subsubsection Decorating Frames.
1709 @cindex frame decorator api
1711 Frame decorators are sister objects to frame filters (@pxref{Frame
1712 Filter API}). Frame decorators are applied by a frame filter and can
1713 only be used in conjunction with frame filters.
1715 The purpose of a frame decorator is to customize the printed content
1716 of each @code{gdb.Frame} in commands where frame filters are executed.
1717 This concept is called decorating a frame. Frame decorators decorate
1718 a @code{gdb.Frame} with Python code contained within each API call.
1719 This separates the actual data contained in a @code{gdb.Frame} from
1720 the decorated data produced by a frame decorator. This abstraction is
1721 necessary to maintain integrity of the data contained in each
1724 Frame decorators have a mandatory interface, defined below.
1726 @value{GDBN} already contains a frame decorator called
1727 @code{FrameDecorator}. This contains substantial amounts of
1728 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
1729 recommended that other frame decorators inherit and extend this
1730 object, and only to override the methods needed.
1732 @defun FrameDecorator.elided (self)
1734 The @code{elided} method groups frames together in a hierarchical
1735 system. An example would be an interpreter, where multiple low-level
1736 frames make up a single call in the interpreted language. In this
1737 example, the frame filter would elide the low-level frames and present
1738 a single high-level frame, representing the call in the interpreted
1739 language, to the user.
1741 The @code{elided} function must return an iterable and this iterable
1742 must contain the frames that are being elided wrapped in a suitable
1743 frame decorator. If no frames are being elided this function may
1744 return an empty iterable, or @code{None}. Elided frames are indented
1745 from normal frames in a @code{CLI} backtrace, or in the case of
1746 @code{GDB/MI}, are placed in the @code{children} field of the eliding
1749 It is the frame filter's task to also filter out the elided frames from
1750 the source iterator. This will avoid printing the frame twice.
1753 @defun FrameDecorator.function (self)
1755 This method returns the name of the function in the frame that is to
1758 This method must return a Python string describing the function, or
1761 If this function returns @code{None}, @value{GDBN} will not print any
1762 data for this field.
1765 @defun FrameDecorator.address (self)
1767 This method returns the address of the frame that is to be printed.
1769 This method must return a Python numeric integer type of sufficient
1770 size to describe the address of the frame, or @code{None}.
1772 If this function returns a @code{None}, @value{GDBN} will not print
1773 any data for this field.
1776 @defun FrameDecorator.filename (self)
1778 This method returns the filename and path associated with this frame.
1780 This method must return a Python string containing the filename and
1781 the path to the object file backing the frame, or @code{None}.
1783 If this function returns a @code{None}, @value{GDBN} will not print
1784 any data for this field.
1787 @defun FrameDecorator.line (self):
1789 This method returns the line number associated with the current
1790 position within the function addressed by this frame.
1792 This method must return a Python integer type, or @code{None}.
1794 If this function returns a @code{None}, @value{GDBN} will not print
1795 any data for this field.
1798 @defun FrameDecorator.frame_args (self)
1801 This method must return an iterable, or @code{None}. Returning an
1802 empty iterable, or @code{None} means frame arguments will not be
1803 printed for this frame. This iterable must contain objects that
1804 implement two methods, described here.
1806 This object must implement a @code{argument} method which takes a
1807 single @code{self} parameter and must return a @code{gdb.Symbol}
1808 (@pxref{Symbols In Python}), or a Python string. The object must also
1809 implement a @code{value} method which takes a single @code{self}
1810 parameter and must return a @code{gdb.Value} (@pxref{Values From
1811 Inferior}), a Python value, or @code{None}. If the @code{value}
1812 method returns @code{None}, and the @code{argument} method returns a
1813 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
1814 the @code{gdb.Symbol} automatically.
1819 class SymValueWrapper():
1821 def __init__(self, symbol, value):
1831 class SomeFrameDecorator()
1834 def frame_args(self):
1837 block = self.inferior_frame.block()
1841 # Iterate over all symbols in a block. Only add
1842 # symbols that are arguments.
1844 if not sym.is_argument:
1846 args.append(SymValueWrapper(sym,None))
1848 # Add example synthetic argument.
1849 args.append(SymValueWrapper(``foo'', 42))
1855 @defun FrameDecorator.frame_locals (self)
1857 This method must return an iterable or @code{None}. Returning an
1858 empty iterable, or @code{None} means frame local arguments will not be
1859 printed for this frame.
1861 The object interface, the description of the various strategies for
1862 reading frame locals, and the example are largely similar to those
1863 described in the @code{frame_args} function, (@pxref{frame_args,,The
1864 frame filter frame_args function}). Below is a modified example:
1867 class SomeFrameDecorator()
1870 def frame_locals(self):
1873 block = self.inferior_frame.block()
1877 # Iterate over all symbols in a block. Add all
1878 # symbols, except arguments.
1882 vars.append(SymValueWrapper(sym,None))
1884 # Add an example of a synthetic local variable.
1885 vars.append(SymValueWrapper(``bar'', 99))
1891 @defun FrameDecorator.inferior_frame (self):
1893 This method must return the underlying @code{gdb.Frame} that this
1894 frame decorator is decorating. @value{GDBN} requires the underlying
1895 frame for internal frame information to determine how to print certain
1896 values when printing a frame.
1899 @node Writing a Frame Filter
1900 @subsubsection Writing a Frame Filter
1901 @cindex writing a frame filter
1903 There are three basic elements that a frame filter must implement: it
1904 must correctly implement the documented interface (@pxref{Frame Filter
1905 API}), it must register itself with @value{GDBN}, and finally, it must
1906 decide if it is to work on the data provided by @value{GDBN}. In all
1907 cases, whether it works on the iterator or not, each frame filter must
1908 return an iterator. A bare-bones frame filter follows the pattern in
1909 the following example.
1914 class FrameFilter():
1917 # Frame filter attribute creation.
1919 # 'name' is the name of the filter that GDB will display.
1921 # 'priority' is the priority of the filter relative to other
1924 # 'enabled' is a boolean that indicates whether this filter is
1925 # enabled and should be executed.
1931 # Register this frame filter with the global frame_filters
1933 gdb.frame_filters[self.name] = self
1935 def filter(self, frame_iter):
1936 # Just return the iterator.
1940 The frame filter in the example above implements the three
1941 requirements for all frame filters. It implements the API, self
1942 registers, and makes a decision on the iterator (in this case, it just
1943 returns the iterator untouched).
1945 The first step is attribute creation and assignment, and as shown in
1946 the comments the filter assigns the following attributes: @code{name},
1947 @code{priority} and whether the filter should be enabled with the
1948 @code{enabled} attribute.
1950 The second step is registering the frame filter with the dictionary or
1951 dictionaries that the frame filter has interest in. As shown in the
1952 comments, this filter just registers itself with the global dictionary
1953 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
1954 is a dictionary that is initialized in the @code{gdb} module when
1955 @value{GDBN} starts. What dictionary a filter registers with is an
1956 important consideration. Generally, if a filter is specific to a set
1957 of code, it should be registered either in the @code{objfile} or
1958 @code{progspace} dictionaries as they are specific to the program
1959 currently loaded in @value{GDBN}. The global dictionary is always
1960 present in @value{GDBN} and is never unloaded. Any filters registered
1961 with the global dictionary will exist until @value{GDBN} exits. To
1962 avoid filters that may conflict, it is generally better to register
1963 frame filters against the dictionaries that more closely align with
1964 the usage of the filter currently in question. @xref{Python
1965 Auto-loading}, for further information on auto-loading Python scripts.
1967 @value{GDBN} takes a hands-off approach to frame filter registration,
1968 therefore it is the frame filter's responsibility to ensure
1969 registration has occurred, and that any exceptions are handled
1970 appropriately. In particular, you may wish to handle exceptions
1971 relating to Python dictionary key uniqueness. It is mandatory that
1972 the dictionary key is the same as frame filter's @code{name}
1973 attribute. When a user manages frame filters (@pxref{Frame Filter
1974 Management}), the names @value{GDBN} will display are those contained
1975 in the @code{name} attribute.
1977 The final step of this example is the implementation of the
1978 @code{filter} method. As shown in the example comments, we define the
1979 @code{filter} method and note that the method must take an iterator,
1980 and also must return an iterator. In this bare-bones example, the
1981 frame filter is not very useful as it just returns the iterator
1982 untouched. However this is a valid operation for frame filters that
1983 have the @code{enabled} attribute set, but decide not to operate on
1986 In the next example, the frame filter operates on all frames and
1987 utilizes a frame decorator to perform some work on the frames.
1988 @xref{Frame Decorator API}, for further information on the frame
1989 decorator interface.
1991 This example works on inlined frames. It highlights frames which are
1992 inlined by tagging them with an ``[inlined]'' tag. By applying a
1993 frame decorator to all frames with the Python @code{itertools imap}
1994 method, the example defers actions to the frame decorator. Frame
1995 decorators are only processed when @value{GDBN} prints the backtrace.
1997 This introduces a new decision making topic: whether to perform
1998 decision making operations at the filtering step, or at the printing
1999 step. In this example's approach, it does not perform any filtering
2000 decisions at the filtering step beyond mapping a frame decorator to
2001 each frame. This allows the actual decision making to be performed
2002 when each frame is printed. This is an important consideration, and
2003 well worth reflecting upon when designing a frame filter. An issue
2004 that frame filters should avoid is unwinding the stack if possible.
2005 Some stacks can run very deep, into the tens of thousands in some
2006 cases. To search every frame to determine if it is inlined ahead of
2007 time may be too expensive at the filtering step. The frame filter
2008 cannot know how many frames it has to iterate over, and it would have
2009 to iterate through them all. This ends up duplicating effort as
2010 @value{GDBN} performs this iteration when it prints the frames.
2012 In this example decision making can be deferred to the printing step.
2013 As each frame is printed, the frame decorator can examine each frame
2014 in turn when @value{GDBN} iterates. From a performance viewpoint,
2015 this is the most appropriate decision to make as it avoids duplicating
2016 the effort that the printing step would undertake anyway. Also, if
2017 there are many frame filters unwinding the stack during filtering, it
2018 can substantially delay the printing of the backtrace which will
2019 result in large memory usage, and a poor user experience.
2022 class InlineFilter():
2025 self.name = "InlinedFrameFilter"
2028 gdb.frame_filters[self.name] = self
2030 def filter(self, frame_iter):
2031 frame_iter = itertools.imap(InlinedFrameDecorator,
2036 This frame filter is somewhat similar to the earlier example, except
2037 that the @code{filter} method applies a frame decorator object called
2038 @code{InlinedFrameDecorator} to each element in the iterator. The
2039 @code{imap} Python method is light-weight. It does not proactively
2040 iterate over the iterator, but rather creates a new iterator which
2041 wraps the existing one.
2043 Below is the frame decorator for this example.
2046 class InlinedFrameDecorator(FrameDecorator):
2048 def __init__(self, fobj):
2049 super(InlinedFrameDecorator, self).__init__(fobj)
2052 frame = fobj.inferior_frame()
2053 name = str(frame.name())
2055 if frame.type() == gdb.INLINE_FRAME:
2056 name = name + " [inlined]"
2061 This frame decorator only defines and overrides the @code{function}
2062 method. It lets the supplied @code{FrameDecorator}, which is shipped
2063 with @value{GDBN}, perform the other work associated with printing
2066 The combination of these two objects create this output from a
2070 #0 0x004004e0 in bar () at inline.c:11
2071 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2072 #2 0x00400566 in main () at inline.c:31
2075 So in the case of this example, a frame decorator is applied to all
2076 frames, regardless of whether they may be inlined or not. As
2077 @value{GDBN} iterates over the iterator produced by the frame filters,
2078 @value{GDBN} executes each frame decorator which then makes a decision
2079 on what to print in the @code{function} callback. Using a strategy
2080 like this is a way to defer decisions on the frame content to printing
2083 @subheading Eliding Frames
2085 It might be that the above example is not desirable for representing
2086 inlined frames, and a hierarchical approach may be preferred. If we
2087 want to hierarchically represent frames, the @code{elided} frame
2088 decorator interface might be preferable.
2090 This example approaches the issue with the @code{elided} method. This
2091 example is quite long, but very simplistic. It is out-of-scope for
2092 this section to write a complete example that comprehensively covers
2093 all approaches of finding and printing inlined frames. However, this
2094 example illustrates the approach an author might use.
2096 This example comprises of three sections.
2099 class InlineFrameFilter():
2102 self.name = "InlinedFrameFilter"
2105 gdb.frame_filters[self.name] = self
2107 def filter(self, frame_iter):
2108 return ElidingInlineIterator(frame_iter)
2111 This frame filter is very similar to the other examples. The only
2112 difference is this frame filter is wrapping the iterator provided to
2113 it (@code{frame_iter}) with a custom iterator called
2114 @code{ElidingInlineIterator}. This again defers actions to when
2115 @value{GDBN} prints the backtrace, as the iterator is not traversed
2118 The iterator for this example is as follows. It is in this section of
2119 the example where decisions are made on the content of the backtrace.
2122 class ElidingInlineIterator:
2123 def __init__(self, ii):
2124 self.input_iterator = ii
2130 frame = next(self.input_iterator)
2132 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2136 eliding_frame = next(self.input_iterator)
2137 except StopIteration:
2139 return ElidingFrameDecorator(eliding_frame, [frame])
2142 This iterator implements the Python iterator protocol. When the
2143 @code{next} function is called (when @value{GDBN} prints each frame),
2144 the iterator checks if this frame decorator, @code{frame}, is wrapping
2145 an inlined frame. If it is not, it returns the existing frame decorator
2146 untouched. If it is wrapping an inlined frame, it assumes that the
2147 inlined frame was contained within the next oldest frame,
2148 @code{eliding_frame}, which it fetches. It then creates and returns a
2149 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2150 elided frame, and the eliding frame.
2153 class ElidingInlineDecorator(FrameDecorator):
2155 def __init__(self, frame, elided_frames):
2156 super(ElidingInlineDecorator, self).__init__(frame)
2158 self.elided_frames = elided_frames
2161 return iter(self.elided_frames)
2164 This frame decorator overrides one function and returns the inlined
2165 frame in the @code{elided} method. As before it lets
2166 @code{FrameDecorator} do the rest of the work involved in printing
2167 this frame. This produces the following output.
2170 #0 0x004004e0 in bar () at inline.c:11
2171 #2 0x00400529 in main () at inline.c:25
2172 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2175 In that output, @code{max} which has been inlined into @code{main} is
2176 printed hierarchically. Another approach would be to combine the
2177 @code{function} method, and the @code{elided} method to both print a
2178 marker in the inlined frame, and also show the hierarchical
2181 @node Xmethods In Python
2182 @subsubsection Xmethods In Python
2183 @cindex xmethods in Python
2185 @dfn{Xmethods} are additional methods or replacements for existing
2186 methods of a C@t{++} class. This feature is useful for those cases
2187 where a method defined in C@t{++} source code could be inlined or
2188 optimized out by the compiler, making it unavailable to @value{GDBN}.
2189 For such cases, one can define an xmethod to serve as a replacement
2190 for the method defined in the C@t{++} source code. @value{GDBN} will
2191 then invoke the xmethod, instead of the C@t{++} method, to
2192 evaluate expressions. One can also use xmethods when debugging
2193 with core files. Moreover, when debugging live programs, invoking an
2194 xmethod need not involve running the inferior (which can potentially
2195 perturb its state). Hence, even if the C@t{++} method is available, it
2196 is better to use its replacement xmethod if one is defined.
2198 The xmethods feature in Python is available via the concepts of an
2199 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2200 implement an xmethod, one has to implement a matcher and a
2201 corresponding worker for it (more than one worker can be
2202 implemented, each catering to a different overloaded instance of the
2203 method). Internally, @value{GDBN} invokes the @code{match} method of a
2204 matcher to match the class type and method name. On a match, the
2205 @code{match} method returns a list of matching @emph{worker} objects.
2206 Each worker object typically corresponds to an overloaded instance of
2207 the xmethod. They implement a @code{get_arg_types} method which
2208 returns a sequence of types corresponding to the arguments the xmethod
2209 requires. @value{GDBN} uses this sequence of types to perform
2210 overload resolution and picks a winning xmethod worker. A winner
2211 is also selected from among the methods @value{GDBN} finds in the
2212 C@t{++} source code. Next, the winning xmethod worker and the
2213 winning C@t{++} method are compared to select an overall winner. In
2214 case of a tie between a xmethod worker and a C@t{++} method, the
2215 xmethod worker is selected as the winner. That is, if a winning
2216 xmethod worker is found to be equivalent to the winning C@t{++}
2217 method, then the xmethod worker is treated as a replacement for
2218 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2219 method. If the winning xmethod worker is the overall winner, then
2220 the corresponding xmethod is invoked via the @code{invoke} method
2221 of the worker object.
2223 If one wants to implement an xmethod as a replacement for an
2224 existing C@t{++} method, then they have to implement an equivalent
2225 xmethod which has exactly the same name and takes arguments of
2226 exactly the same type as the C@t{++} method. If the user wants to
2227 invoke the C@t{++} method even though a replacement xmethod is
2228 available for that method, then they can disable the xmethod.
2230 @xref{Xmethod API}, for API to implement xmethods in Python.
2231 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2234 @subsubsection Xmethod API
2237 The @value{GDBN} Python API provides classes, interfaces and functions
2238 to implement, register and manipulate xmethods.
2239 @xref{Xmethods In Python}.
2241 An xmethod matcher should be an instance of a class derived from
2242 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2243 object with similar interface and attributes. An instance of
2244 @code{XMethodMatcher} has the following attributes:
2247 The name of the matcher.
2251 A boolean value indicating whether the matcher is enabled or disabled.
2255 A list of named methods managed by the matcher. Each object in the list
2256 is an instance of the class @code{XMethod} defined in the module
2257 @code{gdb.xmethod}, or any object with the following attributes:
2262 Name of the xmethod which should be unique for each xmethod
2263 managed by the matcher.
2266 A boolean value indicating whether the xmethod is enabled or
2271 The class @code{XMethod} is a convenience class with same
2272 attributes as above along with the following constructor:
2274 @defun XMethod.__init__ (self, name)
2275 Constructs an enabled xmethod with name @var{name}.
2280 The @code{XMethodMatcher} class has the following methods:
2282 @defun XMethodMatcher.__init__ (self, name)
2283 Constructs an enabled xmethod matcher with name @var{name}. The
2284 @code{methods} attribute is initialized to @code{None}.
2287 @defun XMethodMatcher.match (self, class_type, method_name)
2288 Derived classes should override this method. It should return a
2289 xmethod worker object (or a sequence of xmethod worker
2290 objects) matching the @var{class_type} and @var{method_name}.
2291 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2292 is a string value. If the matcher manages named methods as listed in
2293 its @code{methods} attribute, then only those worker objects whose
2294 corresponding entries in the @code{methods} list are enabled should be
2298 An xmethod worker should be an instance of a class derived from
2299 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
2300 or support the following interface:
2302 @defun XMethodWorker.get_arg_types (self)
2303 This method returns a sequence of @code{gdb.Type} objects corresponding
2304 to the arguments that the xmethod takes. It can return an empty
2305 sequence or @code{None} if the xmethod does not take any arguments.
2306 If the xmethod takes a single argument, then a single
2307 @code{gdb.Type} object corresponding to it can be returned.
2310 @defun XMethodWorker.__call__ (self, *args)
2311 This is the method which does the @emph{work} of the xmethod. The
2312 @var{args} arguments is the tuple of arguments to the xmethod. Each
2313 element in this tuple is a gdb.Value object. The first element is
2314 always the @code{this} pointer value.
2317 For @value{GDBN} to lookup xmethods, the xmethod matchers
2318 should be registered using the following function defined in the module
2321 @defun register_xmethod_matcher (locus, matcher, replace=False)
2322 The @code{matcher} is registered with @code{locus}, replacing an
2323 existing matcher with the same name as @code{matcher} if
2324 @code{replace} is @code{True}. @code{locus} can be a
2325 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
2326 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
2327 @code{None}. If it is @code{None}, then @code{matcher} is registered
2331 @node Writing an Xmethod
2332 @subsubsection Writing an Xmethod
2333 @cindex writing xmethods in Python
2335 Implementing xmethods in Python will require implementing xmethod
2336 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2337 the following C@t{++} class:
2343 MyClass (int a) : a_(a) @{ @}
2345 int geta (void) @{ return a_; @}
2346 int operator+ (int b);
2353 MyClass::operator+ (int b)
2360 Let us define two xmethods for the class @code{MyClass}, one
2361 replacing the method @code{geta}, and another adding an overloaded
2362 flavor of @code{operator+} which takes a @code{MyClass} argument (the
2363 C@t{++} code above already has an overloaded @code{operator+}
2364 which takes an @code{int} argument). The xmethod matcher can be
2368 class MyClass_geta(gdb.xmethod.XMethod):
2370 gdb.xmethod.XMethod.__init__(self, 'geta')
2372 def get_worker(self, method_name):
2373 if method_name == 'geta':
2374 return MyClassWorker_geta()
2377 class MyClass_sum(gdb.xmethod.XMethod):
2379 gdb.xmethod.XMethod.__init__(self, 'sum')
2381 def get_worker(self, method_name):
2382 if method_name == 'operator+':
2383 return MyClassWorker_plus()
2386 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2388 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2389 # List of methods 'managed' by this matcher
2390 self.methods = [MyClass_geta(), MyClass_sum()]
2392 def match(self, class_type, method_name):
2393 if class_type.tag != 'MyClass':
2396 for method in self.methods:
2398 worker = method.get_worker(method_name)
2400 workers.append(worker)
2406 Notice that the @code{match} method of @code{MyClassMatcher} returns
2407 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
2408 method, and a worker object of type @code{MyClassWorker_plus} for the
2409 @code{operator+} method. This is done indirectly via helper classes
2410 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
2411 @code{methods} attribute in a matcher as it is optional. However, if a
2412 matcher manages more than one xmethod, it is a good practice to list the
2413 xmethods in the @code{methods} attribute of the matcher. This will then
2414 facilitate enabling and disabling individual xmethods via the
2415 @code{enable/disable} commands. Notice also that a worker object is
2416 returned only if the corresponding entry in the @code{methods} attribute
2417 of the matcher is enabled.
2419 The implementation of the worker classes returned by the matcher setup
2420 above is as follows:
2423 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
2424 def get_arg_types(self):
2427 def __call__(self, obj):
2431 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
2432 def get_arg_types(self):
2433 return gdb.lookup_type('MyClass')
2435 def __call__(self, obj, other):
2436 return obj['a_'] + other['a_']
2439 For @value{GDBN} to actually lookup a xmethod, it has to be
2440 registered with it. The matcher defined above is registered with
2441 @value{GDBN} globally as follows:
2444 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
2447 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
2455 then, after loading the Python script defining the xmethod matchers
2456 and workers into @code{GDBN}, invoking the method @code{geta} or using
2457 the operator @code{+} on @code{obj} will invoke the xmethods
2468 Consider another example with a C++ template class:
2475 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
2476 ~MyTemplate () @{ delete [] data_; @}
2478 int footprint (void)
2480 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
2489 Let us implement an xmethod for the above class which serves as a
2490 replacement for the @code{footprint} method. The full code listing
2491 of the xmethod workers and xmethod matchers is as follows:
2494 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
2495 def __init__(self, class_type):
2496 self.class_type = class_type
2498 def get_arg_types(self):
2501 def __call__(self, obj):
2502 return (self.class_type.sizeof +
2504 self.class_type.template_argument(0).sizeof)
2507 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
2509 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
2511 def match(self, class_type, method_name):
2512 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
2514 method_name == 'footprint'):
2515 return MyTemplateWorker_footprint(class_type)
2518 Notice that, in this example, we have not used the @code{methods}
2519 attribute of the matcher as the matcher manages only one xmethod. The
2520 user can enable/disable this xmethod by enabling/disabling the matcher
2523 @node Inferiors In Python
2524 @subsubsection Inferiors In Python
2525 @cindex inferiors in Python
2527 @findex gdb.Inferior
2528 Programs which are being run under @value{GDBN} are called inferiors
2529 (@pxref{Inferiors and Programs}). Python scripts can access
2530 information about and manipulate inferiors controlled by @value{GDBN}
2531 via objects of the @code{gdb.Inferior} class.
2533 The following inferior-related functions are available in the @code{gdb}
2536 @defun gdb.inferiors ()
2537 Return a tuple containing all inferior objects.
2540 @defun gdb.selected_inferior ()
2541 Return an object representing the current inferior.
2544 A @code{gdb.Inferior} object has the following attributes:
2546 @defvar Inferior.num
2547 ID of inferior, as assigned by GDB.
2550 @defvar Inferior.pid
2551 Process ID of the inferior, as assigned by the underlying operating
2555 @defvar Inferior.was_attached
2556 Boolean signaling whether the inferior was created using `attach', or
2557 started by @value{GDBN} itself.
2560 A @code{gdb.Inferior} object has the following methods:
2562 @defun Inferior.is_valid ()
2563 Returns @code{True} if the @code{gdb.Inferior} object is valid,
2564 @code{False} if not. A @code{gdb.Inferior} object will become invalid
2565 if the inferior no longer exists within @value{GDBN}. All other
2566 @code{gdb.Inferior} methods will throw an exception if it is invalid
2567 at the time the method is called.
2570 @defun Inferior.threads ()
2571 This method returns a tuple holding all the threads which are valid
2572 when it is called. If there are no valid threads, the method will
2573 return an empty tuple.
2576 @findex Inferior.read_memory
2577 @defun Inferior.read_memory (address, length)
2578 Read @var{length} bytes of memory from the inferior, starting at
2579 @var{address}. Returns a buffer object, which behaves much like an array
2580 or a string. It can be modified and given to the
2581 @code{Inferior.write_memory} function. In @code{Python} 3, the return
2582 value is a @code{memoryview} object.
2585 @findex Inferior.write_memory
2586 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
2587 Write the contents of @var{buffer} to the inferior, starting at
2588 @var{address}. The @var{buffer} parameter must be a Python object
2589 which supports the buffer protocol, i.e., a string, an array or the
2590 object returned from @code{Inferior.read_memory}. If given, @var{length}
2591 determines the number of bytes from @var{buffer} to be written.
2594 @findex gdb.search_memory
2595 @defun Inferior.search_memory (address, length, pattern)
2596 Search a region of the inferior memory starting at @var{address} with
2597 the given @var{length} using the search pattern supplied in
2598 @var{pattern}. The @var{pattern} parameter must be a Python object
2599 which supports the buffer protocol, i.e., a string, an array or the
2600 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
2601 containing the address where the pattern was found, or @code{None} if
2602 the pattern could not be found.
2605 @node Events In Python
2606 @subsubsection Events In Python
2607 @cindex inferior events in Python
2609 @value{GDBN} provides a general event facility so that Python code can be
2610 notified of various state changes, particularly changes that occur in
2613 An @dfn{event} is just an object that describes some state change. The
2614 type of the object and its attributes will vary depending on the details
2615 of the change. All the existing events are described below.
2617 In order to be notified of an event, you must register an event handler
2618 with an @dfn{event registry}. An event registry is an object in the
2619 @code{gdb.events} module which dispatches particular events. A registry
2620 provides methods to register and unregister event handlers:
2622 @defun EventRegistry.connect (object)
2623 Add the given callable @var{object} to the registry. This object will be
2624 called when an event corresponding to this registry occurs.
2627 @defun EventRegistry.disconnect (object)
2628 Remove the given @var{object} from the registry. Once removed, the object
2629 will no longer receive notifications of events.
2635 def exit_handler (event):
2636 print "event type: exit"
2637 print "exit code: %d" % (event.exit_code)
2639 gdb.events.exited.connect (exit_handler)
2642 In the above example we connect our handler @code{exit_handler} to the
2643 registry @code{events.exited}. Once connected, @code{exit_handler} gets
2644 called when the inferior exits. The argument @dfn{event} in this example is
2645 of type @code{gdb.ExitedEvent}. As you can see in the example the
2646 @code{ExitedEvent} object has an attribute which indicates the exit code of
2649 The following is a listing of the event registries that are available and
2650 details of the events they emit:
2655 Emits @code{gdb.ThreadEvent}.
2657 Some events can be thread specific when @value{GDBN} is running in non-stop
2658 mode. When represented in Python, these events all extend
2659 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
2660 events which are emitted by this or other modules might extend this event.
2661 Examples of these events are @code{gdb.BreakpointEvent} and
2662 @code{gdb.ContinueEvent}.
2664 @defvar ThreadEvent.inferior_thread
2665 In non-stop mode this attribute will be set to the specific thread which was
2666 involved in the emitted event. Otherwise, it will be set to @code{None}.
2669 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
2671 This event indicates that the inferior has been continued after a stop. For
2672 inherited attribute refer to @code{gdb.ThreadEvent} above.
2675 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
2676 @code{events.ExitedEvent} has two attributes:
2677 @defvar ExitedEvent.exit_code
2678 An integer representing the exit code, if available, which the inferior
2679 has returned. (The exit code could be unavailable if, for example,
2680 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
2681 the attribute does not exist.
2683 @defvar ExitedEvent inferior
2684 A reference to the inferior which triggered the @code{exited} event.
2688 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
2690 Indicates that the inferior has stopped. All events emitted by this registry
2691 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
2692 will indicate the stopped thread when @value{GDBN} is running in non-stop
2693 mode. Refer to @code{gdb.ThreadEvent} above for more details.
2695 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
2697 This event indicates that the inferior or one of its threads has received as
2698 signal. @code{gdb.SignalEvent} has the following attributes:
2700 @defvar SignalEvent.stop_signal
2701 A string representing the signal received by the inferior. A list of possible
2702 signal values can be obtained by running the command @code{info signals} in
2703 the @value{GDBN} command prompt.
2706 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
2708 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
2709 been hit, and has the following attributes:
2711 @defvar BreakpointEvent.breakpoints
2712 A sequence containing references to all the breakpoints (type
2713 @code{gdb.Breakpoint}) that were hit.
2714 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
2716 @defvar BreakpointEvent.breakpoint
2717 A reference to the first breakpoint that was hit.
2718 This function is maintained for backward compatibility and is now deprecated
2719 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
2722 @item events.new_objfile
2723 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
2724 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
2726 @defvar NewObjFileEvent.new_objfile
2727 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
2728 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
2731 @item events.clear_objfiles
2732 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
2733 files for a program space has been reset.
2734 @code{gdb.ClearObjFilesEvent} has one attribute:
2736 @defvar ClearObjFilesEvent.progspace
2737 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
2738 been cleared. @xref{Progspaces In Python}.
2741 @item events.inferior_call_pre
2742 Emits @code{gdb.InferiorCallPreEvent} which indicates that a function in
2743 the inferior is about to be called.
2745 @defvar InferiorCallPreEvent.ptid
2746 The thread in which the call will be run.
2749 @defvar InferiorCallPreEvent.address
2750 The location of the function to be called.
2753 @item events.inferior_call_post
2754 Emits @code{gdb.InferiorCallPostEvent} which indicates that a function in
2755 the inferior has returned.
2757 @defvar InferiorCallPostEvent.ptid
2758 The thread in which the call was run.
2761 @defvar InferiorCallPostEvent.address
2762 The location of the function that was called.
2765 @item events.memory_changed
2766 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
2767 inferior has been modified by the @value{GDBN} user, for instance via a
2768 command like @w{@code{set *addr = value}}. The event has the following
2771 @defvar MemoryChangedEvent.address
2772 The start address of the changed region.
2775 @defvar MemoryChangedEvent.length
2776 Length in bytes of the changed region.
2779 @item events.register_changed
2780 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
2781 inferior has been modified by the @value{GDBN} user.
2783 @defvar RegisterChangedEvent.frame
2784 A gdb.Frame object representing the frame in which the register was modified.
2786 @defvar RegisterChangedEvent.regnum
2787 Denotes which register was modified.
2792 @node Threads In Python
2793 @subsubsection Threads In Python
2794 @cindex threads in python
2796 @findex gdb.InferiorThread
2797 Python scripts can access information about, and manipulate inferior threads
2798 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
2800 The following thread-related functions are available in the @code{gdb}
2803 @findex gdb.selected_thread
2804 @defun gdb.selected_thread ()
2805 This function returns the thread object for the selected thread. If there
2806 is no selected thread, this will return @code{None}.
2809 A @code{gdb.InferiorThread} object has the following attributes:
2811 @defvar InferiorThread.name
2812 The name of the thread. If the user specified a name using
2813 @code{thread name}, then this returns that name. Otherwise, if an
2814 OS-supplied name is available, then it is returned. Otherwise, this
2815 returns @code{None}.
2817 This attribute can be assigned to. The new value must be a string
2818 object, which sets the new name, or @code{None}, which removes any
2819 user-specified thread name.
2822 @defvar InferiorThread.num
2823 ID of the thread, as assigned by GDB.
2826 @defvar InferiorThread.ptid
2827 ID of the thread, as assigned by the operating system. This attribute is a
2828 tuple containing three integers. The first is the Process ID (PID); the second
2829 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
2830 Either the LWPID or TID may be 0, which indicates that the operating system
2831 does not use that identifier.
2834 A @code{gdb.InferiorThread} object has the following methods:
2836 @defun InferiorThread.is_valid ()
2837 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
2838 @code{False} if not. A @code{gdb.InferiorThread} object will become
2839 invalid if the thread exits, or the inferior that the thread belongs
2840 is deleted. All other @code{gdb.InferiorThread} methods will throw an
2841 exception if it is invalid at the time the method is called.
2844 @defun InferiorThread.switch ()
2845 This changes @value{GDBN}'s currently selected thread to the one represented
2849 @defun InferiorThread.is_stopped ()
2850 Return a Boolean indicating whether the thread is stopped.
2853 @defun InferiorThread.is_running ()
2854 Return a Boolean indicating whether the thread is running.
2857 @defun InferiorThread.is_exited ()
2858 Return a Boolean indicating whether the thread is exited.
2861 @node Commands In Python
2862 @subsubsection Commands In Python
2864 @cindex commands in python
2865 @cindex python commands
2866 You can implement new @value{GDBN} CLI commands in Python. A CLI
2867 command is implemented using an instance of the @code{gdb.Command}
2868 class, most commonly using a subclass.
2870 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
2871 The object initializer for @code{Command} registers the new command
2872 with @value{GDBN}. This initializer is normally invoked from the
2873 subclass' own @code{__init__} method.
2875 @var{name} is the name of the command. If @var{name} consists of
2876 multiple words, then the initial words are looked for as prefix
2877 commands. In this case, if one of the prefix commands does not exist,
2878 an exception is raised.
2880 There is no support for multi-line commands.
2882 @var{command_class} should be one of the @samp{COMMAND_} constants
2883 defined below. This argument tells @value{GDBN} how to categorize the
2884 new command in the help system.
2886 @var{completer_class} is an optional argument. If given, it should be
2887 one of the @samp{COMPLETE_} constants defined below. This argument
2888 tells @value{GDBN} how to perform completion for this command. If not
2889 given, @value{GDBN} will attempt to complete using the object's
2890 @code{complete} method (see below); if no such method is found, an
2891 error will occur when completion is attempted.
2893 @var{prefix} is an optional argument. If @code{True}, then the new
2894 command is a prefix command; sub-commands of this command may be
2897 The help text for the new command is taken from the Python
2898 documentation string for the command's class, if there is one. If no
2899 documentation string is provided, the default value ``This command is
2900 not documented.'' is used.
2903 @cindex don't repeat Python command
2904 @defun Command.dont_repeat ()
2905 By default, a @value{GDBN} command is repeated when the user enters a
2906 blank line at the command prompt. A command can suppress this
2907 behavior by invoking the @code{dont_repeat} method. This is similar
2908 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
2911 @defun Command.invoke (argument, from_tty)
2912 This method is called by @value{GDBN} when this command is invoked.
2914 @var{argument} is a string. It is the argument to the command, after
2915 leading and trailing whitespace has been stripped.
2917 @var{from_tty} is a boolean argument. When true, this means that the
2918 command was entered by the user at the terminal; when false it means
2919 that the command came from elsewhere.
2921 If this method throws an exception, it is turned into a @value{GDBN}
2922 @code{error} call. Otherwise, the return value is ignored.
2924 @findex gdb.string_to_argv
2925 To break @var{argument} up into an argv-like string use
2926 @code{gdb.string_to_argv}. This function behaves identically to
2927 @value{GDBN}'s internal argument lexer @code{buildargv}.
2928 It is recommended to use this for consistency.
2929 Arguments are separated by spaces and may be quoted.
2933 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
2934 ['1', '2 "3', '4 "5', "6 '7"]
2939 @cindex completion of Python commands
2940 @defun Command.complete (text, word)
2941 This method is called by @value{GDBN} when the user attempts
2942 completion on this command. All forms of completion are handled by
2943 this method, that is, the @key{TAB} and @key{M-?} key bindings
2944 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
2947 The arguments @var{text} and @var{word} are both strings; @var{text}
2948 holds the complete command line up to the cursor's location, while
2949 @var{word} holds the last word of the command line; this is computed
2950 using a word-breaking heuristic.
2952 The @code{complete} method can return several values:
2955 If the return value is a sequence, the contents of the sequence are
2956 used as the completions. It is up to @code{complete} to ensure that the
2957 contents actually do complete the word. A zero-length sequence is
2958 allowed, it means that there were no completions available. Only
2959 string elements of the sequence are used; other elements in the
2960 sequence are ignored.
2963 If the return value is one of the @samp{COMPLETE_} constants defined
2964 below, then the corresponding @value{GDBN}-internal completion
2965 function is invoked, and its result is used.
2968 All other results are treated as though there were no available
2973 When a new command is registered, it must be declared as a member of
2974 some general class of commands. This is used to classify top-level
2975 commands in the on-line help system; note that prefix commands are not
2976 listed under their own category but rather that of their top-level
2977 command. The available classifications are represented by constants
2978 defined in the @code{gdb} module:
2981 @findex COMMAND_NONE
2982 @findex gdb.COMMAND_NONE
2983 @item gdb.COMMAND_NONE
2984 The command does not belong to any particular class. A command in
2985 this category will not be displayed in any of the help categories.
2987 @findex COMMAND_RUNNING
2988 @findex gdb.COMMAND_RUNNING
2989 @item gdb.COMMAND_RUNNING
2990 The command is related to running the inferior. For example,
2991 @code{start}, @code{step}, and @code{continue} are in this category.
2992 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
2993 commands in this category.
2995 @findex COMMAND_DATA
2996 @findex gdb.COMMAND_DATA
2997 @item gdb.COMMAND_DATA
2998 The command is related to data or variables. For example,
2999 @code{call}, @code{find}, and @code{print} are in this category. Type
3000 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
3003 @findex COMMAND_STACK
3004 @findex gdb.COMMAND_STACK
3005 @item gdb.COMMAND_STACK
3006 The command has to do with manipulation of the stack. For example,
3007 @code{backtrace}, @code{frame}, and @code{return} are in this
3008 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
3009 list of commands in this category.
3011 @findex COMMAND_FILES
3012 @findex gdb.COMMAND_FILES
3013 @item gdb.COMMAND_FILES
3014 This class is used for file-related commands. For example,
3015 @code{file}, @code{list} and @code{section} are in this category.
3016 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
3017 commands in this category.
3019 @findex COMMAND_SUPPORT
3020 @findex gdb.COMMAND_SUPPORT
3021 @item gdb.COMMAND_SUPPORT
3022 This should be used for ``support facilities'', generally meaning
3023 things that are useful to the user when interacting with @value{GDBN},
3024 but not related to the state of the inferior. For example,
3025 @code{help}, @code{make}, and @code{shell} are in this category. Type
3026 @kbd{help support} at the @value{GDBN} prompt to see a list of
3027 commands in this category.
3029 @findex COMMAND_STATUS
3030 @findex gdb.COMMAND_STATUS
3031 @item gdb.COMMAND_STATUS
3032 The command is an @samp{info}-related command, that is, related to the
3033 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
3034 and @code{show} are in this category. Type @kbd{help status} at the
3035 @value{GDBN} prompt to see a list of commands in this category.
3037 @findex COMMAND_BREAKPOINTS
3038 @findex gdb.COMMAND_BREAKPOINTS
3039 @item gdb.COMMAND_BREAKPOINTS
3040 The command has to do with breakpoints. For example, @code{break},
3041 @code{clear}, and @code{delete} are in this category. Type @kbd{help
3042 breakpoints} at the @value{GDBN} prompt to see a list of commands in
3045 @findex COMMAND_TRACEPOINTS
3046 @findex gdb.COMMAND_TRACEPOINTS
3047 @item gdb.COMMAND_TRACEPOINTS
3048 The command has to do with tracepoints. For example, @code{trace},
3049 @code{actions}, and @code{tfind} are in this category. Type
3050 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
3051 commands in this category.
3053 @findex COMMAND_USER
3054 @findex gdb.COMMAND_USER
3055 @item gdb.COMMAND_USER
3056 The command is a general purpose command for the user, and typically
3057 does not fit in one of the other categories.
3058 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
3059 a list of commands in this category, as well as the list of gdb macros
3060 (@pxref{Sequences}).
3062 @findex COMMAND_OBSCURE
3063 @findex gdb.COMMAND_OBSCURE
3064 @item gdb.COMMAND_OBSCURE
3065 The command is only used in unusual circumstances, or is not of
3066 general interest to users. For example, @code{checkpoint},
3067 @code{fork}, and @code{stop} are in this category. Type @kbd{help
3068 obscure} at the @value{GDBN} prompt to see a list of commands in this
3071 @findex COMMAND_MAINTENANCE
3072 @findex gdb.COMMAND_MAINTENANCE
3073 @item gdb.COMMAND_MAINTENANCE
3074 The command is only useful to @value{GDBN} maintainers. The
3075 @code{maintenance} and @code{flushregs} commands are in this category.
3076 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
3077 commands in this category.
3080 A new command can use a predefined completion function, either by
3081 specifying it via an argument at initialization, or by returning it
3082 from the @code{complete} method. These predefined completion
3083 constants are all defined in the @code{gdb} module:
3086 @vindex COMPLETE_NONE
3087 @item gdb.COMPLETE_NONE
3088 This constant means that no completion should be done.
3090 @vindex COMPLETE_FILENAME
3091 @item gdb.COMPLETE_FILENAME
3092 This constant means that filename completion should be performed.
3094 @vindex COMPLETE_LOCATION
3095 @item gdb.COMPLETE_LOCATION
3096 This constant means that location completion should be done.
3097 @xref{Specify Location}.
3099 @vindex COMPLETE_COMMAND
3100 @item gdb.COMPLETE_COMMAND
3101 This constant means that completion should examine @value{GDBN}
3104 @vindex COMPLETE_SYMBOL
3105 @item gdb.COMPLETE_SYMBOL
3106 This constant means that completion should be done using symbol names
3109 @vindex COMPLETE_EXPRESSION
3110 @item gdb.COMPLETE_EXPRESSION
3111 This constant means that completion should be done on expressions.
3112 Often this means completing on symbol names, but some language
3113 parsers also have support for completing on field names.
3116 The following code snippet shows how a trivial CLI command can be
3117 implemented in Python:
3120 class HelloWorld (gdb.Command):
3121 """Greet the whole world."""
3123 def __init__ (self):
3124 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
3126 def invoke (self, arg, from_tty):
3127 print "Hello, World!"
3132 The last line instantiates the class, and is necessary to trigger the
3133 registration of the command with @value{GDBN}. Depending on how the
3134 Python code is read into @value{GDBN}, you may need to import the
3135 @code{gdb} module explicitly.
3137 @node Parameters In Python
3138 @subsubsection Parameters In Python
3140 @cindex parameters in python
3141 @cindex python parameters
3142 @tindex gdb.Parameter
3144 You can implement new @value{GDBN} parameters using Python. A new
3145 parameter is implemented as an instance of the @code{gdb.Parameter}
3148 Parameters are exposed to the user via the @code{set} and
3149 @code{show} commands. @xref{Help}.
3151 There are many parameters that already exist and can be set in
3152 @value{GDBN}. Two examples are: @code{set follow fork} and
3153 @code{set charset}. Setting these parameters influences certain
3154 behavior in @value{GDBN}. Similarly, you can define parameters that
3155 can be used to influence behavior in custom Python scripts and commands.
3157 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
3158 The object initializer for @code{Parameter} registers the new
3159 parameter with @value{GDBN}. This initializer is normally invoked
3160 from the subclass' own @code{__init__} method.
3162 @var{name} is the name of the new parameter. If @var{name} consists
3163 of multiple words, then the initial words are looked for as prefix
3164 parameters. An example of this can be illustrated with the
3165 @code{set print} set of parameters. If @var{name} is
3166 @code{print foo}, then @code{print} will be searched as the prefix
3167 parameter. In this case the parameter can subsequently be accessed in
3168 @value{GDBN} as @code{set print foo}.
3170 If @var{name} consists of multiple words, and no prefix parameter group
3171 can be found, an exception is raised.
3173 @var{command-class} should be one of the @samp{COMMAND_} constants
3174 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
3175 categorize the new parameter in the help system.
3177 @var{parameter-class} should be one of the @samp{PARAM_} constants
3178 defined below. This argument tells @value{GDBN} the type of the new
3179 parameter; this information is used for input validation and
3182 If @var{parameter-class} is @code{PARAM_ENUM}, then
3183 @var{enum-sequence} must be a sequence of strings. These strings
3184 represent the possible values for the parameter.
3186 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
3187 of a fourth argument will cause an exception to be thrown.
3189 The help text for the new parameter is taken from the Python
3190 documentation string for the parameter's class, if there is one. If
3191 there is no documentation string, a default value is used.
3194 @defvar Parameter.set_doc
3195 If this attribute exists, and is a string, then its value is used as
3196 the help text for this parameter's @code{set} command. The value is
3197 examined when @code{Parameter.__init__} is invoked; subsequent changes
3201 @defvar Parameter.show_doc
3202 If this attribute exists, and is a string, then its value is used as
3203 the help text for this parameter's @code{show} command. The value is
3204 examined when @code{Parameter.__init__} is invoked; subsequent changes
3208 @defvar Parameter.value
3209 The @code{value} attribute holds the underlying value of the
3210 parameter. It can be read and assigned to just as any other
3211 attribute. @value{GDBN} does validation when assignments are made.
3214 There are two methods that should be implemented in any
3215 @code{Parameter} class. These are:
3217 @defun Parameter.get_set_string (self)
3218 @value{GDBN} will call this method when a @var{parameter}'s value has
3219 been changed via the @code{set} API (for example, @kbd{set foo off}).
3220 The @code{value} attribute has already been populated with the new
3221 value and may be used in output. This method must return a string.
3224 @defun Parameter.get_show_string (self, svalue)
3225 @value{GDBN} will call this method when a @var{parameter}'s
3226 @code{show} API has been invoked (for example, @kbd{show foo}). The
3227 argument @code{svalue} receives the string representation of the
3228 current value. This method must return a string.
3231 When a new parameter is defined, its type must be specified. The
3232 available types are represented by constants defined in the @code{gdb}
3236 @findex PARAM_BOOLEAN
3237 @findex gdb.PARAM_BOOLEAN
3238 @item gdb.PARAM_BOOLEAN
3239 The value is a plain boolean. The Python boolean values, @code{True}
3240 and @code{False} are the only valid values.
3242 @findex PARAM_AUTO_BOOLEAN
3243 @findex gdb.PARAM_AUTO_BOOLEAN
3244 @item gdb.PARAM_AUTO_BOOLEAN
3245 The value has three possible states: true, false, and @samp{auto}. In
3246 Python, true and false are represented using boolean constants, and
3247 @samp{auto} is represented using @code{None}.
3249 @findex PARAM_UINTEGER
3250 @findex gdb.PARAM_UINTEGER
3251 @item gdb.PARAM_UINTEGER
3252 The value is an unsigned integer. The value of 0 should be
3253 interpreted to mean ``unlimited''.
3255 @findex PARAM_INTEGER
3256 @findex gdb.PARAM_INTEGER
3257 @item gdb.PARAM_INTEGER
3258 The value is a signed integer. The value of 0 should be interpreted
3259 to mean ``unlimited''.
3261 @findex PARAM_STRING
3262 @findex gdb.PARAM_STRING
3263 @item gdb.PARAM_STRING
3264 The value is a string. When the user modifies the string, any escape
3265 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
3266 translated into corresponding characters and encoded into the current
3269 @findex PARAM_STRING_NOESCAPE
3270 @findex gdb.PARAM_STRING_NOESCAPE
3271 @item gdb.PARAM_STRING_NOESCAPE
3272 The value is a string. When the user modifies the string, escapes are
3273 passed through untranslated.
3275 @findex PARAM_OPTIONAL_FILENAME
3276 @findex gdb.PARAM_OPTIONAL_FILENAME
3277 @item gdb.PARAM_OPTIONAL_FILENAME
3278 The value is a either a filename (a string), or @code{None}.
3280 @findex PARAM_FILENAME
3281 @findex gdb.PARAM_FILENAME
3282 @item gdb.PARAM_FILENAME
3283 The value is a filename. This is just like
3284 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
3286 @findex PARAM_ZINTEGER
3287 @findex gdb.PARAM_ZINTEGER
3288 @item gdb.PARAM_ZINTEGER
3289 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
3290 is interpreted as itself.
3293 @findex gdb.PARAM_ENUM
3294 @item gdb.PARAM_ENUM
3295 The value is a string, which must be one of a collection string
3296 constants provided when the parameter is created.
3299 @node Functions In Python
3300 @subsubsection Writing new convenience functions
3302 @cindex writing convenience functions
3303 @cindex convenience functions in python
3304 @cindex python convenience functions
3305 @tindex gdb.Function
3307 You can implement new convenience functions (@pxref{Convenience Vars})
3308 in Python. A convenience function is an instance of a subclass of the
3309 class @code{gdb.Function}.
3311 @defun Function.__init__ (name)
3312 The initializer for @code{Function} registers the new function with
3313 @value{GDBN}. The argument @var{name} is the name of the function,
3314 a string. The function will be visible to the user as a convenience
3315 variable of type @code{internal function}, whose name is the same as
3316 the given @var{name}.
3318 The documentation for the new function is taken from the documentation
3319 string for the new class.
3322 @defun Function.invoke (@var{*args})
3323 When a convenience function is evaluated, its arguments are converted
3324 to instances of @code{gdb.Value}, and then the function's
3325 @code{invoke} method is called. Note that @value{GDBN} does not
3326 predetermine the arity of convenience functions. Instead, all
3327 available arguments are passed to @code{invoke}, following the
3328 standard Python calling convention. In particular, a convenience
3329 function can have default values for parameters without ill effect.
3331 The return value of this method is used as its value in the enclosing
3332 expression. If an ordinary Python value is returned, it is converted
3333 to a @code{gdb.Value} following the usual rules.
3336 The following code snippet shows how a trivial convenience function can
3337 be implemented in Python:
3340 class Greet (gdb.Function):
3341 """Return string to greet someone.
3342 Takes a name as argument."""
3344 def __init__ (self):
3345 super (Greet, self).__init__ ("greet")
3347 def invoke (self, name):
3348 return "Hello, %s!" % name.string ()
3353 The last line instantiates the class, and is necessary to trigger the
3354 registration of the function with @value{GDBN}. Depending on how the
3355 Python code is read into @value{GDBN}, you may need to import the
3356 @code{gdb} module explicitly.
3358 Now you can use the function in an expression:
3361 (gdb) print $greet("Bob")
3365 @node Progspaces In Python
3366 @subsubsection Program Spaces In Python
3368 @cindex progspaces in python
3369 @tindex gdb.Progspace
3371 A program space, or @dfn{progspace}, represents a symbolic view
3372 of an address space.
3373 It consists of all of the objfiles of the program.
3374 @xref{Objfiles In Python}.
3375 @xref{Inferiors and Programs, program spaces}, for more details
3376 about program spaces.
3378 The following progspace-related functions are available in the
3381 @findex gdb.current_progspace
3382 @defun gdb.current_progspace ()
3383 This function returns the program space of the currently selected inferior.
3384 @xref{Inferiors and Programs}.
3387 @findex gdb.progspaces
3388 @defun gdb.progspaces ()
3389 Return a sequence of all the progspaces currently known to @value{GDBN}.
3392 Each progspace is represented by an instance of the @code{gdb.Progspace}
3395 @defvar Progspace.filename
3396 The file name of the progspace as a string.
3399 @defvar Progspace.pretty_printers
3400 The @code{pretty_printers} attribute is a list of functions. It is
3401 used to look up pretty-printers. A @code{Value} is passed to each
3402 function in order; if the function returns @code{None}, then the
3403 search continues. Otherwise, the return value should be an object
3404 which is used to format the value. @xref{Pretty Printing API}, for more
3408 @defvar Progspace.type_printers
3409 The @code{type_printers} attribute is a list of type printer objects.
3410 @xref{Type Printing API}, for more information.
3413 @defvar Progspace.frame_filters
3414 The @code{frame_filters} attribute is a dictionary of frame filter
3415 objects. @xref{Frame Filter API}, for more information.
3418 One may add arbitrary attributes to @code{gdb.Progspace} objects
3419 in the usual Python way.
3420 This is useful if, for example, one needs to do some extra record keeping
3421 associated with the program space.
3423 In this contrived example, we want to perform some processing when
3424 an objfile with a certain symbol is loaded, but we only want to do
3425 this once because it is expensive. To achieve this we record the results
3426 with the program space because we can't predict when the desired objfile
3431 def clear_objfiles_handler(event):
3432 event.progspace.expensive_computation = None
3433 def expensive(symbol):
3434 """A mock routine to perform an "expensive" computation on symbol."""
3435 print "Computing the answer to the ultimate question ..."
3437 def new_objfile_handler(event):
3438 objfile = event.new_objfile
3439 progspace = objfile.progspace
3440 if not hasattr(progspace, 'expensive_computation') or \
3441 progspace.expensive_computation is None:
3442 # We use 'main' for the symbol to keep the example simple.
3443 # Note: There's no current way to constrain the lookup
3445 symbol = gdb.lookup_global_symbol('main')
3446 if symbol is not None:
3447 progspace.expensive_computation = expensive(symbol)
3448 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
3449 gdb.events.new_objfile.connect(new_objfile_handler)
3451 (gdb) file /tmp/hello
3452 Reading symbols from /tmp/hello...done.
3453 Computing the answer to the ultimate question ...
3454 (gdb) python print gdb.current_progspace().expensive_computation
3457 Starting program: /tmp/hello
3459 [Inferior 1 (process 4242) exited normally]
3462 @node Objfiles In Python
3463 @subsubsection Objfiles In Python
3465 @cindex objfiles in python
3468 @value{GDBN} loads symbols for an inferior from various
3469 symbol-containing files (@pxref{Files}). These include the primary
3470 executable file, any shared libraries used by the inferior, and any
3471 separate debug info files (@pxref{Separate Debug Files}).
3472 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
3474 The following objfile-related functions are available in the
3477 @findex gdb.current_objfile
3478 @defun gdb.current_objfile ()
3479 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
3480 sets the ``current objfile'' to the corresponding objfile. This
3481 function returns the current objfile. If there is no current objfile,
3482 this function returns @code{None}.
3485 @findex gdb.objfiles
3486 @defun gdb.objfiles ()
3487 Return a sequence of all the objfiles current known to @value{GDBN}.
3488 @xref{Objfiles In Python}.
3491 @findex gdb.lookup_objfile
3492 @defun gdb.lookup_objfile (name @r{[}, by_build_id{]})
3493 Look up @var{name}, a file name or build ID, in the list of objfiles
3494 for the current program space (@pxref{Progspaces In Python}).
3495 If the objfile is not found throw the Python @code{ValueError} exception.
3497 If @var{name} is a relative file name, then it will match any
3498 source file name with the same trailing components. For example, if
3499 @var{name} is @samp{gcc/expr.c}, then it will match source file
3500 name of @file{/build/trunk/gcc/expr.c}, but not
3501 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
3503 If @var{by_build_id} is provided and is @code{True} then @var{name}
3504 is the build ID of the objfile. Otherwise, @var{name} is a file name.
3505 This is supported only on some operating systems, notably those which use
3506 the ELF format for binary files and the @sc{gnu} Binutils. For more details
3507 about this feature, see the description of the @option{--build-id}
3508 command-line option in @ref{Options, , Command Line Options, ld.info,
3512 Each objfile is represented by an instance of the @code{gdb.Objfile}
3515 @defvar Objfile.filename
3516 The file name of the objfile as a string, with symbolic links resolved.
3518 The value is @code{None} if the objfile is no longer valid.
3519 See the @code{gdb.Objfile.is_valid} method, described below.
3522 @defvar Objfile.username
3523 The file name of the objfile as specified by the user as a string.
3525 The value is @code{None} if the objfile is no longer valid.
3526 See the @code{gdb.Objfile.is_valid} method, described below.
3529 @defvar Objfile.owner
3530 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
3531 object that debug info is being provided for.
3532 Otherwise this is @code{None}.
3533 Separate debug info objfiles are added with the
3534 @code{gdb.Objfile.add_separate_debug_file} method, described below.
3537 @defvar Objfile.build_id
3538 The build ID of the objfile as a string.
3539 If the objfile does not have a build ID then the value is @code{None}.
3541 This is supported only on some operating systems, notably those which use
3542 the ELF format for binary files and the @sc{gnu} Binutils. For more details
3543 about this feature, see the description of the @option{--build-id}
3544 command-line option in @ref{Options, , Command Line Options, ld.info,
3548 @defvar Objfile.progspace
3549 The containing program space of the objfile as a @code{gdb.Progspace}
3550 object. @xref{Progspaces In Python}.
3553 @defvar Objfile.pretty_printers
3554 The @code{pretty_printers} attribute is a list of functions. It is
3555 used to look up pretty-printers. A @code{Value} is passed to each
3556 function in order; if the function returns @code{None}, then the
3557 search continues. Otherwise, the return value should be an object
3558 which is used to format the value. @xref{Pretty Printing API}, for more
3562 @defvar Objfile.type_printers
3563 The @code{type_printers} attribute is a list of type printer objects.
3564 @xref{Type Printing API}, for more information.
3567 @defvar Objfile.frame_filters
3568 The @code{frame_filters} attribute is a dictionary of frame filter
3569 objects. @xref{Frame Filter API}, for more information.
3572 One may add arbitrary attributes to @code{gdb.Objfile} objects
3573 in the usual Python way.
3574 This is useful if, for example, one needs to do some extra record keeping
3575 associated with the objfile.
3577 In this contrived example we record the time when @value{GDBN}
3583 def new_objfile_handler(event):
3584 # Set the time_loaded attribute of the new objfile.
3585 event.new_objfile.time_loaded = datetime.datetime.today()
3586 gdb.events.new_objfile.connect(new_objfile_handler)
3589 Reading symbols from ./hello...done.
3590 (gdb) python print gdb.objfiles()[0].time_loaded
3591 2014-10-09 11:41:36.770345
3594 A @code{gdb.Objfile} object has the following methods:
3596 @defun Objfile.is_valid ()
3597 Returns @code{True} if the @code{gdb.Objfile} object is valid,
3598 @code{False} if not. A @code{gdb.Objfile} object can become invalid
3599 if the object file it refers to is not loaded in @value{GDBN} any
3600 longer. All other @code{gdb.Objfile} methods will throw an exception
3601 if it is invalid at the time the method is called.
3604 @defun Objfile.add_separate_debug_file (file)
3605 Add @var{file} to the list of files that @value{GDBN} will search for
3606 debug information for the objfile.
3607 This is useful when the debug info has been removed from the program
3608 and stored in a separate file. @value{GDBN} has built-in support for
3609 finding separate debug info files (@pxref{Separate Debug Files}), but if
3610 the file doesn't live in one of the standard places that @value{GDBN}
3611 searches then this function can be used to add a debug info file
3612 from a different place.
3615 @node Frames In Python
3616 @subsubsection Accessing inferior stack frames from Python.
3618 @cindex frames in python
3619 When the debugged program stops, @value{GDBN} is able to analyze its call
3620 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
3621 represents a frame in the stack. A @code{gdb.Frame} object is only valid
3622 while its corresponding frame exists in the inferior's stack. If you try
3623 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
3624 exception (@pxref{Exception Handling}).
3626 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
3630 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
3634 The following frame-related functions are available in the @code{gdb} module:
3636 @findex gdb.selected_frame
3637 @defun gdb.selected_frame ()
3638 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
3641 @findex gdb.newest_frame
3642 @defun gdb.newest_frame ()
3643 Return the newest frame object for the selected thread.
3646 @defun gdb.frame_stop_reason_string (reason)
3647 Return a string explaining the reason why @value{GDBN} stopped unwinding
3648 frames, as expressed by the given @var{reason} code (an integer, see the
3649 @code{unwind_stop_reason} method further down in this section).
3652 A @code{gdb.Frame} object has the following methods:
3654 @defun Frame.is_valid ()
3655 Returns true if the @code{gdb.Frame} object is valid, false if not.
3656 A frame object can become invalid if the frame it refers to doesn't
3657 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
3658 an exception if it is invalid at the time the method is called.
3661 @defun Frame.name ()
3662 Returns the function name of the frame, or @code{None} if it can't be
3666 @defun Frame.architecture ()
3667 Returns the @code{gdb.Architecture} object corresponding to the frame's
3668 architecture. @xref{Architectures In Python}.
3671 @defun Frame.type ()
3672 Returns the type of the frame. The value can be one of:
3674 @item gdb.NORMAL_FRAME
3675 An ordinary stack frame.
3677 @item gdb.DUMMY_FRAME
3678 A fake stack frame that was created by @value{GDBN} when performing an
3679 inferior function call.
3681 @item gdb.INLINE_FRAME
3682 A frame representing an inlined function. The function was inlined
3683 into a @code{gdb.NORMAL_FRAME} that is older than this one.
3685 @item gdb.TAILCALL_FRAME
3686 A frame representing a tail call. @xref{Tail Call Frames}.
3688 @item gdb.SIGTRAMP_FRAME
3689 A signal trampoline frame. This is the frame created by the OS when
3690 it calls into a signal handler.
3692 @item gdb.ARCH_FRAME
3693 A fake stack frame representing a cross-architecture call.
3695 @item gdb.SENTINEL_FRAME
3696 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
3701 @defun Frame.unwind_stop_reason ()
3702 Return an integer representing the reason why it's not possible to find
3703 more frames toward the outermost frame. Use
3704 @code{gdb.frame_stop_reason_string} to convert the value returned by this
3705 function to a string. The value can be one of:
3708 @item gdb.FRAME_UNWIND_NO_REASON
3709 No particular reason (older frames should be available).
3711 @item gdb.FRAME_UNWIND_NULL_ID
3712 The previous frame's analyzer returns an invalid result. This is no
3713 longer used by @value{GDBN}, and is kept only for backward
3716 @item gdb.FRAME_UNWIND_OUTERMOST
3717 This frame is the outermost.
3719 @item gdb.FRAME_UNWIND_UNAVAILABLE
3720 Cannot unwind further, because that would require knowing the
3721 values of registers or memory that have not been collected.
3723 @item gdb.FRAME_UNWIND_INNER_ID
3724 This frame ID looks like it ought to belong to a NEXT frame,
3725 but we got it for a PREV frame. Normally, this is a sign of
3726 unwinder failure. It could also indicate stack corruption.
3728 @item gdb.FRAME_UNWIND_SAME_ID
3729 This frame has the same ID as the previous one. That means
3730 that unwinding further would almost certainly give us another
3731 frame with exactly the same ID, so break the chain. Normally,
3732 this is a sign of unwinder failure. It could also indicate
3735 @item gdb.FRAME_UNWIND_NO_SAVED_PC
3736 The frame unwinder did not find any saved PC, but we needed
3737 one to unwind further.
3739 @item gdb.FRAME_UNWIND_MEMORY_ERROR
3740 The frame unwinder caused an error while trying to access memory.
3742 @item gdb.FRAME_UNWIND_FIRST_ERROR
3743 Any stop reason greater or equal to this value indicates some kind
3744 of error. This special value facilitates writing code that tests
3745 for errors in unwinding in a way that will work correctly even if
3746 the list of the other values is modified in future @value{GDBN}
3747 versions. Using it, you could write:
3749 reason = gdb.selected_frame().unwind_stop_reason ()
3750 reason_str = gdb.frame_stop_reason_string (reason)
3751 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
3752 print "An error occured: %s" % reason_str
3759 Returns the frame's resume address.
3762 @defun Frame.block ()
3763 Return the frame's code block. @xref{Blocks In Python}.
3766 @defun Frame.function ()
3767 Return the symbol for the function corresponding to this frame.
3768 @xref{Symbols In Python}.
3771 @defun Frame.older ()
3772 Return the frame that called this frame.
3775 @defun Frame.newer ()
3776 Return the frame called by this frame.
3779 @defun Frame.find_sal ()
3780 Return the frame's symtab and line object.
3781 @xref{Symbol Tables In Python}.
3784 @defun Frame.read_register (register)
3785 Return the value of @var{register} in this frame. The @var{register}
3786 argument must be a string (e.g., @code{'sp'} or @code{'rax'}).
3787 Returns a @code{Gdb.Value} object. Throws an exception if @var{register}
3791 @defun Frame.read_var (variable @r{[}, block@r{]})
3792 Return the value of @var{variable} in this frame. If the optional
3793 argument @var{block} is provided, search for the variable from that
3794 block; otherwise start at the frame's current block (which is
3795 determined by the frame's current program counter). The @var{variable}
3796 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
3797 @code{gdb.Block} object.
3800 @defun Frame.select ()
3801 Set this frame to be the selected frame. @xref{Stack, ,Examining the
3805 @node Blocks In Python
3806 @subsubsection Accessing blocks from Python.
3808 @cindex blocks in python
3811 In @value{GDBN}, symbols are stored in blocks. A block corresponds
3812 roughly to a scope in the source code. Blocks are organized
3813 hierarchically, and are represented individually in Python as a
3814 @code{gdb.Block}. Blocks rely on debugging information being
3817 A frame has a block. Please see @ref{Frames In Python}, for a more
3818 in-depth discussion of frames.
3820 The outermost block is known as the @dfn{global block}. The global
3821 block typically holds public global variables and functions.
3823 The block nested just inside the global block is the @dfn{static
3824 block}. The static block typically holds file-scoped variables and
3827 @value{GDBN} provides a method to get a block's superblock, but there
3828 is currently no way to examine the sub-blocks of a block, or to
3829 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
3832 Here is a short example that should help explain blocks:
3835 /* This is in the global block. */
3838 /* This is in the static block. */
3839 static int file_scope;
3841 /* 'function' is in the global block, and 'argument' is
3842 in a block nested inside of 'function'. */
3843 int function (int argument)
3845 /* 'local' is in a block inside 'function'. It may or may
3846 not be in the same block as 'argument'. */
3850 /* 'inner' is in a block whose superblock is the one holding
3854 /* If this call is expanded by the compiler, you may see
3855 a nested block here whose function is 'inline_function'
3856 and whose superblock is the one holding 'inner'. */
3862 A @code{gdb.Block} is iterable. The iterator returns the symbols
3863 (@pxref{Symbols In Python}) local to the block. Python programs
3864 should not assume that a specific block object will always contain a
3865 given symbol, since changes in @value{GDBN} features and
3866 infrastructure may cause symbols move across blocks in a symbol
3869 The following block-related functions are available in the @code{gdb}
3872 @findex gdb.block_for_pc
3873 @defun gdb.block_for_pc (pc)
3874 Return the innermost @code{gdb.Block} containing the given @var{pc}
3875 value. If the block cannot be found for the @var{pc} value specified,
3876 the function will return @code{None}.
3879 A @code{gdb.Block} object has the following methods:
3881 @defun Block.is_valid ()
3882 Returns @code{True} if the @code{gdb.Block} object is valid,
3883 @code{False} if not. A block object can become invalid if the block it
3884 refers to doesn't exist anymore in the inferior. All other
3885 @code{gdb.Block} methods will throw an exception if it is invalid at
3886 the time the method is called. The block's validity is also checked
3887 during iteration over symbols of the block.
3890 A @code{gdb.Block} object has the following attributes:
3893 The start address of the block. This attribute is not writable.
3897 The end address of the block. This attribute is not writable.
3900 @defvar Block.function
3901 The name of the block represented as a @code{gdb.Symbol}. If the
3902 block is not named, then this attribute holds @code{None}. This
3903 attribute is not writable.
3905 For ordinary function blocks, the superblock is the static block.
3906 However, you should note that it is possible for a function block to
3907 have a superblock that is not the static block -- for instance this
3908 happens for an inlined function.
3911 @defvar Block.superblock
3912 The block containing this block. If this parent block does not exist,
3913 this attribute holds @code{None}. This attribute is not writable.
3916 @defvar Block.global_block
3917 The global block associated with this block. This attribute is not
3921 @defvar Block.static_block
3922 The static block associated with this block. This attribute is not
3926 @defvar Block.is_global
3927 @code{True} if the @code{gdb.Block} object is a global block,
3928 @code{False} if not. This attribute is not
3932 @defvar Block.is_static
3933 @code{True} if the @code{gdb.Block} object is a static block,
3934 @code{False} if not. This attribute is not writable.
3937 @node Symbols In Python
3938 @subsubsection Python representation of Symbols.
3940 @cindex symbols in python
3943 @value{GDBN} represents every variable, function and type as an
3944 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
3945 Similarly, Python represents these symbols in @value{GDBN} with the
3946 @code{gdb.Symbol} object.
3948 The following symbol-related functions are available in the @code{gdb}
3951 @findex gdb.lookup_symbol
3952 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
3953 This function searches for a symbol by name. The search scope can be
3954 restricted to the parameters defined in the optional domain and block
3957 @var{name} is the name of the symbol. It must be a string. The
3958 optional @var{block} argument restricts the search to symbols visible
3959 in that @var{block}. The @var{block} argument must be a
3960 @code{gdb.Block} object. If omitted, the block for the current frame
3961 is used. The optional @var{domain} argument restricts
3962 the search to the domain type. The @var{domain} argument must be a
3963 domain constant defined in the @code{gdb} module and described later
3966 The result is a tuple of two elements.
3967 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
3969 If the symbol is found, the second element is @code{True} if the symbol
3970 is a field of a method's object (e.g., @code{this} in C@t{++}),
3971 otherwise it is @code{False}.
3972 If the symbol is not found, the second element is @code{False}.
3975 @findex gdb.lookup_global_symbol
3976 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
3977 This function searches for a global symbol by name.
3978 The search scope can be restricted to by the domain argument.
3980 @var{name} is the name of the symbol. It must be a string.
3981 The optional @var{domain} argument restricts the search to the domain type.
3982 The @var{domain} argument must be a domain constant defined in the @code{gdb}
3983 module and described later in this chapter.
3985 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
3989 A @code{gdb.Symbol} object has the following attributes:
3992 The type of the symbol or @code{None} if no type is recorded.
3993 This attribute is represented as a @code{gdb.Type} object.
3994 @xref{Types In Python}. This attribute is not writable.
3997 @defvar Symbol.symtab
3998 The symbol table in which the symbol appears. This attribute is
3999 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
4000 Python}. This attribute is not writable.
4004 The line number in the source code at which the symbol was defined.
4009 The name of the symbol as a string. This attribute is not writable.
4012 @defvar Symbol.linkage_name
4013 The name of the symbol, as used by the linker (i.e., may be mangled).
4014 This attribute is not writable.
4017 @defvar Symbol.print_name
4018 The name of the symbol in a form suitable for output. This is either
4019 @code{name} or @code{linkage_name}, depending on whether the user
4020 asked @value{GDBN} to display demangled or mangled names.
4023 @defvar Symbol.addr_class
4024 The address class of the symbol. This classifies how to find the value
4025 of a symbol. Each address class is a constant defined in the
4026 @code{gdb} module and described later in this chapter.
4029 @defvar Symbol.needs_frame
4030 This is @code{True} if evaluating this symbol's value requires a frame
4031 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
4032 local variables will require a frame, but other symbols will not.
4035 @defvar Symbol.is_argument
4036 @code{True} if the symbol is an argument of a function.
4039 @defvar Symbol.is_constant
4040 @code{True} if the symbol is a constant.
4043 @defvar Symbol.is_function
4044 @code{True} if the symbol is a function or a method.
4047 @defvar Symbol.is_variable
4048 @code{True} if the symbol is a variable.
4051 A @code{gdb.Symbol} object has the following methods:
4053 @defun Symbol.is_valid ()
4054 Returns @code{True} if the @code{gdb.Symbol} object is valid,
4055 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
4056 the symbol it refers to does not exist in @value{GDBN} any longer.
4057 All other @code{gdb.Symbol} methods will throw an exception if it is
4058 invalid at the time the method is called.
4061 @defun Symbol.value (@r{[}frame@r{]})
4062 Compute the value of the symbol, as a @code{gdb.Value}. For
4063 functions, this computes the address of the function, cast to the
4064 appropriate type. If the symbol requires a frame in order to compute
4065 its value, then @var{frame} must be given. If @var{frame} is not
4066 given, or if @var{frame} is invalid, then this method will throw an
4070 The available domain categories in @code{gdb.Symbol} are represented
4071 as constants in the @code{gdb} module:
4074 @vindex SYMBOL_UNDEF_DOMAIN
4075 @item gdb.SYMBOL_UNDEF_DOMAIN
4076 This is used when a domain has not been discovered or none of the
4077 following domains apply. This usually indicates an error either
4078 in the symbol information or in @value{GDBN}'s handling of symbols.
4080 @vindex SYMBOL_VAR_DOMAIN
4081 @item gdb.SYMBOL_VAR_DOMAIN
4082 This domain contains variables, function names, typedef names and enum
4085 @vindex SYMBOL_STRUCT_DOMAIN
4086 @item gdb.SYMBOL_STRUCT_DOMAIN
4087 This domain holds struct, union and enum type names.
4089 @vindex SYMBOL_LABEL_DOMAIN
4090 @item gdb.SYMBOL_LABEL_DOMAIN
4091 This domain contains names of labels (for gotos).
4093 @vindex SYMBOL_VARIABLES_DOMAIN
4094 @item gdb.SYMBOL_VARIABLES_DOMAIN
4095 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
4096 contains everything minus functions and types.
4098 @vindex SYMBOL_FUNCTIONS_DOMAIN
4099 @item gdb.SYMBOL_FUNCTION_DOMAIN
4100 This domain contains all functions.
4102 @vindex SYMBOL_TYPES_DOMAIN
4103 @item gdb.SYMBOL_TYPES_DOMAIN
4104 This domain contains all types.
4107 The available address class categories in @code{gdb.Symbol} are represented
4108 as constants in the @code{gdb} module:
4111 @vindex SYMBOL_LOC_UNDEF
4112 @item gdb.SYMBOL_LOC_UNDEF
4113 If this is returned by address class, it indicates an error either in
4114 the symbol information or in @value{GDBN}'s handling of symbols.
4116 @vindex SYMBOL_LOC_CONST
4117 @item gdb.SYMBOL_LOC_CONST
4118 Value is constant int.
4120 @vindex SYMBOL_LOC_STATIC
4121 @item gdb.SYMBOL_LOC_STATIC
4122 Value is at a fixed address.
4124 @vindex SYMBOL_LOC_REGISTER
4125 @item gdb.SYMBOL_LOC_REGISTER
4126 Value is in a register.
4128 @vindex SYMBOL_LOC_ARG
4129 @item gdb.SYMBOL_LOC_ARG
4130 Value is an argument. This value is at the offset stored within the
4131 symbol inside the frame's argument list.
4133 @vindex SYMBOL_LOC_REF_ARG
4134 @item gdb.SYMBOL_LOC_REF_ARG
4135 Value address is stored in the frame's argument list. Just like
4136 @code{LOC_ARG} except that the value's address is stored at the
4137 offset, not the value itself.
4139 @vindex SYMBOL_LOC_REGPARM_ADDR
4140 @item gdb.SYMBOL_LOC_REGPARM_ADDR
4141 Value is a specified register. Just like @code{LOC_REGISTER} except
4142 the register holds the address of the argument instead of the argument
4145 @vindex SYMBOL_LOC_LOCAL
4146 @item gdb.SYMBOL_LOC_LOCAL
4147 Value is a local variable.
4149 @vindex SYMBOL_LOC_TYPEDEF
4150 @item gdb.SYMBOL_LOC_TYPEDEF
4151 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
4154 @vindex SYMBOL_LOC_BLOCK
4155 @item gdb.SYMBOL_LOC_BLOCK
4158 @vindex SYMBOL_LOC_CONST_BYTES
4159 @item gdb.SYMBOL_LOC_CONST_BYTES
4160 Value is a byte-sequence.
4162 @vindex SYMBOL_LOC_UNRESOLVED
4163 @item gdb.SYMBOL_LOC_UNRESOLVED
4164 Value is at a fixed address, but the address of the variable has to be
4165 determined from the minimal symbol table whenever the variable is
4168 @vindex SYMBOL_LOC_OPTIMIZED_OUT
4169 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
4170 The value does not actually exist in the program.
4172 @vindex SYMBOL_LOC_COMPUTED
4173 @item gdb.SYMBOL_LOC_COMPUTED
4174 The value's address is a computed location.
4177 @node Symbol Tables In Python
4178 @subsubsection Symbol table representation in Python.
4180 @cindex symbol tables in python
4182 @tindex gdb.Symtab_and_line
4184 Access to symbol table data maintained by @value{GDBN} on the inferior
4185 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
4186 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
4187 from the @code{find_sal} method in @code{gdb.Frame} object.
4188 @xref{Frames In Python}.
4190 For more information on @value{GDBN}'s symbol table management, see
4191 @ref{Symbols, ,Examining the Symbol Table}, for more information.
4193 A @code{gdb.Symtab_and_line} object has the following attributes:
4195 @defvar Symtab_and_line.symtab
4196 The symbol table object (@code{gdb.Symtab}) for this frame.
4197 This attribute is not writable.
4200 @defvar Symtab_and_line.pc
4201 Indicates the start of the address range occupied by code for the
4202 current source line. This attribute is not writable.
4205 @defvar Symtab_and_line.last
4206 Indicates the end of the address range occupied by code for the current
4207 source line. This attribute is not writable.
4210 @defvar Symtab_and_line.line
4211 Indicates the current line number for this object. This
4212 attribute is not writable.
4215 A @code{gdb.Symtab_and_line} object has the following methods:
4217 @defun Symtab_and_line.is_valid ()
4218 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
4219 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
4220 invalid if the Symbol table and line object it refers to does not
4221 exist in @value{GDBN} any longer. All other
4222 @code{gdb.Symtab_and_line} methods will throw an exception if it is
4223 invalid at the time the method is called.
4226 A @code{gdb.Symtab} object has the following attributes:
4228 @defvar Symtab.filename
4229 The symbol table's source filename. This attribute is not writable.
4232 @defvar Symtab.objfile
4233 The symbol table's backing object file. @xref{Objfiles In Python}.
4234 This attribute is not writable.
4237 @defvar Symtab.producer
4238 The name and possibly version number of the program that
4239 compiled the code in the symbol table.
4240 The contents of this string is up to the compiler.
4241 If no producer information is available then @code{None} is returned.
4242 This attribute is not writable.
4245 A @code{gdb.Symtab} object has the following methods:
4247 @defun Symtab.is_valid ()
4248 Returns @code{True} if the @code{gdb.Symtab} object is valid,
4249 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
4250 the symbol table it refers to does not exist in @value{GDBN} any
4251 longer. All other @code{gdb.Symtab} methods will throw an exception
4252 if it is invalid at the time the method is called.
4255 @defun Symtab.fullname ()
4256 Return the symbol table's source absolute file name.
4259 @defun Symtab.global_block ()
4260 Return the global block of the underlying symbol table.
4261 @xref{Blocks In Python}.
4264 @defun Symtab.static_block ()
4265 Return the static block of the underlying symbol table.
4266 @xref{Blocks In Python}.
4269 @defun Symtab.linetable ()
4270 Return the line table associated with the symbol table.
4271 @xref{Line Tables In Python}.
4274 @node Line Tables In Python
4275 @subsubsection Manipulating line tables using Python
4277 @cindex line tables in python
4278 @tindex gdb.LineTable
4280 Python code can request and inspect line table information from a
4281 symbol table that is loaded in @value{GDBN}. A line table is a
4282 mapping of source lines to their executable locations in memory. To
4283 acquire the line table information for a particular symbol table, use
4284 the @code{linetable} function (@pxref{Symbol Tables In Python}).
4286 A @code{gdb.LineTable} is iterable. The iterator returns
4287 @code{LineTableEntry} objects that correspond to the source line and
4288 address for each line table entry. @code{LineTableEntry} objects have
4289 the following attributes:
4291 @defvar LineTableEntry.line
4292 The source line number for this line table entry. This number
4293 corresponds to the actual line of source. This attribute is not
4297 @defvar LineTableEntry.pc
4298 The address that is associated with the line table entry where the
4299 executable code for that source line resides in memory. This
4300 attribute is not writable.
4303 As there can be multiple addresses for a single source line, you may
4304 receive multiple @code{LineTableEntry} objects with matching
4305 @code{line} attributes, but with different @code{pc} attributes. The
4306 iterator is sorted in ascending @code{pc} order. Here is a small
4307 example illustrating iterating over a line table.
4310 symtab = gdb.selected_frame().find_sal().symtab
4311 linetable = symtab.linetable()
4312 for line in linetable:
4313 print "Line: "+str(line.line)+" Address: "+hex(line.pc)
4316 This will have the following output:
4319 Line: 33 Address: 0x4005c8L
4320 Line: 37 Address: 0x4005caL
4321 Line: 39 Address: 0x4005d2L
4322 Line: 40 Address: 0x4005f8L
4323 Line: 42 Address: 0x4005ffL
4324 Line: 44 Address: 0x400608L
4325 Line: 42 Address: 0x40060cL
4326 Line: 45 Address: 0x400615L
4329 In addition to being able to iterate over a @code{LineTable}, it also
4330 has the following direct access methods:
4332 @defun LineTable.line (line)
4333 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
4334 entries in the line table for the given @var{line}, which specifies
4335 the source code line. If there are no entries for that source code
4336 @var{line}, the Python @code{None} is returned.
4339 @defun LineTable.has_line (line)
4340 Return a Python @code{Boolean} indicating whether there is an entry in
4341 the line table for this source line. Return @code{True} if an entry
4342 is found, or @code{False} if not.
4345 @defun LineTable.source_lines ()
4346 Return a Python @code{List} of the source line numbers in the symbol
4347 table. Only lines with executable code locations are returned. The
4348 contents of the @code{List} will just be the source line entries
4349 represented as Python @code{Long} values.
4352 @node Breakpoints In Python
4353 @subsubsection Manipulating breakpoints using Python
4355 @cindex breakpoints in python
4356 @tindex gdb.Breakpoint
4358 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
4361 @defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
4362 Create a new breakpoint according to @var{spec}, which is a string
4363 naming the location of the breakpoint, or an expression that defines a
4364 watchpoint. The contents can be any location recognized by the
4365 @code{break} command, or in the case of a watchpoint, by the
4366 @code{watch} command. The optional @var{type} denotes the breakpoint
4367 to create from the types defined later in this chapter. This argument
4368 can be either @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}; it
4369 defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
4370 argument allows the breakpoint to become invisible to the user. The
4371 breakpoint will neither be reported when created, nor will it be
4372 listed in the output from @code{info breakpoints} (but will be listed
4373 with the @code{maint info breakpoints} command). The optional
4374 @var{temporary} argument makes the breakpoint a temporary breakpoint.
4375 Temporary breakpoints are deleted after they have been hit. Any
4376 further access to the Python breakpoint after it has been hit will
4377 result in a runtime error (as that breakpoint has now been
4378 automatically deleted). The optional @var{wp_class} argument defines
4379 the class of watchpoint to create, if @var{type} is
4380 @code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it
4381 is assumed to be a @code{gdb.WP_WRITE} class.
4384 @defun Breakpoint.stop (self)
4385 The @code{gdb.Breakpoint} class can be sub-classed and, in
4386 particular, you may choose to implement the @code{stop} method.
4387 If this method is defined in a sub-class of @code{gdb.Breakpoint},
4388 it will be called when the inferior reaches any location of a
4389 breakpoint which instantiates that sub-class. If the method returns
4390 @code{True}, the inferior will be stopped at the location of the
4391 breakpoint, otherwise the inferior will continue.
4393 If there are multiple breakpoints at the same location with a
4394 @code{stop} method, each one will be called regardless of the
4395 return status of the previous. This ensures that all @code{stop}
4396 methods have a chance to execute at that location. In this scenario
4397 if one of the methods returns @code{True} but the others return
4398 @code{False}, the inferior will still be stopped.
4400 You should not alter the execution state of the inferior (i.e.@:, step,
4401 next, etc.), alter the current frame context (i.e.@:, change the current
4402 active frame), or alter, add or delete any breakpoint. As a general
4403 rule, you should not alter any data within @value{GDBN} or the inferior
4406 Example @code{stop} implementation:
4409 class MyBreakpoint (gdb.Breakpoint):
4411 inf_val = gdb.parse_and_eval("foo")
4418 The available watchpoint types represented by constants are defined in the
4424 Read only watchpoint.
4428 Write only watchpoint.
4432 Read/Write watchpoint.
4435 @defun Breakpoint.is_valid ()
4436 Return @code{True} if this @code{Breakpoint} object is valid,
4437 @code{False} otherwise. A @code{Breakpoint} object can become invalid
4438 if the user deletes the breakpoint. In this case, the object still
4439 exists, but the underlying breakpoint does not. In the cases of
4440 watchpoint scope, the watchpoint remains valid even if execution of the
4441 inferior leaves the scope of that watchpoint.
4444 @defun Breakpoint.delete ()
4445 Permanently deletes the @value{GDBN} breakpoint. This also
4446 invalidates the Python @code{Breakpoint} object. Any further access
4447 to this object's attributes or methods will raise an error.
4450 @defvar Breakpoint.enabled
4451 This attribute is @code{True} if the breakpoint is enabled, and
4452 @code{False} otherwise. This attribute is writable. You can use it to enable
4453 or disable the breakpoint.
4456 @defvar Breakpoint.silent
4457 This attribute is @code{True} if the breakpoint is silent, and
4458 @code{False} otherwise. This attribute is writable.
4460 Note that a breakpoint can also be silent if it has commands and the
4461 first command is @code{silent}. This is not reported by the
4462 @code{silent} attribute.
4465 @defvar Breakpoint.thread
4466 If the breakpoint is thread-specific, this attribute holds the thread
4467 id. If the breakpoint is not thread-specific, this attribute is
4468 @code{None}. This attribute is writable.
4471 @defvar Breakpoint.task
4472 If the breakpoint is Ada task-specific, this attribute holds the Ada task
4473 id. If the breakpoint is not task-specific (or the underlying
4474 language is not Ada), this attribute is @code{None}. This attribute
4478 @defvar Breakpoint.ignore_count
4479 This attribute holds the ignore count for the breakpoint, an integer.
4480 This attribute is writable.
4483 @defvar Breakpoint.number
4484 This attribute holds the breakpoint's number --- the identifier used by
4485 the user to manipulate the breakpoint. This attribute is not writable.
4488 @defvar Breakpoint.type
4489 This attribute holds the breakpoint's type --- the identifier used to
4490 determine the actual breakpoint type or use-case. This attribute is not
4494 @defvar Breakpoint.visible
4495 This attribute tells whether the breakpoint is visible to the user
4496 when set, or when the @samp{info breakpoints} command is run. This
4497 attribute is not writable.
4500 @defvar Breakpoint.temporary
4501 This attribute indicates whether the breakpoint was created as a
4502 temporary breakpoint. Temporary breakpoints are automatically deleted
4503 after that breakpoint has been hit. Access to this attribute, and all
4504 other attributes and functions other than the @code{is_valid}
4505 function, will result in an error after the breakpoint has been hit
4506 (as it has been automatically deleted). This attribute is not
4510 The available types are represented by constants defined in the @code{gdb}
4514 @vindex BP_BREAKPOINT
4515 @item gdb.BP_BREAKPOINT
4516 Normal code breakpoint.
4518 @vindex BP_WATCHPOINT
4519 @item gdb.BP_WATCHPOINT
4520 Watchpoint breakpoint.
4522 @vindex BP_HARDWARE_WATCHPOINT
4523 @item gdb.BP_HARDWARE_WATCHPOINT
4524 Hardware assisted watchpoint.
4526 @vindex BP_READ_WATCHPOINT
4527 @item gdb.BP_READ_WATCHPOINT
4528 Hardware assisted read watchpoint.
4530 @vindex BP_ACCESS_WATCHPOINT
4531 @item gdb.BP_ACCESS_WATCHPOINT
4532 Hardware assisted access watchpoint.
4535 @defvar Breakpoint.hit_count
4536 This attribute holds the hit count for the breakpoint, an integer.
4537 This attribute is writable, but currently it can only be set to zero.
4540 @defvar Breakpoint.location
4541 This attribute holds the location of the breakpoint, as specified by
4542 the user. It is a string. If the breakpoint does not have a location
4543 (that is, it is a watchpoint) the attribute's value is @code{None}. This
4544 attribute is not writable.
4547 @defvar Breakpoint.expression
4548 This attribute holds a breakpoint expression, as specified by
4549 the user. It is a string. If the breakpoint does not have an
4550 expression (the breakpoint is not a watchpoint) the attribute's value
4551 is @code{None}. This attribute is not writable.
4554 @defvar Breakpoint.condition
4555 This attribute holds the condition of the breakpoint, as specified by
4556 the user. It is a string. If there is no condition, this attribute's
4557 value is @code{None}. This attribute is writable.
4560 @defvar Breakpoint.commands
4561 This attribute holds the commands attached to the breakpoint. If
4562 there are commands, this attribute's value is a string holding all the
4563 commands, separated by newlines. If there are no commands, this
4564 attribute is @code{None}. This attribute is not writable.
4567 @node Finish Breakpoints in Python
4568 @subsubsection Finish Breakpoints
4570 @cindex python finish breakpoints
4571 @tindex gdb.FinishBreakpoint
4573 A finish breakpoint is a temporary breakpoint set at the return address of
4574 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
4575 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
4576 and deleted when the execution will run out of the breakpoint scope (i.e.@:
4577 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
4578 Finish breakpoints are thread specific and must be create with the right
4581 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
4582 Create a finish breakpoint at the return address of the @code{gdb.Frame}
4583 object @var{frame}. If @var{frame} is not provided, this defaults to the
4584 newest frame. The optional @var{internal} argument allows the breakpoint to
4585 become invisible to the user. @xref{Breakpoints In Python}, for further
4586 details about this argument.
4589 @defun FinishBreakpoint.out_of_scope (self)
4590 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
4591 @code{return} command, @dots{}), a function may not properly terminate, and
4592 thus never hit the finish breakpoint. When @value{GDBN} notices such a
4593 situation, the @code{out_of_scope} callback will be triggered.
4595 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
4599 class MyFinishBreakpoint (gdb.FinishBreakpoint)
4601 print "normal finish"
4604 def out_of_scope ():
4605 print "abnormal finish"
4609 @defvar FinishBreakpoint.return_value
4610 When @value{GDBN} is stopped at a finish breakpoint and the frame
4611 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
4612 attribute will contain a @code{gdb.Value} object corresponding to the return
4613 value of the function. The value will be @code{None} if the function return
4614 type is @code{void} or if the return value was not computable. This attribute
4618 @node Lazy Strings In Python
4619 @subsubsection Python representation of lazy strings.
4621 @cindex lazy strings in python
4622 @tindex gdb.LazyString
4624 A @dfn{lazy string} is a string whose contents is not retrieved or
4625 encoded until it is needed.
4627 A @code{gdb.LazyString} is represented in @value{GDBN} as an
4628 @code{address} that points to a region of memory, an @code{encoding}
4629 that will be used to encode that region of memory, and a @code{length}
4630 to delimit the region of memory that represents the string. The
4631 difference between a @code{gdb.LazyString} and a string wrapped within
4632 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
4633 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
4634 retrieved and encoded during printing, while a @code{gdb.Value}
4635 wrapping a string is immediately retrieved and encoded on creation.
4637 A @code{gdb.LazyString} object has the following functions:
4639 @defun LazyString.value ()
4640 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
4641 will point to the string in memory, but will lose all the delayed
4642 retrieval, encoding and handling that @value{GDBN} applies to a
4643 @code{gdb.LazyString}.
4646 @defvar LazyString.address
4647 This attribute holds the address of the string. This attribute is not
4651 @defvar LazyString.length
4652 This attribute holds the length of the string in characters. If the
4653 length is -1, then the string will be fetched and encoded up to the
4654 first null of appropriate width. This attribute is not writable.
4657 @defvar LazyString.encoding
4658 This attribute holds the encoding that will be applied to the string
4659 when the string is printed by @value{GDBN}. If the encoding is not
4660 set, or contains an empty string, then @value{GDBN} will select the
4661 most appropriate encoding when the string is printed. This attribute
4665 @defvar LazyString.type
4666 This attribute holds the type that is represented by the lazy string's
4667 type. For a lazy string this will always be a pointer type. To
4668 resolve this to the lazy string's character type, use the type's
4669 @code{target} method. @xref{Types In Python}. This attribute is not
4673 @node Architectures In Python
4674 @subsubsection Python representation of architectures
4675 @cindex Python architectures
4677 @value{GDBN} uses architecture specific parameters and artifacts in a
4678 number of its various computations. An architecture is represented
4679 by an instance of the @code{gdb.Architecture} class.
4681 A @code{gdb.Architecture} class has the following methods:
4683 @defun Architecture.name ()
4684 Return the name (string value) of the architecture.
4687 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
4688 Return a list of disassembled instructions starting from the memory
4689 address @var{start_pc}. The optional arguments @var{end_pc} and
4690 @var{count} determine the number of instructions in the returned list.
4691 If both the optional arguments @var{end_pc} and @var{count} are
4692 specified, then a list of at most @var{count} disassembled instructions
4693 whose start address falls in the closed memory address interval from
4694 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
4695 specified, but @var{count} is specified, then @var{count} number of
4696 instructions starting from the address @var{start_pc} are returned. If
4697 @var{count} is not specified but @var{end_pc} is specified, then all
4698 instructions whose start address falls in the closed memory address
4699 interval from @var{start_pc} to @var{end_pc} are returned. If neither
4700 @var{end_pc} nor @var{count} are specified, then a single instruction at
4701 @var{start_pc} is returned. For all of these cases, each element of the
4702 returned list is a Python @code{dict} with the following string keys:
4707 The value corresponding to this key is a Python long integer capturing
4708 the memory address of the instruction.
4711 The value corresponding to this key is a string value which represents
4712 the instruction with assembly language mnemonics. The assembly
4713 language flavor used is the same as that specified by the current CLI
4714 variable @code{disassembly-flavor}. @xref{Machine Code}.
4717 The value corresponding to this key is the length (integer value) of the
4718 instruction in bytes.
4723 @node Python Auto-loading
4724 @subsection Python Auto-loading
4725 @cindex Python auto-loading
4727 When a new object file is read (for example, due to the @code{file}
4728 command, or because the inferior has loaded a shared library),
4729 @value{GDBN} will look for Python support scripts in several ways:
4730 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
4731 @xref{Auto-loading extensions}.
4733 The auto-loading feature is useful for supplying application-specific
4734 debugging commands and scripts.
4736 Auto-loading can be enabled or disabled,
4737 and the list of auto-loaded scripts can be printed.
4740 @anchor{set auto-load python-scripts}
4741 @kindex set auto-load python-scripts
4742 @item set auto-load python-scripts [on|off]
4743 Enable or disable the auto-loading of Python scripts.
4745 @anchor{show auto-load python-scripts}
4746 @kindex show auto-load python-scripts
4747 @item show auto-load python-scripts
4748 Show whether auto-loading of Python scripts is enabled or disabled.
4750 @anchor{info auto-load python-scripts}
4751 @kindex info auto-load python-scripts
4752 @cindex print list of auto-loaded Python scripts
4753 @item info auto-load python-scripts [@var{regexp}]
4754 Print the list of all Python scripts that @value{GDBN} auto-loaded.
4756 Also printed is the list of Python scripts that were mentioned in
4757 the @code{.debug_gdb_scripts} section and were either not found
4758 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
4759 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
4760 This is useful because their names are not printed when @value{GDBN}
4761 tries to load them and fails. There may be many of them, and printing
4762 an error message for each one is problematic.
4764 If @var{regexp} is supplied only Python scripts with matching names are printed.
4769 (gdb) info auto-load python-scripts
4771 Yes py-section-script.py
4772 full name: /tmp/py-section-script.py
4773 No my-foo-pretty-printers.py
4777 When reading an auto-loaded file or script, @value{GDBN} sets the
4778 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
4779 function (@pxref{Objfiles In Python}). This can be useful for
4780 registering objfile-specific pretty-printers and frame-filters.
4782 @node Python modules
4783 @subsection Python modules
4784 @cindex python modules
4786 @value{GDBN} comes with several modules to assist writing Python code.
4789 * gdb.printing:: Building and registering pretty-printers.
4790 * gdb.types:: Utilities for working with types.
4791 * gdb.prompt:: Utilities for prompt value substitution.
4795 @subsubsection gdb.printing
4796 @cindex gdb.printing
4798 This module provides a collection of utilities for working with
4802 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
4803 This class specifies the API that makes @samp{info pretty-printer},
4804 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
4805 Pretty-printers should generally inherit from this class.
4807 @item SubPrettyPrinter (@var{name})
4808 For printers that handle multiple types, this class specifies the
4809 corresponding API for the subprinters.
4811 @item RegexpCollectionPrettyPrinter (@var{name})
4812 Utility class for handling multiple printers, all recognized via
4813 regular expressions.
4814 @xref{Writing a Pretty-Printer}, for an example.
4816 @item FlagEnumerationPrinter (@var{name})
4817 A pretty-printer which handles printing of @code{enum} values. Unlike
4818 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
4819 work properly when there is some overlap between the enumeration
4820 constants. The argument @var{name} is the name of the printer and
4821 also the name of the @code{enum} type to look up.
4823 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
4824 Register @var{printer} with the pretty-printer list of @var{obj}.
4825 If @var{replace} is @code{True} then any existing copy of the printer
4826 is replaced. Otherwise a @code{RuntimeError} exception is raised
4827 if a printer with the same name already exists.
4831 @subsubsection gdb.types
4834 This module provides a collection of utilities for working with
4835 @code{gdb.Type} objects.
4838 @item get_basic_type (@var{type})
4839 Return @var{type} with const and volatile qualifiers stripped,
4840 and with typedefs and C@t{++} references converted to the underlying type.
4845 typedef const int const_int;
4847 const_int& foo_ref (foo);
4848 int main () @{ return 0; @}
4855 (gdb) python import gdb.types
4856 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
4857 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
4861 @item has_field (@var{type}, @var{field})
4862 Return @code{True} if @var{type}, assumed to be a type with fields
4863 (e.g., a structure or union), has field @var{field}.
4865 @item make_enum_dict (@var{enum_type})
4866 Return a Python @code{dictionary} type produced from @var{enum_type}.
4868 @item deep_items (@var{type})
4869 Returns a Python iterator similar to the standard
4870 @code{gdb.Type.iteritems} method, except that the iterator returned
4871 by @code{deep_items} will recursively traverse anonymous struct or
4872 union fields. For example:
4886 Then in @value{GDBN}:
4888 (@value{GDBP}) python import gdb.types
4889 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
4890 (@value{GDBP}) python print struct_a.keys ()
4892 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
4893 @{['a', 'b0', 'b1']@}
4896 @item get_type_recognizers ()
4897 Return a list of the enabled type recognizers for the current context.
4898 This is called by @value{GDBN} during the type-printing process
4899 (@pxref{Type Printing API}).
4901 @item apply_type_recognizers (recognizers, type_obj)
4902 Apply the type recognizers, @var{recognizers}, to the type object
4903 @var{type_obj}. If any recognizer returns a string, return that
4904 string. Otherwise, return @code{None}. This is called by
4905 @value{GDBN} during the type-printing process (@pxref{Type Printing
4908 @item register_type_printer (locus, printer)
4909 This is a convenience function to register a type printer
4910 @var{printer}. The printer must implement the type printer protocol.
4911 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
4912 the printer is registered with that objfile; a @code{gdb.Progspace},
4913 in which case the printer is registered with that progspace; or
4914 @code{None}, in which case the printer is registered globally.
4917 This is a base class that implements the type printer protocol. Type
4918 printers are encouraged, but not required, to derive from this class.
4919 It defines a constructor:
4921 @defmethod TypePrinter __init__ (self, name)
4922 Initialize the type printer with the given name. The new printer
4923 starts in the enabled state.
4929 @subsubsection gdb.prompt
4932 This module provides a method for prompt value-substitution.
4935 @item substitute_prompt (@var{string})
4936 Return @var{string} with escape sequences substituted by values. Some
4937 escape sequences take arguments. You can specify arguments inside
4938 ``@{@}'' immediately following the escape sequence.
4940 The escape sequences you can pass to this function are:
4944 Substitute a backslash.
4946 Substitute an ESC character.
4948 Substitute the selected frame; an argument names a frame parameter.
4950 Substitute a newline.
4952 Substitute a parameter's value; the argument names the parameter.
4954 Substitute a carriage return.
4956 Substitute the selected thread; an argument names a thread parameter.
4958 Substitute the version of GDB.
4960 Substitute the current working directory.
4962 Begin a sequence of non-printing characters. These sequences are
4963 typically used with the ESC character, and are not counted in the string
4964 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
4965 blue-colored ``(gdb)'' prompt where the length is five.
4967 End a sequence of non-printing characters.
4973 substitute_prompt (``frame: \f,
4974 print arguments: \p@{print frame-arguments@}'')
4977 @exdent will return the string:
4980 "frame: main, print arguments: scalars"