1 @c Copyright (C) 2008-2014 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 * Inferiors In Python:: Python representation of inferiors (processes)
148 * Events In Python:: Listening for events from @value{GDBN}.
149 * Threads In Python:: Accessing inferior threads from Python.
150 * Commands In Python:: Implementing new commands in Python.
151 * Parameters In Python:: Adding new @value{GDBN} parameters.
152 * Functions In Python:: Writing new convenience functions.
153 * Progspaces In Python:: Program spaces.
154 * Objfiles In Python:: Object files.
155 * Frames In Python:: Accessing inferior stack frames from Python.
156 * Blocks In Python:: Accessing blocks from Python.
157 * Symbols In Python:: Python representation of symbols.
158 * Symbol Tables In Python:: Python representation of symbol tables.
159 * Line Tables In Python:: Python representation of line tables.
160 * Breakpoints In Python:: Manipulating breakpoints using Python.
161 * Finish Breakpoints in Python:: Setting Breakpoints on function return
163 * Lazy Strings In Python:: Python representation of lazy strings.
164 * Architectures In Python:: Python representation of architectures.
168 @subsubsection Basic Python
170 @cindex python stdout
171 @cindex python pagination
172 At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
173 @code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
174 A Python program which outputs to one of these streams may have its
175 output interrupted by the user (@pxref{Screen Size}). In this
176 situation, a Python @code{KeyboardInterrupt} exception is thrown.
178 Some care must be taken when writing Python code to run in
179 @value{GDBN}. Two things worth noting in particular:
183 @value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
184 Python code must not override these, or even change the options using
185 @code{sigaction}. If your program changes the handling of these
186 signals, @value{GDBN} will most likely stop working correctly. Note
187 that it is unfortunately common for GUI toolkits to install a
188 @code{SIGCHLD} handler.
191 @value{GDBN} takes care to mark its internal file descriptors as
192 close-on-exec. However, this cannot be done in a thread-safe way on
193 all platforms. Your Python programs should be aware of this and
194 should both create new file descriptors with the close-on-exec flag
195 set and arrange to close unneeded file descriptors before starting a
199 @cindex python functions
200 @cindex python module
202 @value{GDBN} introduces a new Python module, named @code{gdb}. All
203 methods and classes added by @value{GDBN} are placed in this module.
204 @value{GDBN} automatically @code{import}s the @code{gdb} module for
205 use in all scripts evaluated by the @code{python} command.
207 @findex gdb.PYTHONDIR
208 @defvar gdb.PYTHONDIR
209 A string containing the python directory (@pxref{Python}).
213 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
214 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
215 If a GDB exception happens while @var{command} runs, it is
216 translated as described in @ref{Exception Handling,,Exception Handling}.
218 @var{from_tty} specifies whether @value{GDBN} ought to consider this
219 command as having originated from the user invoking it interactively.
220 It must be a boolean value. If omitted, it defaults to @code{False}.
222 By default, any output produced by @var{command} is sent to
223 @value{GDBN}'s standard output. If the @var{to_string} parameter is
224 @code{True}, then output will be collected by @code{gdb.execute} and
225 returned as a string. The default is @code{False}, in which case the
226 return value is @code{None}. If @var{to_string} is @code{True}, the
227 @value{GDBN} virtual terminal will be temporarily set to unlimited width
228 and height, and its pagination will be disabled; @pxref{Screen Size}.
231 @findex gdb.breakpoints
232 @defun gdb.breakpoints ()
233 Return a sequence holding all of @value{GDBN}'s breakpoints.
234 @xref{Breakpoints In Python}, for more information.
237 @findex gdb.parameter
238 @defun gdb.parameter (parameter)
239 Return the value of a @value{GDBN} parameter. @var{parameter} is a
240 string naming the parameter to look up; @var{parameter} may contain
241 spaces if the parameter has a multi-part name. For example,
242 @samp{print object} is a valid parameter name.
244 If the named parameter does not exist, this function throws a
245 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
246 parameter's value is converted to a Python value of the appropriate
251 @defun gdb.history (number)
252 Return a value from @value{GDBN}'s value history (@pxref{Value
253 History}). @var{number} indicates which history element to return.
254 If @var{number} is negative, then @value{GDBN} will take its absolute value
255 and count backward from the last element (i.e., the most recent element) to
256 find the value to return. If @var{number} is zero, then @value{GDBN} will
257 return the most recent element. If the element specified by @var{number}
258 doesn't exist in the value history, a @code{gdb.error} exception will be
261 If no exception is raised, the return value is always an instance of
262 @code{gdb.Value} (@pxref{Values From Inferior}).
265 @findex gdb.parse_and_eval
266 @defun gdb.parse_and_eval (expression)
267 Parse @var{expression} as an expression in the current language,
268 evaluate it, and return the result as a @code{gdb.Value}.
269 @var{expression} must be a string.
271 This function can be useful when implementing a new command
272 (@pxref{Commands In Python}), as it provides a way to parse the
273 command's argument as an expression. It is also useful simply to
274 compute values, for example, it is the only way to get the value of a
275 convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
278 @findex gdb.find_pc_line
279 @defun gdb.find_pc_line (pc)
280 Return the @code{gdb.Symtab_and_line} object corresponding to the
281 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
282 value of @var{pc} is passed as an argument, then the @code{symtab} and
283 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
284 will be @code{None} and 0 respectively.
287 @findex gdb.post_event
288 @defun gdb.post_event (event)
289 Put @var{event}, a callable object taking no arguments, into
290 @value{GDBN}'s internal event queue. This callable will be invoked at
291 some later point, during @value{GDBN}'s event processing. Events
292 posted using @code{post_event} will be run in the order in which they
293 were posted; however, there is no way to know when they will be
294 processed relative to other events inside @value{GDBN}.
296 @value{GDBN} is not thread-safe. If your Python program uses multiple
297 threads, you must be careful to only call @value{GDBN}-specific
298 functions in the main @value{GDBN} thread. @code{post_event} ensures
302 (@value{GDBP}) python
306 > def __init__(self, message):
307 > self.message = message;
308 > def __call__(self):
309 > gdb.write(self.message)
311 >class MyThread1 (threading.Thread):
313 > gdb.post_event(Writer("Hello "))
315 >class MyThread2 (threading.Thread):
317 > gdb.post_event(Writer("World\n"))
322 (@value{GDBP}) Hello World
327 @defun gdb.write (string @r{[}, stream{]})
328 Print a string to @value{GDBN}'s paginated output stream. The
329 optional @var{stream} determines the stream to print to. The default
330 stream is @value{GDBN}'s standard output stream. Possible stream
337 @value{GDBN}'s standard output stream.
342 @value{GDBN}'s standard error stream.
347 @value{GDBN}'s log stream (@pxref{Logging Output}).
350 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
351 call this function and will automatically direct the output to the
357 Flush the buffer of a @value{GDBN} paginated stream so that the
358 contents are displayed immediately. @value{GDBN} will flush the
359 contents of a stream automatically when it encounters a newline in the
360 buffer. The optional @var{stream} determines the stream to flush. The
361 default stream is @value{GDBN}'s standard output stream. Possible
368 @value{GDBN}'s standard output stream.
373 @value{GDBN}'s standard error stream.
378 @value{GDBN}'s log stream (@pxref{Logging Output}).
382 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
383 call this function for the relevant stream.
386 @findex gdb.target_charset
387 @defun gdb.target_charset ()
388 Return the name of the current target character set (@pxref{Character
389 Sets}). This differs from @code{gdb.parameter('target-charset')} in
390 that @samp{auto} is never returned.
393 @findex gdb.target_wide_charset
394 @defun gdb.target_wide_charset ()
395 Return the name of the current target wide character set
396 (@pxref{Character Sets}). This differs from
397 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
401 @findex gdb.solib_name
402 @defun gdb.solib_name (address)
403 Return the name of the shared library holding the given @var{address}
404 as a string, or @code{None}.
407 @findex gdb.decode_line
408 @defun gdb.decode_line @r{[}expression@r{]}
409 Return locations of the line specified by @var{expression}, or of the
410 current line if no argument was given. This function returns a Python
411 tuple containing two elements. The first element contains a string
412 holding any unparsed section of @var{expression} (or @code{None} if
413 the expression has been fully parsed). The second element contains
414 either @code{None} or another tuple that contains all the locations
415 that match the expression represented as @code{gdb.Symtab_and_line}
416 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
417 provided, it is decoded the way that @value{GDBN}'s inbuilt
418 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
421 @defun gdb.prompt_hook (current_prompt)
424 If @var{prompt_hook} is callable, @value{GDBN} will call the method
425 assigned to this operation before a prompt is displayed by
428 The parameter @code{current_prompt} contains the current @value{GDBN}
429 prompt. This method must return a Python string, or @code{None}. If
430 a string is returned, the @value{GDBN} prompt will be set to that
431 string. If @code{None} is returned, @value{GDBN} will continue to use
434 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
435 such as those used by readline for command input, and annotation
436 related prompts are prohibited from being changed.
439 @node Exception Handling
440 @subsubsection Exception Handling
441 @cindex python exceptions
442 @cindex exceptions, python
444 When executing the @code{python} command, Python exceptions
445 uncaught within the Python code are translated to calls to
446 @value{GDBN} error-reporting mechanism. If the command that called
447 @code{python} does not handle the error, @value{GDBN} will
448 terminate it and print an error message containing the Python
449 exception name, the associated value, and the Python call stack
450 backtrace at the point where the exception was raised. Example:
453 (@value{GDBP}) python print foo
454 Traceback (most recent call last):
455 File "<string>", line 1, in <module>
456 NameError: name 'foo' is not defined
459 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
460 Python code are converted to Python exceptions. The type of the
461 Python exception depends on the error.
465 This is the base class for most exceptions generated by @value{GDBN}.
466 It is derived from @code{RuntimeError}, for compatibility with earlier
467 versions of @value{GDBN}.
469 If an error occurring in @value{GDBN} does not fit into some more
470 specific category, then the generated exception will have this type.
472 @item gdb.MemoryError
473 This is a subclass of @code{gdb.error} which is thrown when an
474 operation tried to access invalid memory in the inferior.
476 @item KeyboardInterrupt
477 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
478 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
481 In all cases, your exception handler will see the @value{GDBN} error
482 message as its value and the Python call stack backtrace at the Python
483 statement closest to where the @value{GDBN} error occured as the
487 When implementing @value{GDBN} commands in Python via @code{gdb.Command},
488 it is useful to be able to throw an exception that doesn't cause a
489 traceback to be printed. For example, the user may have invoked the
490 command incorrectly. Use the @code{gdb.GdbError} exception
491 to handle this case. Example:
495 >class HelloWorld (gdb.Command):
496 > """Greet the whole world."""
497 > def __init__ (self):
498 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
499 > def invoke (self, args, from_tty):
500 > argv = gdb.string_to_argv (args)
501 > if len (argv) != 0:
502 > raise gdb.GdbError ("hello-world takes no arguments")
503 > print "Hello, World!"
507 hello-world takes no arguments
510 @node Values From Inferior
511 @subsubsection Values From Inferior
512 @cindex values from inferior, with Python
513 @cindex python, working with values from inferior
515 @cindex @code{gdb.Value}
516 @value{GDBN} provides values it obtains from the inferior program in
517 an object of type @code{gdb.Value}. @value{GDBN} uses this object
518 for its internal bookkeeping of the inferior's values, and for
519 fetching values when necessary.
521 Inferior values that are simple scalars can be used directly in
522 Python expressions that are valid for the value's data type. Here's
523 an example for an integer or floating-point value @code{some_val}:
530 As result of this, @code{bar} will also be a @code{gdb.Value} object
531 whose values are of the same type as those of @code{some_val}. Valid
532 Python operations can also be performed on @code{gdb.Value} objects
533 representing a @code{struct} or @code{class} object. For such cases,
534 the overloaded operator (if present), is used to perform the operation.
535 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
536 representing instances of a @code{class} which overloads the @code{+}
537 operator, then one can use the @code{+} operator in their Python script
545 The result of the operation @code{val3} is also a @code{gdb.Value}
546 object corresponding to the value returned by the overloaded @code{+}
547 operator. In general, overloaded operators are invoked for the
548 following operations: @code{+} (binary addition), @code{-} (binary
549 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
550 @code{>>}, @code{|}, @code{&}, @code{^}.
552 Inferior values that are structures or instances of some class can
553 be accessed using the Python @dfn{dictionary syntax}. For example, if
554 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
555 can access its @code{foo} element with:
558 bar = some_val['foo']
561 @cindex getting structure elements using gdb.Field objects as subscripts
562 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
563 elements can also be accessed by using @code{gdb.Field} objects as
564 subscripts (@pxref{Types In Python}, for more information on
565 @code{gdb.Field} objects). For example, if @code{foo_field} is a
566 @code{gdb.Field} object corresponding to element @code{foo} of the above
567 structure, then @code{bar} can also be accessed as follows:
570 bar = some_val[foo_field]
573 A @code{gdb.Value} that represents a function can be executed via
574 inferior function call. Any arguments provided to the call must match
575 the function's prototype, and must be provided in the order specified
578 For example, @code{some_val} is a @code{gdb.Value} instance
579 representing a function that takes two integers as arguments. To
580 execute this function, call it like so:
583 result = some_val (10,20)
586 Any values returned from a function call will be stored as a
589 The following attributes are provided:
591 @defvar Value.address
592 If this object is addressable, this read-only attribute holds a
593 @code{gdb.Value} object representing the address. Otherwise,
594 this attribute holds @code{None}.
597 @cindex optimized out value in Python
598 @defvar Value.is_optimized_out
599 This read-only boolean attribute is true if the compiler optimized out
600 this value, thus it is not available for fetching from the inferior.
604 The type of this @code{gdb.Value}. The value of this attribute is a
605 @code{gdb.Type} object (@pxref{Types In Python}).
608 @defvar Value.dynamic_type
609 The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time
610 type information (@acronym{RTTI}) to determine the dynamic type of the
611 value. If this value is of class type, it will return the class in
612 which the value is embedded, if any. If this value is of pointer or
613 reference to a class type, it will compute the dynamic type of the
614 referenced object, and return a pointer or reference to that type,
615 respectively. In all other cases, it will return the value's static
618 Note that this feature will only work when debugging a C@t{++} program
619 that includes @acronym{RTTI} for the object in question. Otherwise,
620 it will just return the static type of the value as in @kbd{ptype foo}
621 (@pxref{Symbols, ptype}).
624 @defvar Value.is_lazy
625 The value of this read-only boolean attribute is @code{True} if this
626 @code{gdb.Value} has not yet been fetched from the inferior.
627 @value{GDBN} does not fetch values until necessary, for efficiency.
631 myval = gdb.parse_and_eval ('somevar')
634 The value of @code{somevar} is not fetched at this time. It will be
635 fetched when the value is needed, or when the @code{fetch_lazy}
639 The following methods are provided:
641 @defun Value.__init__ (@var{val})
642 Many Python values can be converted directly to a @code{gdb.Value} via
643 this object initializer. Specifically:
647 A Python boolean is converted to the boolean type from the current
651 A Python integer is converted to the C @code{long} type for the
652 current architecture.
655 A Python long is converted to the C @code{long long} type for the
656 current architecture.
659 A Python float is converted to the C @code{double} type for the
660 current architecture.
663 A Python string is converted to a target string, using the current
666 @item @code{gdb.Value}
667 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
669 @item @code{gdb.LazyString}
670 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
671 Python}), then the lazy string's @code{value} method is called, and
676 @defun Value.cast (type)
677 Return a new instance of @code{gdb.Value} that is the result of
678 casting this instance to the type described by @var{type}, which must
679 be a @code{gdb.Type} object. If the cast cannot be performed for some
680 reason, this method throws an exception.
683 @defun Value.dereference ()
684 For pointer data types, this method returns a new @code{gdb.Value} object
685 whose contents is the object pointed to by the pointer. For example, if
686 @code{foo} is a C pointer to an @code{int}, declared in your C program as
693 then you can use the corresponding @code{gdb.Value} to access what
694 @code{foo} points to like this:
697 bar = foo.dereference ()
700 The result @code{bar} will be a @code{gdb.Value} object holding the
701 value pointed to by @code{foo}.
703 A similar function @code{Value.referenced_value} exists which also
704 returns @code{gdb.Value} objects corresonding to the values pointed to
705 by pointer values (and additionally, values referenced by reference
706 values). However, the behavior of @code{Value.dereference}
707 differs from @code{Value.referenced_value} by the fact that the
708 behavior of @code{Value.dereference} is identical to applying the C
709 unary operator @code{*} on a given value. For example, consider a
710 reference to a pointer @code{ptrref}, declared in your C@t{++} program
718 intptr &ptrref = ptr;
721 Though @code{ptrref} is a reference value, one can apply the method
722 @code{Value.dereference} to the @code{gdb.Value} object corresponding
723 to it and obtain a @code{gdb.Value} which is identical to that
724 corresponding to @code{val}. However, if you apply the method
725 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
726 object identical to that corresponding to @code{ptr}.
729 py_ptrref = gdb.parse_and_eval ("ptrref")
730 py_val = py_ptrref.dereference ()
731 py_ptr = py_ptrref.referenced_value ()
734 The @code{gdb.Value} object @code{py_val} is identical to that
735 corresponding to @code{val}, and @code{py_ptr} is identical to that
736 corresponding to @code{ptr}. In general, @code{Value.dereference} can
737 be applied whenever the C unary operator @code{*} can be applied
738 to the corresponding C value. For those cases where applying both
739 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
740 the results obtained need not be identical (as we have seen in the above
741 example). The results are however identical when applied on
742 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
743 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
746 @defun Value.referenced_value ()
747 For pointer or reference data types, this method returns a new
748 @code{gdb.Value} object corresponding to the value referenced by the
749 pointer/reference value. For pointer data types,
750 @code{Value.dereference} and @code{Value.referenced_value} produce
751 identical results. The difference between these methods is that
752 @code{Value.dereference} cannot get the values referenced by reference
753 values. For example, consider a reference to an @code{int}, declared
754 in your C@t{++} program as
762 then applying @code{Value.dereference} to the @code{gdb.Value} object
763 corresponding to @code{ref} will result in an error, while applying
764 @code{Value.referenced_value} will result in a @code{gdb.Value} object
765 identical to that corresponding to @code{val}.
768 py_ref = gdb.parse_and_eval ("ref")
769 er_ref = py_ref.dereference () # Results in error
770 py_val = py_ref.referenced_value () # Returns the referenced value
773 The @code{gdb.Value} object @code{py_val} is identical to that
774 corresponding to @code{val}.
777 @defun Value.dynamic_cast (type)
778 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
779 operator were used. Consult a C@t{++} reference for details.
782 @defun Value.reinterpret_cast (type)
783 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
784 operator were used. Consult a C@t{++} reference for details.
787 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
788 If this @code{gdb.Value} represents a string, then this method
789 converts the contents to a Python string. Otherwise, this method will
792 Strings are recognized in a language-specific way; whether a given
793 @code{gdb.Value} represents a string is determined by the current
796 For C-like languages, a value is a string if it is a pointer to or an
797 array of characters or ints. The string is assumed to be terminated
798 by a zero of the appropriate width. However if the optional length
799 argument is given, the string will be converted to that given length,
800 ignoring any embedded zeros that the string may contain.
802 If the optional @var{encoding} argument is given, it must be a string
803 naming the encoding of the string in the @code{gdb.Value}, such as
804 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
805 the same encodings as the corresponding argument to Python's
806 @code{string.decode} method, and the Python codec machinery will be used
807 to convert the string. If @var{encoding} is not given, or if
808 @var{encoding} is the empty string, then either the @code{target-charset}
809 (@pxref{Character Sets}) will be used, or a language-specific encoding
810 will be used, if the current language is able to supply one.
812 The optional @var{errors} argument is the same as the corresponding
813 argument to Python's @code{string.decode} method.
815 If the optional @var{length} argument is given, the string will be
816 fetched and converted to the given length.
819 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
820 If this @code{gdb.Value} represents a string, then this method
821 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
822 In Python}). Otherwise, this method will throw an exception.
824 If the optional @var{encoding} argument is given, it must be a string
825 naming the encoding of the @code{gdb.LazyString}. Some examples are:
826 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
827 @var{encoding} argument is an encoding that @value{GDBN} does
828 recognize, @value{GDBN} will raise an error.
830 When a lazy string is printed, the @value{GDBN} encoding machinery is
831 used to convert the string during printing. If the optional
832 @var{encoding} argument is not provided, or is an empty string,
833 @value{GDBN} will automatically select the encoding most suitable for
834 the string type. For further information on encoding in @value{GDBN}
835 please see @ref{Character Sets}.
837 If the optional @var{length} argument is given, the string will be
838 fetched and encoded to the length of characters specified. If
839 the @var{length} argument is not provided, the string will be fetched
840 and encoded until a null of appropriate width is found.
843 @defun Value.fetch_lazy ()
844 If the @code{gdb.Value} object is currently a lazy value
845 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
846 fetched from the inferior. Any errors that occur in the process
847 will produce a Python exception.
849 If the @code{gdb.Value} object is not a lazy value, this method
852 This method does not return a value.
856 @node Types In Python
857 @subsubsection Types In Python
858 @cindex types in Python
859 @cindex Python, working with types
862 @value{GDBN} represents types from the inferior using the class
865 The following type-related functions are available in the @code{gdb}
868 @findex gdb.lookup_type
869 @defun gdb.lookup_type (name @r{[}, block@r{]})
870 This function looks up a type by name. @var{name} is the name of the
871 type to look up. It must be a string.
873 If @var{block} is given, then @var{name} is looked up in that scope.
874 Otherwise, it is searched for globally.
876 Ordinarily, this function will return an instance of @code{gdb.Type}.
877 If the named type cannot be found, it will throw an exception.
880 If the type is a structure or class type, or an enum type, the fields
881 of that type can be accessed using the Python @dfn{dictionary syntax}.
882 For example, if @code{some_type} is a @code{gdb.Type} instance holding
883 a structure type, you can access its @code{foo} field with:
886 bar = some_type['foo']
889 @code{bar} will be a @code{gdb.Field} object; see below under the
890 description of the @code{Type.fields} method for a description of the
891 @code{gdb.Field} class.
893 An instance of @code{Type} has the following attributes:
896 The type code for this type. The type code will be one of the
897 @code{TYPE_CODE_} constants defined below.
901 The name of this type. If this type has no name, then @code{None}
906 The size of this type, in target @code{char} units. Usually, a
907 target's @code{char} type will be an 8-bit byte. However, on some
908 unusual platforms, this type may have a different size.
912 The tag name for this type. The tag name is the name after
913 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
914 languages have this concept. If this type has no tag name, then
915 @code{None} is returned.
918 The following methods are provided:
920 @defun Type.fields ()
921 For structure and union types, this method returns the fields. Range
922 types have two fields, the minimum and maximum values. Enum types
923 have one field per enum constant. Function and method types have one
924 field per parameter. The base types of C@t{++} classes are also
925 represented as fields. If the type has no fields, or does not fit
926 into one of these categories, an empty sequence will be returned.
928 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
931 This attribute is not available for @code{enum} or @code{static}
932 (as in C@t{++} or Java) fields. The value is the position, counting
933 in bits, from the start of the containing type.
936 This attribute is only available for @code{enum} fields, and its value
937 is the enumeration member's integer representation.
940 The name of the field, or @code{None} for anonymous fields.
943 This is @code{True} if the field is artificial, usually meaning that
944 it was provided by the compiler and not the user. This attribute is
945 always provided, and is @code{False} if the field is not artificial.
948 This is @code{True} if the field represents a base class of a C@t{++}
949 structure. This attribute is always provided, and is @code{False}
950 if the field is not a base class of the type that is the argument of
951 @code{fields}, or if that type was not a C@t{++} class.
954 If the field is packed, or is a bitfield, then this will have a
955 non-zero value, which is the size of the field in bits. Otherwise,
956 this will be zero; in this case the field's size is given by its type.
959 The type of the field. This is usually an instance of @code{Type},
960 but it can be @code{None} in some situations.
963 The type which contains this field. This is an instance of
968 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
969 Return a new @code{gdb.Type} object which represents an array of this
970 type. If one argument is given, it is the inclusive upper bound of
971 the array; in this case the lower bound is zero. If two arguments are
972 given, the first argument is the lower bound of the array, and the
973 second argument is the upper bound of the array. An array's length
974 must not be negative, but the bounds can be.
977 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
978 Return a new @code{gdb.Type} object which represents a vector of this
979 type. If one argument is given, it is the inclusive upper bound of
980 the vector; in this case the lower bound is zero. If two arguments are
981 given, the first argument is the lower bound of the vector, and the
982 second argument is the upper bound of the vector. A vector's length
983 must not be negative, but the bounds can be.
985 The difference between an @code{array} and a @code{vector} is that
986 arrays behave like in C: when used in expressions they decay to a pointer
987 to the first element whereas vectors are treated as first class values.
991 Return a new @code{gdb.Type} object which represents a
992 @code{const}-qualified variant of this type.
995 @defun Type.volatile ()
996 Return a new @code{gdb.Type} object which represents a
997 @code{volatile}-qualified variant of this type.
1000 @defun Type.unqualified ()
1001 Return a new @code{gdb.Type} object which represents an unqualified
1002 variant of this type. That is, the result is neither @code{const} nor
1006 @defun Type.range ()
1007 Return a Python @code{Tuple} object that contains two elements: the
1008 low bound of the argument type and the high bound of that type. If
1009 the type does not have a range, @value{GDBN} will raise a
1010 @code{gdb.error} exception (@pxref{Exception Handling}).
1013 @defun Type.reference ()
1014 Return a new @code{gdb.Type} object which represents a reference to this
1018 @defun Type.pointer ()
1019 Return a new @code{gdb.Type} object which represents a pointer to this
1023 @defun Type.strip_typedefs ()
1024 Return a new @code{gdb.Type} that represents the real type,
1025 after removing all layers of typedefs.
1028 @defun Type.target ()
1029 Return a new @code{gdb.Type} object which represents the target type
1032 For a pointer type, the target type is the type of the pointed-to
1033 object. For an array type (meaning C-like arrays), the target type is
1034 the type of the elements of the array. For a function or method type,
1035 the target type is the type of the return value. For a complex type,
1036 the target type is the type of the elements. For a typedef, the
1037 target type is the aliased type.
1039 If the type does not have a target, this method will throw an
1043 @defun Type.template_argument (n @r{[}, block@r{]})
1044 If this @code{gdb.Type} is an instantiation of a template, this will
1045 return a new @code{gdb.Type} which represents the type of the
1046 @var{n}th template argument.
1048 If this @code{gdb.Type} is not a template type, this will throw an
1049 exception. Ordinarily, only C@t{++} code will have template types.
1051 If @var{block} is given, then @var{name} is looked up in that scope.
1052 Otherwise, it is searched for globally.
1056 Each type has a code, which indicates what category this type falls
1057 into. The available type categories are represented by constants
1058 defined in the @code{gdb} module:
1061 @findex TYPE_CODE_PTR
1062 @findex gdb.TYPE_CODE_PTR
1063 @item gdb.TYPE_CODE_PTR
1064 The type is a pointer.
1066 @findex TYPE_CODE_ARRAY
1067 @findex gdb.TYPE_CODE_ARRAY
1068 @item gdb.TYPE_CODE_ARRAY
1069 The type is an array.
1071 @findex TYPE_CODE_STRUCT
1072 @findex gdb.TYPE_CODE_STRUCT
1073 @item gdb.TYPE_CODE_STRUCT
1074 The type is a structure.
1076 @findex TYPE_CODE_UNION
1077 @findex gdb.TYPE_CODE_UNION
1078 @item gdb.TYPE_CODE_UNION
1079 The type is a union.
1081 @findex TYPE_CODE_ENUM
1082 @findex gdb.TYPE_CODE_ENUM
1083 @item gdb.TYPE_CODE_ENUM
1084 The type is an enum.
1086 @findex TYPE_CODE_FLAGS
1087 @findex gdb.TYPE_CODE_FLAGS
1088 @item gdb.TYPE_CODE_FLAGS
1089 A bit flags type, used for things such as status registers.
1091 @findex TYPE_CODE_FUNC
1092 @findex gdb.TYPE_CODE_FUNC
1093 @item gdb.TYPE_CODE_FUNC
1094 The type is a function.
1096 @findex TYPE_CODE_INT
1097 @findex gdb.TYPE_CODE_INT
1098 @item gdb.TYPE_CODE_INT
1099 The type is an integer type.
1101 @findex TYPE_CODE_FLT
1102 @findex gdb.TYPE_CODE_FLT
1103 @item gdb.TYPE_CODE_FLT
1104 A floating point type.
1106 @findex TYPE_CODE_VOID
1107 @findex gdb.TYPE_CODE_VOID
1108 @item gdb.TYPE_CODE_VOID
1109 The special type @code{void}.
1111 @findex TYPE_CODE_SET
1112 @findex gdb.TYPE_CODE_SET
1113 @item gdb.TYPE_CODE_SET
1116 @findex TYPE_CODE_RANGE
1117 @findex gdb.TYPE_CODE_RANGE
1118 @item gdb.TYPE_CODE_RANGE
1119 A range type, that is, an integer type with bounds.
1121 @findex TYPE_CODE_STRING
1122 @findex gdb.TYPE_CODE_STRING
1123 @item gdb.TYPE_CODE_STRING
1124 A string type. Note that this is only used for certain languages with
1125 language-defined string types; C strings are not represented this way.
1127 @findex TYPE_CODE_BITSTRING
1128 @findex gdb.TYPE_CODE_BITSTRING
1129 @item gdb.TYPE_CODE_BITSTRING
1130 A string of bits. It is deprecated.
1132 @findex TYPE_CODE_ERROR
1133 @findex gdb.TYPE_CODE_ERROR
1134 @item gdb.TYPE_CODE_ERROR
1135 An unknown or erroneous type.
1137 @findex TYPE_CODE_METHOD
1138 @findex gdb.TYPE_CODE_METHOD
1139 @item gdb.TYPE_CODE_METHOD
1140 A method type, as found in C@t{++} or Java.
1142 @findex TYPE_CODE_METHODPTR
1143 @findex gdb.TYPE_CODE_METHODPTR
1144 @item gdb.TYPE_CODE_METHODPTR
1145 A pointer-to-member-function.
1147 @findex TYPE_CODE_MEMBERPTR
1148 @findex gdb.TYPE_CODE_MEMBERPTR
1149 @item gdb.TYPE_CODE_MEMBERPTR
1150 A pointer-to-member.
1152 @findex TYPE_CODE_REF
1153 @findex gdb.TYPE_CODE_REF
1154 @item gdb.TYPE_CODE_REF
1157 @findex TYPE_CODE_CHAR
1158 @findex gdb.TYPE_CODE_CHAR
1159 @item gdb.TYPE_CODE_CHAR
1162 @findex TYPE_CODE_BOOL
1163 @findex gdb.TYPE_CODE_BOOL
1164 @item gdb.TYPE_CODE_BOOL
1167 @findex TYPE_CODE_COMPLEX
1168 @findex gdb.TYPE_CODE_COMPLEX
1169 @item gdb.TYPE_CODE_COMPLEX
1170 A complex float type.
1172 @findex TYPE_CODE_TYPEDEF
1173 @findex gdb.TYPE_CODE_TYPEDEF
1174 @item gdb.TYPE_CODE_TYPEDEF
1175 A typedef to some other type.
1177 @findex TYPE_CODE_NAMESPACE
1178 @findex gdb.TYPE_CODE_NAMESPACE
1179 @item gdb.TYPE_CODE_NAMESPACE
1180 A C@t{++} namespace.
1182 @findex TYPE_CODE_DECFLOAT
1183 @findex gdb.TYPE_CODE_DECFLOAT
1184 @item gdb.TYPE_CODE_DECFLOAT
1185 A decimal floating point type.
1187 @findex TYPE_CODE_INTERNAL_FUNCTION
1188 @findex gdb.TYPE_CODE_INTERNAL_FUNCTION
1189 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1190 A function internal to @value{GDBN}. This is the type used to represent
1191 convenience functions.
1194 Further support for types is provided in the @code{gdb.types}
1195 Python module (@pxref{gdb.types}).
1197 @node Pretty Printing API
1198 @subsubsection Pretty Printing API
1200 An example output is provided (@pxref{Pretty Printing}).
1202 A pretty-printer is just an object that holds a value and implements a
1203 specific interface, defined here.
1205 @defun pretty_printer.children (self)
1206 @value{GDBN} will call this method on a pretty-printer to compute the
1207 children of the pretty-printer's value.
1209 This method must return an object conforming to the Python iterator
1210 protocol. Each item returned by the iterator must be a tuple holding
1211 two elements. The first element is the ``name'' of the child; the
1212 second element is the child's value. The value can be any Python
1213 object which is convertible to a @value{GDBN} value.
1215 This method is optional. If it does not exist, @value{GDBN} will act
1216 as though the value has no children.
1219 @defun pretty_printer.display_hint (self)
1220 The CLI may call this method and use its result to change the
1221 formatting of a value. The result will also be supplied to an MI
1222 consumer as a @samp{displayhint} attribute of the variable being
1225 This method is optional. If it does exist, this method must return a
1228 Some display hints are predefined by @value{GDBN}:
1232 Indicate that the object being printed is ``array-like''. The CLI
1233 uses this to respect parameters such as @code{set print elements} and
1234 @code{set print array}.
1237 Indicate that the object being printed is ``map-like'', and that the
1238 children of this value can be assumed to alternate between keys and
1242 Indicate that the object being printed is ``string-like''. If the
1243 printer's @code{to_string} method returns a Python string of some
1244 kind, then @value{GDBN} will call its internal language-specific
1245 string-printing function to format the string. For the CLI this means
1246 adding quotation marks, possibly escaping some characters, respecting
1247 @code{set print elements}, and the like.
1251 @defun pretty_printer.to_string (self)
1252 @value{GDBN} will call this method to display the string
1253 representation of the value passed to the object's constructor.
1255 When printing from the CLI, if the @code{to_string} method exists,
1256 then @value{GDBN} will prepend its result to the values returned by
1257 @code{children}. Exactly how this formatting is done is dependent on
1258 the display hint, and may change as more hints are added. Also,
1259 depending on the print settings (@pxref{Print Settings}), the CLI may
1260 print just the result of @code{to_string} in a stack trace, omitting
1261 the result of @code{children}.
1263 If this method returns a string, it is printed verbatim.
1265 Otherwise, if this method returns an instance of @code{gdb.Value},
1266 then @value{GDBN} prints this value. This may result in a call to
1267 another pretty-printer.
1269 If instead the method returns a Python value which is convertible to a
1270 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1271 the resulting value. Again, this may result in a call to another
1272 pretty-printer. Python scalars (integers, floats, and booleans) and
1273 strings are convertible to @code{gdb.Value}; other types are not.
1275 Finally, if this method returns @code{None} then no further operations
1276 are peformed in this method and nothing is printed.
1278 If the result is not one of these types, an exception is raised.
1281 @value{GDBN} provides a function which can be used to look up the
1282 default pretty-printer for a @code{gdb.Value}:
1284 @findex gdb.default_visualizer
1285 @defun gdb.default_visualizer (value)
1286 This function takes a @code{gdb.Value} object as an argument. If a
1287 pretty-printer for this value exists, then it is returned. If no such
1288 printer exists, then this returns @code{None}.
1291 @node Selecting Pretty-Printers
1292 @subsubsection Selecting Pretty-Printers
1294 The Python list @code{gdb.pretty_printers} contains an array of
1295 functions or callable objects that have been registered via addition
1296 as a pretty-printer. Printers in this list are called @code{global}
1297 printers, they're available when debugging all inferiors.
1298 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1299 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1302 Each function on these lists is passed a single @code{gdb.Value}
1303 argument and should return a pretty-printer object conforming to the
1304 interface definition above (@pxref{Pretty Printing API}). If a function
1305 cannot create a pretty-printer for the value, it should return
1308 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1309 @code{gdb.Objfile} in the current program space and iteratively calls
1310 each enabled lookup routine in the list for that @code{gdb.Objfile}
1311 until it receives a pretty-printer object.
1312 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1313 searches the pretty-printer list of the current program space,
1314 calling each enabled function until an object is returned.
1315 After these lists have been exhausted, it tries the global
1316 @code{gdb.pretty_printers} list, again calling each enabled function until an
1319 The order in which the objfiles are searched is not specified. For a
1320 given list, functions are always invoked from the head of the list,
1321 and iterated over sequentially until the end of the list, or a printer
1324 For various reasons a pretty-printer may not work.
1325 For example, the underlying data structure may have changed and
1326 the pretty-printer is out of date.
1328 The consequences of a broken pretty-printer are severe enough that
1329 @value{GDBN} provides support for enabling and disabling individual
1330 printers. For example, if @code{print frame-arguments} is on,
1331 a backtrace can become highly illegible if any argument is printed
1332 with a broken printer.
1334 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1335 attribute to the registered function or callable object. If this attribute
1336 is present and its value is @code{False}, the printer is disabled, otherwise
1337 the printer is enabled.
1339 @node Writing a Pretty-Printer
1340 @subsubsection Writing a Pretty-Printer
1341 @cindex writing a pretty-printer
1343 A pretty-printer consists of two parts: a lookup function to detect
1344 if the type is supported, and the printer itself.
1346 Here is an example showing how a @code{std::string} printer might be
1347 written. @xref{Pretty Printing API}, for details on the API this class
1351 class StdStringPrinter(object):
1352 "Print a std::string"
1354 def __init__(self, val):
1357 def to_string(self):
1358 return self.val['_M_dataplus']['_M_p']
1360 def display_hint(self):
1364 And here is an example showing how a lookup function for the printer
1365 example above might be written.
1368 def str_lookup_function(val):
1369 lookup_tag = val.type.tag
1370 if lookup_tag == None:
1372 regex = re.compile("^std::basic_string<char,.*>$")
1373 if regex.match(lookup_tag):
1374 return StdStringPrinter(val)
1378 The example lookup function extracts the value's type, and attempts to
1379 match it to a type that it can pretty-print. If it is a type the
1380 printer can pretty-print, it will return a printer object. If not, it
1381 returns @code{None}.
1383 We recommend that you put your core pretty-printers into a Python
1384 package. If your pretty-printers are for use with a library, we
1385 further recommend embedding a version number into the package name.
1386 This practice will enable @value{GDBN} to load multiple versions of
1387 your pretty-printers at the same time, because they will have
1390 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1391 can be evaluated multiple times without changing its meaning. An
1392 ideal auto-load file will consist solely of @code{import}s of your
1393 printer modules, followed by a call to a register pretty-printers with
1394 the current objfile.
1396 Taken as a whole, this approach will scale nicely to multiple
1397 inferiors, each potentially using a different library version.
1398 Embedding a version number in the Python package name will ensure that
1399 @value{GDBN} is able to load both sets of printers simultaneously.
1400 Then, because the search for pretty-printers is done by objfile, and
1401 because your auto-loaded code took care to register your library's
1402 printers with a specific objfile, @value{GDBN} will find the correct
1403 printers for the specific version of the library used by each
1406 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1407 this code might appear in @code{gdb.libstdcxx.v6}:
1410 def register_printers(objfile):
1411 objfile.pretty_printers.append(str_lookup_function)
1415 And then the corresponding contents of the auto-load file would be:
1418 import gdb.libstdcxx.v6
1419 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1422 The previous example illustrates a basic pretty-printer.
1423 There are a few things that can be improved on.
1424 The printer doesn't have a name, making it hard to identify in a
1425 list of installed printers. The lookup function has a name, but
1426 lookup functions can have arbitrary, even identical, names.
1428 Second, the printer only handles one type, whereas a library typically has
1429 several types. One could install a lookup function for each desired type
1430 in the library, but one could also have a single lookup function recognize
1431 several types. The latter is the conventional way this is handled.
1432 If a pretty-printer can handle multiple data types, then its
1433 @dfn{subprinters} are the printers for the individual data types.
1435 The @code{gdb.printing} module provides a formal way of solving these
1436 problems (@pxref{gdb.printing}).
1437 Here is another example that handles multiple types.
1439 These are the types we are going to pretty-print:
1442 struct foo @{ int a, b; @};
1443 struct bar @{ struct foo x, y; @};
1446 Here are the printers:
1450 """Print a foo object."""
1452 def __init__(self, val):
1455 def to_string(self):
1456 return ("a=<" + str(self.val["a"]) +
1457 "> b=<" + str(self.val["b"]) + ">")
1460 """Print a bar object."""
1462 def __init__(self, val):
1465 def to_string(self):
1466 return ("x=<" + str(self.val["x"]) +
1467 "> y=<" + str(self.val["y"]) + ">")
1470 This example doesn't need a lookup function, that is handled by the
1471 @code{gdb.printing} module. Instead a function is provided to build up
1472 the object that handles the lookup.
1477 def build_pretty_printer():
1478 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1480 pp.add_printer('foo', '^foo$', fooPrinter)
1481 pp.add_printer('bar', '^bar$', barPrinter)
1485 And here is the autoload support:
1490 gdb.printing.register_pretty_printer(
1491 gdb.current_objfile(),
1492 my_library.build_pretty_printer())
1495 Finally, when this printer is loaded into @value{GDBN}, here is the
1496 corresponding output of @samp{info pretty-printer}:
1499 (gdb) info pretty-printer
1506 @node Type Printing API
1507 @subsubsection Type Printing API
1508 @cindex type printing API for Python
1510 @value{GDBN} provides a way for Python code to customize type display.
1511 This is mainly useful for substituting canonical typedef names for
1514 @cindex type printer
1515 A @dfn{type printer} is just a Python object conforming to a certain
1516 protocol. A simple base class implementing the protocol is provided;
1517 see @ref{gdb.types}. A type printer must supply at least:
1519 @defivar type_printer enabled
1520 A boolean which is True if the printer is enabled, and False
1521 otherwise. This is manipulated by the @code{enable type-printer}
1522 and @code{disable type-printer} commands.
1525 @defivar type_printer name
1526 The name of the type printer. This must be a string. This is used by
1527 the @code{enable type-printer} and @code{disable type-printer}
1531 @defmethod type_printer instantiate (self)
1532 This is called by @value{GDBN} at the start of type-printing. It is
1533 only called if the type printer is enabled. This method must return a
1534 new object that supplies a @code{recognize} method, as described below.
1538 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1539 will compute a list of type recognizers. This is done by iterating
1540 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1541 followed by the per-progspace type printers (@pxref{Progspaces In
1542 Python}), and finally the global type printers.
1544 @value{GDBN} will call the @code{instantiate} method of each enabled
1545 type printer. If this method returns @code{None}, then the result is
1546 ignored; otherwise, it is appended to the list of recognizers.
1548 Then, when @value{GDBN} is going to display a type name, it iterates
1549 over the list of recognizers. For each one, it calls the recognition
1550 function, stopping if the function returns a non-@code{None} value.
1551 The recognition function is defined as:
1553 @defmethod type_recognizer recognize (self, type)
1554 If @var{type} is not recognized, return @code{None}. Otherwise,
1555 return a string which is to be printed as the name of @var{type}.
1556 @var{type} will be an instance of @code{gdb.Type} (@pxref{Types In
1560 @value{GDBN} uses this two-pass approach so that type printers can
1561 efficiently cache information without holding on to it too long. For
1562 example, it can be convenient to look up type information in a type
1563 printer and hold it for a recognizer's lifetime; if a single pass were
1564 done then type printers would have to make use of the event system in
1565 order to avoid holding information that could become stale as the
1568 @node Frame Filter API
1569 @subsubsection Filtering Frames.
1570 @cindex frame filters api
1572 Frame filters are Python objects that manipulate the visibility of a
1573 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1576 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1577 commands (@pxref{GDB/MI}), those that return a collection of frames
1578 are affected. The commands that work with frame filters are:
1580 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1581 @code{-stack-list-frames}
1582 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1583 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1584 -stack-list-variables command}), @code{-stack-list-arguments}
1585 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1586 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1587 -stack-list-locals command}).
1589 A frame filter works by taking an iterator as an argument, applying
1590 actions to the contents of that iterator, and returning another
1591 iterator (or, possibly, the same iterator it was provided in the case
1592 where the filter does not perform any operations). Typically, frame
1593 filters utilize tools such as the Python's @code{itertools} module to
1594 work with and create new iterators from the source iterator.
1595 Regardless of how a filter chooses to apply actions, it must not alter
1596 the underlying @value{GDBN} frame or frames, or attempt to alter the
1597 call-stack within @value{GDBN}. This preserves data integrity within
1598 @value{GDBN}. Frame filters are executed on a priority basis and care
1599 should be taken that some frame filters may have been executed before,
1600 and that some frame filters will be executed after.
1602 An important consideration when designing frame filters, and well
1603 worth reflecting upon, is that frame filters should avoid unwinding
1604 the call stack if possible. Some stacks can run very deep, into the
1605 tens of thousands in some cases. To search every frame when a frame
1606 filter executes may be too expensive at that step. The frame filter
1607 cannot know how many frames it has to iterate over, and it may have to
1608 iterate through them all. This ends up duplicating effort as
1609 @value{GDBN} performs this iteration when it prints the frames. If
1610 the filter can defer unwinding frames until frame decorators are
1611 executed, after the last filter has executed, it should. @xref{Frame
1612 Decorator API}, for more information on decorators. Also, there are
1613 examples for both frame decorators and filters in later chapters.
1614 @xref{Writing a Frame Filter}, for more information.
1616 The Python dictionary @code{gdb.frame_filters} contains key/object
1617 pairings that comprise a frame filter. Frame filters in this
1618 dictionary are called @code{global} frame filters, and they are
1619 available when debugging all inferiors. These frame filters must
1620 register with the dictionary directly. In addition to the
1621 @code{global} dictionary, there are other dictionaries that are loaded
1622 with different inferiors via auto-loading (@pxref{Python
1623 Auto-loading}). The two other areas where frame filter dictionaries
1624 can be found are: @code{gdb.Progspace} which contains a
1625 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
1626 object which also contains a @code{frame_filters} dictionary
1629 When a command is executed from @value{GDBN} that is compatible with
1630 frame filters, @value{GDBN} combines the @code{global},
1631 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
1632 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
1633 several frames, and thus several object files, might be in use.
1634 @value{GDBN} then prunes any frame filter whose @code{enabled}
1635 attribute is @code{False}. This pruned list is then sorted according
1636 to the @code{priority} attribute in each filter.
1638 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
1639 creates an iterator which wraps each frame in the call stack in a
1640 @code{FrameDecorator} object, and calls each filter in order. The
1641 output from the previous filter will always be the input to the next
1644 Frame filters have a mandatory interface which each frame filter must
1645 implement, defined here:
1647 @defun FrameFilter.filter (iterator)
1648 @value{GDBN} will call this method on a frame filter when it has
1649 reached the order in the priority list for that filter.
1651 For example, if there are four frame filters:
1662 The order that the frame filters will be called is:
1665 Filter3 -> Filter2 -> Filter1 -> Filter4
1668 Note that the output from @code{Filter3} is passed to the input of
1669 @code{Filter2}, and so on.
1671 This @code{filter} method is passed a Python iterator. This iterator
1672 contains a sequence of frame decorators that wrap each
1673 @code{gdb.Frame}, or a frame decorator that wraps another frame
1674 decorator. The first filter that is executed in the sequence of frame
1675 filters will receive an iterator entirely comprised of default
1676 @code{FrameDecorator} objects. However, after each frame filter is
1677 executed, the previous frame filter may have wrapped some or all of
1678 the frame decorators with their own frame decorator. As frame
1679 decorators must also conform to a mandatory interface, these
1680 decorators can be assumed to act in a uniform manner (@pxref{Frame
1683 This method must return an object conforming to the Python iterator
1684 protocol. Each item in the iterator must be an object conforming to
1685 the frame decorator interface. If a frame filter does not wish to
1686 perform any operations on this iterator, it should return that
1689 This method is not optional. If it does not exist, @value{GDBN} will
1690 raise and print an error.
1693 @defvar FrameFilter.name
1694 The @code{name} attribute must be Python string which contains the
1695 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
1696 Management}). This attribute may contain any combination of letters
1697 or numbers. Care should be taken to ensure that it is unique. This
1698 attribute is mandatory.
1701 @defvar FrameFilter.enabled
1702 The @code{enabled} attribute must be Python boolean. This attribute
1703 indicates to @value{GDBN} whether the frame filter is enabled, and
1704 should be considered when frame filters are executed. If
1705 @code{enabled} is @code{True}, then the frame filter will be executed
1706 when any of the backtrace commands detailed earlier in this chapter
1707 are executed. If @code{enabled} is @code{False}, then the frame
1708 filter will not be executed. This attribute is mandatory.
1711 @defvar FrameFilter.priority
1712 The @code{priority} attribute must be Python integer. This attribute
1713 controls the order of execution in relation to other frame filters.
1714 There are no imposed limits on the range of @code{priority} other than
1715 it must be a valid integer. The higher the @code{priority} attribute,
1716 the sooner the frame filter will be executed in relation to other
1717 frame filters. Although @code{priority} can be negative, it is
1718 recommended practice to assume zero is the lowest priority that a
1719 frame filter can be assigned. Frame filters that have the same
1720 priority are executed in unsorted order in that priority slot. This
1721 attribute is mandatory.
1724 @node Frame Decorator API
1725 @subsubsection Decorating Frames.
1726 @cindex frame decorator api
1728 Frame decorators are sister objects to frame filters (@pxref{Frame
1729 Filter API}). Frame decorators are applied by a frame filter and can
1730 only be used in conjunction with frame filters.
1732 The purpose of a frame decorator is to customize the printed content
1733 of each @code{gdb.Frame} in commands where frame filters are executed.
1734 This concept is called decorating a frame. Frame decorators decorate
1735 a @code{gdb.Frame} with Python code contained within each API call.
1736 This separates the actual data contained in a @code{gdb.Frame} from
1737 the decorated data produced by a frame decorator. This abstraction is
1738 necessary to maintain integrity of the data contained in each
1741 Frame decorators have a mandatory interface, defined below.
1743 @value{GDBN} already contains a frame decorator called
1744 @code{FrameDecorator}. This contains substantial amounts of
1745 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
1746 recommended that other frame decorators inherit and extend this
1747 object, and only to override the methods needed.
1749 @defun FrameDecorator.elided (self)
1751 The @code{elided} method groups frames together in a hierarchical
1752 system. An example would be an interpreter, where multiple low-level
1753 frames make up a single call in the interpreted language. In this
1754 example, the frame filter would elide the low-level frames and present
1755 a single high-level frame, representing the call in the interpreted
1756 language, to the user.
1758 The @code{elided} function must return an iterable and this iterable
1759 must contain the frames that are being elided wrapped in a suitable
1760 frame decorator. If no frames are being elided this function may
1761 return an empty iterable, or @code{None}. Elided frames are indented
1762 from normal frames in a @code{CLI} backtrace, or in the case of
1763 @code{GDB/MI}, are placed in the @code{children} field of the eliding
1766 It is the frame filter's task to also filter out the elided frames from
1767 the source iterator. This will avoid printing the frame twice.
1770 @defun FrameDecorator.function (self)
1772 This method returns the name of the function in the frame that is to
1775 This method must return a Python string describing the function, or
1778 If this function returns @code{None}, @value{GDBN} will not print any
1779 data for this field.
1782 @defun FrameDecorator.address (self)
1784 This method returns the address of the frame that is to be printed.
1786 This method must return a Python numeric integer type of sufficient
1787 size to describe the address of the frame, or @code{None}.
1789 If this function returns a @code{None}, @value{GDBN} will not print
1790 any data for this field.
1793 @defun FrameDecorator.filename (self)
1795 This method returns the filename and path associated with this frame.
1797 This method must return a Python string containing the filename and
1798 the path to the object file backing the frame, or @code{None}.
1800 If this function returns a @code{None}, @value{GDBN} will not print
1801 any data for this field.
1804 @defun FrameDecorator.line (self):
1806 This method returns the line number associated with the current
1807 position within the function addressed by this frame.
1809 This method must return a Python integer type, or @code{None}.
1811 If this function returns a @code{None}, @value{GDBN} will not print
1812 any data for this field.
1815 @defun FrameDecorator.frame_args (self)
1818 This method must return an iterable, or @code{None}. Returning an
1819 empty iterable, or @code{None} means frame arguments will not be
1820 printed for this frame. This iterable must contain objects that
1821 implement two methods, described here.
1823 This object must implement a @code{argument} method which takes a
1824 single @code{self} parameter and must return a @code{gdb.Symbol}
1825 (@pxref{Symbols In Python}), or a Python string. The object must also
1826 implement a @code{value} method which takes a single @code{self}
1827 parameter and must return a @code{gdb.Value} (@pxref{Values From
1828 Inferior}), a Python value, or @code{None}. If the @code{value}
1829 method returns @code{None}, and the @code{argument} method returns a
1830 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
1831 the @code{gdb.Symbol} automatically.
1836 class SymValueWrapper():
1838 def __init__(self, symbol, value):
1848 class SomeFrameDecorator()
1851 def frame_args(self):
1854 block = self.inferior_frame.block()
1858 # Iterate over all symbols in a block. Only add
1859 # symbols that are arguments.
1861 if not sym.is_argument:
1863 args.append(SymValueWrapper(sym,None))
1865 # Add example synthetic argument.
1866 args.append(SymValueWrapper(``foo'', 42))
1872 @defun FrameDecorator.frame_locals (self)
1874 This method must return an iterable or @code{None}. Returning an
1875 empty iterable, or @code{None} means frame local arguments will not be
1876 printed for this frame.
1878 The object interface, the description of the various strategies for
1879 reading frame locals, and the example are largely similar to those
1880 described in the @code{frame_args} function, (@pxref{frame_args,,The
1881 frame filter frame_args function}). Below is a modified example:
1884 class SomeFrameDecorator()
1887 def frame_locals(self):
1890 block = self.inferior_frame.block()
1894 # Iterate over all symbols in a block. Add all
1895 # symbols, except arguments.
1899 vars.append(SymValueWrapper(sym,None))
1901 # Add an example of a synthetic local variable.
1902 vars.append(SymValueWrapper(``bar'', 99))
1908 @defun FrameDecorator.inferior_frame (self):
1910 This method must return the underlying @code{gdb.Frame} that this
1911 frame decorator is decorating. @value{GDBN} requires the underlying
1912 frame for internal frame information to determine how to print certain
1913 values when printing a frame.
1916 @node Writing a Frame Filter
1917 @subsubsection Writing a Frame Filter
1918 @cindex writing a frame filter
1920 There are three basic elements that a frame filter must implement: it
1921 must correctly implement the documented interface (@pxref{Frame Filter
1922 API}), it must register itself with @value{GDBN}, and finally, it must
1923 decide if it is to work on the data provided by @value{GDBN}. In all
1924 cases, whether it works on the iterator or not, each frame filter must
1925 return an iterator. A bare-bones frame filter follows the pattern in
1926 the following example.
1931 class FrameFilter():
1934 # Frame filter attribute creation.
1936 # 'name' is the name of the filter that GDB will display.
1938 # 'priority' is the priority of the filter relative to other
1941 # 'enabled' is a boolean that indicates whether this filter is
1942 # enabled and should be executed.
1948 # Register this frame filter with the global frame_filters
1950 gdb.frame_filters[self.name] = self
1952 def filter(self, frame_iter):
1953 # Just return the iterator.
1957 The frame filter in the example above implements the three
1958 requirements for all frame filters. It implements the API, self
1959 registers, and makes a decision on the iterator (in this case, it just
1960 returns the iterator untouched).
1962 The first step is attribute creation and assignment, and as shown in
1963 the comments the filter assigns the following attributes: @code{name},
1964 @code{priority} and whether the filter should be enabled with the
1965 @code{enabled} attribute.
1967 The second step is registering the frame filter with the dictionary or
1968 dictionaries that the frame filter has interest in. As shown in the
1969 comments, this filter just registers itself with the global dictionary
1970 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
1971 is a dictionary that is initialized in the @code{gdb} module when
1972 @value{GDBN} starts. What dictionary a filter registers with is an
1973 important consideration. Generally, if a filter is specific to a set
1974 of code, it should be registered either in the @code{objfile} or
1975 @code{progspace} dictionaries as they are specific to the program
1976 currently loaded in @value{GDBN}. The global dictionary is always
1977 present in @value{GDBN} and is never unloaded. Any filters registered
1978 with the global dictionary will exist until @value{GDBN} exits. To
1979 avoid filters that may conflict, it is generally better to register
1980 frame filters against the dictionaries that more closely align with
1981 the usage of the filter currently in question. @xref{Python
1982 Auto-loading}, for further information on auto-loading Python scripts.
1984 @value{GDBN} takes a hands-off approach to frame filter registration,
1985 therefore it is the frame filter's responsibility to ensure
1986 registration has occurred, and that any exceptions are handled
1987 appropriately. In particular, you may wish to handle exceptions
1988 relating to Python dictionary key uniqueness. It is mandatory that
1989 the dictionary key is the same as frame filter's @code{name}
1990 attribute. When a user manages frame filters (@pxref{Frame Filter
1991 Management}), the names @value{GDBN} will display are those contained
1992 in the @code{name} attribute.
1994 The final step of this example is the implementation of the
1995 @code{filter} method. As shown in the example comments, we define the
1996 @code{filter} method and note that the method must take an iterator,
1997 and also must return an iterator. In this bare-bones example, the
1998 frame filter is not very useful as it just returns the iterator
1999 untouched. However this is a valid operation for frame filters that
2000 have the @code{enabled} attribute set, but decide not to operate on
2003 In the next example, the frame filter operates on all frames and
2004 utilizes a frame decorator to perform some work on the frames.
2005 @xref{Frame Decorator API}, for further information on the frame
2006 decorator interface.
2008 This example works on inlined frames. It highlights frames which are
2009 inlined by tagging them with an ``[inlined]'' tag. By applying a
2010 frame decorator to all frames with the Python @code{itertools imap}
2011 method, the example defers actions to the frame decorator. Frame
2012 decorators are only processed when @value{GDBN} prints the backtrace.
2014 This introduces a new decision making topic: whether to perform
2015 decision making operations at the filtering step, or at the printing
2016 step. In this example's approach, it does not perform any filtering
2017 decisions at the filtering step beyond mapping a frame decorator to
2018 each frame. This allows the actual decision making to be performed
2019 when each frame is printed. This is an important consideration, and
2020 well worth reflecting upon when designing a frame filter. An issue
2021 that frame filters should avoid is unwinding the stack if possible.
2022 Some stacks can run very deep, into the tens of thousands in some
2023 cases. To search every frame to determine if it is inlined ahead of
2024 time may be too expensive at the filtering step. The frame filter
2025 cannot know how many frames it has to iterate over, and it would have
2026 to iterate through them all. This ends up duplicating effort as
2027 @value{GDBN} performs this iteration when it prints the frames.
2029 In this example decision making can be deferred to the printing step.
2030 As each frame is printed, the frame decorator can examine each frame
2031 in turn when @value{GDBN} iterates. From a performance viewpoint,
2032 this is the most appropriate decision to make as it avoids duplicating
2033 the effort that the printing step would undertake anyway. Also, if
2034 there are many frame filters unwinding the stack during filtering, it
2035 can substantially delay the printing of the backtrace which will
2036 result in large memory usage, and a poor user experience.
2039 class InlineFilter():
2042 self.name = "InlinedFrameFilter"
2045 gdb.frame_filters[self.name] = self
2047 def filter(self, frame_iter):
2048 frame_iter = itertools.imap(InlinedFrameDecorator,
2053 This frame filter is somewhat similar to the earlier example, except
2054 that the @code{filter} method applies a frame decorator object called
2055 @code{InlinedFrameDecorator} to each element in the iterator. The
2056 @code{imap} Python method is light-weight. It does not proactively
2057 iterate over the iterator, but rather creates a new iterator which
2058 wraps the existing one.
2060 Below is the frame decorator for this example.
2063 class InlinedFrameDecorator(FrameDecorator):
2065 def __init__(self, fobj):
2066 super(InlinedFrameDecorator, self).__init__(fobj)
2069 frame = fobj.inferior_frame()
2070 name = str(frame.name())
2072 if frame.type() == gdb.INLINE_FRAME:
2073 name = name + " [inlined]"
2078 This frame decorator only defines and overrides the @code{function}
2079 method. It lets the supplied @code{FrameDecorator}, which is shipped
2080 with @value{GDBN}, perform the other work associated with printing
2083 The combination of these two objects create this output from a
2087 #0 0x004004e0 in bar () at inline.c:11
2088 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2089 #2 0x00400566 in main () at inline.c:31
2092 So in the case of this example, a frame decorator is applied to all
2093 frames, regardless of whether they may be inlined or not. As
2094 @value{GDBN} iterates over the iterator produced by the frame filters,
2095 @value{GDBN} executes each frame decorator which then makes a decision
2096 on what to print in the @code{function} callback. Using a strategy
2097 like this is a way to defer decisions on the frame content to printing
2100 @subheading Eliding Frames
2102 It might be that the above example is not desirable for representing
2103 inlined frames, and a hierarchical approach may be preferred. If we
2104 want to hierarchically represent frames, the @code{elided} frame
2105 decorator interface might be preferable.
2107 This example approaches the issue with the @code{elided} method. This
2108 example is quite long, but very simplistic. It is out-of-scope for
2109 this section to write a complete example that comprehensively covers
2110 all approaches of finding and printing inlined frames. However, this
2111 example illustrates the approach an author might use.
2113 This example comprises of three sections.
2116 class InlineFrameFilter():
2119 self.name = "InlinedFrameFilter"
2122 gdb.frame_filters[self.name] = self
2124 def filter(self, frame_iter):
2125 return ElidingInlineIterator(frame_iter)
2128 This frame filter is very similar to the other examples. The only
2129 difference is this frame filter is wrapping the iterator provided to
2130 it (@code{frame_iter}) with a custom iterator called
2131 @code{ElidingInlineIterator}. This again defers actions to when
2132 @value{GDBN} prints the backtrace, as the iterator is not traversed
2135 The iterator for this example is as follows. It is in this section of
2136 the example where decisions are made on the content of the backtrace.
2139 class ElidingInlineIterator:
2140 def __init__(self, ii):
2141 self.input_iterator = ii
2147 frame = next(self.input_iterator)
2149 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2153 eliding_frame = next(self.input_iterator)
2154 except StopIteration:
2156 return ElidingFrameDecorator(eliding_frame, [frame])
2159 This iterator implements the Python iterator protocol. When the
2160 @code{next} function is called (when @value{GDBN} prints each frame),
2161 the iterator checks if this frame decorator, @code{frame}, is wrapping
2162 an inlined frame. If it is not, it returns the existing frame decorator
2163 untouched. If it is wrapping an inlined frame, it assumes that the
2164 inlined frame was contained within the next oldest frame,
2165 @code{eliding_frame}, which it fetches. It then creates and returns a
2166 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2167 elided frame, and the eliding frame.
2170 class ElidingInlineDecorator(FrameDecorator):
2172 def __init__(self, frame, elided_frames):
2173 super(ElidingInlineDecorator, self).__init__(frame)
2175 self.elided_frames = elided_frames
2178 return iter(self.elided_frames)
2181 This frame decorator overrides one function and returns the inlined
2182 frame in the @code{elided} method. As before it lets
2183 @code{FrameDecorator} do the rest of the work involved in printing
2184 this frame. This produces the following output.
2187 #0 0x004004e0 in bar () at inline.c:11
2188 #2 0x00400529 in main () at inline.c:25
2189 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2192 In that output, @code{max} which has been inlined into @code{main} is
2193 printed hierarchically. Another approach would be to combine the
2194 @code{function} method, and the @code{elided} method to both print a
2195 marker in the inlined frame, and also show the hierarchical
2198 @node Inferiors In Python
2199 @subsubsection Inferiors In Python
2200 @cindex inferiors in Python
2202 @findex gdb.Inferior
2203 Programs which are being run under @value{GDBN} are called inferiors
2204 (@pxref{Inferiors and Programs}). Python scripts can access
2205 information about and manipulate inferiors controlled by @value{GDBN}
2206 via objects of the @code{gdb.Inferior} class.
2208 The following inferior-related functions are available in the @code{gdb}
2211 @defun gdb.inferiors ()
2212 Return a tuple containing all inferior objects.
2215 @defun gdb.selected_inferior ()
2216 Return an object representing the current inferior.
2219 A @code{gdb.Inferior} object has the following attributes:
2221 @defvar Inferior.num
2222 ID of inferior, as assigned by GDB.
2225 @defvar Inferior.pid
2226 Process ID of the inferior, as assigned by the underlying operating
2230 @defvar Inferior.was_attached
2231 Boolean signaling whether the inferior was created using `attach', or
2232 started by @value{GDBN} itself.
2235 A @code{gdb.Inferior} object has the following methods:
2237 @defun Inferior.is_valid ()
2238 Returns @code{True} if the @code{gdb.Inferior} object is valid,
2239 @code{False} if not. A @code{gdb.Inferior} object will become invalid
2240 if the inferior no longer exists within @value{GDBN}. All other
2241 @code{gdb.Inferior} methods will throw an exception if it is invalid
2242 at the time the method is called.
2245 @defun Inferior.threads ()
2246 This method returns a tuple holding all the threads which are valid
2247 when it is called. If there are no valid threads, the method will
2248 return an empty tuple.
2251 @findex Inferior.read_memory
2252 @defun Inferior.read_memory (address, length)
2253 Read @var{length} bytes of memory from the inferior, starting at
2254 @var{address}. Returns a buffer object, which behaves much like an array
2255 or a string. It can be modified and given to the
2256 @code{Inferior.write_memory} function. In @code{Python} 3, the return
2257 value is a @code{memoryview} object.
2260 @findex Inferior.write_memory
2261 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
2262 Write the contents of @var{buffer} to the inferior, starting at
2263 @var{address}. The @var{buffer} parameter must be a Python object
2264 which supports the buffer protocol, i.e., a string, an array or the
2265 object returned from @code{Inferior.read_memory}. If given, @var{length}
2266 determines the number of bytes from @var{buffer} to be written.
2269 @findex gdb.search_memory
2270 @defun Inferior.search_memory (address, length, pattern)
2271 Search a region of the inferior memory starting at @var{address} with
2272 the given @var{length} using the search pattern supplied in
2273 @var{pattern}. The @var{pattern} parameter must be a Python object
2274 which supports the buffer protocol, i.e., a string, an array or the
2275 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
2276 containing the address where the pattern was found, or @code{None} if
2277 the pattern could not be found.
2280 @node Events In Python
2281 @subsubsection Events In Python
2282 @cindex inferior events in Python
2284 @value{GDBN} provides a general event facility so that Python code can be
2285 notified of various state changes, particularly changes that occur in
2288 An @dfn{event} is just an object that describes some state change. The
2289 type of the object and its attributes will vary depending on the details
2290 of the change. All the existing events are described below.
2292 In order to be notified of an event, you must register an event handler
2293 with an @dfn{event registry}. An event registry is an object in the
2294 @code{gdb.events} module which dispatches particular events. A registry
2295 provides methods to register and unregister event handlers:
2297 @defun EventRegistry.connect (object)
2298 Add the given callable @var{object} to the registry. This object will be
2299 called when an event corresponding to this registry occurs.
2302 @defun EventRegistry.disconnect (object)
2303 Remove the given @var{object} from the registry. Once removed, the object
2304 will no longer receive notifications of events.
2310 def exit_handler (event):
2311 print "event type: exit"
2312 print "exit code: %d" % (event.exit_code)
2314 gdb.events.exited.connect (exit_handler)
2317 In the above example we connect our handler @code{exit_handler} to the
2318 registry @code{events.exited}. Once connected, @code{exit_handler} gets
2319 called when the inferior exits. The argument @dfn{event} in this example is
2320 of type @code{gdb.ExitedEvent}. As you can see in the example the
2321 @code{ExitedEvent} object has an attribute which indicates the exit code of
2324 The following is a listing of the event registries that are available and
2325 details of the events they emit:
2330 Emits @code{gdb.ThreadEvent}.
2332 Some events can be thread specific when @value{GDBN} is running in non-stop
2333 mode. When represented in Python, these events all extend
2334 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
2335 events which are emitted by this or other modules might extend this event.
2336 Examples of these events are @code{gdb.BreakpointEvent} and
2337 @code{gdb.ContinueEvent}.
2339 @defvar ThreadEvent.inferior_thread
2340 In non-stop mode this attribute will be set to the specific thread which was
2341 involved in the emitted event. Otherwise, it will be set to @code{None}.
2344 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
2346 This event indicates that the inferior has been continued after a stop. For
2347 inherited attribute refer to @code{gdb.ThreadEvent} above.
2350 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
2351 @code{events.ExitedEvent} has two attributes:
2352 @defvar ExitedEvent.exit_code
2353 An integer representing the exit code, if available, which the inferior
2354 has returned. (The exit code could be unavailable if, for example,
2355 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
2356 the attribute does not exist.
2358 @defvar ExitedEvent inferior
2359 A reference to the inferior which triggered the @code{exited} event.
2363 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
2365 Indicates that the inferior has stopped. All events emitted by this registry
2366 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
2367 will indicate the stopped thread when @value{GDBN} is running in non-stop
2368 mode. Refer to @code{gdb.ThreadEvent} above for more details.
2370 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
2372 This event indicates that the inferior or one of its threads has received as
2373 signal. @code{gdb.SignalEvent} has the following attributes:
2375 @defvar SignalEvent.stop_signal
2376 A string representing the signal received by the inferior. A list of possible
2377 signal values can be obtained by running the command @code{info signals} in
2378 the @value{GDBN} command prompt.
2381 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
2383 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
2384 been hit, and has the following attributes:
2386 @defvar BreakpointEvent.breakpoints
2387 A sequence containing references to all the breakpoints (type
2388 @code{gdb.Breakpoint}) that were hit.
2389 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
2391 @defvar BreakpointEvent.breakpoint
2392 A reference to the first breakpoint that was hit.
2393 This function is maintained for backward compatibility and is now deprecated
2394 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
2397 @item events.new_objfile
2398 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
2399 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
2401 @defvar NewObjFileEvent.new_objfile
2402 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
2403 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
2408 @node Threads In Python
2409 @subsubsection Threads In Python
2410 @cindex threads in python
2412 @findex gdb.InferiorThread
2413 Python scripts can access information about, and manipulate inferior threads
2414 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
2416 The following thread-related functions are available in the @code{gdb}
2419 @findex gdb.selected_thread
2420 @defun gdb.selected_thread ()
2421 This function returns the thread object for the selected thread. If there
2422 is no selected thread, this will return @code{None}.
2425 A @code{gdb.InferiorThread} object has the following attributes:
2427 @defvar InferiorThread.name
2428 The name of the thread. If the user specified a name using
2429 @code{thread name}, then this returns that name. Otherwise, if an
2430 OS-supplied name is available, then it is returned. Otherwise, this
2431 returns @code{None}.
2433 This attribute can be assigned to. The new value must be a string
2434 object, which sets the new name, or @code{None}, which removes any
2435 user-specified thread name.
2438 @defvar InferiorThread.num
2439 ID of the thread, as assigned by GDB.
2442 @defvar InferiorThread.ptid
2443 ID of the thread, as assigned by the operating system. This attribute is a
2444 tuple containing three integers. The first is the Process ID (PID); the second
2445 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
2446 Either the LWPID or TID may be 0, which indicates that the operating system
2447 does not use that identifier.
2450 A @code{gdb.InferiorThread} object has the following methods:
2452 @defun InferiorThread.is_valid ()
2453 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
2454 @code{False} if not. A @code{gdb.InferiorThread} object will become
2455 invalid if the thread exits, or the inferior that the thread belongs
2456 is deleted. All other @code{gdb.InferiorThread} methods will throw an
2457 exception if it is invalid at the time the method is called.
2460 @defun InferiorThread.switch ()
2461 This changes @value{GDBN}'s currently selected thread to the one represented
2465 @defun InferiorThread.is_stopped ()
2466 Return a Boolean indicating whether the thread is stopped.
2469 @defun InferiorThread.is_running ()
2470 Return a Boolean indicating whether the thread is running.
2473 @defun InferiorThread.is_exited ()
2474 Return a Boolean indicating whether the thread is exited.
2477 @node Commands In Python
2478 @subsubsection Commands In Python
2480 @cindex commands in python
2481 @cindex python commands
2482 You can implement new @value{GDBN} CLI commands in Python. A CLI
2483 command is implemented using an instance of the @code{gdb.Command}
2484 class, most commonly using a subclass.
2486 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
2487 The object initializer for @code{Command} registers the new command
2488 with @value{GDBN}. This initializer is normally invoked from the
2489 subclass' own @code{__init__} method.
2491 @var{name} is the name of the command. If @var{name} consists of
2492 multiple words, then the initial words are looked for as prefix
2493 commands. In this case, if one of the prefix commands does not exist,
2494 an exception is raised.
2496 There is no support for multi-line commands.
2498 @var{command_class} should be one of the @samp{COMMAND_} constants
2499 defined below. This argument tells @value{GDBN} how to categorize the
2500 new command in the help system.
2502 @var{completer_class} is an optional argument. If given, it should be
2503 one of the @samp{COMPLETE_} constants defined below. This argument
2504 tells @value{GDBN} how to perform completion for this command. If not
2505 given, @value{GDBN} will attempt to complete using the object's
2506 @code{complete} method (see below); if no such method is found, an
2507 error will occur when completion is attempted.
2509 @var{prefix} is an optional argument. If @code{True}, then the new
2510 command is a prefix command; sub-commands of this command may be
2513 The help text for the new command is taken from the Python
2514 documentation string for the command's class, if there is one. If no
2515 documentation string is provided, the default value ``This command is
2516 not documented.'' is used.
2519 @cindex don't repeat Python command
2520 @defun Command.dont_repeat ()
2521 By default, a @value{GDBN} command is repeated when the user enters a
2522 blank line at the command prompt. A command can suppress this
2523 behavior by invoking the @code{dont_repeat} method. This is similar
2524 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
2527 @defun Command.invoke (argument, from_tty)
2528 This method is called by @value{GDBN} when this command is invoked.
2530 @var{argument} is a string. It is the argument to the command, after
2531 leading and trailing whitespace has been stripped.
2533 @var{from_tty} is a boolean argument. When true, this means that the
2534 command was entered by the user at the terminal; when false it means
2535 that the command came from elsewhere.
2537 If this method throws an exception, it is turned into a @value{GDBN}
2538 @code{error} call. Otherwise, the return value is ignored.
2540 @findex gdb.string_to_argv
2541 To break @var{argument} up into an argv-like string use
2542 @code{gdb.string_to_argv}. This function behaves identically to
2543 @value{GDBN}'s internal argument lexer @code{buildargv}.
2544 It is recommended to use this for consistency.
2545 Arguments are separated by spaces and may be quoted.
2549 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
2550 ['1', '2 "3', '4 "5', "6 '7"]
2555 @cindex completion of Python commands
2556 @defun Command.complete (text, word)
2557 This method is called by @value{GDBN} when the user attempts
2558 completion on this command. All forms of completion are handled by
2559 this method, that is, the @key{TAB} and @key{M-?} key bindings
2560 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
2563 The arguments @var{text} and @var{word} are both strings. @var{text}
2564 holds the complete command line up to the cursor's location.
2565 @var{word} holds the last word of the command line; this is computed
2566 using a word-breaking heuristic.
2568 The @code{complete} method can return several values:
2571 If the return value is a sequence, the contents of the sequence are
2572 used as the completions. It is up to @code{complete} to ensure that the
2573 contents actually do complete the word. A zero-length sequence is
2574 allowed, it means that there were no completions available. Only
2575 string elements of the sequence are used; other elements in the
2576 sequence are ignored.
2579 If the return value is one of the @samp{COMPLETE_} constants defined
2580 below, then the corresponding @value{GDBN}-internal completion
2581 function is invoked, and its result is used.
2584 All other results are treated as though there were no available
2589 When a new command is registered, it must be declared as a member of
2590 some general class of commands. This is used to classify top-level
2591 commands in the on-line help system; note that prefix commands are not
2592 listed under their own category but rather that of their top-level
2593 command. The available classifications are represented by constants
2594 defined in the @code{gdb} module:
2597 @findex COMMAND_NONE
2598 @findex gdb.COMMAND_NONE
2599 @item gdb.COMMAND_NONE
2600 The command does not belong to any particular class. A command in
2601 this category will not be displayed in any of the help categories.
2603 @findex COMMAND_RUNNING
2604 @findex gdb.COMMAND_RUNNING
2605 @item gdb.COMMAND_RUNNING
2606 The command is related to running the inferior. For example,
2607 @code{start}, @code{step}, and @code{continue} are in this category.
2608 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
2609 commands in this category.
2611 @findex COMMAND_DATA
2612 @findex gdb.COMMAND_DATA
2613 @item gdb.COMMAND_DATA
2614 The command is related to data or variables. For example,
2615 @code{call}, @code{find}, and @code{print} are in this category. Type
2616 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
2619 @findex COMMAND_STACK
2620 @findex gdb.COMMAND_STACK
2621 @item gdb.COMMAND_STACK
2622 The command has to do with manipulation of the stack. For example,
2623 @code{backtrace}, @code{frame}, and @code{return} are in this
2624 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
2625 list of commands in this category.
2627 @findex COMMAND_FILES
2628 @findex gdb.COMMAND_FILES
2629 @item gdb.COMMAND_FILES
2630 This class is used for file-related commands. For example,
2631 @code{file}, @code{list} and @code{section} are in this category.
2632 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
2633 commands in this category.
2635 @findex COMMAND_SUPPORT
2636 @findex gdb.COMMAND_SUPPORT
2637 @item gdb.COMMAND_SUPPORT
2638 This should be used for ``support facilities'', generally meaning
2639 things that are useful to the user when interacting with @value{GDBN},
2640 but not related to the state of the inferior. For example,
2641 @code{help}, @code{make}, and @code{shell} are in this category. Type
2642 @kbd{help support} at the @value{GDBN} prompt to see a list of
2643 commands in this category.
2645 @findex COMMAND_STATUS
2646 @findex gdb.COMMAND_STATUS
2647 @item gdb.COMMAND_STATUS
2648 The command is an @samp{info}-related command, that is, related to the
2649 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
2650 and @code{show} are in this category. Type @kbd{help status} at the
2651 @value{GDBN} prompt to see a list of commands in this category.
2653 @findex COMMAND_BREAKPOINTS
2654 @findex gdb.COMMAND_BREAKPOINTS
2655 @item gdb.COMMAND_BREAKPOINTS
2656 The command has to do with breakpoints. For example, @code{break},
2657 @code{clear}, and @code{delete} are in this category. Type @kbd{help
2658 breakpoints} at the @value{GDBN} prompt to see a list of commands in
2661 @findex COMMAND_TRACEPOINTS
2662 @findex gdb.COMMAND_TRACEPOINTS
2663 @item gdb.COMMAND_TRACEPOINTS
2664 The command has to do with tracepoints. For example, @code{trace},
2665 @code{actions}, and @code{tfind} are in this category. Type
2666 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
2667 commands in this category.
2669 @findex COMMAND_USER
2670 @findex gdb.COMMAND_USER
2671 @item gdb.COMMAND_USER
2672 The command is a general purpose command for the user, and typically
2673 does not fit in one of the other categories.
2674 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
2675 a list of commands in this category, as well as the list of gdb macros
2676 (@pxref{Sequences}).
2678 @findex COMMAND_OBSCURE
2679 @findex gdb.COMMAND_OBSCURE
2680 @item gdb.COMMAND_OBSCURE
2681 The command is only used in unusual circumstances, or is not of
2682 general interest to users. For example, @code{checkpoint},
2683 @code{fork}, and @code{stop} are in this category. Type @kbd{help
2684 obscure} at the @value{GDBN} prompt to see a list of commands in this
2687 @findex COMMAND_MAINTENANCE
2688 @findex gdb.COMMAND_MAINTENANCE
2689 @item gdb.COMMAND_MAINTENANCE
2690 The command is only useful to @value{GDBN} maintainers. The
2691 @code{maintenance} and @code{flushregs} commands are in this category.
2692 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
2693 commands in this category.
2696 A new command can use a predefined completion function, either by
2697 specifying it via an argument at initialization, or by returning it
2698 from the @code{complete} method. These predefined completion
2699 constants are all defined in the @code{gdb} module:
2702 @findex COMPLETE_NONE
2703 @findex gdb.COMPLETE_NONE
2704 @item gdb.COMPLETE_NONE
2705 This constant means that no completion should be done.
2707 @findex COMPLETE_FILENAME
2708 @findex gdb.COMPLETE_FILENAME
2709 @item gdb.COMPLETE_FILENAME
2710 This constant means that filename completion should be performed.
2712 @findex COMPLETE_LOCATION
2713 @findex gdb.COMPLETE_LOCATION
2714 @item gdb.COMPLETE_LOCATION
2715 This constant means that location completion should be done.
2716 @xref{Specify Location}.
2718 @findex COMPLETE_COMMAND
2719 @findex gdb.COMPLETE_COMMAND
2720 @item gdb.COMPLETE_COMMAND
2721 This constant means that completion should examine @value{GDBN}
2724 @findex COMPLETE_SYMBOL
2725 @findex gdb.COMPLETE_SYMBOL
2726 @item gdb.COMPLETE_SYMBOL
2727 This constant means that completion should be done using symbol names
2730 @findex COMPLETE_EXPRESSION
2731 @findex gdb.COMPLETE_EXPRESSION
2732 @item gdb.COMPLETE_EXPRESSION
2733 This constant means that completion should be done on expressions.
2734 Often this means completing on symbol names, but some language
2735 parsers also have support for completing on field names.
2738 The following code snippet shows how a trivial CLI command can be
2739 implemented in Python:
2742 class HelloWorld (gdb.Command):
2743 """Greet the whole world."""
2745 def __init__ (self):
2746 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
2748 def invoke (self, arg, from_tty):
2749 print "Hello, World!"
2754 The last line instantiates the class, and is necessary to trigger the
2755 registration of the command with @value{GDBN}. Depending on how the
2756 Python code is read into @value{GDBN}, you may need to import the
2757 @code{gdb} module explicitly.
2759 @node Parameters In Python
2760 @subsubsection Parameters In Python
2762 @cindex parameters in python
2763 @cindex python parameters
2764 @tindex gdb.Parameter
2766 You can implement new @value{GDBN} parameters using Python. A new
2767 parameter is implemented as an instance of the @code{gdb.Parameter}
2770 Parameters are exposed to the user via the @code{set} and
2771 @code{show} commands. @xref{Help}.
2773 There are many parameters that already exist and can be set in
2774 @value{GDBN}. Two examples are: @code{set follow fork} and
2775 @code{set charset}. Setting these parameters influences certain
2776 behavior in @value{GDBN}. Similarly, you can define parameters that
2777 can be used to influence behavior in custom Python scripts and commands.
2779 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
2780 The object initializer for @code{Parameter} registers the new
2781 parameter with @value{GDBN}. This initializer is normally invoked
2782 from the subclass' own @code{__init__} method.
2784 @var{name} is the name of the new parameter. If @var{name} consists
2785 of multiple words, then the initial words are looked for as prefix
2786 parameters. An example of this can be illustrated with the
2787 @code{set print} set of parameters. If @var{name} is
2788 @code{print foo}, then @code{print} will be searched as the prefix
2789 parameter. In this case the parameter can subsequently be accessed in
2790 @value{GDBN} as @code{set print foo}.
2792 If @var{name} consists of multiple words, and no prefix parameter group
2793 can be found, an exception is raised.
2795 @var{command-class} should be one of the @samp{COMMAND_} constants
2796 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
2797 categorize the new parameter in the help system.
2799 @var{parameter-class} should be one of the @samp{PARAM_} constants
2800 defined below. This argument tells @value{GDBN} the type of the new
2801 parameter; this information is used for input validation and
2804 If @var{parameter-class} is @code{PARAM_ENUM}, then
2805 @var{enum-sequence} must be a sequence of strings. These strings
2806 represent the possible values for the parameter.
2808 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
2809 of a fourth argument will cause an exception to be thrown.
2811 The help text for the new parameter is taken from the Python
2812 documentation string for the parameter's class, if there is one. If
2813 there is no documentation string, a default value is used.
2816 @defvar Parameter.set_doc
2817 If this attribute exists, and is a string, then its value is used as
2818 the help text for this parameter's @code{set} command. The value is
2819 examined when @code{Parameter.__init__} is invoked; subsequent changes
2823 @defvar Parameter.show_doc
2824 If this attribute exists, and is a string, then its value is used as
2825 the help text for this parameter's @code{show} command. The value is
2826 examined when @code{Parameter.__init__} is invoked; subsequent changes
2830 @defvar Parameter.value
2831 The @code{value} attribute holds the underlying value of the
2832 parameter. It can be read and assigned to just as any other
2833 attribute. @value{GDBN} does validation when assignments are made.
2836 There are two methods that should be implemented in any
2837 @code{Parameter} class. These are:
2839 @defun Parameter.get_set_string (self)
2840 @value{GDBN} will call this method when a @var{parameter}'s value has
2841 been changed via the @code{set} API (for example, @kbd{set foo off}).
2842 The @code{value} attribute has already been populated with the new
2843 value and may be used in output. This method must return a string.
2846 @defun Parameter.get_show_string (self, svalue)
2847 @value{GDBN} will call this method when a @var{parameter}'s
2848 @code{show} API has been invoked (for example, @kbd{show foo}). The
2849 argument @code{svalue} receives the string representation of the
2850 current value. This method must return a string.
2853 When a new parameter is defined, its type must be specified. The
2854 available types are represented by constants defined in the @code{gdb}
2858 @findex PARAM_BOOLEAN
2859 @findex gdb.PARAM_BOOLEAN
2860 @item gdb.PARAM_BOOLEAN
2861 The value is a plain boolean. The Python boolean values, @code{True}
2862 and @code{False} are the only valid values.
2864 @findex PARAM_AUTO_BOOLEAN
2865 @findex gdb.PARAM_AUTO_BOOLEAN
2866 @item gdb.PARAM_AUTO_BOOLEAN
2867 The value has three possible states: true, false, and @samp{auto}. In
2868 Python, true and false are represented using boolean constants, and
2869 @samp{auto} is represented using @code{None}.
2871 @findex PARAM_UINTEGER
2872 @findex gdb.PARAM_UINTEGER
2873 @item gdb.PARAM_UINTEGER
2874 The value is an unsigned integer. The value of 0 should be
2875 interpreted to mean ``unlimited''.
2877 @findex PARAM_INTEGER
2878 @findex gdb.PARAM_INTEGER
2879 @item gdb.PARAM_INTEGER
2880 The value is a signed integer. The value of 0 should be interpreted
2881 to mean ``unlimited''.
2883 @findex PARAM_STRING
2884 @findex gdb.PARAM_STRING
2885 @item gdb.PARAM_STRING
2886 The value is a string. When the user modifies the string, any escape
2887 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
2888 translated into corresponding characters and encoded into the current
2891 @findex PARAM_STRING_NOESCAPE
2892 @findex gdb.PARAM_STRING_NOESCAPE
2893 @item gdb.PARAM_STRING_NOESCAPE
2894 The value is a string. When the user modifies the string, escapes are
2895 passed through untranslated.
2897 @findex PARAM_OPTIONAL_FILENAME
2898 @findex gdb.PARAM_OPTIONAL_FILENAME
2899 @item gdb.PARAM_OPTIONAL_FILENAME
2900 The value is a either a filename (a string), or @code{None}.
2902 @findex PARAM_FILENAME
2903 @findex gdb.PARAM_FILENAME
2904 @item gdb.PARAM_FILENAME
2905 The value is a filename. This is just like
2906 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
2908 @findex PARAM_ZINTEGER
2909 @findex gdb.PARAM_ZINTEGER
2910 @item gdb.PARAM_ZINTEGER
2911 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
2912 is interpreted as itself.
2915 @findex gdb.PARAM_ENUM
2916 @item gdb.PARAM_ENUM
2917 The value is a string, which must be one of a collection string
2918 constants provided when the parameter is created.
2921 @node Functions In Python
2922 @subsubsection Writing new convenience functions
2924 @cindex writing convenience functions
2925 @cindex convenience functions in python
2926 @cindex python convenience functions
2927 @tindex gdb.Function
2929 You can implement new convenience functions (@pxref{Convenience Vars})
2930 in Python. A convenience function is an instance of a subclass of the
2931 class @code{gdb.Function}.
2933 @defun Function.__init__ (name)
2934 The initializer for @code{Function} registers the new function with
2935 @value{GDBN}. The argument @var{name} is the name of the function,
2936 a string. The function will be visible to the user as a convenience
2937 variable of type @code{internal function}, whose name is the same as
2938 the given @var{name}.
2940 The documentation for the new function is taken from the documentation
2941 string for the new class.
2944 @defun Function.invoke (@var{*args})
2945 When a convenience function is evaluated, its arguments are converted
2946 to instances of @code{gdb.Value}, and then the function's
2947 @code{invoke} method is called. Note that @value{GDBN} does not
2948 predetermine the arity of convenience functions. Instead, all
2949 available arguments are passed to @code{invoke}, following the
2950 standard Python calling convention. In particular, a convenience
2951 function can have default values for parameters without ill effect.
2953 The return value of this method is used as its value in the enclosing
2954 expression. If an ordinary Python value is returned, it is converted
2955 to a @code{gdb.Value} following the usual rules.
2958 The following code snippet shows how a trivial convenience function can
2959 be implemented in Python:
2962 class Greet (gdb.Function):
2963 """Return string to greet someone.
2964 Takes a name as argument."""
2966 def __init__ (self):
2967 super (Greet, self).__init__ ("greet")
2969 def invoke (self, name):
2970 return "Hello, %s!" % name.string ()
2975 The last line instantiates the class, and is necessary to trigger the
2976 registration of the function with @value{GDBN}. Depending on how the
2977 Python code is read into @value{GDBN}, you may need to import the
2978 @code{gdb} module explicitly.
2980 Now you can use the function in an expression:
2983 (gdb) print $greet("Bob")
2987 @node Progspaces In Python
2988 @subsubsection Program Spaces In Python
2990 @cindex progspaces in python
2991 @tindex gdb.Progspace
2993 A program space, or @dfn{progspace}, represents a symbolic view
2994 of an address space.
2995 It consists of all of the objfiles of the program.
2996 @xref{Objfiles In Python}.
2997 @xref{Inferiors and Programs, program spaces}, for more details
2998 about program spaces.
3000 The following progspace-related functions are available in the
3003 @findex gdb.current_progspace
3004 @defun gdb.current_progspace ()
3005 This function returns the program space of the currently selected inferior.
3006 @xref{Inferiors and Programs}.
3009 @findex gdb.progspaces
3010 @defun gdb.progspaces ()
3011 Return a sequence of all the progspaces currently known to @value{GDBN}.
3014 Each progspace is represented by an instance of the @code{gdb.Progspace}
3017 @defvar Progspace.filename
3018 The file name of the progspace as a string.
3021 @defvar Progspace.pretty_printers
3022 The @code{pretty_printers} attribute is a list of functions. It is
3023 used to look up pretty-printers. A @code{Value} is passed to each
3024 function in order; if the function returns @code{None}, then the
3025 search continues. Otherwise, the return value should be an object
3026 which is used to format the value. @xref{Pretty Printing API}, for more
3030 @defvar Progspace.type_printers
3031 The @code{type_printers} attribute is a list of type printer objects.
3032 @xref{Type Printing API}, for more information.
3035 @defvar Progspace.frame_filters
3036 The @code{frame_filters} attribute is a dictionary of frame filter
3037 objects. @xref{Frame Filter API}, for more information.
3040 @node Objfiles In Python
3041 @subsubsection Objfiles In Python
3043 @cindex objfiles in python
3046 @value{GDBN} loads symbols for an inferior from various
3047 symbol-containing files (@pxref{Files}). These include the primary
3048 executable file, any shared libraries used by the inferior, and any
3049 separate debug info files (@pxref{Separate Debug Files}).
3050 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
3052 The following objfile-related functions are available in the
3055 @findex gdb.current_objfile
3056 @defun gdb.current_objfile ()
3057 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
3058 sets the ``current objfile'' to the corresponding objfile. This
3059 function returns the current objfile. If there is no current objfile,
3060 this function returns @code{None}.
3063 @findex gdb.objfiles
3064 @defun gdb.objfiles ()
3065 Return a sequence of all the objfiles current known to @value{GDBN}.
3066 @xref{Objfiles In Python}.
3069 Each objfile is represented by an instance of the @code{gdb.Objfile}
3072 @defvar Objfile.filename
3073 The file name of the objfile as a string.
3076 @defvar Objfile.pretty_printers
3077 The @code{pretty_printers} attribute is a list of functions. It is
3078 used to look up pretty-printers. A @code{Value} is passed to each
3079 function in order; if the function returns @code{None}, then the
3080 search continues. Otherwise, the return value should be an object
3081 which is used to format the value. @xref{Pretty Printing API}, for more
3085 @defvar Objfile.type_printers
3086 The @code{type_printers} attribute is a list of type printer objects.
3087 @xref{Type Printing API}, for more information.
3090 @defvar Objfile.frame_filters
3091 The @code{frame_filters} attribute is a dictionary of frame filter
3092 objects. @xref{Frame Filter API}, for more information.
3095 A @code{gdb.Objfile} object has the following methods:
3097 @defun Objfile.is_valid ()
3098 Returns @code{True} if the @code{gdb.Objfile} object is valid,
3099 @code{False} if not. A @code{gdb.Objfile} object can become invalid
3100 if the object file it refers to is not loaded in @value{GDBN} any
3101 longer. All other @code{gdb.Objfile} methods will throw an exception
3102 if it is invalid at the time the method is called.
3105 @node Frames In Python
3106 @subsubsection Accessing inferior stack frames from Python.
3108 @cindex frames in python
3109 When the debugged program stops, @value{GDBN} is able to analyze its call
3110 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
3111 represents a frame in the stack. A @code{gdb.Frame} object is only valid
3112 while its corresponding frame exists in the inferior's stack. If you try
3113 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
3114 exception (@pxref{Exception Handling}).
3116 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
3120 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
3124 The following frame-related functions are available in the @code{gdb} module:
3126 @findex gdb.selected_frame
3127 @defun gdb.selected_frame ()
3128 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
3131 @findex gdb.newest_frame
3132 @defun gdb.newest_frame ()
3133 Return the newest frame object for the selected thread.
3136 @defun gdb.frame_stop_reason_string (reason)
3137 Return a string explaining the reason why @value{GDBN} stopped unwinding
3138 frames, as expressed by the given @var{reason} code (an integer, see the
3139 @code{unwind_stop_reason} method further down in this section).
3142 A @code{gdb.Frame} object has the following methods:
3144 @defun Frame.is_valid ()
3145 Returns true if the @code{gdb.Frame} object is valid, false if not.
3146 A frame object can become invalid if the frame it refers to doesn't
3147 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
3148 an exception if it is invalid at the time the method is called.
3151 @defun Frame.name ()
3152 Returns the function name of the frame, or @code{None} if it can't be
3156 @defun Frame.architecture ()
3157 Returns the @code{gdb.Architecture} object corresponding to the frame's
3158 architecture. @xref{Architectures In Python}.
3161 @defun Frame.type ()
3162 Returns the type of the frame. The value can be one of:
3164 @item gdb.NORMAL_FRAME
3165 An ordinary stack frame.
3167 @item gdb.DUMMY_FRAME
3168 A fake stack frame that was created by @value{GDBN} when performing an
3169 inferior function call.
3171 @item gdb.INLINE_FRAME
3172 A frame representing an inlined function. The function was inlined
3173 into a @code{gdb.NORMAL_FRAME} that is older than this one.
3175 @item gdb.TAILCALL_FRAME
3176 A frame representing a tail call. @xref{Tail Call Frames}.
3178 @item gdb.SIGTRAMP_FRAME
3179 A signal trampoline frame. This is the frame created by the OS when
3180 it calls into a signal handler.
3182 @item gdb.ARCH_FRAME
3183 A fake stack frame representing a cross-architecture call.
3185 @item gdb.SENTINEL_FRAME
3186 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
3191 @defun Frame.unwind_stop_reason ()
3192 Return an integer representing the reason why it's not possible to find
3193 more frames toward the outermost frame. Use
3194 @code{gdb.frame_stop_reason_string} to convert the value returned by this
3195 function to a string. The value can be one of:
3198 @item gdb.FRAME_UNWIND_NO_REASON
3199 No particular reason (older frames should be available).
3201 @item gdb.FRAME_UNWIND_NULL_ID
3202 The previous frame's analyzer returns an invalid result. This is no
3203 longer used by @value{GDBN}, and is kept only for backward
3206 @item gdb.FRAME_UNWIND_OUTERMOST
3207 This frame is the outermost.
3209 @item gdb.FRAME_UNWIND_UNAVAILABLE
3210 Cannot unwind further, because that would require knowing the
3211 values of registers or memory that have not been collected.
3213 @item gdb.FRAME_UNWIND_INNER_ID
3214 This frame ID looks like it ought to belong to a NEXT frame,
3215 but we got it for a PREV frame. Normally, this is a sign of
3216 unwinder failure. It could also indicate stack corruption.
3218 @item gdb.FRAME_UNWIND_SAME_ID
3219 This frame has the same ID as the previous one. That means
3220 that unwinding further would almost certainly give us another
3221 frame with exactly the same ID, so break the chain. Normally,
3222 this is a sign of unwinder failure. It could also indicate
3225 @item gdb.FRAME_UNWIND_NO_SAVED_PC
3226 The frame unwinder did not find any saved PC, but we needed
3227 one to unwind further.
3229 @item gdb.FRAME_UNWIND_FIRST_ERROR
3230 Any stop reason greater or equal to this value indicates some kind
3231 of error. This special value facilitates writing code that tests
3232 for errors in unwinding in a way that will work correctly even if
3233 the list of the other values is modified in future @value{GDBN}
3234 versions. Using it, you could write:
3236 reason = gdb.selected_frame().unwind_stop_reason ()
3237 reason_str = gdb.frame_stop_reason_string (reason)
3238 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
3239 print "An error occured: %s" % reason_str
3246 Returns the frame's resume address.
3249 @defun Frame.block ()
3250 Return the frame's code block. @xref{Blocks In Python}.
3253 @defun Frame.function ()
3254 Return the symbol for the function corresponding to this frame.
3255 @xref{Symbols In Python}.
3258 @defun Frame.older ()
3259 Return the frame that called this frame.
3262 @defun Frame.newer ()
3263 Return the frame called by this frame.
3266 @defun Frame.find_sal ()
3267 Return the frame's symtab and line object.
3268 @xref{Symbol Tables In Python}.
3271 @defun Frame.read_var (variable @r{[}, block@r{]})
3272 Return the value of @var{variable} in this frame. If the optional
3273 argument @var{block} is provided, search for the variable from that
3274 block; otherwise start at the frame's current block (which is
3275 determined by the frame's current program counter). @var{variable}
3276 must be a string or a @code{gdb.Symbol} object. @var{block} must be a
3277 @code{gdb.Block} object.
3280 @defun Frame.select ()
3281 Set this frame to be the selected frame. @xref{Stack, ,Examining the
3285 @node Blocks In Python
3286 @subsubsection Accessing blocks from Python.
3288 @cindex blocks in python
3291 In @value{GDBN}, symbols are stored in blocks. A block corresponds
3292 roughly to a scope in the source code. Blocks are organized
3293 hierarchically, and are represented individually in Python as a
3294 @code{gdb.Block}. Blocks rely on debugging information being
3297 A frame has a block. Please see @ref{Frames In Python}, for a more
3298 in-depth discussion of frames.
3300 The outermost block is known as the @dfn{global block}. The global
3301 block typically holds public global variables and functions.
3303 The block nested just inside the global block is the @dfn{static
3304 block}. The static block typically holds file-scoped variables and
3307 @value{GDBN} provides a method to get a block's superblock, but there
3308 is currently no way to examine the sub-blocks of a block, or to
3309 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
3312 Here is a short example that should help explain blocks:
3315 /* This is in the global block. */
3318 /* This is in the static block. */
3319 static int file_scope;
3321 /* 'function' is in the global block, and 'argument' is
3322 in a block nested inside of 'function'. */
3323 int function (int argument)
3325 /* 'local' is in a block inside 'function'. It may or may
3326 not be in the same block as 'argument'. */
3330 /* 'inner' is in a block whose superblock is the one holding
3334 /* If this call is expanded by the compiler, you may see
3335 a nested block here whose function is 'inline_function'
3336 and whose superblock is the one holding 'inner'. */
3342 A @code{gdb.Block} is iterable. The iterator returns the symbols
3343 (@pxref{Symbols In Python}) local to the block. Python programs
3344 should not assume that a specific block object will always contain a
3345 given symbol, since changes in @value{GDBN} features and
3346 infrastructure may cause symbols move across blocks in a symbol
3349 The following block-related functions are available in the @code{gdb}
3352 @findex gdb.block_for_pc
3353 @defun gdb.block_for_pc (pc)
3354 Return the innermost @code{gdb.Block} containing the given @var{pc}
3355 value. If the block cannot be found for the @var{pc} value specified,
3356 the function will return @code{None}.
3359 A @code{gdb.Block} object has the following methods:
3361 @defun Block.is_valid ()
3362 Returns @code{True} if the @code{gdb.Block} object is valid,
3363 @code{False} if not. A block object can become invalid if the block it
3364 refers to doesn't exist anymore in the inferior. All other
3365 @code{gdb.Block} methods will throw an exception if it is invalid at
3366 the time the method is called. The block's validity is also checked
3367 during iteration over symbols of the block.
3370 A @code{gdb.Block} object has the following attributes:
3373 The start address of the block. This attribute is not writable.
3377 The end address of the block. This attribute is not writable.
3380 @defvar Block.function
3381 The name of the block represented as a @code{gdb.Symbol}. If the
3382 block is not named, then this attribute holds @code{None}. This
3383 attribute is not writable.
3385 For ordinary function blocks, the superblock is the static block.
3386 However, you should note that it is possible for a function block to
3387 have a superblock that is not the static block -- for instance this
3388 happens for an inlined function.
3391 @defvar Block.superblock
3392 The block containing this block. If this parent block does not exist,
3393 this attribute holds @code{None}. This attribute is not writable.
3396 @defvar Block.global_block
3397 The global block associated with this block. This attribute is not
3401 @defvar Block.static_block
3402 The static block associated with this block. This attribute is not
3406 @defvar Block.is_global
3407 @code{True} if the @code{gdb.Block} object is a global block,
3408 @code{False} if not. This attribute is not
3412 @defvar Block.is_static
3413 @code{True} if the @code{gdb.Block} object is a static block,
3414 @code{False} if not. This attribute is not writable.
3417 @node Symbols In Python
3418 @subsubsection Python representation of Symbols.
3420 @cindex symbols in python
3423 @value{GDBN} represents every variable, function and type as an
3424 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
3425 Similarly, Python represents these symbols in @value{GDBN} with the
3426 @code{gdb.Symbol} object.
3428 The following symbol-related functions are available in the @code{gdb}
3431 @findex gdb.lookup_symbol
3432 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
3433 This function searches for a symbol by name. The search scope can be
3434 restricted to the parameters defined in the optional domain and block
3437 @var{name} is the name of the symbol. It must be a string. The
3438 optional @var{block} argument restricts the search to symbols visible
3439 in that @var{block}. The @var{block} argument must be a
3440 @code{gdb.Block} object. If omitted, the block for the current frame
3441 is used. The optional @var{domain} argument restricts
3442 the search to the domain type. The @var{domain} argument must be a
3443 domain constant defined in the @code{gdb} module and described later
3446 The result is a tuple of two elements.
3447 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
3449 If the symbol is found, the second element is @code{True} if the symbol
3450 is a field of a method's object (e.g., @code{this} in C@t{++}),
3451 otherwise it is @code{False}.
3452 If the symbol is not found, the second element is @code{False}.
3455 @findex gdb.lookup_global_symbol
3456 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
3457 This function searches for a global symbol by name.
3458 The search scope can be restricted to by the domain argument.
3460 @var{name} is the name of the symbol. It must be a string.
3461 The optional @var{domain} argument restricts the search to the domain type.
3462 The @var{domain} argument must be a domain constant defined in the @code{gdb}
3463 module and described later in this chapter.
3465 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
3469 A @code{gdb.Symbol} object has the following attributes:
3472 The type of the symbol or @code{None} if no type is recorded.
3473 This attribute is represented as a @code{gdb.Type} object.
3474 @xref{Types In Python}. This attribute is not writable.
3477 @defvar Symbol.symtab
3478 The symbol table in which the symbol appears. This attribute is
3479 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
3480 Python}. This attribute is not writable.
3484 The line number in the source code at which the symbol was defined.
3489 The name of the symbol as a string. This attribute is not writable.
3492 @defvar Symbol.linkage_name
3493 The name of the symbol, as used by the linker (i.e., may be mangled).
3494 This attribute is not writable.
3497 @defvar Symbol.print_name
3498 The name of the symbol in a form suitable for output. This is either
3499 @code{name} or @code{linkage_name}, depending on whether the user
3500 asked @value{GDBN} to display demangled or mangled names.
3503 @defvar Symbol.addr_class
3504 The address class of the symbol. This classifies how to find the value
3505 of a symbol. Each address class is a constant defined in the
3506 @code{gdb} module and described later in this chapter.
3509 @defvar Symbol.needs_frame
3510 This is @code{True} if evaluating this symbol's value requires a frame
3511 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
3512 local variables will require a frame, but other symbols will not.
3515 @defvar Symbol.is_argument
3516 @code{True} if the symbol is an argument of a function.
3519 @defvar Symbol.is_constant
3520 @code{True} if the symbol is a constant.
3523 @defvar Symbol.is_function
3524 @code{True} if the symbol is a function or a method.
3527 @defvar Symbol.is_variable
3528 @code{True} if the symbol is a variable.
3531 A @code{gdb.Symbol} object has the following methods:
3533 @defun Symbol.is_valid ()
3534 Returns @code{True} if the @code{gdb.Symbol} object is valid,
3535 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
3536 the symbol it refers to does not exist in @value{GDBN} any longer.
3537 All other @code{gdb.Symbol} methods will throw an exception if it is
3538 invalid at the time the method is called.
3541 @defun Symbol.value (@r{[}frame@r{]})
3542 Compute the value of the symbol, as a @code{gdb.Value}. For
3543 functions, this computes the address of the function, cast to the
3544 appropriate type. If the symbol requires a frame in order to compute
3545 its value, then @var{frame} must be given. If @var{frame} is not
3546 given, or if @var{frame} is invalid, then this method will throw an
3550 The available domain categories in @code{gdb.Symbol} are represented
3551 as constants in the @code{gdb} module:
3554 @findex SYMBOL_UNDEF_DOMAIN
3555 @findex gdb.SYMBOL_UNDEF_DOMAIN
3556 @item gdb.SYMBOL_UNDEF_DOMAIN
3557 This is used when a domain has not been discovered or none of the
3558 following domains apply. This usually indicates an error either
3559 in the symbol information or in @value{GDBN}'s handling of symbols.
3560 @findex SYMBOL_VAR_DOMAIN
3561 @findex gdb.SYMBOL_VAR_DOMAIN
3562 @item gdb.SYMBOL_VAR_DOMAIN
3563 This domain contains variables, function names, typedef names and enum
3565 @findex SYMBOL_STRUCT_DOMAIN
3566 @findex gdb.SYMBOL_STRUCT_DOMAIN
3567 @item gdb.SYMBOL_STRUCT_DOMAIN
3568 This domain holds struct, union and enum type names.
3569 @findex SYMBOL_LABEL_DOMAIN
3570 @findex gdb.SYMBOL_LABEL_DOMAIN
3571 @item gdb.SYMBOL_LABEL_DOMAIN
3572 This domain contains names of labels (for gotos).
3573 @findex SYMBOL_VARIABLES_DOMAIN
3574 @findex gdb.SYMBOL_VARIABLES_DOMAIN
3575 @item gdb.SYMBOL_VARIABLES_DOMAIN
3576 This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
3577 contains everything minus functions and types.
3578 @findex SYMBOL_FUNCTIONS_DOMAIN
3579 @findex gdb.SYMBOL_FUNCTIONS_DOMAIN
3580 @item gdb.SYMBOL_FUNCTION_DOMAIN
3581 This domain contains all functions.
3582 @findex SYMBOL_TYPES_DOMAIN
3583 @findex gdb.SYMBOL_TYPES_DOMAIN
3584 @item gdb.SYMBOL_TYPES_DOMAIN
3585 This domain contains all types.
3588 The available address class categories in @code{gdb.Symbol} are represented
3589 as constants in the @code{gdb} module:
3592 @findex SYMBOL_LOC_UNDEF
3593 @findex gdb.SYMBOL_LOC_UNDEF
3594 @item gdb.SYMBOL_LOC_UNDEF
3595 If this is returned by address class, it indicates an error either in
3596 the symbol information or in @value{GDBN}'s handling of symbols.
3597 @findex SYMBOL_LOC_CONST
3598 @findex gdb.SYMBOL_LOC_CONST
3599 @item gdb.SYMBOL_LOC_CONST
3600 Value is constant int.
3601 @findex SYMBOL_LOC_STATIC
3602 @findex gdb.SYMBOL_LOC_STATIC
3603 @item gdb.SYMBOL_LOC_STATIC
3604 Value is at a fixed address.
3605 @findex SYMBOL_LOC_REGISTER
3606 @findex gdb.SYMBOL_LOC_REGISTER
3607 @item gdb.SYMBOL_LOC_REGISTER
3608 Value is in a register.
3609 @findex SYMBOL_LOC_ARG
3610 @findex gdb.SYMBOL_LOC_ARG
3611 @item gdb.SYMBOL_LOC_ARG
3612 Value is an argument. This value is at the offset stored within the
3613 symbol inside the frame's argument list.
3614 @findex SYMBOL_LOC_REF_ARG
3615 @findex gdb.SYMBOL_LOC_REF_ARG
3616 @item gdb.SYMBOL_LOC_REF_ARG
3617 Value address is stored in the frame's argument list. Just like
3618 @code{LOC_ARG} except that the value's address is stored at the
3619 offset, not the value itself.
3620 @findex SYMBOL_LOC_REGPARM_ADDR
3621 @findex gdb.SYMBOL_LOC_REGPARM_ADDR
3622 @item gdb.SYMBOL_LOC_REGPARM_ADDR
3623 Value is a specified register. Just like @code{LOC_REGISTER} except
3624 the register holds the address of the argument instead of the argument
3626 @findex SYMBOL_LOC_LOCAL
3627 @findex gdb.SYMBOL_LOC_LOCAL
3628 @item gdb.SYMBOL_LOC_LOCAL
3629 Value is a local variable.
3630 @findex SYMBOL_LOC_TYPEDEF
3631 @findex gdb.SYMBOL_LOC_TYPEDEF
3632 @item gdb.SYMBOL_LOC_TYPEDEF
3633 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
3635 @findex SYMBOL_LOC_BLOCK
3636 @findex gdb.SYMBOL_LOC_BLOCK
3637 @item gdb.SYMBOL_LOC_BLOCK
3639 @findex SYMBOL_LOC_CONST_BYTES
3640 @findex gdb.SYMBOL_LOC_CONST_BYTES
3641 @item gdb.SYMBOL_LOC_CONST_BYTES
3642 Value is a byte-sequence.
3643 @findex SYMBOL_LOC_UNRESOLVED
3644 @findex gdb.SYMBOL_LOC_UNRESOLVED
3645 @item gdb.SYMBOL_LOC_UNRESOLVED
3646 Value is at a fixed address, but the address of the variable has to be
3647 determined from the minimal symbol table whenever the variable is
3649 @findex SYMBOL_LOC_OPTIMIZED_OUT
3650 @findex gdb.SYMBOL_LOC_OPTIMIZED_OUT
3651 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
3652 The value does not actually exist in the program.
3653 @findex SYMBOL_LOC_COMPUTED
3654 @findex gdb.SYMBOL_LOC_COMPUTED
3655 @item gdb.SYMBOL_LOC_COMPUTED
3656 The value's address is a computed location.
3659 @node Symbol Tables In Python
3660 @subsubsection Symbol table representation in Python.
3662 @cindex symbol tables in python
3664 @tindex gdb.Symtab_and_line
3666 Access to symbol table data maintained by @value{GDBN} on the inferior
3667 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
3668 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
3669 from the @code{find_sal} method in @code{gdb.Frame} object.
3670 @xref{Frames In Python}.
3672 For more information on @value{GDBN}'s symbol table management, see
3673 @ref{Symbols, ,Examining the Symbol Table}, for more information.
3675 A @code{gdb.Symtab_and_line} object has the following attributes:
3677 @defvar Symtab_and_line.symtab
3678 The symbol table object (@code{gdb.Symtab}) for this frame.
3679 This attribute is not writable.
3682 @defvar Symtab_and_line.pc
3683 Indicates the start of the address range occupied by code for the
3684 current source line. This attribute is not writable.
3687 @defvar Symtab_and_line.last
3688 Indicates the end of the address range occupied by code for the current
3689 source line. This attribute is not writable.
3692 @defvar Symtab_and_line.line
3693 Indicates the current line number for this object. This
3694 attribute is not writable.
3697 A @code{gdb.Symtab_and_line} object has the following methods:
3699 @defun Symtab_and_line.is_valid ()
3700 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
3701 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
3702 invalid if the Symbol table and line object it refers to does not
3703 exist in @value{GDBN} any longer. All other
3704 @code{gdb.Symtab_and_line} methods will throw an exception if it is
3705 invalid at the time the method is called.
3708 A @code{gdb.Symtab} object has the following attributes:
3710 @defvar Symtab.filename
3711 The symbol table's source filename. This attribute is not writable.
3714 @defvar Symtab.objfile
3715 The symbol table's backing object file. @xref{Objfiles In Python}.
3716 This attribute is not writable.
3719 A @code{gdb.Symtab} object has the following methods:
3721 @defun Symtab.is_valid ()
3722 Returns @code{True} if the @code{gdb.Symtab} object is valid,
3723 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
3724 the symbol table it refers to does not exist in @value{GDBN} any
3725 longer. All other @code{gdb.Symtab} methods will throw an exception
3726 if it is invalid at the time the method is called.
3729 @defun Symtab.fullname ()
3730 Return the symbol table's source absolute file name.
3733 @defun Symtab.global_block ()
3734 Return the global block of the underlying symbol table.
3735 @xref{Blocks In Python}.
3738 @defun Symtab.static_block ()
3739 Return the static block of the underlying symbol table.
3740 @xref{Blocks In Python}.
3743 @defun Symtab.linetable ()
3744 Return the line table associated with the symbol table.
3745 @xref{Line Tables In Python}.
3748 @node Line Tables In Python
3749 @subsubsection Manipulating line tables using Python
3751 @cindex line tables in python
3752 @tindex gdb.LineTable
3754 Python code can request and inspect line table information from a
3755 symbol table that is loaded in @value{GDBN}. A line table is a
3756 mapping of source lines to their executable locations in memory. To
3757 acquire the line table information for a particular symbol table, use
3758 the @code{linetable} function (@pxref{Symbol Tables In Python}).
3760 A @code{gdb.LineTable} is iterable. The iterator returns
3761 @code{LineTableEntry} objects that correspond to the source line and
3762 address for each line table entry. @code{LineTableEntry} objects have
3763 the following attributes:
3765 @defvar LineTableEntry.line
3766 The source line number for this line table entry. This number
3767 corresponds to the actual line of source. This attribute is not
3771 @defvar LineTableEntry.pc
3772 The address that is associated with the line table entry where the
3773 executable code for that source line resides in memory. This
3774 attribute is not writable.
3777 As there can be multiple addresses for a single source line, you may
3778 receive multiple @code{LineTableEntry} objects with matching
3779 @code{line} attributes, but with different @code{pc} attributes. The
3780 iterator is sorted in ascending @code{pc} order. Here is a small
3781 example illustrating iterating over a line table.
3784 symtab = gdb.selected_frame().find_sal().symtab
3785 linetable = symtab.linetable()
3786 for line in linetable:
3787 print "Line: "+str(line.line)+" Address: "+hex(line.pc)
3790 This will have the following output:
3793 Line: 33 Address: 0x4005c8L
3794 Line: 37 Address: 0x4005caL
3795 Line: 39 Address: 0x4005d2L
3796 Line: 40 Address: 0x4005f8L
3797 Line: 42 Address: 0x4005ffL
3798 Line: 44 Address: 0x400608L
3799 Line: 42 Address: 0x40060cL
3800 Line: 45 Address: 0x400615L
3803 In addition to being able to iterate over a @code{LineTable}, it also
3804 has the following direct access methods:
3806 @defun LineTable.line (line)
3807 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
3808 entries in the line table for the given @var{line}. @var{line} refers
3809 to the source code line. If there are no entries for that source code
3810 @var{line}, the Python @code{None} is returned.
3813 @defun LineTable.has_line (line)
3814 Return a Python @code{Boolean} indicating whether there is an entry in
3815 the line table for this source line. Return @code{True} if an entry
3816 is found, or @code{False} if not.
3819 @defun LineTable.source_lines ()
3820 Return a Python @code{List} of the source line numbers in the symbol
3821 table. Only lines with executable code locations are returned. The
3822 contents of the @code{List} will just be the source line entries
3823 represented as Python @code{Long} values.
3826 @node Breakpoints In Python
3827 @subsubsection Manipulating breakpoints using Python
3829 @cindex breakpoints in python
3830 @tindex gdb.Breakpoint
3832 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
3835 @defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
3836 Create a new breakpoint. @var{spec} is a string naming the location
3837 of the breakpoint, or an expression that defines a watchpoint. The
3838 contents can be any location recognized by the @code{break} command,
3839 or in the case of a watchpoint, by the @code{watch} command. The
3840 optional @var{type} denotes the breakpoint to create from the types
3841 defined later in this chapter. This argument can be either:
3842 @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type}
3843 defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
3844 argument allows the breakpoint to become invisible to the user. The
3845 breakpoint will neither be reported when created, nor will it be
3846 listed in the output from @code{info breakpoints} (but will be listed
3847 with the @code{maint info breakpoints} command). The optional
3848 @var{temporary} argument makes the breakpoint a temporary breakpoint.
3849 Temporary breakpoints are deleted after they have been hit. Any
3850 further access to the Python breakpoint after it has been hit will
3851 result in a runtime error (as that breakpoint has now been
3852 automatically deleted). The optional @var{wp_class} argument defines
3853 the class of watchpoint to create, if @var{type} is
3854 @code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it
3855 is assumed to be a @code{gdb.WP_WRITE} class.
3858 @defun Breakpoint.stop (self)
3859 The @code{gdb.Breakpoint} class can be sub-classed and, in
3860 particular, you may choose to implement the @code{stop} method.
3861 If this method is defined in a sub-class of @code{gdb.Breakpoint},
3862 it will be called when the inferior reaches any location of a
3863 breakpoint which instantiates that sub-class. If the method returns
3864 @code{True}, the inferior will be stopped at the location of the
3865 breakpoint, otherwise the inferior will continue.
3867 If there are multiple breakpoints at the same location with a
3868 @code{stop} method, each one will be called regardless of the
3869 return status of the previous. This ensures that all @code{stop}
3870 methods have a chance to execute at that location. In this scenario
3871 if one of the methods returns @code{True} but the others return
3872 @code{False}, the inferior will still be stopped.
3874 You should not alter the execution state of the inferior (i.e.@:, step,
3875 next, etc.), alter the current frame context (i.e.@:, change the current
3876 active frame), or alter, add or delete any breakpoint. As a general
3877 rule, you should not alter any data within @value{GDBN} or the inferior
3880 Example @code{stop} implementation:
3883 class MyBreakpoint (gdb.Breakpoint):
3885 inf_val = gdb.parse_and_eval("foo")
3892 The available watchpoint types represented by constants are defined in the
3899 Read only watchpoint.
3902 @findex gdb.WP_WRITE
3904 Write only watchpoint.
3907 @findex gdb.WP_ACCESS
3909 Read/Write watchpoint.
3912 @defun Breakpoint.is_valid ()
3913 Return @code{True} if this @code{Breakpoint} object is valid,
3914 @code{False} otherwise. A @code{Breakpoint} object can become invalid
3915 if the user deletes the breakpoint. In this case, the object still
3916 exists, but the underlying breakpoint does not. In the cases of
3917 watchpoint scope, the watchpoint remains valid even if execution of the
3918 inferior leaves the scope of that watchpoint.
3921 @defun Breakpoint.delete
3922 Permanently deletes the @value{GDBN} breakpoint. This also
3923 invalidates the Python @code{Breakpoint} object. Any further access
3924 to this object's attributes or methods will raise an error.
3927 @defvar Breakpoint.enabled
3928 This attribute is @code{True} if the breakpoint is enabled, and
3929 @code{False} otherwise. This attribute is writable.
3932 @defvar Breakpoint.silent
3933 This attribute is @code{True} if the breakpoint is silent, and
3934 @code{False} otherwise. This attribute is writable.
3936 Note that a breakpoint can also be silent if it has commands and the
3937 first command is @code{silent}. This is not reported by the
3938 @code{silent} attribute.
3941 @defvar Breakpoint.thread
3942 If the breakpoint is thread-specific, this attribute holds the thread
3943 id. If the breakpoint is not thread-specific, this attribute is
3944 @code{None}. This attribute is writable.
3947 @defvar Breakpoint.task
3948 If the breakpoint is Ada task-specific, this attribute holds the Ada task
3949 id. If the breakpoint is not task-specific (or the underlying
3950 language is not Ada), this attribute is @code{None}. This attribute
3954 @defvar Breakpoint.ignore_count
3955 This attribute holds the ignore count for the breakpoint, an integer.
3956 This attribute is writable.
3959 @defvar Breakpoint.number
3960 This attribute holds the breakpoint's number --- the identifier used by
3961 the user to manipulate the breakpoint. This attribute is not writable.
3964 @defvar Breakpoint.type
3965 This attribute holds the breakpoint's type --- the identifier used to
3966 determine the actual breakpoint type or use-case. This attribute is not
3970 @defvar Breakpoint.visible
3971 This attribute tells whether the breakpoint is visible to the user
3972 when set, or when the @samp{info breakpoints} command is run. This
3973 attribute is not writable.
3976 @defvar Breakpoint.temporary
3977 This attribute indicates whether the breakpoint was created as a
3978 temporary breakpoint. Temporary breakpoints are automatically deleted
3979 after that breakpoint has been hit. Access to this attribute, and all
3980 other attributes and functions other than the @code{is_valid}
3981 function, will result in an error after the breakpoint has been hit
3982 (as it has been automatically deleted). This attribute is not
3986 The available types are represented by constants defined in the @code{gdb}
3990 @findex BP_BREAKPOINT
3991 @findex gdb.BP_BREAKPOINT
3992 @item gdb.BP_BREAKPOINT
3993 Normal code breakpoint.
3995 @findex BP_WATCHPOINT
3996 @findex gdb.BP_WATCHPOINT
3997 @item gdb.BP_WATCHPOINT
3998 Watchpoint breakpoint.
4000 @findex BP_HARDWARE_WATCHPOINT
4001 @findex gdb.BP_HARDWARE_WATCHPOINT
4002 @item gdb.BP_HARDWARE_WATCHPOINT
4003 Hardware assisted watchpoint.
4005 @findex BP_READ_WATCHPOINT
4006 @findex gdb.BP_READ_WATCHPOINT
4007 @item gdb.BP_READ_WATCHPOINT
4008 Hardware assisted read watchpoint.
4010 @findex BP_ACCESS_WATCHPOINT
4011 @findex gdb.BP_ACCESS_WATCHPOINT
4012 @item gdb.BP_ACCESS_WATCHPOINT
4013 Hardware assisted access watchpoint.
4016 @defvar Breakpoint.hit_count
4017 This attribute holds the hit count for the breakpoint, an integer.
4018 This attribute is writable, but currently it can only be set to zero.
4021 @defvar Breakpoint.location
4022 This attribute holds the location of the breakpoint, as specified by
4023 the user. It is a string. If the breakpoint does not have a location
4024 (that is, it is a watchpoint) the attribute's value is @code{None}. This
4025 attribute is not writable.
4028 @defvar Breakpoint.expression
4029 This attribute holds a breakpoint expression, as specified by
4030 the user. It is a string. If the breakpoint does not have an
4031 expression (the breakpoint is not a watchpoint) the attribute's value
4032 is @code{None}. This attribute is not writable.
4035 @defvar Breakpoint.condition
4036 This attribute holds the condition of the breakpoint, as specified by
4037 the user. It is a string. If there is no condition, this attribute's
4038 value is @code{None}. This attribute is writable.
4041 @defvar Breakpoint.commands
4042 This attribute holds the commands attached to the breakpoint. If
4043 there are commands, this attribute's value is a string holding all the
4044 commands, separated by newlines. If there are no commands, this
4045 attribute is @code{None}. This attribute is not writable.
4048 @node Finish Breakpoints in Python
4049 @subsubsection Finish Breakpoints
4051 @cindex python finish breakpoints
4052 @tindex gdb.FinishBreakpoint
4054 A finish breakpoint is a temporary breakpoint set at the return address of
4055 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
4056 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
4057 and deleted when the execution will run out of the breakpoint scope (i.e.@:
4058 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
4059 Finish breakpoints are thread specific and must be create with the right
4062 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
4063 Create a finish breakpoint at the return address of the @code{gdb.Frame}
4064 object @var{frame}. If @var{frame} is not provided, this defaults to the
4065 newest frame. The optional @var{internal} argument allows the breakpoint to
4066 become invisible to the user. @xref{Breakpoints In Python}, for further
4067 details about this argument.
4070 @defun FinishBreakpoint.out_of_scope (self)
4071 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
4072 @code{return} command, @dots{}), a function may not properly terminate, and
4073 thus never hit the finish breakpoint. When @value{GDBN} notices such a
4074 situation, the @code{out_of_scope} callback will be triggered.
4076 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
4080 class MyFinishBreakpoint (gdb.FinishBreakpoint)
4082 print "normal finish"
4085 def out_of_scope ():
4086 print "abnormal finish"
4090 @defvar FinishBreakpoint.return_value
4091 When @value{GDBN} is stopped at a finish breakpoint and the frame
4092 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
4093 attribute will contain a @code{gdb.Value} object corresponding to the return
4094 value of the function. The value will be @code{None} if the function return
4095 type is @code{void} or if the return value was not computable. This attribute
4099 @node Lazy Strings In Python
4100 @subsubsection Python representation of lazy strings.
4102 @cindex lazy strings in python
4103 @tindex gdb.LazyString
4105 A @dfn{lazy string} is a string whose contents is not retrieved or
4106 encoded until it is needed.
4108 A @code{gdb.LazyString} is represented in @value{GDBN} as an
4109 @code{address} that points to a region of memory, an @code{encoding}
4110 that will be used to encode that region of memory, and a @code{length}
4111 to delimit the region of memory that represents the string. The
4112 difference between a @code{gdb.LazyString} and a string wrapped within
4113 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
4114 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
4115 retrieved and encoded during printing, while a @code{gdb.Value}
4116 wrapping a string is immediately retrieved and encoded on creation.
4118 A @code{gdb.LazyString} object has the following functions:
4120 @defun LazyString.value ()
4121 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
4122 will point to the string in memory, but will lose all the delayed
4123 retrieval, encoding and handling that @value{GDBN} applies to a
4124 @code{gdb.LazyString}.
4127 @defvar LazyString.address
4128 This attribute holds the address of the string. This attribute is not
4132 @defvar LazyString.length
4133 This attribute holds the length of the string in characters. If the
4134 length is -1, then the string will be fetched and encoded up to the
4135 first null of appropriate width. This attribute is not writable.
4138 @defvar LazyString.encoding
4139 This attribute holds the encoding that will be applied to the string
4140 when the string is printed by @value{GDBN}. If the encoding is not
4141 set, or contains an empty string, then @value{GDBN} will select the
4142 most appropriate encoding when the string is printed. This attribute
4146 @defvar LazyString.type
4147 This attribute holds the type that is represented by the lazy string's
4148 type. For a lazy string this will always be a pointer type. To
4149 resolve this to the lazy string's character type, use the type's
4150 @code{target} method. @xref{Types In Python}. This attribute is not
4154 @node Architectures In Python
4155 @subsubsection Python representation of architectures
4156 @cindex Python architectures
4158 @value{GDBN} uses architecture specific parameters and artifacts in a
4159 number of its various computations. An architecture is represented
4160 by an instance of the @code{gdb.Architecture} class.
4162 A @code{gdb.Architecture} class has the following methods:
4164 @defun Architecture.name ()
4165 Return the name (string value) of the architecture.
4168 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
4169 Return a list of disassembled instructions starting from the memory
4170 address @var{start_pc}. The optional arguments @var{end_pc} and
4171 @var{count} determine the number of instructions in the returned list.
4172 If both the optional arguments @var{end_pc} and @var{count} are
4173 specified, then a list of at most @var{count} disassembled instructions
4174 whose start address falls in the closed memory address interval from
4175 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
4176 specified, but @var{count} is specified, then @var{count} number of
4177 instructions starting from the address @var{start_pc} are returned. If
4178 @var{count} is not specified but @var{end_pc} is specified, then all
4179 instructions whose start address falls in the closed memory address
4180 interval from @var{start_pc} to @var{end_pc} are returned. If neither
4181 @var{end_pc} nor @var{count} are specified, then a single instruction at
4182 @var{start_pc} is returned. For all of these cases, each element of the
4183 returned list is a Python @code{dict} with the following string keys:
4188 The value corresponding to this key is a Python long integer capturing
4189 the memory address of the instruction.
4192 The value corresponding to this key is a string value which represents
4193 the instruction with assembly language mnemonics. The assembly
4194 language flavor used is the same as that specified by the current CLI
4195 variable @code{disassembly-flavor}. @xref{Machine Code}.
4198 The value corresponding to this key is the length (integer value) of the
4199 instruction in bytes.
4204 @node Python Auto-loading
4205 @subsection Python Auto-loading
4206 @cindex Python auto-loading
4208 When a new object file is read (for example, due to the @code{file}
4209 command, or because the inferior has loaded a shared library),
4210 @value{GDBN} will look for Python support scripts in several ways:
4211 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
4212 @xref{Auto-loading extensions}.
4214 The auto-loading feature is useful for supplying application-specific
4215 debugging commands and scripts.
4217 Auto-loading can be enabled or disabled,
4218 and the list of auto-loaded scripts can be printed.
4221 @anchor{set auto-load python-scripts}
4222 @kindex set auto-load python-scripts
4223 @item set auto-load python-scripts [on|off]
4224 Enable or disable the auto-loading of Python scripts.
4226 @anchor{show auto-load python-scripts}
4227 @kindex show auto-load python-scripts
4228 @item show auto-load python-scripts
4229 Show whether auto-loading of Python scripts is enabled or disabled.
4231 @anchor{info auto-load python-scripts}
4232 @kindex info auto-load python-scripts
4233 @cindex print list of auto-loaded Python scripts
4234 @item info auto-load python-scripts [@var{regexp}]
4235 Print the list of all Python scripts that @value{GDBN} auto-loaded.
4237 Also printed is the list of Python scripts that were mentioned in
4238 the @code{.debug_gdb_scripts} section and were not found
4239 (@pxref{dotdebug_gdb_scripts section}).
4240 This is useful because their names are not printed when @value{GDBN}
4241 tries to load them and fails. There may be many of them, and printing
4242 an error message for each one is problematic.
4244 If @var{regexp} is supplied only Python scripts with matching names are printed.
4249 (gdb) info auto-load python-scripts
4251 Yes py-section-script.py
4252 full name: /tmp/py-section-script.py
4253 No my-foo-pretty-printers.py
4257 When reading an auto-loaded file, @value{GDBN} sets the
4258 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
4259 function (@pxref{Objfiles In Python}). This can be useful for
4260 registering objfile-specific pretty-printers and frame-filters.
4262 @node Python modules
4263 @subsection Python modules
4264 @cindex python modules
4266 @value{GDBN} comes with several modules to assist writing Python code.
4269 * gdb.printing:: Building and registering pretty-printers.
4270 * gdb.types:: Utilities for working with types.
4271 * gdb.prompt:: Utilities for prompt value substitution.
4275 @subsubsection gdb.printing
4276 @cindex gdb.printing
4278 This module provides a collection of utilities for working with
4282 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
4283 This class specifies the API that makes @samp{info pretty-printer},
4284 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
4285 Pretty-printers should generally inherit from this class.
4287 @item SubPrettyPrinter (@var{name})
4288 For printers that handle multiple types, this class specifies the
4289 corresponding API for the subprinters.
4291 @item RegexpCollectionPrettyPrinter (@var{name})
4292 Utility class for handling multiple printers, all recognized via
4293 regular expressions.
4294 @xref{Writing a Pretty-Printer}, for an example.
4296 @item FlagEnumerationPrinter (@var{name})
4297 A pretty-printer which handles printing of @code{enum} values. Unlike
4298 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
4299 work properly when there is some overlap between the enumeration
4300 constants. @var{name} is the name of the printer and also the name of
4301 the @code{enum} type to look up.
4303 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
4304 Register @var{printer} with the pretty-printer list of @var{obj}.
4305 If @var{replace} is @code{True} then any existing copy of the printer
4306 is replaced. Otherwise a @code{RuntimeError} exception is raised
4307 if a printer with the same name already exists.
4311 @subsubsection gdb.types
4314 This module provides a collection of utilities for working with
4315 @code{gdb.Type} objects.
4318 @item get_basic_type (@var{type})
4319 Return @var{type} with const and volatile qualifiers stripped,
4320 and with typedefs and C@t{++} references converted to the underlying type.
4325 typedef const int const_int;
4327 const_int& foo_ref (foo);
4328 int main () @{ return 0; @}
4335 (gdb) python import gdb.types
4336 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
4337 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
4341 @item has_field (@var{type}, @var{field})
4342 Return @code{True} if @var{type}, assumed to be a type with fields
4343 (e.g., a structure or union), has field @var{field}.
4345 @item make_enum_dict (@var{enum_type})
4346 Return a Python @code{dictionary} type produced from @var{enum_type}.
4348 @item deep_items (@var{type})
4349 Returns a Python iterator similar to the standard
4350 @code{gdb.Type.iteritems} method, except that the iterator returned
4351 by @code{deep_items} will recursively traverse anonymous struct or
4352 union fields. For example:
4366 Then in @value{GDBN}:
4368 (@value{GDBP}) python import gdb.types
4369 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
4370 (@value{GDBP}) python print struct_a.keys ()
4372 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
4373 @{['a', 'b0', 'b1']@}
4376 @item get_type_recognizers ()
4377 Return a list of the enabled type recognizers for the current context.
4378 This is called by @value{GDBN} during the type-printing process
4379 (@pxref{Type Printing API}).
4381 @item apply_type_recognizers (recognizers, type_obj)
4382 Apply the type recognizers, @var{recognizers}, to the type object
4383 @var{type_obj}. If any recognizer returns a string, return that
4384 string. Otherwise, return @code{None}. This is called by
4385 @value{GDBN} during the type-printing process (@pxref{Type Printing
4388 @item register_type_printer (locus, printer)
4389 This is a convenience function to register a type printer.
4390 @var{printer} is the type printer to register. It must implement the
4391 type printer protocol. @var{locus} is either a @code{gdb.Objfile}, in
4392 which case the printer is registered with that objfile; a
4393 @code{gdb.Progspace}, in which case the printer is registered with
4394 that progspace; or @code{None}, in which case the printer is
4395 registered globally.
4398 This is a base class that implements the type printer protocol. Type
4399 printers are encouraged, but not required, to derive from this class.
4400 It defines a constructor:
4402 @defmethod TypePrinter __init__ (self, name)
4403 Initialize the type printer with the given name. The new printer
4404 starts in the enabled state.
4410 @subsubsection gdb.prompt
4413 This module provides a method for prompt value-substitution.
4416 @item substitute_prompt (@var{string})
4417 Return @var{string} with escape sequences substituted by values. Some
4418 escape sequences take arguments. You can specify arguments inside
4419 ``@{@}'' immediately following the escape sequence.
4421 The escape sequences you can pass to this function are:
4425 Substitute a backslash.
4427 Substitute an ESC character.
4429 Substitute the selected frame; an argument names a frame parameter.
4431 Substitute a newline.
4433 Substitute a parameter's value; the argument names the parameter.
4435 Substitute a carriage return.
4437 Substitute the selected thread; an argument names a thread parameter.
4439 Substitute the version of GDB.
4441 Substitute the current working directory.
4443 Begin a sequence of non-printing characters. These sequences are
4444 typically used with the ESC character, and are not counted in the string
4445 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
4446 blue-colored ``(gdb)'' prompt where the length is five.
4448 End a sequence of non-printing characters.
4454 substitute_prompt (``frame: \f,
4455 print arguments: \p@{print frame-arguments@}'')
4458 @exdent will return the string:
4461 "frame: main, print arguments: scalars"