1 @c Copyright (C) 2008--2022 Free Software Foundation, Inc.
2 @c Permission is granted to copy, distribute and/or modify this document
3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
4 @c any later version published by the Free Software Foundation; with the
5 @c Invariant Sections being ``Free Software'' and ``Free Software Needs
6 @c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
7 @c and with the Back-Cover Texts as in (a) below.
9 @c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
10 @c this GNU Manual. Buying copies from GNU Press supports the FSF in
11 @c developing GNU and promoting software freedom.''
14 @section Extending @value{GDBN} using Python
15 @cindex python scripting
16 @cindex scripting with python
18 You can extend @value{GDBN} using the @uref{http://www.python.org/,
19 Python programming language}. This feature is available only if
20 @value{GDBN} was configured using @option{--with-python}.
21 @value{GDBN} can be built against either Python 2 or Python 3; which
22 one you have depends on this configure-time option.
24 @cindex python directory
25 Python scripts used by @value{GDBN} should be installed in
26 @file{@var{data-directory}/python}, where @var{data-directory} is
27 the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
28 This directory, known as the @dfn{python directory},
29 is automatically added to the Python Search Path in order to allow
30 the Python interpreter to locate all scripts installed at this location.
32 Additionally, @value{GDBN} commands and convenience functions which
33 are written in Python and are located in the
34 @file{@var{data-directory}/python/gdb/command} or
35 @file{@var{data-directory}/python/gdb/function} directories are
36 automatically imported when @value{GDBN} starts.
39 * Python Commands:: Accessing Python from @value{GDBN}.
40 * Python API:: Accessing @value{GDBN} from Python.
41 * Python Auto-loading:: Automatically loading Python code.
42 * Python modules:: Python modules provided by @value{GDBN}.
46 @subsection Python Commands
47 @cindex python commands
48 @cindex commands to access python
50 @value{GDBN} provides two commands for accessing the Python interpreter,
51 and one related setting:
54 @kindex python-interactive
56 @item python-interactive @r{[}@var{command}@r{]}
57 @itemx pi @r{[}@var{command}@r{]}
58 Without an argument, the @code{python-interactive} command can be used
59 to start an interactive Python prompt. To return to @value{GDBN},
60 type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
62 Alternatively, a single-line Python command can be given as an
63 argument and evaluated. If the command is an expression, the result
64 will be printed; otherwise, nothing will be printed. For example:
67 (@value{GDBP}) python-interactive 2 + 3
73 @item python @r{[}@var{command}@r{]}
74 @itemx py @r{[}@var{command}@r{]}
75 The @code{python} command can be used to evaluate Python code.
77 If given an argument, the @code{python} command will evaluate the
78 argument as a Python command. For example:
81 (@value{GDBP}) python print 23
85 If you do not provide an argument to @code{python}, it will act as a
86 multi-line command, like @code{define}. In this case, the Python
87 script is made up of subsequent command lines, given after the
88 @code{python} command. This command list is terminated using a line
89 containing @code{end}. For example:
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.
107 @kindex set python ignore-environment
108 @item set python ignore-environment @r{[}on@r{|}off@r{]}
109 By default this option is @samp{off}, and, when @value{GDBN}
110 initializes its internal Python interpreter, the Python interpreter
111 will check the environment for variables that will effect how it
112 behaves, for example @env{PYTHONHOME}, and
113 @env{PYTHONPATH}@footnote{See the ENVIRONMENT VARIABLES section of
114 @command{man 1 python} for a comprehensive list.}.
116 If this option is set to @samp{on} before Python is initialized then
117 Python will ignore all such environment variables. As Python is
118 initialized early during @value{GDBN}'s startup process, then this
119 option must be placed into the early initialization file
120 (@pxref{Initialization Files}) to have the desired effect.
122 This option is equivalent to passing @option{-E} to the real
123 @command{python} executable.
125 @kindex set python dont-write-bytecode
126 @item set python dont-write-bytecode @r{[}auto@r{|}on@r{|}off@r{]}
127 When this option is @samp{off}, then, once @value{GDBN} has
128 initialized the Python interpreter, the interpreter will byte-compile
129 any Python modules that it imports and write the byte code to disk in
132 If this option is set to @samp{on} before Python is initialized then
133 Python will no longer write the byte code to disk. As Python is
134 initialized early during @value{GDBN}'s startup process, then this
135 option must be placed into the early initialization file
136 (@pxref{Initialization Files}) to have the desired effect.
138 By default this option is set to @samp{auto}, in this mode Python will
139 check the environment variable @env{PYTHONDONTWRITEBYTECODE} to see
140 if it should write out byte-code or not.
142 This option is equivalent to passing @option{-B} to the real
143 @command{python} executable.
146 It is also possible to execute a Python script from the @value{GDBN}
150 @item source @file{script-name}
151 The script name must end with @samp{.py} and @value{GDBN} must be configured
152 to recognize the script language based on filename extension using
153 the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
156 The following commands are intended to help debug @value{GDBN} itself:
159 @kindex set debug py-breakpoint
160 @kindex show debug py-breakpoint
161 @item set debug py-breakpoint on@r{|}off
162 @itemx show debug py-breakpoint
163 When @samp{on}, @value{GDBN} prints debug messages related to the
164 Python breakpoint API. This is @samp{off} by default.
166 @kindex set debug py-unwind
167 @kindex show debug py-unwind
168 @item set debug py-unwind on@r{|}off
169 @itemx show debug py-unwind
170 When @samp{on}, @value{GDBN} prints debug messages related to the
171 Python unwinder API. This is @samp{off} by default.
175 @subsection Python API
177 @cindex programming in python
179 You can get quick online help for @value{GDBN}'s Python API by issuing
180 the command @w{@kbd{python help (gdb)}}.
182 Functions and methods which have two or more optional arguments allow
183 them to be specified using keyword syntax. This allows passing some
184 optional arguments while skipping others. Example:
185 @w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
188 * Basic Python:: Basic Python Functions.
189 * Exception Handling:: How Python exceptions are translated.
190 * Values From Inferior:: Python representation of values.
191 * Types In Python:: Python representation of types.
192 * Pretty Printing API:: Pretty-printing values.
193 * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
194 * Writing a Pretty-Printer:: Writing a Pretty-Printer.
195 * Type Printing API:: Pretty-printing types.
196 * Frame Filter API:: Filtering Frames.
197 * Frame Decorator API:: Decorating Frames.
198 * Writing a Frame Filter:: Writing a Frame Filter.
199 * Unwinding Frames in Python:: Writing frame unwinder.
200 * Xmethods In Python:: Adding and replacing methods of C++ classes.
201 * Xmethod API:: Xmethod types.
202 * Writing an Xmethod:: Writing an xmethod.
203 * Inferiors In Python:: Python representation of inferiors (processes)
204 * Events In Python:: Listening for events from @value{GDBN}.
205 * Threads In Python:: Accessing inferior threads from Python.
206 * Recordings In Python:: Accessing recordings from Python.
207 * Commands In Python:: Implementing new commands in Python.
208 * Parameters In Python:: Adding new @value{GDBN} parameters.
209 * Functions In Python:: Writing new convenience functions.
210 * Progspaces In Python:: Program spaces.
211 * Objfiles In Python:: Object files.
212 * Frames In Python:: Accessing inferior stack frames from Python.
213 * Blocks In Python:: Accessing blocks from Python.
214 * Symbols In Python:: Python representation of symbols.
215 * Symbol Tables In Python:: Python representation of symbol tables.
216 * Line Tables In Python:: Python representation of line tables.
217 * Breakpoints In Python:: Manipulating breakpoints using Python.
218 * Finish Breakpoints in Python:: Setting Breakpoints on function return
220 * Lazy Strings In Python:: Python representation of lazy strings.
221 * Architectures In Python:: Python representation of architectures.
222 * Registers In Python:: Python representation of registers.
223 * Connections In Python:: Python representation of connections.
224 * TUI Windows In Python:: Implementing new TUI windows.
228 @subsubsection Basic Python
230 @cindex python stdout
231 @cindex python pagination
232 At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
233 @code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
234 A Python program which outputs to one of these streams may have its
235 output interrupted by the user (@pxref{Screen Size}). In this
236 situation, a Python @code{KeyboardInterrupt} exception is thrown.
238 Some care must be taken when writing Python code to run in
239 @value{GDBN}. Two things worth noting in particular:
243 @value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
244 Python code must not override these, or even change the options using
245 @code{sigaction}. If your program changes the handling of these
246 signals, @value{GDBN} will most likely stop working correctly. Note
247 that it is unfortunately common for GUI toolkits to install a
248 @code{SIGCHLD} handler.
251 @value{GDBN} takes care to mark its internal file descriptors as
252 close-on-exec. However, this cannot be done in a thread-safe way on
253 all platforms. Your Python programs should be aware of this and
254 should both create new file descriptors with the close-on-exec flag
255 set and arrange to close unneeded file descriptors before starting a
259 @cindex python functions
260 @cindex python module
262 @value{GDBN} introduces a new Python module, named @code{gdb}. All
263 methods and classes added by @value{GDBN} are placed in this module.
264 @value{GDBN} automatically @code{import}s the @code{gdb} module for
265 use in all scripts evaluated by the @code{python} command.
267 Some types of the @code{gdb} module come with a textual representation
268 (accessible through the @code{repr} or @code{str} functions). These are
269 offered for debugging purposes only, expect them to change over time.
271 @findex gdb.PYTHONDIR
272 @defvar gdb.PYTHONDIR
273 A string containing the python directory (@pxref{Python}).
277 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
278 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
279 If a GDB exception happens while @var{command} runs, it is
280 translated as described in @ref{Exception Handling,,Exception Handling}.
282 The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
283 command as having originated from the user invoking it interactively.
284 It must be a boolean value. If omitted, it defaults to @code{False}.
286 By default, any output produced by @var{command} is sent to
287 @value{GDBN}'s standard output (and to the log output if logging is
288 turned on). If the @var{to_string} parameter is
289 @code{True}, then output will be collected by @code{gdb.execute} and
290 returned as a string. The default is @code{False}, in which case the
291 return value is @code{None}. If @var{to_string} is @code{True}, the
292 @value{GDBN} virtual terminal will be temporarily set to unlimited width
293 and height, and its pagination will be disabled; @pxref{Screen Size}.
296 @findex gdb.breakpoints
297 @defun gdb.breakpoints ()
298 Return a sequence holding all of @value{GDBN}'s breakpoints.
299 @xref{Breakpoints In Python}, for more information. In @value{GDBN}
300 version 7.11 and earlier, this function returned @code{None} if there
301 were no breakpoints. This peculiarity was subsequently fixed, and now
302 @code{gdb.breakpoints} returns an empty sequence in this case.
305 @defun gdb.rbreak (regex @r{[}, minsyms @r{[}, throttle, @r{[}, symtabs @r{]]]})
306 Return a Python list holding a collection of newly set
307 @code{gdb.Breakpoint} objects matching function names defined by the
308 @var{regex} pattern. If the @var{minsyms} keyword is @code{True}, all
309 system functions (those not explicitly defined in the inferior) will
310 also be included in the match. The @var{throttle} keyword takes an
311 integer that defines the maximum number of pattern matches for
312 functions matched by the @var{regex} pattern. If the number of
313 matches exceeds the integer value of @var{throttle}, a
314 @code{RuntimeError} will be raised and no breakpoints will be created.
315 If @var{throttle} is not defined then there is no imposed limit on the
316 maximum number of matches and breakpoints to be created. The
317 @var{symtabs} keyword takes a Python iterable that yields a collection
318 of @code{gdb.Symtab} objects and will restrict the search to those
319 functions only contained within the @code{gdb.Symtab} objects.
322 @findex gdb.parameter
323 @defun gdb.parameter (parameter)
324 Return the value of a @value{GDBN} @var{parameter} given by its name,
325 a string; the parameter name string may contain spaces if the parameter has a
326 multi-part name. For example, @samp{print object} is a valid
329 If the named parameter does not exist, this function throws a
330 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
331 parameter's value is converted to a Python value of the appropriate
335 @findex gdb.set_parameter
336 @defun gdb.set_parameter (name, value)
337 Sets the gdb parameter @var{name} to @var{value}. As with
338 @code{gdb.parameter}, the parameter name string may contain spaces if
339 the parameter has a multi-part name.
342 @findex gdb.with_parameter
343 @defun gdb.with_parameter (name, value)
344 Create a Python context manager (for use with the Python
345 @command{with} statement) that temporarily sets the gdb parameter
346 @var{name} to @var{value}. On exit from the context, the previous
347 value will be restored.
349 This uses @code{gdb.parameter} in its implementation, so it can throw
350 the same exceptions as that function.
352 For example, it's sometimes useful to evaluate some Python code with a
353 particular gdb language:
356 with gdb.with_parameter('language', 'pascal'):
357 ... language-specific operations
362 @defun gdb.history (number)
363 Return a value from @value{GDBN}'s value history (@pxref{Value
364 History}). The @var{number} argument indicates which history element to return.
365 If @var{number} is negative, then @value{GDBN} will take its absolute value
366 and count backward from the last element (i.e., the most recent element) to
367 find the value to return. If @var{number} is zero, then @value{GDBN} will
368 return the most recent element. If the element specified by @var{number}
369 doesn't exist in the value history, a @code{gdb.error} exception will be
372 If no exception is raised, the return value is always an instance of
373 @code{gdb.Value} (@pxref{Values From Inferior}).
376 @defun gdb.add_history (value)
377 Takes @var{value}, an instance of @code{gdb.Value} (@pxref{Values From
378 Inferior}), and appends the value this object represents to
379 @value{GDBN}'s value history (@pxref{Value History}), and return an
380 integer, its history number. If @var{value} is not a
381 @code{gdb.Value}, it is is converted using the @code{gdb.Value}
382 constructor. If @var{value} can't be converted to a @code{gdb.Value}
383 then a @code{TypeError} is raised.
385 When a command implemented in Python prints a single @code{gdb.Value}
386 as its result, then placing the value into the history will allow the
387 user convenient access to those values via CLI history facilities.
390 @defun gdb.history_count ()
391 Return an integer indicating the number of values in @value{GDBN}'s
392 value history (@pxref{Value History}).
395 @findex gdb.convenience_variable
396 @defun gdb.convenience_variable (name)
397 Return the value of the convenience variable (@pxref{Convenience
398 Vars}) named @var{name}. @var{name} must be a string. The name
399 should not include the @samp{$} that is used to mark a convenience
400 variable in an expression. If the convenience variable does not
401 exist, then @code{None} is returned.
404 @findex gdb.set_convenience_variable
405 @defun gdb.set_convenience_variable (name, value)
406 Set the value of the convenience variable (@pxref{Convenience Vars})
407 named @var{name}. @var{name} must be a string. The name should not
408 include the @samp{$} that is used to mark a convenience variable in an
409 expression. If @var{value} is @code{None}, then the convenience
410 variable is removed. Otherwise, if @var{value} is not a
411 @code{gdb.Value} (@pxref{Values From Inferior}), it is is converted
412 using the @code{gdb.Value} constructor.
415 @findex gdb.parse_and_eval
416 @defun gdb.parse_and_eval (expression)
417 Parse @var{expression}, which must be a string, as an expression in
418 the current language, evaluate it, and return the result as a
421 This function can be useful when implementing a new command
422 (@pxref{Commands In Python}), as it provides a way to parse the
423 command's argument as an expression. It is also useful simply to
427 @findex gdb.find_pc_line
428 @defun gdb.find_pc_line (pc)
429 Return the @code{gdb.Symtab_and_line} object corresponding to the
430 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
431 value of @var{pc} is passed as an argument, then the @code{symtab} and
432 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
433 will be @code{None} and 0 respectively. This is identical to
434 @code{gdb.current_progspace().find_pc_line(pc)} and is included for
435 historical compatibility.
438 @findex gdb.post_event
439 @defun gdb.post_event (event)
440 Put @var{event}, a callable object taking no arguments, into
441 @value{GDBN}'s internal event queue. This callable will be invoked at
442 some later point, during @value{GDBN}'s event processing. Events
443 posted using @code{post_event} will be run in the order in which they
444 were posted; however, there is no way to know when they will be
445 processed relative to other events inside @value{GDBN}.
447 @value{GDBN} is not thread-safe. If your Python program uses multiple
448 threads, you must be careful to only call @value{GDBN}-specific
449 functions in the @value{GDBN} thread. @code{post_event} ensures
453 (@value{GDBP}) python
457 > def __init__(self, message):
458 > self.message = message;
459 > def __call__(self):
460 > gdb.write(self.message)
462 >class MyThread1 (threading.Thread):
464 > gdb.post_event(Writer("Hello "))
466 >class MyThread2 (threading.Thread):
468 > gdb.post_event(Writer("World\n"))
473 (@value{GDBP}) Hello World
478 @defun gdb.write (string @r{[}, stream@r{]})
479 Print a string to @value{GDBN}'s paginated output stream. The
480 optional @var{stream} determines the stream to print to. The default
481 stream is @value{GDBN}'s standard output stream. Possible stream
488 @value{GDBN}'s standard output stream.
493 @value{GDBN}'s standard error stream.
498 @value{GDBN}'s log stream (@pxref{Logging Output}).
501 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
502 call this function and will automatically direct the output to the
508 Flush the buffer of a @value{GDBN} paginated stream so that the
509 contents are displayed immediately. @value{GDBN} will flush the
510 contents of a stream automatically when it encounters a newline in the
511 buffer. The optional @var{stream} determines the stream to flush. The
512 default stream is @value{GDBN}'s standard output stream. Possible
519 @value{GDBN}'s standard output stream.
524 @value{GDBN}'s standard error stream.
529 @value{GDBN}'s log stream (@pxref{Logging Output}).
533 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
534 call this function for the relevant stream.
537 @findex gdb.target_charset
538 @defun gdb.target_charset ()
539 Return the name of the current target character set (@pxref{Character
540 Sets}). This differs from @code{gdb.parameter('target-charset')} in
541 that @samp{auto} is never returned.
544 @findex gdb.target_wide_charset
545 @defun gdb.target_wide_charset ()
546 Return the name of the current target wide character set
547 (@pxref{Character Sets}). This differs from
548 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
552 @findex gdb.host_charset
553 @defun gdb.host_charset ()
554 Return a string, the name of the current host character set
555 (@pxref{Character Sets}). This differs from
556 @code{gdb.parameter('host-charset')} in that @samp{auto} is never
560 @findex gdb.solib_name
561 @defun gdb.solib_name (address)
562 Return the name of the shared library holding the given @var{address}
563 as a string, or @code{None}. This is identical to
564 @code{gdb.current_progspace().solib_name(address)} and is included for
565 historical compatibility.
568 @findex gdb.decode_line
569 @defun gdb.decode_line (@r{[}expression@r{]})
570 Return locations of the line specified by @var{expression}, or of the
571 current line if no argument was given. This function returns a Python
572 tuple containing two elements. The first element contains a string
573 holding any unparsed section of @var{expression} (or @code{None} if
574 the expression has been fully parsed). The second element contains
575 either @code{None} or another tuple that contains all the locations
576 that match the expression represented as @code{gdb.Symtab_and_line}
577 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
578 provided, it is decoded the way that @value{GDBN}'s inbuilt
579 @code{break} or @code{edit} commands do (@pxref{Specify Location}).
582 @defun gdb.prompt_hook (current_prompt)
585 If @var{prompt_hook} is callable, @value{GDBN} will call the method
586 assigned to this operation before a prompt is displayed by
589 The parameter @code{current_prompt} contains the current @value{GDBN}
590 prompt. This method must return a Python string, or @code{None}. If
591 a string is returned, the @value{GDBN} prompt will be set to that
592 string. If @code{None} is returned, @value{GDBN} will continue to use
595 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
596 such as those used by readline for command input, and annotation
597 related prompts are prohibited from being changed.
600 @defun gdb.architecture_names ()
601 Return a list containing all of the architecture names that the
602 current build of @value{GDBN} supports. Each architecture name is a
603 string. The names returned in this list are the same names as are
604 returned from @code{gdb.Architecture.name}
605 (@pxref{gdbpy_architecture_name,,Architecture.name}).
608 @anchor{gdbpy_connections}
609 @defun gdb.connections
610 Return a list of @code{gdb.TargetConnection} objects, one for each
611 currently active connection (@pxref{Connections In Python}). The
612 connection objects are in no particular order in the returned list.
615 @node Exception Handling
616 @subsubsection Exception Handling
617 @cindex python exceptions
618 @cindex exceptions, python
620 When executing the @code{python} command, Python exceptions
621 uncaught within the Python code are translated to calls to
622 @value{GDBN} error-reporting mechanism. If the command that called
623 @code{python} does not handle the error, @value{GDBN} will
624 terminate it and print an error message containing the Python
625 exception name, the associated value, and the Python call stack
626 backtrace at the point where the exception was raised. Example:
629 (@value{GDBP}) python print foo
630 Traceback (most recent call last):
631 File "<string>", line 1, in <module>
632 NameError: name 'foo' is not defined
635 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
636 Python code are converted to Python exceptions. The type of the
637 Python exception depends on the error.
641 This is the base class for most exceptions generated by @value{GDBN}.
642 It is derived from @code{RuntimeError}, for compatibility with earlier
643 versions of @value{GDBN}.
645 If an error occurring in @value{GDBN} does not fit into some more
646 specific category, then the generated exception will have this type.
648 @item gdb.MemoryError
649 This is a subclass of @code{gdb.error} which is thrown when an
650 operation tried to access invalid memory in the inferior.
652 @item KeyboardInterrupt
653 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
654 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
657 In all cases, your exception handler will see the @value{GDBN} error
658 message as its value and the Python call stack backtrace at the Python
659 statement closest to where the @value{GDBN} error occured as the
663 When implementing @value{GDBN} commands in Python via
664 @code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
665 to be able to throw an exception that doesn't cause a traceback to be
666 printed. For example, the user may have invoked the command
667 incorrectly. @value{GDBN} provides a special exception class that can
668 be used for this purpose.
672 When thrown from a command or function, this exception will cause the
673 command or function to fail, but the Python stack will not be
674 displayed. @value{GDBN} does not throw this exception itself, but
675 rather recognizes it when thrown from user Python code. Example:
679 >class HelloWorld (gdb.Command):
680 > """Greet the whole world."""
681 > def __init__ (self):
682 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
683 > def invoke (self, args, from_tty):
684 > argv = gdb.string_to_argv (args)
685 > if len (argv) != 0:
686 > raise gdb.GdbError ("hello-world takes no arguments")
687 > print ("Hello, World!")
691 hello-world takes no arguments
695 @node Values From Inferior
696 @subsubsection Values From Inferior
697 @cindex values from inferior, with Python
698 @cindex python, working with values from inferior
700 @cindex @code{gdb.Value}
701 @value{GDBN} provides values it obtains from the inferior program in
702 an object of type @code{gdb.Value}. @value{GDBN} uses this object
703 for its internal bookkeeping of the inferior's values, and for
704 fetching values when necessary.
706 Inferior values that are simple scalars can be used directly in
707 Python expressions that are valid for the value's data type. Here's
708 an example for an integer or floating-point value @code{some_val}:
715 As result of this, @code{bar} will also be a @code{gdb.Value} object
716 whose values are of the same type as those of @code{some_val}. Valid
717 Python operations can also be performed on @code{gdb.Value} objects
718 representing a @code{struct} or @code{class} object. For such cases,
719 the overloaded operator (if present), is used to perform the operation.
720 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
721 representing instances of a @code{class} which overloads the @code{+}
722 operator, then one can use the @code{+} operator in their Python script
730 The result of the operation @code{val3} is also a @code{gdb.Value}
731 object corresponding to the value returned by the overloaded @code{+}
732 operator. In general, overloaded operators are invoked for the
733 following operations: @code{+} (binary addition), @code{-} (binary
734 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
735 @code{>>}, @code{|}, @code{&}, @code{^}.
737 Inferior values that are structures or instances of some class can
738 be accessed using the Python @dfn{dictionary syntax}. For example, if
739 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
740 can access its @code{foo} element with:
743 bar = some_val['foo']
746 @cindex getting structure elements using gdb.Field objects as subscripts
747 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
748 elements can also be accessed by using @code{gdb.Field} objects as
749 subscripts (@pxref{Types In Python}, for more information on
750 @code{gdb.Field} objects). For example, if @code{foo_field} is a
751 @code{gdb.Field} object corresponding to element @code{foo} of the above
752 structure, then @code{bar} can also be accessed as follows:
755 bar = some_val[foo_field]
758 A @code{gdb.Value} that represents a function can be executed via
759 inferior function call. Any arguments provided to the call must match
760 the function's prototype, and must be provided in the order specified
763 For example, @code{some_val} is a @code{gdb.Value} instance
764 representing a function that takes two integers as arguments. To
765 execute this function, call it like so:
768 result = some_val (10,20)
771 Any values returned from a function call will be stored as a
774 The following attributes are provided:
776 @defvar Value.address
777 If this object is addressable, this read-only attribute holds a
778 @code{gdb.Value} object representing the address. Otherwise,
779 this attribute holds @code{None}.
782 @cindex optimized out value in Python
783 @defvar Value.is_optimized_out
784 This read-only boolean attribute is true if the compiler optimized out
785 this value, thus it is not available for fetching from the inferior.
789 The type of this @code{gdb.Value}. The value of this attribute is a
790 @code{gdb.Type} object (@pxref{Types In Python}).
793 @defvar Value.dynamic_type
794 The dynamic type of this @code{gdb.Value}. This uses the object's
795 virtual table and the C@t{++} run-time type information
796 (@acronym{RTTI}) to determine the dynamic type of the value. If this
797 value is of class type, it will return the class in which the value is
798 embedded, if any. If this value is of pointer or reference to a class
799 type, it will compute the dynamic type of the referenced object, and
800 return a pointer or reference to that type, respectively. In all
801 other cases, it will return the value's static type.
803 Note that this feature will only work when debugging a C@t{++} program
804 that includes @acronym{RTTI} for the object in question. Otherwise,
805 it will just return the static type of the value as in @kbd{ptype foo}
806 (@pxref{Symbols, ptype}).
809 @defvar Value.is_lazy
810 The value of this read-only boolean attribute is @code{True} if this
811 @code{gdb.Value} has not yet been fetched from the inferior.
812 @value{GDBN} does not fetch values until necessary, for efficiency.
816 myval = gdb.parse_and_eval ('somevar')
819 The value of @code{somevar} is not fetched at this time. It will be
820 fetched when the value is needed, or when the @code{fetch_lazy}
824 The following methods are provided:
826 @defun Value.__init__ (@var{val})
827 Many Python values can be converted directly to a @code{gdb.Value} via
828 this object initializer. Specifically:
832 A Python boolean is converted to the boolean type from the current
836 A Python integer is converted to the C @code{long} type for the
837 current architecture.
840 A Python long is converted to the C @code{long long} type for the
841 current architecture.
844 A Python float is converted to the C @code{double} type for the
845 current architecture.
848 A Python string is converted to a target string in the current target
849 language using the current target encoding.
850 If a character cannot be represented in the current target encoding,
851 then an exception is thrown.
853 @item @code{gdb.Value}
854 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
856 @item @code{gdb.LazyString}
857 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
858 Python}), then the lazy string's @code{value} method is called, and
863 @defun Value.__init__ (@var{val}, @var{type})
864 This second form of the @code{gdb.Value} constructor returns a
865 @code{gdb.Value} of type @var{type} where the value contents are taken
866 from the Python buffer object specified by @var{val}. The number of
867 bytes in the Python buffer object must be greater than or equal to the
870 If @var{type} is @code{None} then this version of @code{__init__}
871 behaves as though @var{type} was not passed at all.
874 @defun Value.cast (type)
875 Return a new instance of @code{gdb.Value} that is the result of
876 casting this instance to the type described by @var{type}, which must
877 be a @code{gdb.Type} object. If the cast cannot be performed for some
878 reason, this method throws an exception.
881 @defun Value.dereference ()
882 For pointer data types, this method returns a new @code{gdb.Value} object
883 whose contents is the object pointed to by the pointer. For example, if
884 @code{foo} is a C pointer to an @code{int}, declared in your C program as
891 then you can use the corresponding @code{gdb.Value} to access what
892 @code{foo} points to like this:
895 bar = foo.dereference ()
898 The result @code{bar} will be a @code{gdb.Value} object holding the
899 value pointed to by @code{foo}.
901 A similar function @code{Value.referenced_value} exists which also
902 returns @code{gdb.Value} objects corresponding to the values pointed to
903 by pointer values (and additionally, values referenced by reference
904 values). However, the behavior of @code{Value.dereference}
905 differs from @code{Value.referenced_value} by the fact that the
906 behavior of @code{Value.dereference} is identical to applying the C
907 unary operator @code{*} on a given value. For example, consider a
908 reference to a pointer @code{ptrref}, declared in your C@t{++} program
916 intptr &ptrref = ptr;
919 Though @code{ptrref} is a reference value, one can apply the method
920 @code{Value.dereference} to the @code{gdb.Value} object corresponding
921 to it and obtain a @code{gdb.Value} which is identical to that
922 corresponding to @code{val}. However, if you apply the method
923 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
924 object identical to that corresponding to @code{ptr}.
927 py_ptrref = gdb.parse_and_eval ("ptrref")
928 py_val = py_ptrref.dereference ()
929 py_ptr = py_ptrref.referenced_value ()
932 The @code{gdb.Value} object @code{py_val} is identical to that
933 corresponding to @code{val}, and @code{py_ptr} is identical to that
934 corresponding to @code{ptr}. In general, @code{Value.dereference} can
935 be applied whenever the C unary operator @code{*} can be applied
936 to the corresponding C value. For those cases where applying both
937 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
938 the results obtained need not be identical (as we have seen in the above
939 example). The results are however identical when applied on
940 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
941 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
944 @defun Value.referenced_value ()
945 For pointer or reference data types, this method returns a new
946 @code{gdb.Value} object corresponding to the value referenced by the
947 pointer/reference value. For pointer data types,
948 @code{Value.dereference} and @code{Value.referenced_value} produce
949 identical results. The difference between these methods is that
950 @code{Value.dereference} cannot get the values referenced by reference
951 values. For example, consider a reference to an @code{int}, declared
952 in your C@t{++} program as
960 then applying @code{Value.dereference} to the @code{gdb.Value} object
961 corresponding to @code{ref} will result in an error, while applying
962 @code{Value.referenced_value} will result in a @code{gdb.Value} object
963 identical to that corresponding to @code{val}.
966 py_ref = gdb.parse_and_eval ("ref")
967 er_ref = py_ref.dereference () # Results in error
968 py_val = py_ref.referenced_value () # Returns the referenced value
971 The @code{gdb.Value} object @code{py_val} is identical to that
972 corresponding to @code{val}.
975 @defun Value.reference_value ()
976 Return a @code{gdb.Value} object which is a reference to the value
977 encapsulated by this instance.
980 @defun Value.const_value ()
981 Return a @code{gdb.Value} object which is a @code{const} version of the
982 value encapsulated by this instance.
985 @defun Value.dynamic_cast (type)
986 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
987 operator were used. Consult a C@t{++} reference for details.
990 @defun Value.reinterpret_cast (type)
991 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
992 operator were used. Consult a C@t{++} reference for details.
995 @defun Value.format_string (...)
996 Convert a @code{gdb.Value} to a string, similarly to what the @code{print}
997 command does. Invoked with no arguments, this is equivalent to calling
998 the @code{str} function on the @code{gdb.Value}. The representation of
999 the same value may change across different versions of @value{GDBN}, so
1000 you shouldn't, for instance, parse the strings returned by this method.
1002 All the arguments are keyword only. If an argument is not specified, the
1003 current global default setting is used.
1007 @code{True} if pretty-printers (@pxref{Pretty Printing}) should not be
1008 used to format the value. @code{False} if enabled pretty-printers
1009 matching the type represented by the @code{gdb.Value} should be used to
1013 @code{True} if arrays should be pretty printed to be more convenient to
1014 read, @code{False} if they shouldn't (see @code{set print array} in
1015 @ref{Print Settings}).
1017 @item pretty_structs
1018 @code{True} if structs should be pretty printed to be more convenient to
1019 read, @code{False} if they shouldn't (see @code{set print pretty} in
1020 @ref{Print Settings}).
1023 @code{True} if array indexes should be included in the string
1024 representation of arrays, @code{False} if they shouldn't (see @code{set
1025 print array-indexes} in @ref{Print Settings}).
1028 @code{True} if the string representation of a pointer should include the
1029 corresponding symbol name (if one exists), @code{False} if it shouldn't
1030 (see @code{set print symbol} in @ref{Print Settings}).
1033 @code{True} if unions which are contained in other structures or unions
1034 should be expanded, @code{False} if they shouldn't (see @code{set print
1035 union} in @ref{Print Settings}).
1038 @code{True} if the string representation of a pointer should include the
1039 address, @code{False} if it shouldn't (see @code{set print address} in
1040 @ref{Print Settings}).
1043 @code{True} if C@t{++} references should be resolved to the value they
1044 refer to, @code{False} (the default) if they shouldn't. Note that, unlike
1045 for the @code{print} command, references are not automatically expanded
1046 when using the @code{format_string} method or the @code{str}
1047 function. There is no global @code{print} setting to change the default
1050 @item actual_objects
1051 @code{True} if the representation of a pointer to an object should
1052 identify the @emph{actual} (derived) type of the object rather than the
1053 @emph{declared} type, using the virtual function table. @code{False} if
1054 the @emph{declared} type should be used. (See @code{set print object} in
1055 @ref{Print Settings}).
1057 @item static_members
1058 @code{True} if static members should be included in the string
1059 representation of a C@t{++} object, @code{False} if they shouldn't (see
1060 @code{set print static-members} in @ref{Print Settings}).
1063 Number of array elements to print, or @code{0} to print an unlimited
1064 number of elements (see @code{set print elements} in @ref{Print
1068 The maximum depth to print for nested structs and unions, or @code{-1}
1069 to print an unlimited number of elements (see @code{set print
1070 max-depth} in @ref{Print Settings}).
1072 @item repeat_threshold
1073 Set the threshold for suppressing display of repeated array elements, or
1074 @code{0} to represent all elements, even if repeated. (See @code{set
1075 print repeats} in @ref{Print Settings}).
1078 A string containing a single character representing the format to use for
1079 the returned string. For instance, @code{'x'} is equivalent to using the
1080 @value{GDBN} command @code{print} with the @code{/x} option and formats
1081 the value as a hexadecimal number.
1084 @code{True} if @value{GDBN} should apply styling to the returned
1085 string. When styling is applied, the returned string might contain
1086 ANSI terminal escape sequences. Escape sequences will only be
1087 included if styling is turned on, see @ref{Output Styling}.
1088 Additionally, @value{GDBN} only styles some value contents, so not
1089 every output string will contain escape sequences.
1091 When @code{False}, which is the default, no output styling is applied.
1095 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
1096 If this @code{gdb.Value} represents a string, then this method
1097 converts the contents to a Python string. Otherwise, this method will
1100 Values are interpreted as strings according to the rules of the
1101 current language. If the optional length argument is given, the
1102 string will be converted to that length, and will include any embedded
1103 zeroes that the string may contain. Otherwise, for languages
1104 where the string is zero-terminated, the entire string will be
1107 For example, in C-like languages, a value is a string if it is a pointer
1108 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
1111 If the optional @var{encoding} argument is given, it must be a string
1112 naming the encoding of the string in the @code{gdb.Value}, such as
1113 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
1114 the same encodings as the corresponding argument to Python's
1115 @code{string.decode} method, and the Python codec machinery will be used
1116 to convert the string. If @var{encoding} is not given, or if
1117 @var{encoding} is the empty string, then either the @code{target-charset}
1118 (@pxref{Character Sets}) will be used, or a language-specific encoding
1119 will be used, if the current language is able to supply one.
1121 The optional @var{errors} argument is the same as the corresponding
1122 argument to Python's @code{string.decode} method.
1124 If the optional @var{length} argument is given, the string will be
1125 fetched and converted to the given length.
1128 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
1129 If this @code{gdb.Value} represents a string, then this method
1130 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
1131 In Python}). Otherwise, this method will throw an exception.
1133 If the optional @var{encoding} argument is given, it must be a string
1134 naming the encoding of the @code{gdb.LazyString}. Some examples are:
1135 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
1136 @var{encoding} argument is an encoding that @value{GDBN} does
1137 recognize, @value{GDBN} will raise an error.
1139 When a lazy string is printed, the @value{GDBN} encoding machinery is
1140 used to convert the string during printing. If the optional
1141 @var{encoding} argument is not provided, or is an empty string,
1142 @value{GDBN} will automatically select the encoding most suitable for
1143 the string type. For further information on encoding in @value{GDBN}
1144 please see @ref{Character Sets}.
1146 If the optional @var{length} argument is given, the string will be
1147 fetched and encoded to the length of characters specified. If
1148 the @var{length} argument is not provided, the string will be fetched
1149 and encoded until a null of appropriate width is found.
1152 @defun Value.fetch_lazy ()
1153 If the @code{gdb.Value} object is currently a lazy value
1154 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
1155 fetched from the inferior. Any errors that occur in the process
1156 will produce a Python exception.
1158 If the @code{gdb.Value} object is not a lazy value, this method
1161 This method does not return a value.
1165 @node Types In Python
1166 @subsubsection Types In Python
1167 @cindex types in Python
1168 @cindex Python, working with types
1171 @value{GDBN} represents types from the inferior using the class
1174 The following type-related functions are available in the @code{gdb}
1177 @findex gdb.lookup_type
1178 @defun gdb.lookup_type (name @r{[}, block@r{]})
1179 This function looks up a type by its @var{name}, which must be a string.
1181 If @var{block} is given, then @var{name} is looked up in that scope.
1182 Otherwise, it is searched for globally.
1184 Ordinarily, this function will return an instance of @code{gdb.Type}.
1185 If the named type cannot be found, it will throw an exception.
1188 Integer types can be found without looking them up by name.
1189 @xref{Architectures In Python}, for the @code{integer_type} method.
1191 If the type is a structure or class type, or an enum type, the fields
1192 of that type can be accessed using the Python @dfn{dictionary syntax}.
1193 For example, if @code{some_type} is a @code{gdb.Type} instance holding
1194 a structure type, you can access its @code{foo} field with:
1197 bar = some_type['foo']
1200 @code{bar} will be a @code{gdb.Field} object; see below under the
1201 description of the @code{Type.fields} method for a description of the
1202 @code{gdb.Field} class.
1204 An instance of @code{Type} has the following attributes:
1206 @defvar Type.alignof
1207 The alignment of this type, in bytes. Type alignment comes from the
1208 debugging information; if it was not specified, then @value{GDBN} will
1209 use the relevant ABI to try to determine the alignment. In some
1210 cases, even this is not possible, and zero will be returned.
1214 The type code for this type. The type code will be one of the
1215 @code{TYPE_CODE_} constants defined below.
1218 @defvar Type.dynamic
1219 A boolean indicating whether this type is dynamic. In some
1220 situations, such as Rust @code{enum} types or Ada variant records, the
1221 concrete type of a value may vary depending on its contents. That is,
1222 the declared type of a variable, or the type returned by
1223 @code{gdb.lookup_type} may be dynamic; while the type of the
1224 variable's value will be a concrete instance of that dynamic type.
1226 For example, consider this code:
1232 Here, at least conceptually (whether your compiler actually does this
1233 is a separate issue), examining @w{@code{gdb.lookup_symbol("array", ...).type}}
1234 could yield a @code{gdb.Type} which reports a size of @code{None}.
1235 This is the dynamic type.
1237 However, examining @code{gdb.parse_and_eval("array").type} would yield
1238 a concrete type, whose length would be known.
1242 The name of this type. If this type has no name, then @code{None}
1247 The size of this type, in target @code{char} units. Usually, a
1248 target's @code{char} type will be an 8-bit byte. However, on some
1249 unusual platforms, this type may have a different size. A dynamic
1250 type may not have a fixed size; in this case, this attribute's value
1251 will be @code{None}.
1255 The tag name for this type. The tag name is the name after
1256 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1257 languages have this concept. If this type has no tag name, then
1258 @code{None} is returned.
1261 @defvar Type.objfile
1262 The @code{gdb.Objfile} that this type was defined in, or @code{None} if
1263 there is no associated objfile.
1266 @defvar Type.is_scalar
1267 This property is @code{True} if the type is a scalar type, otherwise,
1268 this property is @code{False}. Examples of non-scalar types include
1269 structures, unions, and classes.
1272 The following methods are provided:
1274 @defun Type.fields ()
1276 Return the fields of this type. The behavior depends on the type code:
1281 For structure and union types, this method returns the fields.
1284 Range types have two fields, the minimum and maximum values.
1287 Enum types have one field per enum constant.
1290 Function and method types have one field per parameter. The base types of
1291 C@t{++} classes are also represented as fields.
1294 Array types have one field representing the array's range.
1297 If the type does not fit into one of these categories, a @code{TypeError}
1302 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
1305 This attribute is not available for @code{enum} or @code{static}
1306 (as in C@t{++}) fields. The value is the position, counting
1307 in bits, from the start of the containing type. Note that, in a
1308 dynamic type, the position of a field may not be constant. In this
1309 case, the value will be @code{None}. Also, a dynamic type may have
1310 fields that do not appear in a corresponding concrete type.
1313 This attribute is only available for @code{enum} fields, and its value
1314 is the enumeration member's integer representation.
1317 The name of the field, or @code{None} for anonymous fields.
1320 This is @code{True} if the field is artificial, usually meaning that
1321 it was provided by the compiler and not the user. This attribute is
1322 always provided, and is @code{False} if the field is not artificial.
1325 This is @code{True} if the field represents a base class of a C@t{++}
1326 structure. This attribute is always provided, and is @code{False}
1327 if the field is not a base class of the type that is the argument of
1328 @code{fields}, or if that type was not a C@t{++} class.
1331 If the field is packed, or is a bitfield, then this will have a
1332 non-zero value, which is the size of the field in bits. Otherwise,
1333 this will be zero; in this case the field's size is given by its type.
1336 The type of the field. This is usually an instance of @code{Type},
1337 but it can be @code{None} in some situations.
1340 The type which contains this field. This is an instance of
1345 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
1346 Return a new @code{gdb.Type} object which represents an array of this
1347 type. If one argument is given, it is the inclusive upper bound of
1348 the array; in this case the lower bound is zero. If two arguments are
1349 given, the first argument is the lower bound of the array, and the
1350 second argument is the upper bound of the array. An array's length
1351 must not be negative, but the bounds can be.
1354 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
1355 Return a new @code{gdb.Type} object which represents a vector of this
1356 type. If one argument is given, it is the inclusive upper bound of
1357 the vector; in this case the lower bound is zero. If two arguments are
1358 given, the first argument is the lower bound of the vector, and the
1359 second argument is the upper bound of the vector. A vector's length
1360 must not be negative, but the bounds can be.
1362 The difference between an @code{array} and a @code{vector} is that
1363 arrays behave like in C: when used in expressions they decay to a pointer
1364 to the first element whereas vectors are treated as first class values.
1367 @defun Type.const ()
1368 Return a new @code{gdb.Type} object which represents a
1369 @code{const}-qualified variant of this type.
1372 @defun Type.volatile ()
1373 Return a new @code{gdb.Type} object which represents a
1374 @code{volatile}-qualified variant of this type.
1377 @defun Type.unqualified ()
1378 Return a new @code{gdb.Type} object which represents an unqualified
1379 variant of this type. That is, the result is neither @code{const} nor
1383 @defun Type.range ()
1384 Return a Python @code{Tuple} object that contains two elements: the
1385 low bound of the argument type and the high bound of that type. If
1386 the type does not have a range, @value{GDBN} will raise a
1387 @code{gdb.error} exception (@pxref{Exception Handling}).
1390 @defun Type.reference ()
1391 Return a new @code{gdb.Type} object which represents a reference to this
1395 @defun Type.pointer ()
1396 Return a new @code{gdb.Type} object which represents a pointer to this
1400 @defun Type.strip_typedefs ()
1401 Return a new @code{gdb.Type} that represents the real type,
1402 after removing all layers of typedefs.
1405 @defun Type.target ()
1406 Return a new @code{gdb.Type} object which represents the target type
1409 For a pointer type, the target type is the type of the pointed-to
1410 object. For an array type (meaning C-like arrays), the target type is
1411 the type of the elements of the array. For a function or method type,
1412 the target type is the type of the return value. For a complex type,
1413 the target type is the type of the elements. For a typedef, the
1414 target type is the aliased type.
1416 If the type does not have a target, this method will throw an
1420 @defun Type.template_argument (n @r{[}, block@r{]})
1421 If this @code{gdb.Type} is an instantiation of a template, this will
1422 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1423 value of the @var{n}th template argument (indexed starting at 0).
1425 If this @code{gdb.Type} is not a template type, or if the type has fewer
1426 than @var{n} template arguments, this will throw an exception.
1427 Ordinarily, only C@t{++} code will have template types.
1429 If @var{block} is given, then @var{name} is looked up in that scope.
1430 Otherwise, it is searched for globally.
1433 @defun Type.optimized_out ()
1434 Return @code{gdb.Value} instance of this type whose value is optimized
1435 out. This allows a frame decorator to indicate that the value of an
1436 argument or a local variable is not known.
1439 Each type has a code, which indicates what category this type falls
1440 into. The available type categories are represented by constants
1441 defined in the @code{gdb} module:
1444 @vindex TYPE_CODE_PTR
1445 @item gdb.TYPE_CODE_PTR
1446 The type is a pointer.
1448 @vindex TYPE_CODE_ARRAY
1449 @item gdb.TYPE_CODE_ARRAY
1450 The type is an array.
1452 @vindex TYPE_CODE_STRUCT
1453 @item gdb.TYPE_CODE_STRUCT
1454 The type is a structure.
1456 @vindex TYPE_CODE_UNION
1457 @item gdb.TYPE_CODE_UNION
1458 The type is a union.
1460 @vindex TYPE_CODE_ENUM
1461 @item gdb.TYPE_CODE_ENUM
1462 The type is an enum.
1464 @vindex TYPE_CODE_FLAGS
1465 @item gdb.TYPE_CODE_FLAGS
1466 A bit flags type, used for things such as status registers.
1468 @vindex TYPE_CODE_FUNC
1469 @item gdb.TYPE_CODE_FUNC
1470 The type is a function.
1472 @vindex TYPE_CODE_INT
1473 @item gdb.TYPE_CODE_INT
1474 The type is an integer type.
1476 @vindex TYPE_CODE_FLT
1477 @item gdb.TYPE_CODE_FLT
1478 A floating point type.
1480 @vindex TYPE_CODE_VOID
1481 @item gdb.TYPE_CODE_VOID
1482 The special type @code{void}.
1484 @vindex TYPE_CODE_SET
1485 @item gdb.TYPE_CODE_SET
1488 @vindex TYPE_CODE_RANGE
1489 @item gdb.TYPE_CODE_RANGE
1490 A range type, that is, an integer type with bounds.
1492 @vindex TYPE_CODE_STRING
1493 @item gdb.TYPE_CODE_STRING
1494 A string type. Note that this is only used for certain languages with
1495 language-defined string types; C strings are not represented this way.
1497 @vindex TYPE_CODE_BITSTRING
1498 @item gdb.TYPE_CODE_BITSTRING
1499 A string of bits. It is deprecated.
1501 @vindex TYPE_CODE_ERROR
1502 @item gdb.TYPE_CODE_ERROR
1503 An unknown or erroneous type.
1505 @vindex TYPE_CODE_METHOD
1506 @item gdb.TYPE_CODE_METHOD
1507 A method type, as found in C@t{++}.
1509 @vindex TYPE_CODE_METHODPTR
1510 @item gdb.TYPE_CODE_METHODPTR
1511 A pointer-to-member-function.
1513 @vindex TYPE_CODE_MEMBERPTR
1514 @item gdb.TYPE_CODE_MEMBERPTR
1515 A pointer-to-member.
1517 @vindex TYPE_CODE_REF
1518 @item gdb.TYPE_CODE_REF
1521 @vindex TYPE_CODE_RVALUE_REF
1522 @item gdb.TYPE_CODE_RVALUE_REF
1523 A C@t{++}11 rvalue reference type.
1525 @vindex TYPE_CODE_CHAR
1526 @item gdb.TYPE_CODE_CHAR
1529 @vindex TYPE_CODE_BOOL
1530 @item gdb.TYPE_CODE_BOOL
1533 @vindex TYPE_CODE_COMPLEX
1534 @item gdb.TYPE_CODE_COMPLEX
1535 A complex float type.
1537 @vindex TYPE_CODE_TYPEDEF
1538 @item gdb.TYPE_CODE_TYPEDEF
1539 A typedef to some other type.
1541 @vindex TYPE_CODE_NAMESPACE
1542 @item gdb.TYPE_CODE_NAMESPACE
1543 A C@t{++} namespace.
1545 @vindex TYPE_CODE_DECFLOAT
1546 @item gdb.TYPE_CODE_DECFLOAT
1547 A decimal floating point type.
1549 @vindex TYPE_CODE_INTERNAL_FUNCTION
1550 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1551 A function internal to @value{GDBN}. This is the type used to represent
1552 convenience functions.
1555 Further support for types is provided in the @code{gdb.types}
1556 Python module (@pxref{gdb.types}).
1558 @node Pretty Printing API
1559 @subsubsection Pretty Printing API
1560 @cindex python pretty printing api
1562 A pretty-printer is just an object that holds a value and implements a
1563 specific interface, defined here. An example output is provided
1564 (@pxref{Pretty Printing}).
1566 @defun pretty_printer.children (self)
1567 @value{GDBN} will call this method on a pretty-printer to compute the
1568 children of the pretty-printer's value.
1570 This method must return an object conforming to the Python iterator
1571 protocol. Each item returned by the iterator must be a tuple holding
1572 two elements. The first element is the ``name'' of the child; the
1573 second element is the child's value. The value can be any Python
1574 object which is convertible to a @value{GDBN} value.
1576 This method is optional. If it does not exist, @value{GDBN} will act
1577 as though the value has no children.
1579 For efficiency, the @code{children} method should lazily compute its
1580 results. This will let @value{GDBN} read as few elements as
1581 necessary, for example when various print settings (@pxref{Print
1582 Settings}) or @code{-var-list-children} (@pxref{GDB/MI Variable
1583 Objects}) limit the number of elements to be displayed.
1585 Children may be hidden from display based on the value of @samp{set
1586 print max-depth} (@pxref{Print Settings}).
1589 @defun pretty_printer.display_hint (self)
1590 The CLI may call this method and use its result to change the
1591 formatting of a value. The result will also be supplied to an MI
1592 consumer as a @samp{displayhint} attribute of the variable being
1595 This method is optional. If it does exist, this method must return a
1596 string or the special value @code{None}.
1598 Some display hints are predefined by @value{GDBN}:
1602 Indicate that the object being printed is ``array-like''. The CLI
1603 uses this to respect parameters such as @code{set print elements} and
1604 @code{set print array}.
1607 Indicate that the object being printed is ``map-like'', and that the
1608 children of this value can be assumed to alternate between keys and
1612 Indicate that the object being printed is ``string-like''. If the
1613 printer's @code{to_string} method returns a Python string of some
1614 kind, then @value{GDBN} will call its internal language-specific
1615 string-printing function to format the string. For the CLI this means
1616 adding quotation marks, possibly escaping some characters, respecting
1617 @code{set print elements}, and the like.
1620 The special value @code{None} causes @value{GDBN} to apply the default
1624 @defun pretty_printer.to_string (self)
1625 @value{GDBN} will call this method to display the string
1626 representation of the value passed to the object's constructor.
1628 When printing from the CLI, if the @code{to_string} method exists,
1629 then @value{GDBN} will prepend its result to the values returned by
1630 @code{children}. Exactly how this formatting is done is dependent on
1631 the display hint, and may change as more hints are added. Also,
1632 depending on the print settings (@pxref{Print Settings}), the CLI may
1633 print just the result of @code{to_string} in a stack trace, omitting
1634 the result of @code{children}.
1636 If this method returns a string, it is printed verbatim.
1638 Otherwise, if this method returns an instance of @code{gdb.Value},
1639 then @value{GDBN} prints this value. This may result in a call to
1640 another pretty-printer.
1642 If instead the method returns a Python value which is convertible to a
1643 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1644 the resulting value. Again, this may result in a call to another
1645 pretty-printer. Python scalars (integers, floats, and booleans) and
1646 strings are convertible to @code{gdb.Value}; other types are not.
1648 Finally, if this method returns @code{None} then no further operations
1649 are peformed in this method and nothing is printed.
1651 If the result is not one of these types, an exception is raised.
1654 @value{GDBN} provides a function which can be used to look up the
1655 default pretty-printer for a @code{gdb.Value}:
1657 @findex gdb.default_visualizer
1658 @defun gdb.default_visualizer (value)
1659 This function takes a @code{gdb.Value} object as an argument. If a
1660 pretty-printer for this value exists, then it is returned. If no such
1661 printer exists, then this returns @code{None}.
1664 @node Selecting Pretty-Printers
1665 @subsubsection Selecting Pretty-Printers
1666 @cindex selecting python pretty-printers
1668 @value{GDBN} provides several ways to register a pretty-printer:
1669 globally, per program space, and per objfile. When choosing how to
1670 register your pretty-printer, a good rule is to register it with the
1671 smallest scope possible: that is prefer a specific objfile first, then
1672 a program space, and only register a printer globally as a last
1675 @findex gdb.pretty_printers
1676 @defvar gdb.pretty_printers
1677 The Python list @code{gdb.pretty_printers} contains an array of
1678 functions or callable objects that have been registered via addition
1679 as a pretty-printer. Printers in this list are called @code{global}
1680 printers, they're available when debugging all inferiors.
1683 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1684 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1687 Each function on these lists is passed a single @code{gdb.Value}
1688 argument and should return a pretty-printer object conforming to the
1689 interface definition above (@pxref{Pretty Printing API}). If a function
1690 cannot create a pretty-printer for the value, it should return
1693 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1694 @code{gdb.Objfile} in the current program space and iteratively calls
1695 each enabled lookup routine in the list for that @code{gdb.Objfile}
1696 until it receives a pretty-printer object.
1697 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1698 searches the pretty-printer list of the current program space,
1699 calling each enabled function until an object is returned.
1700 After these lists have been exhausted, it tries the global
1701 @code{gdb.pretty_printers} list, again calling each enabled function until an
1704 The order in which the objfiles are searched is not specified. For a
1705 given list, functions are always invoked from the head of the list,
1706 and iterated over sequentially until the end of the list, or a printer
1709 For various reasons a pretty-printer may not work.
1710 For example, the underlying data structure may have changed and
1711 the pretty-printer is out of date.
1713 The consequences of a broken pretty-printer are severe enough that
1714 @value{GDBN} provides support for enabling and disabling individual
1715 printers. For example, if @code{print frame-arguments} is on,
1716 a backtrace can become highly illegible if any argument is printed
1717 with a broken printer.
1719 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1720 attribute to the registered function or callable object. If this attribute
1721 is present and its value is @code{False}, the printer is disabled, otherwise
1722 the printer is enabled.
1724 @node Writing a Pretty-Printer
1725 @subsubsection Writing a Pretty-Printer
1726 @cindex writing a pretty-printer
1728 A pretty-printer consists of two parts: a lookup function to detect
1729 if the type is supported, and the printer itself.
1731 Here is an example showing how a @code{std::string} printer might be
1732 written. @xref{Pretty Printing API}, for details on the API this class
1736 class StdStringPrinter(object):
1737 "Print a std::string"
1739 def __init__(self, val):
1742 def to_string(self):
1743 return self.val['_M_dataplus']['_M_p']
1745 def display_hint(self):
1749 And here is an example showing how a lookup function for the printer
1750 example above might be written.
1753 def str_lookup_function(val):
1754 lookup_tag = val.type.tag
1755 if lookup_tag is None:
1757 regex = re.compile("^std::basic_string<char,.*>$")
1758 if regex.match(lookup_tag):
1759 return StdStringPrinter(val)
1763 The example lookup function extracts the value's type, and attempts to
1764 match it to a type that it can pretty-print. If it is a type the
1765 printer can pretty-print, it will return a printer object. If not, it
1766 returns @code{None}.
1768 We recommend that you put your core pretty-printers into a Python
1769 package. If your pretty-printers are for use with a library, we
1770 further recommend embedding a version number into the package name.
1771 This practice will enable @value{GDBN} to load multiple versions of
1772 your pretty-printers at the same time, because they will have
1775 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1776 can be evaluated multiple times without changing its meaning. An
1777 ideal auto-load file will consist solely of @code{import}s of your
1778 printer modules, followed by a call to a register pretty-printers with
1779 the current objfile.
1781 Taken as a whole, this approach will scale nicely to multiple
1782 inferiors, each potentially using a different library version.
1783 Embedding a version number in the Python package name will ensure that
1784 @value{GDBN} is able to load both sets of printers simultaneously.
1785 Then, because the search for pretty-printers is done by objfile, and
1786 because your auto-loaded code took care to register your library's
1787 printers with a specific objfile, @value{GDBN} will find the correct
1788 printers for the specific version of the library used by each
1791 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1792 this code might appear in @code{gdb.libstdcxx.v6}:
1795 def register_printers(objfile):
1796 objfile.pretty_printers.append(str_lookup_function)
1800 And then the corresponding contents of the auto-load file would be:
1803 import gdb.libstdcxx.v6
1804 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1807 The previous example illustrates a basic pretty-printer.
1808 There are a few things that can be improved on.
1809 The printer doesn't have a name, making it hard to identify in a
1810 list of installed printers. The lookup function has a name, but
1811 lookup functions can have arbitrary, even identical, names.
1813 Second, the printer only handles one type, whereas a library typically has
1814 several types. One could install a lookup function for each desired type
1815 in the library, but one could also have a single lookup function recognize
1816 several types. The latter is the conventional way this is handled.
1817 If a pretty-printer can handle multiple data types, then its
1818 @dfn{subprinters} are the printers for the individual data types.
1820 The @code{gdb.printing} module provides a formal way of solving these
1821 problems (@pxref{gdb.printing}).
1822 Here is another example that handles multiple types.
1824 These are the types we are going to pretty-print:
1827 struct foo @{ int a, b; @};
1828 struct bar @{ struct foo x, y; @};
1831 Here are the printers:
1835 """Print a foo object."""
1837 def __init__(self, val):
1840 def to_string(self):
1841 return ("a=<" + str(self.val["a"]) +
1842 "> b=<" + str(self.val["b"]) + ">")
1845 """Print a bar object."""
1847 def __init__(self, val):
1850 def to_string(self):
1851 return ("x=<" + str(self.val["x"]) +
1852 "> y=<" + str(self.val["y"]) + ">")
1855 This example doesn't need a lookup function, that is handled by the
1856 @code{gdb.printing} module. Instead a function is provided to build up
1857 the object that handles the lookup.
1862 def build_pretty_printer():
1863 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1865 pp.add_printer('foo', '^foo$', fooPrinter)
1866 pp.add_printer('bar', '^bar$', barPrinter)
1870 And here is the autoload support:
1875 gdb.printing.register_pretty_printer(
1876 gdb.current_objfile(),
1877 my_library.build_pretty_printer())
1880 Finally, when this printer is loaded into @value{GDBN}, here is the
1881 corresponding output of @samp{info pretty-printer}:
1884 (gdb) info pretty-printer
1891 @node Type Printing API
1892 @subsubsection Type Printing API
1893 @cindex type printing API for Python
1895 @value{GDBN} provides a way for Python code to customize type display.
1896 This is mainly useful for substituting canonical typedef names for
1899 @cindex type printer
1900 A @dfn{type printer} is just a Python object conforming to a certain
1901 protocol. A simple base class implementing the protocol is provided;
1902 see @ref{gdb.types}. A type printer must supply at least:
1904 @defivar type_printer enabled
1905 A boolean which is True if the printer is enabled, and False
1906 otherwise. This is manipulated by the @code{enable type-printer}
1907 and @code{disable type-printer} commands.
1910 @defivar type_printer name
1911 The name of the type printer. This must be a string. This is used by
1912 the @code{enable type-printer} and @code{disable type-printer}
1916 @defmethod type_printer instantiate (self)
1917 This is called by @value{GDBN} at the start of type-printing. It is
1918 only called if the type printer is enabled. This method must return a
1919 new object that supplies a @code{recognize} method, as described below.
1923 When displaying a type, say via the @code{ptype} command, @value{GDBN}
1924 will compute a list of type recognizers. This is done by iterating
1925 first over the per-objfile type printers (@pxref{Objfiles In Python}),
1926 followed by the per-progspace type printers (@pxref{Progspaces In
1927 Python}), and finally the global type printers.
1929 @value{GDBN} will call the @code{instantiate} method of each enabled
1930 type printer. If this method returns @code{None}, then the result is
1931 ignored; otherwise, it is appended to the list of recognizers.
1933 Then, when @value{GDBN} is going to display a type name, it iterates
1934 over the list of recognizers. For each one, it calls the recognition
1935 function, stopping if the function returns a non-@code{None} value.
1936 The recognition function is defined as:
1938 @defmethod type_recognizer recognize (self, type)
1939 If @var{type} is not recognized, return @code{None}. Otherwise,
1940 return a string which is to be printed as the name of @var{type}.
1941 The @var{type} argument will be an instance of @code{gdb.Type}
1942 (@pxref{Types In Python}).
1945 @value{GDBN} uses this two-pass approach so that type printers can
1946 efficiently cache information without holding on to it too long. For
1947 example, it can be convenient to look up type information in a type
1948 printer and hold it for a recognizer's lifetime; if a single pass were
1949 done then type printers would have to make use of the event system in
1950 order to avoid holding information that could become stale as the
1953 @node Frame Filter API
1954 @subsubsection Filtering Frames
1955 @cindex frame filters api
1957 Frame filters are Python objects that manipulate the visibility of a
1958 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
1961 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
1962 commands (@pxref{GDB/MI}), those that return a collection of frames
1963 are affected. The commands that work with frame filters are:
1965 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
1966 @code{-stack-list-frames}
1967 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
1968 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
1969 -stack-list-variables command}), @code{-stack-list-arguments}
1970 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
1971 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
1972 -stack-list-locals command}).
1974 A frame filter works by taking an iterator as an argument, applying
1975 actions to the contents of that iterator, and returning another
1976 iterator (or, possibly, the same iterator it was provided in the case
1977 where the filter does not perform any operations). Typically, frame
1978 filters utilize tools such as the Python's @code{itertools} module to
1979 work with and create new iterators from the source iterator.
1980 Regardless of how a filter chooses to apply actions, it must not alter
1981 the underlying @value{GDBN} frame or frames, or attempt to alter the
1982 call-stack within @value{GDBN}. This preserves data integrity within
1983 @value{GDBN}. Frame filters are executed on a priority basis and care
1984 should be taken that some frame filters may have been executed before,
1985 and that some frame filters will be executed after.
1987 An important consideration when designing frame filters, and well
1988 worth reflecting upon, is that frame filters should avoid unwinding
1989 the call stack if possible. Some stacks can run very deep, into the
1990 tens of thousands in some cases. To search every frame when a frame
1991 filter executes may be too expensive at that step. The frame filter
1992 cannot know how many frames it has to iterate over, and it may have to
1993 iterate through them all. This ends up duplicating effort as
1994 @value{GDBN} performs this iteration when it prints the frames. If
1995 the filter can defer unwinding frames until frame decorators are
1996 executed, after the last filter has executed, it should. @xref{Frame
1997 Decorator API}, for more information on decorators. Also, there are
1998 examples for both frame decorators and filters in later chapters.
1999 @xref{Writing a Frame Filter}, for more information.
2001 The Python dictionary @code{gdb.frame_filters} contains key/object
2002 pairings that comprise a frame filter. Frame filters in this
2003 dictionary are called @code{global} frame filters, and they are
2004 available when debugging all inferiors. These frame filters must
2005 register with the dictionary directly. In addition to the
2006 @code{global} dictionary, there are other dictionaries that are loaded
2007 with different inferiors via auto-loading (@pxref{Python
2008 Auto-loading}). The two other areas where frame filter dictionaries
2009 can be found are: @code{gdb.Progspace} which contains a
2010 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
2011 object which also contains a @code{frame_filters} dictionary
2014 When a command is executed from @value{GDBN} that is compatible with
2015 frame filters, @value{GDBN} combines the @code{global},
2016 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
2017 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
2018 several frames, and thus several object files, might be in use.
2019 @value{GDBN} then prunes any frame filter whose @code{enabled}
2020 attribute is @code{False}. This pruned list is then sorted according
2021 to the @code{priority} attribute in each filter.
2023 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
2024 creates an iterator which wraps each frame in the call stack in a
2025 @code{FrameDecorator} object, and calls each filter in order. The
2026 output from the previous filter will always be the input to the next
2029 Frame filters have a mandatory interface which each frame filter must
2030 implement, defined here:
2032 @defun FrameFilter.filter (iterator)
2033 @value{GDBN} will call this method on a frame filter when it has
2034 reached the order in the priority list for that filter.
2036 For example, if there are four frame filters:
2047 The order that the frame filters will be called is:
2050 Filter3 -> Filter2 -> Filter1 -> Filter4
2053 Note that the output from @code{Filter3} is passed to the input of
2054 @code{Filter2}, and so on.
2056 This @code{filter} method is passed a Python iterator. This iterator
2057 contains a sequence of frame decorators that wrap each
2058 @code{gdb.Frame}, or a frame decorator that wraps another frame
2059 decorator. The first filter that is executed in the sequence of frame
2060 filters will receive an iterator entirely comprised of default
2061 @code{FrameDecorator} objects. However, after each frame filter is
2062 executed, the previous frame filter may have wrapped some or all of
2063 the frame decorators with their own frame decorator. As frame
2064 decorators must also conform to a mandatory interface, these
2065 decorators can be assumed to act in a uniform manner (@pxref{Frame
2068 This method must return an object conforming to the Python iterator
2069 protocol. Each item in the iterator must be an object conforming to
2070 the frame decorator interface. If a frame filter does not wish to
2071 perform any operations on this iterator, it should return that
2074 This method is not optional. If it does not exist, @value{GDBN} will
2075 raise and print an error.
2078 @defvar FrameFilter.name
2079 The @code{name} attribute must be Python string which contains the
2080 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
2081 Management}). This attribute may contain any combination of letters
2082 or numbers. Care should be taken to ensure that it is unique. This
2083 attribute is mandatory.
2086 @defvar FrameFilter.enabled
2087 The @code{enabled} attribute must be Python boolean. This attribute
2088 indicates to @value{GDBN} whether the frame filter is enabled, and
2089 should be considered when frame filters are executed. If
2090 @code{enabled} is @code{True}, then the frame filter will be executed
2091 when any of the backtrace commands detailed earlier in this chapter
2092 are executed. If @code{enabled} is @code{False}, then the frame
2093 filter will not be executed. This attribute is mandatory.
2096 @defvar FrameFilter.priority
2097 The @code{priority} attribute must be Python integer. This attribute
2098 controls the order of execution in relation to other frame filters.
2099 There are no imposed limits on the range of @code{priority} other than
2100 it must be a valid integer. The higher the @code{priority} attribute,
2101 the sooner the frame filter will be executed in relation to other
2102 frame filters. Although @code{priority} can be negative, it is
2103 recommended practice to assume zero is the lowest priority that a
2104 frame filter can be assigned. Frame filters that have the same
2105 priority are executed in unsorted order in that priority slot. This
2106 attribute is mandatory. 100 is a good default priority.
2109 @node Frame Decorator API
2110 @subsubsection Decorating Frames
2111 @cindex frame decorator api
2113 Frame decorators are sister objects to frame filters (@pxref{Frame
2114 Filter API}). Frame decorators are applied by a frame filter and can
2115 only be used in conjunction with frame filters.
2117 The purpose of a frame decorator is to customize the printed content
2118 of each @code{gdb.Frame} in commands where frame filters are executed.
2119 This concept is called decorating a frame. Frame decorators decorate
2120 a @code{gdb.Frame} with Python code contained within each API call.
2121 This separates the actual data contained in a @code{gdb.Frame} from
2122 the decorated data produced by a frame decorator. This abstraction is
2123 necessary to maintain integrity of the data contained in each
2126 Frame decorators have a mandatory interface, defined below.
2128 @value{GDBN} already contains a frame decorator called
2129 @code{FrameDecorator}. This contains substantial amounts of
2130 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
2131 recommended that other frame decorators inherit and extend this
2132 object, and only to override the methods needed.
2134 @tindex gdb.FrameDecorator
2135 @code{FrameDecorator} is defined in the Python module
2136 @code{gdb.FrameDecorator}, so your code can import it like:
2138 from gdb.FrameDecorator import FrameDecorator
2141 @defun FrameDecorator.elided (self)
2143 The @code{elided} method groups frames together in a hierarchical
2144 system. An example would be an interpreter, where multiple low-level
2145 frames make up a single call in the interpreted language. In this
2146 example, the frame filter would elide the low-level frames and present
2147 a single high-level frame, representing the call in the interpreted
2148 language, to the user.
2150 The @code{elided} function must return an iterable and this iterable
2151 must contain the frames that are being elided wrapped in a suitable
2152 frame decorator. If no frames are being elided this function may
2153 return an empty iterable, or @code{None}. Elided frames are indented
2154 from normal frames in a @code{CLI} backtrace, or in the case of
2155 @code{GDB/MI}, are placed in the @code{children} field of the eliding
2158 It is the frame filter's task to also filter out the elided frames from
2159 the source iterator. This will avoid printing the frame twice.
2162 @defun FrameDecorator.function (self)
2164 This method returns the name of the function in the frame that is to
2167 This method must return a Python string describing the function, or
2170 If this function returns @code{None}, @value{GDBN} will not print any
2171 data for this field.
2174 @defun FrameDecorator.address (self)
2176 This method returns the address of the frame that is to be printed.
2178 This method must return a Python numeric integer type of sufficient
2179 size to describe the address of the frame, or @code{None}.
2181 If this function returns a @code{None}, @value{GDBN} will not print
2182 any data for this field.
2185 @defun FrameDecorator.filename (self)
2187 This method returns the filename and path associated with this frame.
2189 This method must return a Python string containing the filename and
2190 the path to the object file backing the frame, or @code{None}.
2192 If this function returns a @code{None}, @value{GDBN} will not print
2193 any data for this field.
2196 @defun FrameDecorator.line (self):
2198 This method returns the line number associated with the current
2199 position within the function addressed by this frame.
2201 This method must return a Python integer type, or @code{None}.
2203 If this function returns a @code{None}, @value{GDBN} will not print
2204 any data for this field.
2207 @defun FrameDecorator.frame_args (self)
2210 This method must return an iterable, or @code{None}. Returning an
2211 empty iterable, or @code{None} means frame arguments will not be
2212 printed for this frame. This iterable must contain objects that
2213 implement two methods, described here.
2215 This object must implement a @code{symbol} method which takes a
2216 single @code{self} parameter and must return a @code{gdb.Symbol}
2217 (@pxref{Symbols In Python}), or a Python string. The object must also
2218 implement a @code{value} method which takes a single @code{self}
2219 parameter and must return a @code{gdb.Value} (@pxref{Values From
2220 Inferior}), a Python value, or @code{None}. If the @code{value}
2221 method returns @code{None}, and the @code{argument} method returns a
2222 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
2223 the @code{gdb.Symbol} automatically.
2228 class SymValueWrapper():
2230 def __init__(self, symbol, value):
2240 class SomeFrameDecorator()
2243 def frame_args(self):
2246 block = self.inferior_frame.block()
2250 # Iterate over all symbols in a block. Only add
2251 # symbols that are arguments.
2253 if not sym.is_argument:
2255 args.append(SymValueWrapper(sym,None))
2257 # Add example synthetic argument.
2258 args.append(SymValueWrapper(``foo'', 42))
2264 @defun FrameDecorator.frame_locals (self)
2266 This method must return an iterable or @code{None}. Returning an
2267 empty iterable, or @code{None} means frame local arguments will not be
2268 printed for this frame.
2270 The object interface, the description of the various strategies for
2271 reading frame locals, and the example are largely similar to those
2272 described in the @code{frame_args} function, (@pxref{frame_args,,The
2273 frame filter frame_args function}). Below is a modified example:
2276 class SomeFrameDecorator()
2279 def frame_locals(self):
2282 block = self.inferior_frame.block()
2286 # Iterate over all symbols in a block. Add all
2287 # symbols, except arguments.
2291 vars.append(SymValueWrapper(sym,None))
2293 # Add an example of a synthetic local variable.
2294 vars.append(SymValueWrapper(``bar'', 99))
2300 @defun FrameDecorator.inferior_frame (self):
2302 This method must return the underlying @code{gdb.Frame} that this
2303 frame decorator is decorating. @value{GDBN} requires the underlying
2304 frame for internal frame information to determine how to print certain
2305 values when printing a frame.
2308 @node Writing a Frame Filter
2309 @subsubsection Writing a Frame Filter
2310 @cindex writing a frame filter
2312 There are three basic elements that a frame filter must implement: it
2313 must correctly implement the documented interface (@pxref{Frame Filter
2314 API}), it must register itself with @value{GDBN}, and finally, it must
2315 decide if it is to work on the data provided by @value{GDBN}. In all
2316 cases, whether it works on the iterator or not, each frame filter must
2317 return an iterator. A bare-bones frame filter follows the pattern in
2318 the following example.
2323 class FrameFilter():
2326 # Frame filter attribute creation.
2328 # 'name' is the name of the filter that GDB will display.
2330 # 'priority' is the priority of the filter relative to other
2333 # 'enabled' is a boolean that indicates whether this filter is
2334 # enabled and should be executed.
2340 # Register this frame filter with the global frame_filters
2342 gdb.frame_filters[self.name] = self
2344 def filter(self, frame_iter):
2345 # Just return the iterator.
2349 The frame filter in the example above implements the three
2350 requirements for all frame filters. It implements the API, self
2351 registers, and makes a decision on the iterator (in this case, it just
2352 returns the iterator untouched).
2354 The first step is attribute creation and assignment, and as shown in
2355 the comments the filter assigns the following attributes: @code{name},
2356 @code{priority} and whether the filter should be enabled with the
2357 @code{enabled} attribute.
2359 The second step is registering the frame filter with the dictionary or
2360 dictionaries that the frame filter has interest in. As shown in the
2361 comments, this filter just registers itself with the global dictionary
2362 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
2363 is a dictionary that is initialized in the @code{gdb} module when
2364 @value{GDBN} starts. What dictionary a filter registers with is an
2365 important consideration. Generally, if a filter is specific to a set
2366 of code, it should be registered either in the @code{objfile} or
2367 @code{progspace} dictionaries as they are specific to the program
2368 currently loaded in @value{GDBN}. The global dictionary is always
2369 present in @value{GDBN} and is never unloaded. Any filters registered
2370 with the global dictionary will exist until @value{GDBN} exits. To
2371 avoid filters that may conflict, it is generally better to register
2372 frame filters against the dictionaries that more closely align with
2373 the usage of the filter currently in question. @xref{Python
2374 Auto-loading}, for further information on auto-loading Python scripts.
2376 @value{GDBN} takes a hands-off approach to frame filter registration,
2377 therefore it is the frame filter's responsibility to ensure
2378 registration has occurred, and that any exceptions are handled
2379 appropriately. In particular, you may wish to handle exceptions
2380 relating to Python dictionary key uniqueness. It is mandatory that
2381 the dictionary key is the same as frame filter's @code{name}
2382 attribute. When a user manages frame filters (@pxref{Frame Filter
2383 Management}), the names @value{GDBN} will display are those contained
2384 in the @code{name} attribute.
2386 The final step of this example is the implementation of the
2387 @code{filter} method. As shown in the example comments, we define the
2388 @code{filter} method and note that the method must take an iterator,
2389 and also must return an iterator. In this bare-bones example, the
2390 frame filter is not very useful as it just returns the iterator
2391 untouched. However this is a valid operation for frame filters that
2392 have the @code{enabled} attribute set, but decide not to operate on
2395 In the next example, the frame filter operates on all frames and
2396 utilizes a frame decorator to perform some work on the frames.
2397 @xref{Frame Decorator API}, for further information on the frame
2398 decorator interface.
2400 This example works on inlined frames. It highlights frames which are
2401 inlined by tagging them with an ``[inlined]'' tag. By applying a
2402 frame decorator to all frames with the Python @code{itertools imap}
2403 method, the example defers actions to the frame decorator. Frame
2404 decorators are only processed when @value{GDBN} prints the backtrace.
2406 This introduces a new decision making topic: whether to perform
2407 decision making operations at the filtering step, or at the printing
2408 step. In this example's approach, it does not perform any filtering
2409 decisions at the filtering step beyond mapping a frame decorator to
2410 each frame. This allows the actual decision making to be performed
2411 when each frame is printed. This is an important consideration, and
2412 well worth reflecting upon when designing a frame filter. An issue
2413 that frame filters should avoid is unwinding the stack if possible.
2414 Some stacks can run very deep, into the tens of thousands in some
2415 cases. To search every frame to determine if it is inlined ahead of
2416 time may be too expensive at the filtering step. The frame filter
2417 cannot know how many frames it has to iterate over, and it would have
2418 to iterate through them all. This ends up duplicating effort as
2419 @value{GDBN} performs this iteration when it prints the frames.
2421 In this example decision making can be deferred to the printing step.
2422 As each frame is printed, the frame decorator can examine each frame
2423 in turn when @value{GDBN} iterates. From a performance viewpoint,
2424 this is the most appropriate decision to make as it avoids duplicating
2425 the effort that the printing step would undertake anyway. Also, if
2426 there are many frame filters unwinding the stack during filtering, it
2427 can substantially delay the printing of the backtrace which will
2428 result in large memory usage, and a poor user experience.
2431 class InlineFilter():
2434 self.name = "InlinedFrameFilter"
2437 gdb.frame_filters[self.name] = self
2439 def filter(self, frame_iter):
2440 frame_iter = itertools.imap(InlinedFrameDecorator,
2445 This frame filter is somewhat similar to the earlier example, except
2446 that the @code{filter} method applies a frame decorator object called
2447 @code{InlinedFrameDecorator} to each element in the iterator. The
2448 @code{imap} Python method is light-weight. It does not proactively
2449 iterate over the iterator, but rather creates a new iterator which
2450 wraps the existing one.
2452 Below is the frame decorator for this example.
2455 class InlinedFrameDecorator(FrameDecorator):
2457 def __init__(self, fobj):
2458 super(InlinedFrameDecorator, self).__init__(fobj)
2461 frame = self.inferior_frame()
2462 name = str(frame.name())
2464 if frame.type() == gdb.INLINE_FRAME:
2465 name = name + " [inlined]"
2470 This frame decorator only defines and overrides the @code{function}
2471 method. It lets the supplied @code{FrameDecorator}, which is shipped
2472 with @value{GDBN}, perform the other work associated with printing
2475 The combination of these two objects create this output from a
2479 #0 0x004004e0 in bar () at inline.c:11
2480 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2481 #2 0x00400566 in main () at inline.c:31
2484 So in the case of this example, a frame decorator is applied to all
2485 frames, regardless of whether they may be inlined or not. As
2486 @value{GDBN} iterates over the iterator produced by the frame filters,
2487 @value{GDBN} executes each frame decorator which then makes a decision
2488 on what to print in the @code{function} callback. Using a strategy
2489 like this is a way to defer decisions on the frame content to printing
2492 @subheading Eliding Frames
2494 It might be that the above example is not desirable for representing
2495 inlined frames, and a hierarchical approach may be preferred. If we
2496 want to hierarchically represent frames, the @code{elided} frame
2497 decorator interface might be preferable.
2499 This example approaches the issue with the @code{elided} method. This
2500 example is quite long, but very simplistic. It is out-of-scope for
2501 this section to write a complete example that comprehensively covers
2502 all approaches of finding and printing inlined frames. However, this
2503 example illustrates the approach an author might use.
2505 This example comprises of three sections.
2508 class InlineFrameFilter():
2511 self.name = "InlinedFrameFilter"
2514 gdb.frame_filters[self.name] = self
2516 def filter(self, frame_iter):
2517 return ElidingInlineIterator(frame_iter)
2520 This frame filter is very similar to the other examples. The only
2521 difference is this frame filter is wrapping the iterator provided to
2522 it (@code{frame_iter}) with a custom iterator called
2523 @code{ElidingInlineIterator}. This again defers actions to when
2524 @value{GDBN} prints the backtrace, as the iterator is not traversed
2527 The iterator for this example is as follows. It is in this section of
2528 the example where decisions are made on the content of the backtrace.
2531 class ElidingInlineIterator:
2532 def __init__(self, ii):
2533 self.input_iterator = ii
2539 frame = next(self.input_iterator)
2541 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2545 eliding_frame = next(self.input_iterator)
2546 except StopIteration:
2548 return ElidingFrameDecorator(eliding_frame, [frame])
2551 This iterator implements the Python iterator protocol. When the
2552 @code{next} function is called (when @value{GDBN} prints each frame),
2553 the iterator checks if this frame decorator, @code{frame}, is wrapping
2554 an inlined frame. If it is not, it returns the existing frame decorator
2555 untouched. If it is wrapping an inlined frame, it assumes that the
2556 inlined frame was contained within the next oldest frame,
2557 @code{eliding_frame}, which it fetches. It then creates and returns a
2558 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2559 elided frame, and the eliding frame.
2562 class ElidingInlineDecorator(FrameDecorator):
2564 def __init__(self, frame, elided_frames):
2565 super(ElidingInlineDecorator, self).__init__(frame)
2567 self.elided_frames = elided_frames
2570 return iter(self.elided_frames)
2573 This frame decorator overrides one function and returns the inlined
2574 frame in the @code{elided} method. As before it lets
2575 @code{FrameDecorator} do the rest of the work involved in printing
2576 this frame. This produces the following output.
2579 #0 0x004004e0 in bar () at inline.c:11
2580 #2 0x00400529 in main () at inline.c:25
2581 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2584 In that output, @code{max} which has been inlined into @code{main} is
2585 printed hierarchically. Another approach would be to combine the
2586 @code{function} method, and the @code{elided} method to both print a
2587 marker in the inlined frame, and also show the hierarchical
2590 @node Unwinding Frames in Python
2591 @subsubsection Unwinding Frames in Python
2592 @cindex unwinding frames in Python
2594 In @value{GDBN} terminology ``unwinding'' is the process of finding
2595 the previous frame (that is, caller's) from the current one. An
2596 unwinder has three methods. The first one checks if it can handle
2597 given frame (``sniff'' it). For the frames it can sniff an unwinder
2598 provides two additional methods: it can return frame's ID, and it can
2599 fetch registers from the previous frame. A running @value{GDBN}
2600 mantains a list of the unwinders and calls each unwinder's sniffer in
2601 turn until it finds the one that recognizes the current frame. There
2602 is an API to register an unwinder.
2604 The unwinders that come with @value{GDBN} handle standard frames.
2605 However, mixed language applications (for example, an application
2606 running Java Virtual Machine) sometimes use frame layouts that cannot
2607 be handled by the @value{GDBN} unwinders. You can write Python code
2608 that can handle such custom frames.
2610 You implement a frame unwinder in Python as a class with which has two
2611 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2612 a single method @code{__call__}, which examines a given frame and
2613 returns an object (an instance of @code{gdb.UnwindInfo class)}
2614 describing it. If an unwinder does not recognize a frame, it should
2615 return @code{None}. The code in @value{GDBN} that enables writing
2616 unwinders in Python uses this object to return frame's ID and previous
2617 frame registers when @value{GDBN} core asks for them.
2619 An unwinder should do as little work as possible. Some otherwise
2620 innocuous operations can cause problems (even crashes, as this code is
2621 not not well-hardened yet). For example, making an inferior call from
2622 an unwinder is unadvisable, as an inferior call will reset
2623 @value{GDBN}'s stack unwinding process, potentially causing re-entrant
2626 @subheading Unwinder Input
2628 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2629 provides a method to read frame's registers:
2631 @defun PendingFrame.read_register (reg)
2632 This method returns the contents of the register @var{reg} in the
2633 frame as a @code{gdb.Value} object. For a description of the
2634 acceptable values of @var{reg} see
2635 @ref{gdbpy_frame_read_register,,Frame.read_register}. If @var{reg}
2636 does not name a register for the current architecture, this method
2637 will throw an exception.
2639 Note that this method will always return a @code{gdb.Value} for a
2640 valid register name. This does not mean that the value will be valid.
2641 For example, you may request a register that an earlier unwinder could
2642 not unwind---the value will be unavailable. Instead, the
2643 @code{gdb.Value} returned from this method will be lazy; that is, its
2644 underlying bits will not be fetched until it is first used. So,
2645 attempting to use such a value will cause an exception at the point of
2648 The type of the returned @code{gdb.Value} depends on the register and
2649 the architecture. It is common for registers to have a scalar type,
2650 like @code{long long}; but many other types are possible, such as
2651 pointer, pointer-to-function, floating point or vector types.
2654 It also provides a factory method to create a @code{gdb.UnwindInfo}
2655 instance to be returned to @value{GDBN}:
2657 @defun PendingFrame.create_unwind_info (frame_id)
2658 Returns a new @code{gdb.UnwindInfo} instance identified by given
2659 @var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2660 using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2661 determine which function will be used, as follows:
2665 The frame is identified by the given stack address and PC. The stack
2666 address must be chosen so that it is constant throughout the lifetime
2667 of the frame, so a typical choice is the value of the stack pointer at
2668 the start of the function---in the DWARF standard, this would be the
2669 ``Call Frame Address''.
2671 This is the most common case by far. The other cases are documented
2672 for completeness but are only useful in specialized situations.
2674 @item sp, pc, special
2675 The frame is identified by the stack address, the PC, and a
2676 ``special'' address. The special address is used on architectures
2677 that can have frames that do not change the stack, but which are still
2678 distinct, for example the IA-64, which has a second stack for
2679 registers. Both @var{sp} and @var{special} must be constant
2680 throughout the lifetime of the frame.
2683 The frame is identified by the stack address only. Any other stack
2684 frame with a matching @var{sp} will be considered to match this frame.
2685 Inside gdb, this is called a ``wild frame''. You will never need
2689 Each attribute value should be an instance of @code{gdb.Value}.
2693 @defun PendingFrame.architecture ()
2694 Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
2695 for this @code{gdb.PendingFrame}. This represents the architecture of
2696 the particular frame being unwound.
2699 @defun PendingFrame.level ()
2700 Return an integer, the stack frame level for this frame.
2701 @xref{Frames, ,Stack Frames}.
2704 @subheading Unwinder Output: UnwindInfo
2706 Use @code{PendingFrame.create_unwind_info} method described above to
2707 create a @code{gdb.UnwindInfo} instance. Use the following method to
2708 specify caller registers that have been saved in this frame:
2710 @defun gdb.UnwindInfo.add_saved_register (reg, value)
2711 @var{reg} identifies the register, for a description of the acceptable
2712 values see @ref{gdbpy_frame_read_register,,Frame.read_register}.
2713 @var{value} is a register value (a @code{gdb.Value} object).
2716 @subheading Unwinder Skeleton Code
2718 @value{GDBN} comes with the module containing the base @code{Unwinder}
2719 class. Derive your unwinder class from it and structure the code as
2723 from gdb.unwinders import Unwinder
2725 class FrameId(object):
2726 def __init__(self, sp, pc):
2731 class MyUnwinder(Unwinder):
2733 super(MyUnwinder, self).__init___(<expects unwinder name argument>)
2735 def __call__(pending_frame):
2736 if not <we recognize frame>:
2738 # Create UnwindInfo. Usually the frame is identified by the stack
2739 # pointer and the program counter.
2740 sp = pending_frame.read_register(<SP number>)
2741 pc = pending_frame.read_register(<PC number>)
2742 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2744 # Find the values of the registers in the caller's frame and
2745 # save them in the result:
2746 unwind_info.add_saved_register(<register>, <value>)
2749 # Return the result:
2754 @subheading Registering a Unwinder
2756 An object file, a program space, and the @value{GDBN} proper can have
2757 unwinders registered with it.
2759 The @code{gdb.unwinders} module provides the function to register a
2762 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2763 @var{locus} is specifies an object file or a program space to which
2764 @var{unwinder} is added. Passing @code{None} or @code{gdb} adds
2765 @var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
2766 added @var{unwinder} will be called before any other unwinder from the
2767 same locus. Two unwinders in the same locus cannot have the same
2768 name. An attempt to add a unwinder with already existing name raises
2769 an exception unless @var{replace} is @code{True}, in which case the
2770 old unwinder is deleted.
2773 @subheading Unwinder Precedence
2775 @value{GDBN} first calls the unwinders from all the object files in no
2776 particular order, then the unwinders from the current program space,
2777 and finally the unwinders from @value{GDBN}.
2779 @node Xmethods In Python
2780 @subsubsection Xmethods In Python
2781 @cindex xmethods in Python
2783 @dfn{Xmethods} are additional methods or replacements for existing
2784 methods of a C@t{++} class. This feature is useful for those cases
2785 where a method defined in C@t{++} source code could be inlined or
2786 optimized out by the compiler, making it unavailable to @value{GDBN}.
2787 For such cases, one can define an xmethod to serve as a replacement
2788 for the method defined in the C@t{++} source code. @value{GDBN} will
2789 then invoke the xmethod, instead of the C@t{++} method, to
2790 evaluate expressions. One can also use xmethods when debugging
2791 with core files. Moreover, when debugging live programs, invoking an
2792 xmethod need not involve running the inferior (which can potentially
2793 perturb its state). Hence, even if the C@t{++} method is available, it
2794 is better to use its replacement xmethod if one is defined.
2796 The xmethods feature in Python is available via the concepts of an
2797 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2798 implement an xmethod, one has to implement a matcher and a
2799 corresponding worker for it (more than one worker can be
2800 implemented, each catering to a different overloaded instance of the
2801 method). Internally, @value{GDBN} invokes the @code{match} method of a
2802 matcher to match the class type and method name. On a match, the
2803 @code{match} method returns a list of matching @emph{worker} objects.
2804 Each worker object typically corresponds to an overloaded instance of
2805 the xmethod. They implement a @code{get_arg_types} method which
2806 returns a sequence of types corresponding to the arguments the xmethod
2807 requires. @value{GDBN} uses this sequence of types to perform
2808 overload resolution and picks a winning xmethod worker. A winner
2809 is also selected from among the methods @value{GDBN} finds in the
2810 C@t{++} source code. Next, the winning xmethod worker and the
2811 winning C@t{++} method are compared to select an overall winner. In
2812 case of a tie between a xmethod worker and a C@t{++} method, the
2813 xmethod worker is selected as the winner. That is, if a winning
2814 xmethod worker is found to be equivalent to the winning C@t{++}
2815 method, then the xmethod worker is treated as a replacement for
2816 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2817 method. If the winning xmethod worker is the overall winner, then
2818 the corresponding xmethod is invoked via the @code{__call__} method
2819 of the worker object.
2821 If one wants to implement an xmethod as a replacement for an
2822 existing C@t{++} method, then they have to implement an equivalent
2823 xmethod which has exactly the same name and takes arguments of
2824 exactly the same type as the C@t{++} method. If the user wants to
2825 invoke the C@t{++} method even though a replacement xmethod is
2826 available for that method, then they can disable the xmethod.
2828 @xref{Xmethod API}, for API to implement xmethods in Python.
2829 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2832 @subsubsection Xmethod API
2835 The @value{GDBN} Python API provides classes, interfaces and functions
2836 to implement, register and manipulate xmethods.
2837 @xref{Xmethods In Python}.
2839 An xmethod matcher should be an instance of a class derived from
2840 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2841 object with similar interface and attributes. An instance of
2842 @code{XMethodMatcher} has the following attributes:
2845 The name of the matcher.
2849 A boolean value indicating whether the matcher is enabled or disabled.
2853 A list of named methods managed by the matcher. Each object in the list
2854 is an instance of the class @code{XMethod} defined in the module
2855 @code{gdb.xmethod}, or any object with the following attributes:
2860 Name of the xmethod which should be unique for each xmethod
2861 managed by the matcher.
2864 A boolean value indicating whether the xmethod is enabled or
2869 The class @code{XMethod} is a convenience class with same
2870 attributes as above along with the following constructor:
2872 @defun XMethod.__init__ (self, name)
2873 Constructs an enabled xmethod with name @var{name}.
2878 The @code{XMethodMatcher} class has the following methods:
2880 @defun XMethodMatcher.__init__ (self, name)
2881 Constructs an enabled xmethod matcher with name @var{name}. The
2882 @code{methods} attribute is initialized to @code{None}.
2885 @defun XMethodMatcher.match (self, class_type, method_name)
2886 Derived classes should override this method. It should return a
2887 xmethod worker object (or a sequence of xmethod worker
2888 objects) matching the @var{class_type} and @var{method_name}.
2889 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
2890 is a string value. If the matcher manages named methods as listed in
2891 its @code{methods} attribute, then only those worker objects whose
2892 corresponding entries in the @code{methods} list are enabled should be
2896 An xmethod worker should be an instance of a class derived from
2897 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
2898 or support the following interface:
2900 @defun XMethodWorker.get_arg_types (self)
2901 This method returns a sequence of @code{gdb.Type} objects corresponding
2902 to the arguments that the xmethod takes. It can return an empty
2903 sequence or @code{None} if the xmethod does not take any arguments.
2904 If the xmethod takes a single argument, then a single
2905 @code{gdb.Type} object corresponding to it can be returned.
2908 @defun XMethodWorker.get_result_type (self, *args)
2909 This method returns a @code{gdb.Type} object representing the type
2910 of the result of invoking this xmethod.
2911 The @var{args} argument is the same tuple of arguments that would be
2912 passed to the @code{__call__} method of this worker.
2915 @defun XMethodWorker.__call__ (self, *args)
2916 This is the method which does the @emph{work} of the xmethod. The
2917 @var{args} arguments is the tuple of arguments to the xmethod. Each
2918 element in this tuple is a gdb.Value object. The first element is
2919 always the @code{this} pointer value.
2922 For @value{GDBN} to lookup xmethods, the xmethod matchers
2923 should be registered using the following function defined in the module
2926 @defun register_xmethod_matcher (locus, matcher, replace=False)
2927 The @code{matcher} is registered with @code{locus}, replacing an
2928 existing matcher with the same name as @code{matcher} if
2929 @code{replace} is @code{True}. @code{locus} can be a
2930 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
2931 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
2932 @code{None}. If it is @code{None}, then @code{matcher} is registered
2936 @node Writing an Xmethod
2937 @subsubsection Writing an Xmethod
2938 @cindex writing xmethods in Python
2940 Implementing xmethods in Python will require implementing xmethod
2941 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
2942 the following C@t{++} class:
2948 MyClass (int a) : a_(a) @{ @}
2950 int geta (void) @{ return a_; @}
2951 int operator+ (int b);
2958 MyClass::operator+ (int b)
2965 Let us define two xmethods for the class @code{MyClass}, one
2966 replacing the method @code{geta}, and another adding an overloaded
2967 flavor of @code{operator+} which takes a @code{MyClass} argument (the
2968 C@t{++} code above already has an overloaded @code{operator+}
2969 which takes an @code{int} argument). The xmethod matcher can be
2973 class MyClass_geta(gdb.xmethod.XMethod):
2975 gdb.xmethod.XMethod.__init__(self, 'geta')
2977 def get_worker(self, method_name):
2978 if method_name == 'geta':
2979 return MyClassWorker_geta()
2982 class MyClass_sum(gdb.xmethod.XMethod):
2984 gdb.xmethod.XMethod.__init__(self, 'sum')
2986 def get_worker(self, method_name):
2987 if method_name == 'operator+':
2988 return MyClassWorker_plus()
2991 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
2993 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
2994 # List of methods 'managed' by this matcher
2995 self.methods = [MyClass_geta(), MyClass_sum()]
2997 def match(self, class_type, method_name):
2998 if class_type.tag != 'MyClass':
3001 for method in self.methods:
3003 worker = method.get_worker(method_name)
3005 workers.append(worker)
3011 Notice that the @code{match} method of @code{MyClassMatcher} returns
3012 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
3013 method, and a worker object of type @code{MyClassWorker_plus} for the
3014 @code{operator+} method. This is done indirectly via helper classes
3015 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
3016 @code{methods} attribute in a matcher as it is optional. However, if a
3017 matcher manages more than one xmethod, it is a good practice to list the
3018 xmethods in the @code{methods} attribute of the matcher. This will then
3019 facilitate enabling and disabling individual xmethods via the
3020 @code{enable/disable} commands. Notice also that a worker object is
3021 returned only if the corresponding entry in the @code{methods} attribute
3022 of the matcher is enabled.
3024 The implementation of the worker classes returned by the matcher setup
3025 above is as follows:
3028 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
3029 def get_arg_types(self):
3032 def get_result_type(self, obj):
3033 return gdb.lookup_type('int')
3035 def __call__(self, obj):
3039 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
3040 def get_arg_types(self):
3041 return gdb.lookup_type('MyClass')
3043 def get_result_type(self, obj):
3044 return gdb.lookup_type('int')
3046 def __call__(self, obj, other):
3047 return obj['a_'] + other['a_']
3050 For @value{GDBN} to actually lookup a xmethod, it has to be
3051 registered with it. The matcher defined above is registered with
3052 @value{GDBN} globally as follows:
3055 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
3058 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
3066 then, after loading the Python script defining the xmethod matchers
3067 and workers into @code{GDBN}, invoking the method @code{geta} or using
3068 the operator @code{+} on @code{obj} will invoke the xmethods
3079 Consider another example with a C++ template class:
3086 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
3087 ~MyTemplate () @{ delete [] data_; @}
3089 int footprint (void)
3091 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
3100 Let us implement an xmethod for the above class which serves as a
3101 replacement for the @code{footprint} method. The full code listing
3102 of the xmethod workers and xmethod matchers is as follows:
3105 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
3106 def __init__(self, class_type):
3107 self.class_type = class_type
3109 def get_arg_types(self):
3112 def get_result_type(self):
3113 return gdb.lookup_type('int')
3115 def __call__(self, obj):
3116 return (self.class_type.sizeof +
3118 self.class_type.template_argument(0).sizeof)
3121 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
3123 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
3125 def match(self, class_type, method_name):
3126 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
3128 method_name == 'footprint'):
3129 return MyTemplateWorker_footprint(class_type)
3132 Notice that, in this example, we have not used the @code{methods}
3133 attribute of the matcher as the matcher manages only one xmethod. The
3134 user can enable/disable this xmethod by enabling/disabling the matcher
3137 @node Inferiors In Python
3138 @subsubsection Inferiors In Python
3139 @cindex inferiors in Python
3141 @findex gdb.Inferior
3142 Programs which are being run under @value{GDBN} are called inferiors
3143 (@pxref{Inferiors Connections and Programs}). Python scripts can access
3144 information about and manipulate inferiors controlled by @value{GDBN}
3145 via objects of the @code{gdb.Inferior} class.
3147 The following inferior-related functions are available in the @code{gdb}
3150 @defun gdb.inferiors ()
3151 Return a tuple containing all inferior objects.
3154 @defun gdb.selected_inferior ()
3155 Return an object representing the current inferior.
3158 A @code{gdb.Inferior} object has the following attributes:
3160 @defvar Inferior.num
3161 ID of inferior, as assigned by GDB.
3164 @anchor{gdbpy_inferior_connection}
3165 @defvar Inferior.connection
3166 The @code{gdb.TargetConnection} for this inferior (@pxref{Connections
3167 In Python}), or @code{None} if this inferior has no connection.
3170 @defvar Inferior.connection_num
3171 ID of inferior's connection as assigned by @value{GDBN}, or None if
3172 the inferior is not connected to a target. @xref{Inferiors Connections
3173 and Programs}. This is equivalent to
3174 @code{gdb.Inferior.connection.num} in the case where
3175 @code{gdb.Inferior.connection} is not @code{None}.
3178 @defvar Inferior.pid
3179 Process ID of the inferior, as assigned by the underlying operating
3183 @defvar Inferior.was_attached
3184 Boolean signaling whether the inferior was created using `attach', or
3185 started by @value{GDBN} itself.
3188 @defvar Inferior.progspace
3189 The inferior's program space. @xref{Progspaces In Python}.
3192 A @code{gdb.Inferior} object has the following methods:
3194 @defun Inferior.is_valid ()
3195 Returns @code{True} if the @code{gdb.Inferior} object is valid,
3196 @code{False} if not. A @code{gdb.Inferior} object will become invalid
3197 if the inferior no longer exists within @value{GDBN}. All other
3198 @code{gdb.Inferior} methods will throw an exception if it is invalid
3199 at the time the method is called.
3202 @defun Inferior.threads ()
3203 This method returns a tuple holding all the threads which are valid
3204 when it is called. If there are no valid threads, the method will
3205 return an empty tuple.
3208 @defun Inferior.architecture ()
3209 Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
3210 for this inferior. This represents the architecture of the inferior
3211 as a whole. Some platforms can have multiple architectures in a
3212 single address space, so this may not match the architecture of a
3213 particular frame (@pxref{Frames In Python}).
3216 @findex Inferior.read_memory
3217 @defun Inferior.read_memory (address, length)
3218 Read @var{length} addressable memory units from the inferior, starting at
3219 @var{address}. Returns a buffer object, which behaves much like an array
3220 or a string. It can be modified and given to the
3221 @code{Inferior.write_memory} function. In Python 3, the return
3222 value is a @code{memoryview} object.
3225 @findex Inferior.write_memory
3226 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
3227 Write the contents of @var{buffer} to the inferior, starting at
3228 @var{address}. The @var{buffer} parameter must be a Python object
3229 which supports the buffer protocol, i.e., a string, an array or the
3230 object returned from @code{Inferior.read_memory}. If given, @var{length}
3231 determines the number of addressable memory units from @var{buffer} to be
3235 @findex gdb.search_memory
3236 @defun Inferior.search_memory (address, length, pattern)
3237 Search a region of the inferior memory starting at @var{address} with
3238 the given @var{length} using the search pattern supplied in
3239 @var{pattern}. The @var{pattern} parameter must be a Python object
3240 which supports the buffer protocol, i.e., a string, an array or the
3241 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
3242 containing the address where the pattern was found, or @code{None} if
3243 the pattern could not be found.
3246 @findex Inferior.thread_from_handle
3247 @findex Inferior.thread_from_thread_handle
3248 @defun Inferior.thread_from_handle (handle)
3249 Return the thread object corresponding to @var{handle}, a thread
3250 library specific data structure such as @code{pthread_t} for pthreads
3251 library implementations.
3253 The function @code{Inferior.thread_from_thread_handle} provides
3254 the same functionality, but use of @code{Inferior.thread_from_thread_handle}
3258 @node Events In Python
3259 @subsubsection Events In Python
3260 @cindex inferior events in Python
3262 @value{GDBN} provides a general event facility so that Python code can be
3263 notified of various state changes, particularly changes that occur in
3266 An @dfn{event} is just an object that describes some state change. The
3267 type of the object and its attributes will vary depending on the details
3268 of the change. All the existing events are described below.
3270 In order to be notified of an event, you must register an event handler
3271 with an @dfn{event registry}. An event registry is an object in the
3272 @code{gdb.events} module which dispatches particular events. A registry
3273 provides methods to register and unregister event handlers:
3275 @defun EventRegistry.connect (object)
3276 Add the given callable @var{object} to the registry. This object will be
3277 called when an event corresponding to this registry occurs.
3280 @defun EventRegistry.disconnect (object)
3281 Remove the given @var{object} from the registry. Once removed, the object
3282 will no longer receive notifications of events.
3288 def exit_handler (event):
3289 print ("event type: exit")
3290 if hasattr (event, 'exit_code'):
3291 print ("exit code: %d" % (event.exit_code))
3293 print ("exit code not available")
3295 gdb.events.exited.connect (exit_handler)
3298 In the above example we connect our handler @code{exit_handler} to the
3299 registry @code{events.exited}. Once connected, @code{exit_handler} gets
3300 called when the inferior exits. The argument @dfn{event} in this example is
3301 of type @code{gdb.ExitedEvent}. As you can see in the example the
3302 @code{ExitedEvent} object has an attribute which indicates the exit code of
3305 The following is a listing of the event registries that are available and
3306 details of the events they emit:
3311 Emits @code{gdb.ThreadEvent}.
3313 Some events can be thread specific when @value{GDBN} is running in non-stop
3314 mode. When represented in Python, these events all extend
3315 @code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
3316 events which are emitted by this or other modules might extend this event.
3317 Examples of these events are @code{gdb.BreakpointEvent} and
3318 @code{gdb.ContinueEvent}.
3320 @defvar ThreadEvent.inferior_thread
3321 In non-stop mode this attribute will be set to the specific thread which was
3322 involved in the emitted event. Otherwise, it will be set to @code{None}.
3325 Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
3327 This event indicates that the inferior has been continued after a stop. For
3328 inherited attribute refer to @code{gdb.ThreadEvent} above.
3331 Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
3332 @code{events.ExitedEvent} has two attributes:
3333 @defvar ExitedEvent.exit_code
3334 An integer representing the exit code, if available, which the inferior
3335 has returned. (The exit code could be unavailable if, for example,
3336 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
3337 the attribute does not exist.
3339 @defvar ExitedEvent.inferior
3340 A reference to the inferior which triggered the @code{exited} event.
3344 Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
3346 Indicates that the inferior has stopped. All events emitted by this registry
3347 extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
3348 will indicate the stopped thread when @value{GDBN} is running in non-stop
3349 mode. Refer to @code{gdb.ThreadEvent} above for more details.
3351 Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
3353 This event indicates that the inferior or one of its threads has received as
3354 signal. @code{gdb.SignalEvent} has the following attributes:
3356 @defvar SignalEvent.stop_signal
3357 A string representing the signal received by the inferior. A list of possible
3358 signal values can be obtained by running the command @code{info signals} in
3359 the @value{GDBN} command prompt.
3362 Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
3364 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
3365 been hit, and has the following attributes:
3367 @defvar BreakpointEvent.breakpoints
3368 A sequence containing references to all the breakpoints (type
3369 @code{gdb.Breakpoint}) that were hit.
3370 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
3372 @defvar BreakpointEvent.breakpoint
3373 A reference to the first breakpoint that was hit.
3374 This function is maintained for backward compatibility and is now deprecated
3375 in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
3378 @item events.new_objfile
3379 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
3380 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
3382 @defvar NewObjFileEvent.new_objfile
3383 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
3384 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
3387 @item events.clear_objfiles
3388 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
3389 files for a program space has been reset.
3390 @code{gdb.ClearObjFilesEvent} has one attribute:
3392 @defvar ClearObjFilesEvent.progspace
3393 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
3394 been cleared. @xref{Progspaces In Python}.
3397 @item events.inferior_call
3398 Emits events just before and after a function in the inferior is
3399 called by @value{GDBN}. Before an inferior call, this emits an event
3400 of type @code{gdb.InferiorCallPreEvent}, and after an inferior call,
3401 this emits an event of type @code{gdb.InferiorCallPostEvent}.
3404 @tindex gdb.InferiorCallPreEvent
3405 @item @code{gdb.InferiorCallPreEvent}
3406 Indicates that a function in the inferior is about to be called.
3408 @defvar InferiorCallPreEvent.ptid
3409 The thread in which the call will be run.
3412 @defvar InferiorCallPreEvent.address
3413 The location of the function to be called.
3416 @tindex gdb.InferiorCallPostEvent
3417 @item @code{gdb.InferiorCallPostEvent}
3418 Indicates that a function in the inferior has just been called.
3420 @defvar InferiorCallPostEvent.ptid
3421 The thread in which the call was run.
3424 @defvar InferiorCallPostEvent.address
3425 The location of the function that was called.
3429 @item events.memory_changed
3430 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
3431 inferior has been modified by the @value{GDBN} user, for instance via a
3432 command like @w{@code{set *addr = value}}. The event has the following
3435 @defvar MemoryChangedEvent.address
3436 The start address of the changed region.
3439 @defvar MemoryChangedEvent.length
3440 Length in bytes of the changed region.
3443 @item events.register_changed
3444 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
3445 inferior has been modified by the @value{GDBN} user.
3447 @defvar RegisterChangedEvent.frame
3448 A gdb.Frame object representing the frame in which the register was modified.
3450 @defvar RegisterChangedEvent.regnum
3451 Denotes which register was modified.
3454 @item events.breakpoint_created
3455 This is emitted when a new breakpoint has been created. The argument
3456 that is passed is the new @code{gdb.Breakpoint} object.
3458 @item events.breakpoint_modified
3459 This is emitted when a breakpoint has been modified in some way. The
3460 argument that is passed is the new @code{gdb.Breakpoint} object.
3462 @item events.breakpoint_deleted
3463 This is emitted when a breakpoint has been deleted. The argument that
3464 is passed is the @code{gdb.Breakpoint} object. When this event is
3465 emitted, the @code{gdb.Breakpoint} object will already be in its
3466 invalid state; that is, the @code{is_valid} method will return
3469 @item events.before_prompt
3470 This event carries no payload. It is emitted each time @value{GDBN}
3471 presents a prompt to the user.
3473 @item events.new_inferior
3474 This is emitted when a new inferior is created. Note that the
3475 inferior is not necessarily running; in fact, it may not even have an
3476 associated executable.
3478 The event is of type @code{gdb.NewInferiorEvent}. This has a single
3481 @defvar NewInferiorEvent.inferior
3482 The new inferior, a @code{gdb.Inferior} object.
3485 @item events.inferior_deleted
3486 This is emitted when an inferior has been deleted. Note that this is
3487 not the same as process exit; it is notified when the inferior itself
3488 is removed, say via @code{remove-inferiors}.
3490 The event is of type @code{gdb.InferiorDeletedEvent}. This has a single
3493 @defvar NewInferiorEvent.inferior
3494 The inferior that is being removed, a @code{gdb.Inferior} object.
3497 @item events.new_thread
3498 This is emitted when @value{GDBN} notices a new thread. The event is of
3499 type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}.
3500 This has a single attribute:
3502 @defvar NewThreadEvent.inferior_thread
3506 @item events.gdb_exiting
3507 This is emitted when @value{GDBN} exits. This event is not emitted if
3508 @value{GDBN} exits as a result of an internal error, or after an
3509 unexpected signal. The event is of type @code{gdb.GdbExitingEvent},
3510 which has a single attribute:
3512 @defvar GdbExitingEvent.exit_code
3513 An integer, the value of the exit code @value{GDBN} will return.
3516 @item events.connection_removed
3517 This is emitted when @value{GDBN} removes a connection
3518 (@pxref{Connections In Python}). The event is of type
3519 @code{gdb.ConnectionEvent}. This has a single read-only attribute:
3521 @defvar ConnectionEvent.connection
3522 The @code{gdb.TargetConnection} that is being removed.
3527 @node Threads In Python
3528 @subsubsection Threads In Python
3529 @cindex threads in python
3531 @findex gdb.InferiorThread
3532 Python scripts can access information about, and manipulate inferior threads
3533 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
3535 The following thread-related functions are available in the @code{gdb}
3538 @findex gdb.selected_thread
3539 @defun gdb.selected_thread ()
3540 This function returns the thread object for the selected thread. If there
3541 is no selected thread, this will return @code{None}.
3544 To get the list of threads for an inferior, use the @code{Inferior.threads()}
3545 method. @xref{Inferiors In Python}.
3547 A @code{gdb.InferiorThread} object has the following attributes:
3549 @defvar InferiorThread.name
3550 The name of the thread. If the user specified a name using
3551 @code{thread name}, then this returns that name. Otherwise, if an
3552 OS-supplied name is available, then it is returned. Otherwise, this
3553 returns @code{None}.
3555 This attribute can be assigned to. The new value must be a string
3556 object, which sets the new name, or @code{None}, which removes any
3557 user-specified thread name.
3560 @defvar InferiorThread.num
3561 The per-inferior number of the thread, as assigned by GDB.
3564 @defvar InferiorThread.global_num
3565 The global ID of the thread, as assigned by GDB. You can use this to
3566 make Python breakpoints thread-specific, for example
3567 (@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
3570 @defvar InferiorThread.ptid
3571 ID of the thread, as assigned by the operating system. This attribute is a
3572 tuple containing three integers. The first is the Process ID (PID); the second
3573 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
3574 Either the LWPID or TID may be 0, which indicates that the operating system
3575 does not use that identifier.
3578 @defvar InferiorThread.inferior
3579 The inferior this thread belongs to. This attribute is represented as
3580 a @code{gdb.Inferior} object. This attribute is not writable.
3583 @defvar InferiorThread.details
3584 A string containing target specific thread state information. The
3585 format of this string varies by target. If there is no additional
3586 state information for this thread, then this attribute contains
3589 For example, on a @sc{gnu}/Linux system, a thread that is in the
3590 process of exiting will return the string @samp{Exiting}. For remote
3591 targets the @code{details} string will be obtained with the
3592 @samp{qThreadExtraInfo} remote packet, if the target supports it
3593 (@pxref{qThreadExtraInfo,,@samp{qThreadExtraInfo}}).
3595 @value{GDBN} displays the @code{details} string as part of the
3596 @samp{Target Id} column, in the @code{info threads} output
3597 (@pxref{info_threads,,@samp{info threads}}).
3600 A @code{gdb.InferiorThread} object has the following methods:
3602 @defun InferiorThread.is_valid ()
3603 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
3604 @code{False} if not. A @code{gdb.InferiorThread} object will become
3605 invalid if the thread exits, or the inferior that the thread belongs
3606 is deleted. All other @code{gdb.InferiorThread} methods will throw an
3607 exception if it is invalid at the time the method is called.
3610 @defun InferiorThread.switch ()
3611 This changes @value{GDBN}'s currently selected thread to the one represented
3615 @defun InferiorThread.is_stopped ()
3616 Return a Boolean indicating whether the thread is stopped.
3619 @defun InferiorThread.is_running ()
3620 Return a Boolean indicating whether the thread is running.
3623 @defun InferiorThread.is_exited ()
3624 Return a Boolean indicating whether the thread is exited.
3627 @defun InferiorThread.handle ()
3628 Return the thread object's handle, represented as a Python @code{bytes}
3629 object. A @code{gdb.Value} representation of the handle may be
3630 constructed via @code{gdb.Value(bufobj, type)} where @var{bufobj} is
3631 the Python @code{bytes} representation of the handle and @var{type} is
3632 a @code{gdb.Type} for the handle type.
3635 @node Recordings In Python
3636 @subsubsection Recordings In Python
3637 @cindex recordings in python
3639 The following recordings-related functions
3640 (@pxref{Process Record and Replay}) are available in the @code{gdb}
3643 @defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
3644 Start a recording using the given @var{method} and @var{format}. If
3645 no @var{format} is given, the default format for the recording method
3646 is used. If no @var{method} is given, the default method will be used.
3647 Returns a @code{gdb.Record} object on success. Throw an exception on
3650 The following strings can be passed as @var{method}:
3656 @code{"btrace"}: Possible values for @var{format}: @code{"pt"},
3657 @code{"bts"} or leave out for default format.
3661 @defun gdb.current_recording ()
3662 Access a currently running recording. Return a @code{gdb.Record}
3663 object on success. Return @code{None} if no recording is currently
3667 @defun gdb.stop_recording ()
3668 Stop the current recording. Throw an exception if no recording is
3669 currently active. All record objects become invalid after this call.
3672 A @code{gdb.Record} object has the following attributes:
3674 @defvar Record.method
3675 A string with the current recording method, e.g.@: @code{full} or
3679 @defvar Record.format
3680 A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
3684 @defvar Record.begin
3685 A method specific instruction object representing the first instruction
3690 A method specific instruction object representing the current
3691 instruction, that is not actually part of the recording.
3694 @defvar Record.replay_position
3695 The instruction representing the current replay position. If there is
3696 no replay active, this will be @code{None}.
3699 @defvar Record.instruction_history
3700 A list with all recorded instructions.
3703 @defvar Record.function_call_history
3704 A list with all recorded function call segments.
3707 A @code{gdb.Record} object has the following methods:
3709 @defun Record.goto (instruction)
3710 Move the replay position to the given @var{instruction}.
3713 The common @code{gdb.Instruction} class that recording method specific
3714 instruction objects inherit from, has the following attributes:
3716 @defvar Instruction.pc
3717 An integer representing this instruction's address.
3720 @defvar Instruction.data
3721 A buffer with the raw instruction data. In Python 3, the return value is a
3722 @code{memoryview} object.
3725 @defvar Instruction.decoded
3726 A human readable string with the disassembled instruction.
3729 @defvar Instruction.size
3730 The size of the instruction in bytes.
3733 Additionally @code{gdb.RecordInstruction} has the following attributes:
3735 @defvar RecordInstruction.number
3736 An integer identifying this instruction. @code{number} corresponds to
3737 the numbers seen in @code{record instruction-history}
3738 (@pxref{Process Record and Replay}).
3741 @defvar RecordInstruction.sal
3742 A @code{gdb.Symtab_and_line} object representing the associated symtab
3743 and line of this instruction. May be @code{None} if no debug information is
3747 @defvar RecordInstruction.is_speculative
3748 A boolean indicating whether the instruction was executed speculatively.
3751 If an error occured during recording or decoding a recording, this error is
3752 represented by a @code{gdb.RecordGap} object in the instruction list. It has
3753 the following attributes:
3755 @defvar RecordGap.number
3756 An integer identifying this gap. @code{number} corresponds to the numbers seen
3757 in @code{record instruction-history} (@pxref{Process Record and Replay}).
3760 @defvar RecordGap.error_code
3761 A numerical representation of the reason for the gap. The value is specific to
3762 the current recording method.
3765 @defvar RecordGap.error_string
3766 A human readable string with the reason for the gap.
3769 A @code{gdb.RecordFunctionSegment} object has the following attributes:
3771 @defvar RecordFunctionSegment.number
3772 An integer identifying this function segment. @code{number} corresponds to
3773 the numbers seen in @code{record function-call-history}
3774 (@pxref{Process Record and Replay}).
3777 @defvar RecordFunctionSegment.symbol
3778 A @code{gdb.Symbol} object representing the associated symbol. May be
3779 @code{None} if no debug information is available.
3782 @defvar RecordFunctionSegment.level
3783 An integer representing the function call's stack level. May be
3784 @code{None} if the function call is a gap.
3787 @defvar RecordFunctionSegment.instructions
3788 A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
3789 associated with this function call.
3792 @defvar RecordFunctionSegment.up
3793 A @code{gdb.RecordFunctionSegment} object representing the caller's
3794 function segment. If the call has not been recorded, this will be the
3795 function segment to which control returns. If neither the call nor the
3796 return have been recorded, this will be @code{None}.
3799 @defvar RecordFunctionSegment.prev
3800 A @code{gdb.RecordFunctionSegment} object representing the previous
3801 segment of this function call. May be @code{None}.
3804 @defvar RecordFunctionSegment.next
3805 A @code{gdb.RecordFunctionSegment} object representing the next segment of
3806 this function call. May be @code{None}.
3809 The following example demonstrates the usage of these objects and
3810 functions to create a function that will rewind a record to the last
3811 time a function in a different file was executed. This would typically
3812 be used to track the execution of user provided callback functions in a
3813 library which typically are not visible in a back trace.
3817 rec = gdb.current_recording ()
3821 insn = rec.instruction_history
3826 position = insn.index (rec.replay_position)
3830 filename = insn[position].sal.symtab.fullname ()
3834 for i in reversed (insn[:position]):
3836 current = i.sal.symtab.fullname ()
3840 if filename == current:
3847 Another possible application is to write a function that counts the
3848 number of code executions in a given line range. This line range can
3849 contain parts of functions or span across several functions and is not
3850 limited to be contiguous.
3853 def countrange (filename, linerange):
3856 def filter_only (file_name):
3857 for call in gdb.current_recording ().function_call_history:
3859 if file_name in call.symbol.symtab.fullname ():
3864 for c in filter_only (filename):
3865 for i in c.instructions:
3867 if i.sal.line in linerange:
3876 @node Commands In Python
3877 @subsubsection Commands In Python
3879 @cindex commands in python
3880 @cindex python commands
3881 You can implement new @value{GDBN} CLI commands in Python. A CLI
3882 command is implemented using an instance of the @code{gdb.Command}
3883 class, most commonly using a subclass.
3885 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
3886 The object initializer for @code{Command} registers the new command
3887 with @value{GDBN}. This initializer is normally invoked from the
3888 subclass' own @code{__init__} method.
3890 @var{name} is the name of the command. If @var{name} consists of
3891 multiple words, then the initial words are looked for as prefix
3892 commands. In this case, if one of the prefix commands does not exist,
3893 an exception is raised.
3895 There is no support for multi-line commands.
3897 @var{command_class} should be one of the @samp{COMMAND_} constants
3898 defined below. This argument tells @value{GDBN} how to categorize the
3899 new command in the help system.
3901 @var{completer_class} is an optional argument. If given, it should be
3902 one of the @samp{COMPLETE_} constants defined below. This argument
3903 tells @value{GDBN} how to perform completion for this command. If not
3904 given, @value{GDBN} will attempt to complete using the object's
3905 @code{complete} method (see below); if no such method is found, an
3906 error will occur when completion is attempted.
3908 @var{prefix} is an optional argument. If @code{True}, then the new
3909 command is a prefix command; sub-commands of this command may be
3912 The help text for the new command is taken from the Python
3913 documentation string for the command's class, if there is one. If no
3914 documentation string is provided, the default value ``This command is
3915 not documented.'' is used.
3918 @cindex don't repeat Python command
3919 @defun Command.dont_repeat ()
3920 By default, a @value{GDBN} command is repeated when the user enters a
3921 blank line at the command prompt. A command can suppress this
3922 behavior by invoking the @code{dont_repeat} method. This is similar
3923 to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
3926 @defun Command.invoke (argument, from_tty)
3927 This method is called by @value{GDBN} when this command is invoked.
3929 @var{argument} is a string. It is the argument to the command, after
3930 leading and trailing whitespace has been stripped.
3932 @var{from_tty} is a boolean argument. When true, this means that the
3933 command was entered by the user at the terminal; when false it means
3934 that the command came from elsewhere.
3936 If this method throws an exception, it is turned into a @value{GDBN}
3937 @code{error} call. Otherwise, the return value is ignored.
3939 @findex gdb.string_to_argv
3940 To break @var{argument} up into an argv-like string use
3941 @code{gdb.string_to_argv}. This function behaves identically to
3942 @value{GDBN}'s internal argument lexer @code{buildargv}.
3943 It is recommended to use this for consistency.
3944 Arguments are separated by spaces and may be quoted.
3948 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
3949 ['1', '2 "3', '4 "5', "6 '7"]
3954 @cindex completion of Python commands
3955 @defun Command.complete (text, word)
3956 This method is called by @value{GDBN} when the user attempts
3957 completion on this command. All forms of completion are handled by
3958 this method, that is, the @key{TAB} and @key{M-?} key bindings
3959 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
3962 The arguments @var{text} and @var{word} are both strings; @var{text}
3963 holds the complete command line up to the cursor's location, while
3964 @var{word} holds the last word of the command line; this is computed
3965 using a word-breaking heuristic.
3967 The @code{complete} method can return several values:
3970 If the return value is a sequence, the contents of the sequence are
3971 used as the completions. It is up to @code{complete} to ensure that the
3972 contents actually do complete the word. A zero-length sequence is
3973 allowed, it means that there were no completions available. Only
3974 string elements of the sequence are used; other elements in the
3975 sequence are ignored.
3978 If the return value is one of the @samp{COMPLETE_} constants defined
3979 below, then the corresponding @value{GDBN}-internal completion
3980 function is invoked, and its result is used.
3983 All other results are treated as though there were no available
3988 When a new command is registered, it must be declared as a member of
3989 some general class of commands. This is used to classify top-level
3990 commands in the on-line help system; note that prefix commands are not
3991 listed under their own category but rather that of their top-level
3992 command. The available classifications are represented by constants
3993 defined in the @code{gdb} module:
3996 @findex COMMAND_NONE
3997 @findex gdb.COMMAND_NONE
3998 @item gdb.COMMAND_NONE
3999 The command does not belong to any particular class. A command in
4000 this category will not be displayed in any of the help categories.
4002 @findex COMMAND_RUNNING
4003 @findex gdb.COMMAND_RUNNING
4004 @item gdb.COMMAND_RUNNING
4005 The command is related to running the inferior. For example,
4006 @code{start}, @code{step}, and @code{continue} are in this category.
4007 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
4008 commands in this category.
4010 @findex COMMAND_DATA
4011 @findex gdb.COMMAND_DATA
4012 @item gdb.COMMAND_DATA
4013 The command is related to data or variables. For example,
4014 @code{call}, @code{find}, and @code{print} are in this category. Type
4015 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
4018 @findex COMMAND_STACK
4019 @findex gdb.COMMAND_STACK
4020 @item gdb.COMMAND_STACK
4021 The command has to do with manipulation of the stack. For example,
4022 @code{backtrace}, @code{frame}, and @code{return} are in this
4023 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
4024 list of commands in this category.
4026 @findex COMMAND_FILES
4027 @findex gdb.COMMAND_FILES
4028 @item gdb.COMMAND_FILES
4029 This class is used for file-related commands. For example,
4030 @code{file}, @code{list} and @code{section} are in this category.
4031 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
4032 commands in this category.
4034 @findex COMMAND_SUPPORT
4035 @findex gdb.COMMAND_SUPPORT
4036 @item gdb.COMMAND_SUPPORT
4037 This should be used for ``support facilities'', generally meaning
4038 things that are useful to the user when interacting with @value{GDBN},
4039 but not related to the state of the inferior. For example,
4040 @code{help}, @code{make}, and @code{shell} are in this category. Type
4041 @kbd{help support} at the @value{GDBN} prompt to see a list of
4042 commands in this category.
4044 @findex COMMAND_STATUS
4045 @findex gdb.COMMAND_STATUS
4046 @item gdb.COMMAND_STATUS
4047 The command is an @samp{info}-related command, that is, related to the
4048 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
4049 and @code{show} are in this category. Type @kbd{help status} at the
4050 @value{GDBN} prompt to see a list of commands in this category.
4052 @findex COMMAND_BREAKPOINTS
4053 @findex gdb.COMMAND_BREAKPOINTS
4054 @item gdb.COMMAND_BREAKPOINTS
4055 The command has to do with breakpoints. For example, @code{break},
4056 @code{clear}, and @code{delete} are in this category. Type @kbd{help
4057 breakpoints} at the @value{GDBN} prompt to see a list of commands in
4060 @findex COMMAND_TRACEPOINTS
4061 @findex gdb.COMMAND_TRACEPOINTS
4062 @item gdb.COMMAND_TRACEPOINTS
4063 The command has to do with tracepoints. For example, @code{trace},
4064 @code{actions}, and @code{tfind} are in this category. Type
4065 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
4066 commands in this category.
4069 @findex gdb.COMMAND_TUI
4070 @item gdb.COMMAND_TUI
4071 The command has to do with the text user interface (@pxref{TUI}).
4072 Type @kbd{help tui} at the @value{GDBN} prompt to see a list of
4073 commands in this category.
4075 @findex COMMAND_USER
4076 @findex gdb.COMMAND_USER
4077 @item gdb.COMMAND_USER
4078 The command is a general purpose command for the user, and typically
4079 does not fit in one of the other categories.
4080 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
4081 a list of commands in this category, as well as the list of gdb macros
4082 (@pxref{Sequences}).
4084 @findex COMMAND_OBSCURE
4085 @findex gdb.COMMAND_OBSCURE
4086 @item gdb.COMMAND_OBSCURE
4087 The command is only used in unusual circumstances, or is not of
4088 general interest to users. For example, @code{checkpoint},
4089 @code{fork}, and @code{stop} are in this category. Type @kbd{help
4090 obscure} at the @value{GDBN} prompt to see a list of commands in this
4093 @findex COMMAND_MAINTENANCE
4094 @findex gdb.COMMAND_MAINTENANCE
4095 @item gdb.COMMAND_MAINTENANCE
4096 The command is only useful to @value{GDBN} maintainers. The
4097 @code{maintenance} and @code{flushregs} commands are in this category.
4098 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
4099 commands in this category.
4102 A new command can use a predefined completion function, either by
4103 specifying it via an argument at initialization, or by returning it
4104 from the @code{complete} method. These predefined completion
4105 constants are all defined in the @code{gdb} module:
4108 @vindex COMPLETE_NONE
4109 @item gdb.COMPLETE_NONE
4110 This constant means that no completion should be done.
4112 @vindex COMPLETE_FILENAME
4113 @item gdb.COMPLETE_FILENAME
4114 This constant means that filename completion should be performed.
4116 @vindex COMPLETE_LOCATION
4117 @item gdb.COMPLETE_LOCATION
4118 This constant means that location completion should be done.
4119 @xref{Specify Location}.
4121 @vindex COMPLETE_COMMAND
4122 @item gdb.COMPLETE_COMMAND
4123 This constant means that completion should examine @value{GDBN}
4126 @vindex COMPLETE_SYMBOL
4127 @item gdb.COMPLETE_SYMBOL
4128 This constant means that completion should be done using symbol names
4131 @vindex COMPLETE_EXPRESSION
4132 @item gdb.COMPLETE_EXPRESSION
4133 This constant means that completion should be done on expressions.
4134 Often this means completing on symbol names, but some language
4135 parsers also have support for completing on field names.
4138 The following code snippet shows how a trivial CLI command can be
4139 implemented in Python:
4142 class HelloWorld (gdb.Command):
4143 """Greet the whole world."""
4145 def __init__ (self):
4146 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
4148 def invoke (self, arg, from_tty):
4149 print ("Hello, World!")
4154 The last line instantiates the class, and is necessary to trigger the
4155 registration of the command with @value{GDBN}. Depending on how the
4156 Python code is read into @value{GDBN}, you may need to import the
4157 @code{gdb} module explicitly.
4159 @node Parameters In Python
4160 @subsubsection Parameters In Python
4162 @cindex parameters in python
4163 @cindex python parameters
4164 @tindex gdb.Parameter
4166 You can implement new @value{GDBN} parameters using Python. A new
4167 parameter is implemented as an instance of the @code{gdb.Parameter}
4170 Parameters are exposed to the user via the @code{set} and
4171 @code{show} commands. @xref{Help}.
4173 There are many parameters that already exist and can be set in
4174 @value{GDBN}. Two examples are: @code{set follow fork} and
4175 @code{set charset}. Setting these parameters influences certain
4176 behavior in @value{GDBN}. Similarly, you can define parameters that
4177 can be used to influence behavior in custom Python scripts and commands.
4179 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
4180 The object initializer for @code{Parameter} registers the new
4181 parameter with @value{GDBN}. This initializer is normally invoked
4182 from the subclass' own @code{__init__} method.
4184 @var{name} is the name of the new parameter. If @var{name} consists
4185 of multiple words, then the initial words are looked for as prefix
4186 parameters. An example of this can be illustrated with the
4187 @code{set print} set of parameters. If @var{name} is
4188 @code{print foo}, then @code{print} will be searched as the prefix
4189 parameter. In this case the parameter can subsequently be accessed in
4190 @value{GDBN} as @code{set print foo}.
4192 If @var{name} consists of multiple words, and no prefix parameter group
4193 can be found, an exception is raised.
4195 @var{command-class} should be one of the @samp{COMMAND_} constants
4196 (@pxref{Commands In Python}). This argument tells @value{GDBN} how to
4197 categorize the new parameter in the help system.
4199 @var{parameter-class} should be one of the @samp{PARAM_} constants
4200 defined below. This argument tells @value{GDBN} the type of the new
4201 parameter; this information is used for input validation and
4204 If @var{parameter-class} is @code{PARAM_ENUM}, then
4205 @var{enum-sequence} must be a sequence of strings. These strings
4206 represent the possible values for the parameter.
4208 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
4209 of a fourth argument will cause an exception to be thrown.
4211 The help text for the new parameter includes the Python documentation
4212 string from the parameter's class, if there is one. If there is no
4213 documentation string, a default value is used. The documentation
4214 string is included in the output of the parameters @code{help set} and
4215 @code{help show} commands, and should be written taking this into
4219 @defvar Parameter.set_doc
4220 If this attribute exists, and is a string, then its value is used as
4221 the first part of the help text for this parameter's @code{set}
4222 command. The second part of the help text is taken from the
4223 documentation string for the parameter's class, if there is one.
4225 The value of @code{set_doc} should give a brief summary specific to
4226 the set action, this text is only displayed when the user runs the
4227 @code{help set} command for this parameter. The class documentation
4228 should be used to give a fuller description of what the parameter
4229 does, this text is displayed for both the @code{help set} and
4230 @code{help show} commands.
4232 The @code{set_doc} value is examined when @code{Parameter.__init__} is
4233 invoked; subsequent changes have no effect.
4236 @defvar Parameter.show_doc
4237 If this attribute exists, and is a string, then its value is used as
4238 the first part of the help text for this parameter's @code{show}
4239 command. The second part of the help text is taken from the
4240 documentation string for the parameter's class, if there is one.
4242 The value of @code{show_doc} should give a brief summary specific to
4243 the show action, this text is only displayed when the user runs the
4244 @code{help show} command for this parameter. The class documentation
4245 should be used to give a fuller description of what the parameter
4246 does, this text is displayed for both the @code{help set} and
4247 @code{help show} commands.
4249 The @code{show_doc} value is examined when @code{Parameter.__init__}
4250 is invoked; subsequent changes have no effect.
4253 @defvar Parameter.value
4254 The @code{value} attribute holds the underlying value of the
4255 parameter. It can be read and assigned to just as any other
4256 attribute. @value{GDBN} does validation when assignments are made.
4259 There are two methods that may be implemented in any @code{Parameter}
4262 @defun Parameter.get_set_string (self)
4263 If this method exists, @value{GDBN} will call it when a
4264 @var{parameter}'s value has been changed via the @code{set} API (for
4265 example, @kbd{set foo off}). The @code{value} attribute has already
4266 been populated with the new value and may be used in output. This
4267 method must return a string. If the returned string is not empty,
4268 @value{GDBN} will present it to the user.
4270 If this method raises the @code{gdb.GdbError} exception
4271 (@pxref{Exception Handling}), then @value{GDBN} will print the
4272 exception's string and the @code{set} command will fail. Note,
4273 however, that the @code{value} attribute will not be reset in this
4274 case. So, if your parameter must validate values, it should store the
4275 old value internally and reset the exposed value, like so:
4278 class ExampleParam (gdb.Parameter):
4279 def __init__ (self, name):
4280 super (ExampleParam, self).__init__ (name,
4284 self.saved_value = True
4287 def get_set_string (self):
4288 if not self.validate():
4289 self.value = self.saved_value
4290 raise gdb.GdbError('Failed to validate')
4291 self.saved_value = self.value
4296 @defun Parameter.get_show_string (self, svalue)
4297 @value{GDBN} will call this method when a @var{parameter}'s
4298 @code{show} API has been invoked (for example, @kbd{show foo}). The
4299 argument @code{svalue} receives the string representation of the
4300 current value. This method must return a string.
4303 When a new parameter is defined, its type must be specified. The
4304 available types are represented by constants defined in the @code{gdb}
4308 @findex PARAM_BOOLEAN
4309 @findex gdb.PARAM_BOOLEAN
4310 @item gdb.PARAM_BOOLEAN
4311 The value is a plain boolean. The Python boolean values, @code{True}
4312 and @code{False} are the only valid values.
4314 @findex PARAM_AUTO_BOOLEAN
4315 @findex gdb.PARAM_AUTO_BOOLEAN
4316 @item gdb.PARAM_AUTO_BOOLEAN
4317 The value has three possible states: true, false, and @samp{auto}. In
4318 Python, true and false are represented using boolean constants, and
4319 @samp{auto} is represented using @code{None}.
4321 @findex PARAM_UINTEGER
4322 @findex gdb.PARAM_UINTEGER
4323 @item gdb.PARAM_UINTEGER
4324 The value is an unsigned integer. The value of 0 should be
4325 interpreted to mean ``unlimited''.
4327 @findex PARAM_INTEGER
4328 @findex gdb.PARAM_INTEGER
4329 @item gdb.PARAM_INTEGER
4330 The value is a signed integer. The value of 0 should be interpreted
4331 to mean ``unlimited''.
4333 @findex PARAM_STRING
4334 @findex gdb.PARAM_STRING
4335 @item gdb.PARAM_STRING
4336 The value is a string. When the user modifies the string, any escape
4337 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
4338 translated into corresponding characters and encoded into the current
4341 @findex PARAM_STRING_NOESCAPE
4342 @findex gdb.PARAM_STRING_NOESCAPE
4343 @item gdb.PARAM_STRING_NOESCAPE
4344 The value is a string. When the user modifies the string, escapes are
4345 passed through untranslated.
4347 @findex PARAM_OPTIONAL_FILENAME
4348 @findex gdb.PARAM_OPTIONAL_FILENAME
4349 @item gdb.PARAM_OPTIONAL_FILENAME
4350 The value is a either a filename (a string), or @code{None}.
4352 @findex PARAM_FILENAME
4353 @findex gdb.PARAM_FILENAME
4354 @item gdb.PARAM_FILENAME
4355 The value is a filename. This is just like
4356 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
4358 @findex PARAM_ZINTEGER
4359 @findex gdb.PARAM_ZINTEGER
4360 @item gdb.PARAM_ZINTEGER
4361 The value is an integer. This is like @code{PARAM_INTEGER}, except 0
4362 is interpreted as itself.
4364 @findex PARAM_ZUINTEGER
4365 @findex gdb.PARAM_ZUINTEGER
4366 @item gdb.PARAM_ZUINTEGER
4367 The value is an unsigned integer. This is like @code{PARAM_INTEGER},
4368 except 0 is interpreted as itself, and the value cannot be negative.
4370 @findex PARAM_ZUINTEGER_UNLIMITED
4371 @findex gdb.PARAM_ZUINTEGER_UNLIMITED
4372 @item gdb.PARAM_ZUINTEGER_UNLIMITED
4373 The value is a signed integer. This is like @code{PARAM_ZUINTEGER},
4374 except the special value -1 should be interpreted to mean
4375 ``unlimited''. Other negative values are not allowed.
4378 @findex gdb.PARAM_ENUM
4379 @item gdb.PARAM_ENUM
4380 The value is a string, which must be one of a collection string
4381 constants provided when the parameter is created.
4384 @node Functions In Python
4385 @subsubsection Writing new convenience functions
4387 @cindex writing convenience functions
4388 @cindex convenience functions in python
4389 @cindex python convenience functions
4390 @tindex gdb.Function
4392 You can implement new convenience functions (@pxref{Convenience Vars})
4393 in Python. A convenience function is an instance of a subclass of the
4394 class @code{gdb.Function}.
4396 @defun Function.__init__ (name)
4397 The initializer for @code{Function} registers the new function with
4398 @value{GDBN}. The argument @var{name} is the name of the function,
4399 a string. The function will be visible to the user as a convenience
4400 variable of type @code{internal function}, whose name is the same as
4401 the given @var{name}.
4403 The documentation for the new function is taken from the documentation
4404 string for the new class.
4407 @defun Function.invoke (@var{*args})
4408 When a convenience function is evaluated, its arguments are converted
4409 to instances of @code{gdb.Value}, and then the function's
4410 @code{invoke} method is called. Note that @value{GDBN} does not
4411 predetermine the arity of convenience functions. Instead, all
4412 available arguments are passed to @code{invoke}, following the
4413 standard Python calling convention. In particular, a convenience
4414 function can have default values for parameters without ill effect.
4416 The return value of this method is used as its value in the enclosing
4417 expression. If an ordinary Python value is returned, it is converted
4418 to a @code{gdb.Value} following the usual rules.
4421 The following code snippet shows how a trivial convenience function can
4422 be implemented in Python:
4425 class Greet (gdb.Function):
4426 """Return string to greet someone.
4427 Takes a name as argument."""
4429 def __init__ (self):
4430 super (Greet, self).__init__ ("greet")
4432 def invoke (self, name):
4433 return "Hello, %s!" % name.string ()
4438 The last line instantiates the class, and is necessary to trigger the
4439 registration of the function with @value{GDBN}. Depending on how the
4440 Python code is read into @value{GDBN}, you may need to import the
4441 @code{gdb} module explicitly.
4443 Now you can use the function in an expression:
4446 (gdb) print $greet("Bob")
4450 @node Progspaces In Python
4451 @subsubsection Program Spaces In Python
4453 @cindex progspaces in python
4454 @tindex gdb.Progspace
4456 A program space, or @dfn{progspace}, represents a symbolic view
4457 of an address space.
4458 It consists of all of the objfiles of the program.
4459 @xref{Objfiles In Python}.
4460 @xref{Inferiors Connections and Programs, program spaces}, for more details
4461 about program spaces.
4463 The following progspace-related functions are available in the
4466 @findex gdb.current_progspace
4467 @defun gdb.current_progspace ()
4468 This function returns the program space of the currently selected inferior.
4469 @xref{Inferiors Connections and Programs}. This is identical to
4470 @code{gdb.selected_inferior().progspace} (@pxref{Inferiors In Python}) and is
4471 included for historical compatibility.
4474 @findex gdb.progspaces
4475 @defun gdb.progspaces ()
4476 Return a sequence of all the progspaces currently known to @value{GDBN}.
4479 Each progspace is represented by an instance of the @code{gdb.Progspace}
4482 @defvar Progspace.filename
4483 The file name of the progspace as a string.
4486 @defvar Progspace.pretty_printers
4487 The @code{pretty_printers} attribute is a list of functions. It is
4488 used to look up pretty-printers. A @code{Value} is passed to each
4489 function in order; if the function returns @code{None}, then the
4490 search continues. Otherwise, the return value should be an object
4491 which is used to format the value. @xref{Pretty Printing API}, for more
4495 @defvar Progspace.type_printers
4496 The @code{type_printers} attribute is a list of type printer objects.
4497 @xref{Type Printing API}, for more information.
4500 @defvar Progspace.frame_filters
4501 The @code{frame_filters} attribute is a dictionary of frame filter
4502 objects. @xref{Frame Filter API}, for more information.
4505 A program space has the following methods:
4507 @findex Progspace.block_for_pc
4508 @defun Progspace.block_for_pc (pc)
4509 Return the innermost @code{gdb.Block} containing the given @var{pc}
4510 value. If the block cannot be found for the @var{pc} value specified,
4511 the function will return @code{None}.
4514 @findex Progspace.find_pc_line
4515 @defun Progspace.find_pc_line (pc)
4516 Return the @code{gdb.Symtab_and_line} object corresponding to the
4517 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid value
4518 of @var{pc} is passed as an argument, then the @code{symtab} and
4519 @code{line} attributes of the returned @code{gdb.Symtab_and_line}
4520 object will be @code{None} and 0 respectively.
4523 @findex Progspace.is_valid
4524 @defun Progspace.is_valid ()
4525 Returns @code{True} if the @code{gdb.Progspace} object is valid,
4526 @code{False} if not. A @code{gdb.Progspace} object can become invalid
4527 if the program space file it refers to is not referenced by any
4528 inferior. All other @code{gdb.Progspace} methods will throw an
4529 exception if it is invalid at the time the method is called.
4532 @findex Progspace.objfiles
4533 @defun Progspace.objfiles ()
4534 Return a sequence of all the objfiles referenced by this program
4535 space. @xref{Objfiles In Python}.
4538 @findex Progspace.solib_name
4539 @defun Progspace.solib_name (address)
4540 Return the name of the shared library holding the given @var{address}
4541 as a string, or @code{None}.
4544 One may add arbitrary attributes to @code{gdb.Progspace} objects
4545 in the usual Python way.
4546 This is useful if, for example, one needs to do some extra record keeping
4547 associated with the program space.
4549 In this contrived example, we want to perform some processing when
4550 an objfile with a certain symbol is loaded, but we only want to do
4551 this once because it is expensive. To achieve this we record the results
4552 with the program space because we can't predict when the desired objfile
4557 def clear_objfiles_handler(event):
4558 event.progspace.expensive_computation = None
4559 def expensive(symbol):
4560 """A mock routine to perform an "expensive" computation on symbol."""
4561 print ("Computing the answer to the ultimate question ...")
4563 def new_objfile_handler(event):
4564 objfile = event.new_objfile
4565 progspace = objfile.progspace
4566 if not hasattr(progspace, 'expensive_computation') or \
4567 progspace.expensive_computation is None:
4568 # We use 'main' for the symbol to keep the example simple.
4569 # Note: There's no current way to constrain the lookup
4571 symbol = gdb.lookup_global_symbol('main')
4572 if symbol is not None:
4573 progspace.expensive_computation = expensive(symbol)
4574 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
4575 gdb.events.new_objfile.connect(new_objfile_handler)
4577 (gdb) file /tmp/hello
4578 Reading symbols from /tmp/hello...
4579 Computing the answer to the ultimate question ...
4580 (gdb) python print gdb.current_progspace().expensive_computation
4583 Starting program: /tmp/hello
4585 [Inferior 1 (process 4242) exited normally]
4588 @node Objfiles In Python
4589 @subsubsection Objfiles In Python
4591 @cindex objfiles in python
4594 @value{GDBN} loads symbols for an inferior from various
4595 symbol-containing files (@pxref{Files}). These include the primary
4596 executable file, any shared libraries used by the inferior, and any
4597 separate debug info files (@pxref{Separate Debug Files}).
4598 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
4600 The following objfile-related functions are available in the
4603 @findex gdb.current_objfile
4604 @defun gdb.current_objfile ()
4605 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
4606 sets the ``current objfile'' to the corresponding objfile. This
4607 function returns the current objfile. If there is no current objfile,
4608 this function returns @code{None}.
4611 @findex gdb.objfiles
4612 @defun gdb.objfiles ()
4613 Return a sequence of objfiles referenced by the current program space.
4614 @xref{Objfiles In Python}, and @ref{Progspaces In Python}. This is identical
4615 to @code{gdb.selected_inferior().progspace.objfiles()} and is included for
4616 historical compatibility.
4619 @findex gdb.lookup_objfile
4620 @defun gdb.lookup_objfile (name @r{[}, by_build_id@r{]})
4621 Look up @var{name}, a file name or build ID, in the list of objfiles
4622 for the current program space (@pxref{Progspaces In Python}).
4623 If the objfile is not found throw the Python @code{ValueError} exception.
4625 If @var{name} is a relative file name, then it will match any
4626 source file name with the same trailing components. For example, if
4627 @var{name} is @samp{gcc/expr.c}, then it will match source file
4628 name of @file{/build/trunk/gcc/expr.c}, but not
4629 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
4631 If @var{by_build_id} is provided and is @code{True} then @var{name}
4632 is the build ID of the objfile. Otherwise, @var{name} is a file name.
4633 This is supported only on some operating systems, notably those which use
4634 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4635 about this feature, see the description of the @option{--build-id}
4636 command-line option in @ref{Options, , Command Line Options, ld,
4640 Each objfile is represented by an instance of the @code{gdb.Objfile}
4643 @defvar Objfile.filename
4644 The file name of the objfile as a string, with symbolic links resolved.
4646 The value is @code{None} if the objfile is no longer valid.
4647 See the @code{gdb.Objfile.is_valid} method, described below.
4650 @defvar Objfile.username
4651 The file name of the objfile as specified by the user as a string.
4653 The value is @code{None} if the objfile is no longer valid.
4654 See the @code{gdb.Objfile.is_valid} method, described below.
4657 @defvar Objfile.owner
4658 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
4659 object that debug info is being provided for.
4660 Otherwise this is @code{None}.
4661 Separate debug info objfiles are added with the
4662 @code{gdb.Objfile.add_separate_debug_file} method, described below.
4665 @defvar Objfile.build_id
4666 The build ID of the objfile as a string.
4667 If the objfile does not have a build ID then the value is @code{None}.
4669 This is supported only on some operating systems, notably those which use
4670 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4671 about this feature, see the description of the @option{--build-id}
4672 command-line option in @ref{Options, , Command Line Options, ld,
4676 @defvar Objfile.progspace
4677 The containing program space of the objfile as a @code{gdb.Progspace}
4678 object. @xref{Progspaces In Python}.
4681 @defvar Objfile.pretty_printers
4682 The @code{pretty_printers} attribute is a list of functions. It is
4683 used to look up pretty-printers. A @code{Value} is passed to each
4684 function in order; if the function returns @code{None}, then the
4685 search continues. Otherwise, the return value should be an object
4686 which is used to format the value. @xref{Pretty Printing API}, for more
4690 @defvar Objfile.type_printers
4691 The @code{type_printers} attribute is a list of type printer objects.
4692 @xref{Type Printing API}, for more information.
4695 @defvar Objfile.frame_filters
4696 The @code{frame_filters} attribute is a dictionary of frame filter
4697 objects. @xref{Frame Filter API}, for more information.
4700 One may add arbitrary attributes to @code{gdb.Objfile} objects
4701 in the usual Python way.
4702 This is useful if, for example, one needs to do some extra record keeping
4703 associated with the objfile.
4705 In this contrived example we record the time when @value{GDBN}
4711 def new_objfile_handler(event):
4712 # Set the time_loaded attribute of the new objfile.
4713 event.new_objfile.time_loaded = datetime.datetime.today()
4714 gdb.events.new_objfile.connect(new_objfile_handler)
4717 Reading symbols from ./hello...
4718 (gdb) python print gdb.objfiles()[0].time_loaded
4719 2014-10-09 11:41:36.770345
4722 A @code{gdb.Objfile} object has the following methods:
4724 @defun Objfile.is_valid ()
4725 Returns @code{True} if the @code{gdb.Objfile} object is valid,
4726 @code{False} if not. A @code{gdb.Objfile} object can become invalid
4727 if the object file it refers to is not loaded in @value{GDBN} any
4728 longer. All other @code{gdb.Objfile} methods will throw an exception
4729 if it is invalid at the time the method is called.
4732 @defun Objfile.add_separate_debug_file (file)
4733 Add @var{file} to the list of files that @value{GDBN} will search for
4734 debug information for the objfile.
4735 This is useful when the debug info has been removed from the program
4736 and stored in a separate file. @value{GDBN} has built-in support for
4737 finding separate debug info files (@pxref{Separate Debug Files}), but if
4738 the file doesn't live in one of the standard places that @value{GDBN}
4739 searches then this function can be used to add a debug info file
4740 from a different place.
4743 @defun Objfile.lookup_global_symbol (name @r{[}, domain@r{]})
4744 Search for a global symbol named @var{name} in this objfile. Optionally, the
4745 search scope can be restricted with the @var{domain} argument.
4746 The @var{domain} argument must be a domain constant defined in the @code{gdb}
4747 module and described in @ref{Symbols In Python}. This function is similar to
4748 @code{gdb.lookup_global_symbol}, except that the search is limited to this
4751 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
4755 @defun Objfile.lookup_static_symbol (name @r{[}, domain@r{]})
4756 Like @code{Objfile.lookup_global_symbol}, but searches for a global
4757 symbol with static linkage named @var{name} in this objfile.
4760 @node Frames In Python
4761 @subsubsection Accessing inferior stack frames from Python
4763 @cindex frames in python
4764 When the debugged program stops, @value{GDBN} is able to analyze its call
4765 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
4766 represents a frame in the stack. A @code{gdb.Frame} object is only valid
4767 while its corresponding frame exists in the inferior's stack. If you try
4768 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
4769 exception (@pxref{Exception Handling}).
4771 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
4775 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
4779 The following frame-related functions are available in the @code{gdb} module:
4781 @findex gdb.selected_frame
4782 @defun gdb.selected_frame ()
4783 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
4786 @findex gdb.newest_frame
4787 @defun gdb.newest_frame ()
4788 Return the newest frame object for the selected thread.
4791 @defun gdb.frame_stop_reason_string (reason)
4792 Return a string explaining the reason why @value{GDBN} stopped unwinding
4793 frames, as expressed by the given @var{reason} code (an integer, see the
4794 @code{unwind_stop_reason} method further down in this section).
4797 @findex gdb.invalidate_cached_frames
4798 @defun gdb.invalidate_cached_frames
4799 @value{GDBN} internally keeps a cache of the frames that have been
4800 unwound. This function invalidates this cache.
4802 This function should not generally be called by ordinary Python code.
4803 It is documented for the sake of completeness.
4806 A @code{gdb.Frame} object has the following methods:
4808 @defun Frame.is_valid ()
4809 Returns true if the @code{gdb.Frame} object is valid, false if not.
4810 A frame object can become invalid if the frame it refers to doesn't
4811 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
4812 an exception if it is invalid at the time the method is called.
4815 @defun Frame.name ()
4816 Returns the function name of the frame, or @code{None} if it can't be
4820 @defun Frame.architecture ()
4821 Returns the @code{gdb.Architecture} object corresponding to the frame's
4822 architecture. @xref{Architectures In Python}.
4825 @defun Frame.type ()
4826 Returns the type of the frame. The value can be one of:
4828 @item gdb.NORMAL_FRAME
4829 An ordinary stack frame.
4831 @item gdb.DUMMY_FRAME
4832 A fake stack frame that was created by @value{GDBN} when performing an
4833 inferior function call.
4835 @item gdb.INLINE_FRAME
4836 A frame representing an inlined function. The function was inlined
4837 into a @code{gdb.NORMAL_FRAME} that is older than this one.
4839 @item gdb.TAILCALL_FRAME
4840 A frame representing a tail call. @xref{Tail Call Frames}.
4842 @item gdb.SIGTRAMP_FRAME
4843 A signal trampoline frame. This is the frame created by the OS when
4844 it calls into a signal handler.
4846 @item gdb.ARCH_FRAME
4847 A fake stack frame representing a cross-architecture call.
4849 @item gdb.SENTINEL_FRAME
4850 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
4855 @defun Frame.unwind_stop_reason ()
4856 Return an integer representing the reason why it's not possible to find
4857 more frames toward the outermost frame. Use
4858 @code{gdb.frame_stop_reason_string} to convert the value returned by this
4859 function to a string. The value can be one of:
4862 @item gdb.FRAME_UNWIND_NO_REASON
4863 No particular reason (older frames should be available).
4865 @item gdb.FRAME_UNWIND_NULL_ID
4866 The previous frame's analyzer returns an invalid result. This is no
4867 longer used by @value{GDBN}, and is kept only for backward
4870 @item gdb.FRAME_UNWIND_OUTERMOST
4871 This frame is the outermost.
4873 @item gdb.FRAME_UNWIND_UNAVAILABLE
4874 Cannot unwind further, because that would require knowing the
4875 values of registers or memory that have not been collected.
4877 @item gdb.FRAME_UNWIND_INNER_ID
4878 This frame ID looks like it ought to belong to a NEXT frame,
4879 but we got it for a PREV frame. Normally, this is a sign of
4880 unwinder failure. It could also indicate stack corruption.
4882 @item gdb.FRAME_UNWIND_SAME_ID
4883 This frame has the same ID as the previous one. That means
4884 that unwinding further would almost certainly give us another
4885 frame with exactly the same ID, so break the chain. Normally,
4886 this is a sign of unwinder failure. It could also indicate
4889 @item gdb.FRAME_UNWIND_NO_SAVED_PC
4890 The frame unwinder did not find any saved PC, but we needed
4891 one to unwind further.
4893 @item gdb.FRAME_UNWIND_MEMORY_ERROR
4894 The frame unwinder caused an error while trying to access memory.
4896 @item gdb.FRAME_UNWIND_FIRST_ERROR
4897 Any stop reason greater or equal to this value indicates some kind
4898 of error. This special value facilitates writing code that tests
4899 for errors in unwinding in a way that will work correctly even if
4900 the list of the other values is modified in future @value{GDBN}
4901 versions. Using it, you could write:
4903 reason = gdb.selected_frame().unwind_stop_reason ()
4904 reason_str = gdb.frame_stop_reason_string (reason)
4905 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
4906 print ("An error occured: %s" % reason_str)
4913 Returns the frame's resume address.
4916 @defun Frame.block ()
4917 Return the frame's code block. @xref{Blocks In Python}. If the frame
4918 does not have a block -- for example, if there is no debugging
4919 information for the code in question -- then this will throw an
4923 @defun Frame.function ()
4924 Return the symbol for the function corresponding to this frame.
4925 @xref{Symbols In Python}.
4928 @defun Frame.older ()
4929 Return the frame that called this frame.
4932 @defun Frame.newer ()
4933 Return the frame called by this frame.
4936 @defun Frame.find_sal ()
4937 Return the frame's symtab and line object.
4938 @xref{Symbol Tables In Python}.
4941 @anchor{gdbpy_frame_read_register}
4942 @defun Frame.read_register (register)
4943 Return the value of @var{register} in this frame. Returns a
4944 @code{Gdb.Value} object. Throws an exception if @var{register} does
4945 not exist. The @var{register} argument must be one of the following:
4948 A string that is the name of a valid register (e.g., @code{'sp'} or
4951 A @code{gdb.RegisterDescriptor} object (@pxref{Registers In Python}).
4953 A @value{GDBN} internal, platform specific number. Using these
4954 numbers is supported for historic reasons, but is not recommended as
4955 future changes to @value{GDBN} could change the mapping between
4956 numbers and the registers they represent, breaking any Python code
4957 that uses the platform-specific numbers. The numbers are usually
4958 found in the corresponding @file{@var{platform}-tdep.h} file in the
4959 @value{GDBN} source tree.
4961 Using a string to access registers will be slightly slower than the
4962 other two methods as @value{GDBN} must look up the mapping between
4963 name and internal register number. If performance is critical
4964 consider looking up and caching a @code{gdb.RegisterDescriptor}
4968 @defun Frame.read_var (variable @r{[}, block@r{]})
4969 Return the value of @var{variable} in this frame. If the optional
4970 argument @var{block} is provided, search for the variable from that
4971 block; otherwise start at the frame's current block (which is
4972 determined by the frame's current program counter). The @var{variable}
4973 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
4974 @code{gdb.Block} object.
4977 @defun Frame.select ()
4978 Set this frame to be the selected frame. @xref{Stack, ,Examining the
4982 @defun Frame.level ()
4983 Return an integer, the stack frame level for this frame. @xref{Frames, ,Stack Frames}.
4986 @node Blocks In Python
4987 @subsubsection Accessing blocks from Python
4989 @cindex blocks in python
4992 In @value{GDBN}, symbols are stored in blocks. A block corresponds
4993 roughly to a scope in the source code. Blocks are organized
4994 hierarchically, and are represented individually in Python as a
4995 @code{gdb.Block}. Blocks rely on debugging information being
4998 A frame has a block. Please see @ref{Frames In Python}, for a more
4999 in-depth discussion of frames.
5001 The outermost block is known as the @dfn{global block}. The global
5002 block typically holds public global variables and functions.
5004 The block nested just inside the global block is the @dfn{static
5005 block}. The static block typically holds file-scoped variables and
5008 @value{GDBN} provides a method to get a block's superblock, but there
5009 is currently no way to examine the sub-blocks of a block, or to
5010 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
5013 Here is a short example that should help explain blocks:
5016 /* This is in the global block. */
5019 /* This is in the static block. */
5020 static int file_scope;
5022 /* 'function' is in the global block, and 'argument' is
5023 in a block nested inside of 'function'. */
5024 int function (int argument)
5026 /* 'local' is in a block inside 'function'. It may or may
5027 not be in the same block as 'argument'. */
5031 /* 'inner' is in a block whose superblock is the one holding
5035 /* If this call is expanded by the compiler, you may see
5036 a nested block here whose function is 'inline_function'
5037 and whose superblock is the one holding 'inner'. */
5043 A @code{gdb.Block} is iterable. The iterator returns the symbols
5044 (@pxref{Symbols In Python}) local to the block. Python programs
5045 should not assume that a specific block object will always contain a
5046 given symbol, since changes in @value{GDBN} features and
5047 infrastructure may cause symbols move across blocks in a symbol
5048 table. You can also use Python's @dfn{dictionary syntax} to access
5049 variables in this block, e.g.:
5052 symbol = some_block['variable'] # symbol is of type gdb.Symbol
5055 The following block-related functions are available in the @code{gdb}
5058 @findex gdb.block_for_pc
5059 @defun gdb.block_for_pc (pc)
5060 Return the innermost @code{gdb.Block} containing the given @var{pc}
5061 value. If the block cannot be found for the @var{pc} value specified,
5062 the function will return @code{None}. This is identical to
5063 @code{gdb.current_progspace().block_for_pc(pc)} and is included for
5064 historical compatibility.
5067 A @code{gdb.Block} object has the following methods:
5069 @defun Block.is_valid ()
5070 Returns @code{True} if the @code{gdb.Block} object is valid,
5071 @code{False} if not. A block object can become invalid if the block it
5072 refers to doesn't exist anymore in the inferior. All other
5073 @code{gdb.Block} methods will throw an exception if it is invalid at
5074 the time the method is called. The block's validity is also checked
5075 during iteration over symbols of the block.
5078 A @code{gdb.Block} object has the following attributes:
5081 The start address of the block. This attribute is not writable.
5085 One past the last address that appears in the block. This attribute
5089 @defvar Block.function
5090 The name of the block represented as a @code{gdb.Symbol}. If the
5091 block is not named, then this attribute holds @code{None}. This
5092 attribute is not writable.
5094 For ordinary function blocks, the superblock is the static block.
5095 However, you should note that it is possible for a function block to
5096 have a superblock that is not the static block -- for instance this
5097 happens for an inlined function.
5100 @defvar Block.superblock
5101 The block containing this block. If this parent block does not exist,
5102 this attribute holds @code{None}. This attribute is not writable.
5105 @defvar Block.global_block
5106 The global block associated with this block. This attribute is not
5110 @defvar Block.static_block
5111 The static block associated with this block. This attribute is not
5115 @defvar Block.is_global
5116 @code{True} if the @code{gdb.Block} object is a global block,
5117 @code{False} if not. This attribute is not
5121 @defvar Block.is_static
5122 @code{True} if the @code{gdb.Block} object is a static block,
5123 @code{False} if not. This attribute is not writable.
5126 @node Symbols In Python
5127 @subsubsection Python representation of Symbols
5129 @cindex symbols in python
5132 @value{GDBN} represents every variable, function and type as an
5133 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
5134 Similarly, Python represents these symbols in @value{GDBN} with the
5135 @code{gdb.Symbol} object.
5137 The following symbol-related functions are available in the @code{gdb}
5140 @findex gdb.lookup_symbol
5141 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
5142 This function searches for a symbol by name. The search scope can be
5143 restricted to the parameters defined in the optional domain and block
5146 @var{name} is the name of the symbol. It must be a string. The
5147 optional @var{block} argument restricts the search to symbols visible
5148 in that @var{block}. The @var{block} argument must be a
5149 @code{gdb.Block} object. If omitted, the block for the current frame
5150 is used. The optional @var{domain} argument restricts
5151 the search to the domain type. The @var{domain} argument must be a
5152 domain constant defined in the @code{gdb} module and described later
5155 The result is a tuple of two elements.
5156 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
5158 If the symbol is found, the second element is @code{True} if the symbol
5159 is a field of a method's object (e.g., @code{this} in C@t{++}),
5160 otherwise it is @code{False}.
5161 If the symbol is not found, the second element is @code{False}.
5164 @findex gdb.lookup_global_symbol
5165 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
5166 This function searches for a global symbol by name.
5167 The search scope can be restricted to by the domain argument.
5169 @var{name} is the name of the symbol. It must be a string.
5170 The optional @var{domain} argument restricts the search to the domain type.
5171 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5172 module and described later in this chapter.
5174 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
5178 @findex gdb.lookup_static_symbol
5179 @defun gdb.lookup_static_symbol (name @r{[}, domain@r{]})
5180 This function searches for a global symbol with static linkage by name.
5181 The search scope can be restricted to by the domain argument.
5183 @var{name} is the name of the symbol. It must be a string.
5184 The optional @var{domain} argument restricts the search to the domain type.
5185 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5186 module and described later in this chapter.
5188 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
5191 Note that this function will not find function-scoped static variables. To look
5192 up such variables, iterate over the variables of the function's
5193 @code{gdb.Block} and check that @code{block.addr_class} is
5194 @code{gdb.SYMBOL_LOC_STATIC}.
5196 There can be multiple global symbols with static linkage with the same
5197 name. This function will only return the first matching symbol that
5198 it finds. Which symbol is found depends on where @value{GDBN} is
5199 currently stopped, as @value{GDBN} will first search for matching
5200 symbols in the current object file, and then search all other object
5201 files. If the application is not yet running then @value{GDBN} will
5202 search all object files in the order they appear in the debug
5206 @findex gdb.lookup_static_symbols
5207 @defun gdb.lookup_static_symbols (name @r{[}, domain@r{]})
5208 Similar to @code{gdb.lookup_static_symbol}, this function searches for
5209 global symbols with static linkage by name, and optionally restricted
5210 by the domain argument. However, this function returns a list of all
5211 matching symbols found, not just the first one.
5213 @var{name} is the name of the symbol. It must be a string.
5214 The optional @var{domain} argument restricts the search to the domain type.
5215 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5216 module and described later in this chapter.
5218 The result is a list of @code{gdb.Symbol} objects which could be empty
5219 if no matching symbols were found.
5221 Note that this function will not find function-scoped static variables. To look
5222 up such variables, iterate over the variables of the function's
5223 @code{gdb.Block} and check that @code{block.addr_class} is
5224 @code{gdb.SYMBOL_LOC_STATIC}.
5227 A @code{gdb.Symbol} object has the following attributes:
5230 The type of the symbol or @code{None} if no type is recorded.
5231 This attribute is represented as a @code{gdb.Type} object.
5232 @xref{Types In Python}. This attribute is not writable.
5235 @defvar Symbol.symtab
5236 The symbol table in which the symbol appears. This attribute is
5237 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
5238 Python}. This attribute is not writable.
5242 The line number in the source code at which the symbol was defined.
5247 The name of the symbol as a string. This attribute is not writable.
5250 @defvar Symbol.linkage_name
5251 The name of the symbol, as used by the linker (i.e., may be mangled).
5252 This attribute is not writable.
5255 @defvar Symbol.print_name
5256 The name of the symbol in a form suitable for output. This is either
5257 @code{name} or @code{linkage_name}, depending on whether the user
5258 asked @value{GDBN} to display demangled or mangled names.
5261 @defvar Symbol.addr_class
5262 The address class of the symbol. This classifies how to find the value
5263 of a symbol. Each address class is a constant defined in the
5264 @code{gdb} module and described later in this chapter.
5267 @defvar Symbol.needs_frame
5268 This is @code{True} if evaluating this symbol's value requires a frame
5269 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
5270 local variables will require a frame, but other symbols will not.
5273 @defvar Symbol.is_argument
5274 @code{True} if the symbol is an argument of a function.
5277 @defvar Symbol.is_constant
5278 @code{True} if the symbol is a constant.
5281 @defvar Symbol.is_function
5282 @code{True} if the symbol is a function or a method.
5285 @defvar Symbol.is_variable
5286 @code{True} if the symbol is a variable.
5289 A @code{gdb.Symbol} object has the following methods:
5291 @defun Symbol.is_valid ()
5292 Returns @code{True} if the @code{gdb.Symbol} object is valid,
5293 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
5294 the symbol it refers to does not exist in @value{GDBN} any longer.
5295 All other @code{gdb.Symbol} methods will throw an exception if it is
5296 invalid at the time the method is called.
5299 @defun Symbol.value (@r{[}frame@r{]})
5300 Compute the value of the symbol, as a @code{gdb.Value}. For
5301 functions, this computes the address of the function, cast to the
5302 appropriate type. If the symbol requires a frame in order to compute
5303 its value, then @var{frame} must be given. If @var{frame} is not
5304 given, or if @var{frame} is invalid, then this method will throw an
5308 The available domain categories in @code{gdb.Symbol} are represented
5309 as constants in the @code{gdb} module:
5312 @vindex SYMBOL_UNDEF_DOMAIN
5313 @item gdb.SYMBOL_UNDEF_DOMAIN
5314 This is used when a domain has not been discovered or none of the
5315 following domains apply. This usually indicates an error either
5316 in the symbol information or in @value{GDBN}'s handling of symbols.
5318 @vindex SYMBOL_VAR_DOMAIN
5319 @item gdb.SYMBOL_VAR_DOMAIN
5320 This domain contains variables, function names, typedef names and enum
5323 @vindex SYMBOL_STRUCT_DOMAIN
5324 @item gdb.SYMBOL_STRUCT_DOMAIN
5325 This domain holds struct, union and enum type names.
5327 @vindex SYMBOL_LABEL_DOMAIN
5328 @item gdb.SYMBOL_LABEL_DOMAIN
5329 This domain contains names of labels (for gotos).
5331 @vindex SYMBOL_MODULE_DOMAIN
5332 @item gdb.SYMBOL_MODULE_DOMAIN
5333 This domain contains names of Fortran module types.
5335 @vindex SYMBOL_COMMON_BLOCK_DOMAIN
5336 @item gdb.SYMBOL_COMMON_BLOCK_DOMAIN
5337 This domain contains names of Fortran common blocks.
5340 The available address class categories in @code{gdb.Symbol} are represented
5341 as constants in the @code{gdb} module:
5344 @vindex SYMBOL_LOC_UNDEF
5345 @item gdb.SYMBOL_LOC_UNDEF
5346 If this is returned by address class, it indicates an error either in
5347 the symbol information or in @value{GDBN}'s handling of symbols.
5349 @vindex SYMBOL_LOC_CONST
5350 @item gdb.SYMBOL_LOC_CONST
5351 Value is constant int.
5353 @vindex SYMBOL_LOC_STATIC
5354 @item gdb.SYMBOL_LOC_STATIC
5355 Value is at a fixed address.
5357 @vindex SYMBOL_LOC_REGISTER
5358 @item gdb.SYMBOL_LOC_REGISTER
5359 Value is in a register.
5361 @vindex SYMBOL_LOC_ARG
5362 @item gdb.SYMBOL_LOC_ARG
5363 Value is an argument. This value is at the offset stored within the
5364 symbol inside the frame's argument list.
5366 @vindex SYMBOL_LOC_REF_ARG
5367 @item gdb.SYMBOL_LOC_REF_ARG
5368 Value address is stored in the frame's argument list. Just like
5369 @code{LOC_ARG} except that the value's address is stored at the
5370 offset, not the value itself.
5372 @vindex SYMBOL_LOC_REGPARM_ADDR
5373 @item gdb.SYMBOL_LOC_REGPARM_ADDR
5374 Value is a specified register. Just like @code{LOC_REGISTER} except
5375 the register holds the address of the argument instead of the argument
5378 @vindex SYMBOL_LOC_LOCAL
5379 @item gdb.SYMBOL_LOC_LOCAL
5380 Value is a local variable.
5382 @vindex SYMBOL_LOC_TYPEDEF
5383 @item gdb.SYMBOL_LOC_TYPEDEF
5384 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
5387 @vindex SYMBOL_LOC_LABEL
5388 @item gdb.SYMBOL_LOC_LABEL
5391 @vindex SYMBOL_LOC_BLOCK
5392 @item gdb.SYMBOL_LOC_BLOCK
5395 @vindex SYMBOL_LOC_CONST_BYTES
5396 @item gdb.SYMBOL_LOC_CONST_BYTES
5397 Value is a byte-sequence.
5399 @vindex SYMBOL_LOC_UNRESOLVED
5400 @item gdb.SYMBOL_LOC_UNRESOLVED
5401 Value is at a fixed address, but the address of the variable has to be
5402 determined from the minimal symbol table whenever the variable is
5405 @vindex SYMBOL_LOC_OPTIMIZED_OUT
5406 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
5407 The value does not actually exist in the program.
5409 @vindex SYMBOL_LOC_COMPUTED
5410 @item gdb.SYMBOL_LOC_COMPUTED
5411 The value's address is a computed location.
5413 @vindex SYMBOL_LOC_COMMON_BLOCK
5414 @item gdb.SYMBOL_LOC_COMMON_BLOCK
5415 The value's address is a symbol. This is only used for Fortran common
5419 @node Symbol Tables In Python
5420 @subsubsection Symbol table representation in Python
5422 @cindex symbol tables in python
5424 @tindex gdb.Symtab_and_line
5426 Access to symbol table data maintained by @value{GDBN} on the inferior
5427 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
5428 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
5429 from the @code{find_sal} method in @code{gdb.Frame} object.
5430 @xref{Frames In Python}.
5432 For more information on @value{GDBN}'s symbol table management, see
5433 @ref{Symbols, ,Examining the Symbol Table}, for more information.
5435 A @code{gdb.Symtab_and_line} object has the following attributes:
5437 @defvar Symtab_and_line.symtab
5438 The symbol table object (@code{gdb.Symtab}) for this frame.
5439 This attribute is not writable.
5442 @defvar Symtab_and_line.pc
5443 Indicates the start of the address range occupied by code for the
5444 current source line. This attribute is not writable.
5447 @defvar Symtab_and_line.last
5448 Indicates the end of the address range occupied by code for the current
5449 source line. This attribute is not writable.
5452 @defvar Symtab_and_line.line
5453 Indicates the current line number for this object. This
5454 attribute is not writable.
5457 A @code{gdb.Symtab_and_line} object has the following methods:
5459 @defun Symtab_and_line.is_valid ()
5460 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
5461 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
5462 invalid if the Symbol table and line object it refers to does not
5463 exist in @value{GDBN} any longer. All other
5464 @code{gdb.Symtab_and_line} methods will throw an exception if it is
5465 invalid at the time the method is called.
5468 A @code{gdb.Symtab} object has the following attributes:
5470 @defvar Symtab.filename
5471 The symbol table's source filename. This attribute is not writable.
5474 @defvar Symtab.objfile
5475 The symbol table's backing object file. @xref{Objfiles In Python}.
5476 This attribute is not writable.
5479 @defvar Symtab.producer
5480 The name and possibly version number of the program that
5481 compiled the code in the symbol table.
5482 The contents of this string is up to the compiler.
5483 If no producer information is available then @code{None} is returned.
5484 This attribute is not writable.
5487 A @code{gdb.Symtab} object has the following methods:
5489 @defun Symtab.is_valid ()
5490 Returns @code{True} if the @code{gdb.Symtab} object is valid,
5491 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
5492 the symbol table it refers to does not exist in @value{GDBN} any
5493 longer. All other @code{gdb.Symtab} methods will throw an exception
5494 if it is invalid at the time the method is called.
5497 @defun Symtab.fullname ()
5498 Return the symbol table's source absolute file name.
5501 @defun Symtab.global_block ()
5502 Return the global block of the underlying symbol table.
5503 @xref{Blocks In Python}.
5506 @defun Symtab.static_block ()
5507 Return the static block of the underlying symbol table.
5508 @xref{Blocks In Python}.
5511 @defun Symtab.linetable ()
5512 Return the line table associated with the symbol table.
5513 @xref{Line Tables In Python}.
5516 @node Line Tables In Python
5517 @subsubsection Manipulating line tables using Python
5519 @cindex line tables in python
5520 @tindex gdb.LineTable
5522 Python code can request and inspect line table information from a
5523 symbol table that is loaded in @value{GDBN}. A line table is a
5524 mapping of source lines to their executable locations in memory. To
5525 acquire the line table information for a particular symbol table, use
5526 the @code{linetable} function (@pxref{Symbol Tables In Python}).
5528 A @code{gdb.LineTable} is iterable. The iterator returns
5529 @code{LineTableEntry} objects that correspond to the source line and
5530 address for each line table entry. @code{LineTableEntry} objects have
5531 the following attributes:
5533 @defvar LineTableEntry.line
5534 The source line number for this line table entry. This number
5535 corresponds to the actual line of source. This attribute is not
5539 @defvar LineTableEntry.pc
5540 The address that is associated with the line table entry where the
5541 executable code for that source line resides in memory. This
5542 attribute is not writable.
5545 As there can be multiple addresses for a single source line, you may
5546 receive multiple @code{LineTableEntry} objects with matching
5547 @code{line} attributes, but with different @code{pc} attributes. The
5548 iterator is sorted in ascending @code{pc} order. Here is a small
5549 example illustrating iterating over a line table.
5552 symtab = gdb.selected_frame().find_sal().symtab
5553 linetable = symtab.linetable()
5554 for line in linetable:
5555 print ("Line: "+str(line.line)+" Address: "+hex(line.pc))
5558 This will have the following output:
5561 Line: 33 Address: 0x4005c8L
5562 Line: 37 Address: 0x4005caL
5563 Line: 39 Address: 0x4005d2L
5564 Line: 40 Address: 0x4005f8L
5565 Line: 42 Address: 0x4005ffL
5566 Line: 44 Address: 0x400608L
5567 Line: 42 Address: 0x40060cL
5568 Line: 45 Address: 0x400615L
5571 In addition to being able to iterate over a @code{LineTable}, it also
5572 has the following direct access methods:
5574 @defun LineTable.line (line)
5575 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
5576 entries in the line table for the given @var{line}, which specifies
5577 the source code line. If there are no entries for that source code
5578 @var{line}, the Python @code{None} is returned.
5581 @defun LineTable.has_line (line)
5582 Return a Python @code{Boolean} indicating whether there is an entry in
5583 the line table for this source line. Return @code{True} if an entry
5584 is found, or @code{False} if not.
5587 @defun LineTable.source_lines ()
5588 Return a Python @code{List} of the source line numbers in the symbol
5589 table. Only lines with executable code locations are returned. The
5590 contents of the @code{List} will just be the source line entries
5591 represented as Python @code{Long} values.
5594 @node Breakpoints In Python
5595 @subsubsection Manipulating breakpoints using Python
5597 @cindex breakpoints in python
5598 @tindex gdb.Breakpoint
5600 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
5603 A breakpoint can be created using one of the two forms of the
5604 @code{gdb.Breakpoint} constructor. The first one accepts a string
5605 like one would pass to the @code{break}
5606 (@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
5607 (@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
5608 create both breakpoints and watchpoints. The second accepts separate Python
5609 arguments similar to @ref{Explicit Locations}, and can only be used to create
5612 @defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]})
5613 Create a new breakpoint according to @var{spec}, which is a string naming the
5614 location of a breakpoint, or an expression that defines a watchpoint. The
5615 string should describe a location in a format recognized by the @code{break}
5616 command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
5617 watchpoint, by the @code{watch} command
5618 (@pxref{Set Watchpoints, , Setting Watchpoints}).
5620 The optional @var{type} argument specifies the type of the breakpoint to create,
5623 The optional @var{wp_class} argument defines the class of watchpoint to create,
5624 if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
5625 defaults to @code{gdb.WP_WRITE}.
5627 The optional @var{internal} argument allows the breakpoint to become invisible
5628 to the user. The breakpoint will neither be reported when created, nor will it
5629 be listed in the output from @code{info breakpoints} (but will be listed with
5630 the @code{maint info breakpoints} command).
5632 The optional @var{temporary} argument makes the breakpoint a temporary
5633 breakpoint. Temporary breakpoints are deleted after they have been hit. Any
5634 further access to the Python breakpoint after it has been hit will result in a
5635 runtime error (as that breakpoint has now been automatically deleted).
5637 The optional @var{qualified} argument is a boolean that allows interpreting
5638 the function passed in @code{spec} as a fully-qualified name. It is equivalent
5639 to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
5640 @ref{Explicit Locations}).
5644 @defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]})
5645 This second form of creating a new breakpoint specifies the explicit
5646 location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
5647 be created in the specified source file @var{source}, at the specified
5648 @var{function}, @var{label} and @var{line}.
5650 @var{internal}, @var{temporary} and @var{qualified} have the same usage as
5651 explained previously.
5654 The available types are represented by constants defined in the @code{gdb}
5658 @vindex BP_BREAKPOINT
5659 @item gdb.BP_BREAKPOINT
5660 Normal code breakpoint.
5662 @vindex BP_HARDWARE_BREAKPOINT
5663 @item gdb.BP_HARDWARE_BREAKPOINT
5664 Hardware assisted code breakpoint.
5666 @vindex BP_WATCHPOINT
5667 @item gdb.BP_WATCHPOINT
5668 Watchpoint breakpoint.
5670 @vindex BP_HARDWARE_WATCHPOINT
5671 @item gdb.BP_HARDWARE_WATCHPOINT
5672 Hardware assisted watchpoint.
5674 @vindex BP_READ_WATCHPOINT
5675 @item gdb.BP_READ_WATCHPOINT
5676 Hardware assisted read watchpoint.
5678 @vindex BP_ACCESS_WATCHPOINT
5679 @item gdb.BP_ACCESS_WATCHPOINT
5680 Hardware assisted access watchpoint.
5682 @vindex BP_CATCHPOINT
5683 @item gdb.BP_CATCHPOINT
5684 Catchpoint. Currently, this type can't be used when creating
5685 @code{gdb.Breakpoint} objects, but will be present in
5686 @code{gdb.Breakpoint} objects reported from
5687 @code{gdb.BreakpointEvent}s (@pxref{Events In Python}).
5690 The available watchpoint types are represented by constants defined in the
5696 Read only watchpoint.
5700 Write only watchpoint.
5704 Read/Write watchpoint.
5707 @defun Breakpoint.stop (self)
5708 The @code{gdb.Breakpoint} class can be sub-classed and, in
5709 particular, you may choose to implement the @code{stop} method.
5710 If this method is defined in a sub-class of @code{gdb.Breakpoint},
5711 it will be called when the inferior reaches any location of a
5712 breakpoint which instantiates that sub-class. If the method returns
5713 @code{True}, the inferior will be stopped at the location of the
5714 breakpoint, otherwise the inferior will continue.
5716 If there are multiple breakpoints at the same location with a
5717 @code{stop} method, each one will be called regardless of the
5718 return status of the previous. This ensures that all @code{stop}
5719 methods have a chance to execute at that location. In this scenario
5720 if one of the methods returns @code{True} but the others return
5721 @code{False}, the inferior will still be stopped.
5723 You should not alter the execution state of the inferior (i.e.@:, step,
5724 next, etc.), alter the current frame context (i.e.@:, change the current
5725 active frame), or alter, add or delete any breakpoint. As a general
5726 rule, you should not alter any data within @value{GDBN} or the inferior
5729 Example @code{stop} implementation:
5732 class MyBreakpoint (gdb.Breakpoint):
5734 inf_val = gdb.parse_and_eval("foo")
5741 @defun Breakpoint.is_valid ()
5742 Return @code{True} if this @code{Breakpoint} object is valid,
5743 @code{False} otherwise. A @code{Breakpoint} object can become invalid
5744 if the user deletes the breakpoint. In this case, the object still
5745 exists, but the underlying breakpoint does not. In the cases of
5746 watchpoint scope, the watchpoint remains valid even if execution of the
5747 inferior leaves the scope of that watchpoint.
5750 @defun Breakpoint.delete ()
5751 Permanently deletes the @value{GDBN} breakpoint. This also
5752 invalidates the Python @code{Breakpoint} object. Any further access
5753 to this object's attributes or methods will raise an error.
5756 @defvar Breakpoint.enabled
5757 This attribute is @code{True} if the breakpoint is enabled, and
5758 @code{False} otherwise. This attribute is writable. You can use it to enable
5759 or disable the breakpoint.
5762 @defvar Breakpoint.silent
5763 This attribute is @code{True} if the breakpoint is silent, and
5764 @code{False} otherwise. This attribute is writable.
5766 Note that a breakpoint can also be silent if it has commands and the
5767 first command is @code{silent}. This is not reported by the
5768 @code{silent} attribute.
5771 @defvar Breakpoint.pending
5772 This attribute is @code{True} if the breakpoint is pending, and
5773 @code{False} otherwise. @xref{Set Breaks}. This attribute is
5777 @anchor{python_breakpoint_thread}
5778 @defvar Breakpoint.thread
5779 If the breakpoint is thread-specific, this attribute holds the
5780 thread's global id. If the breakpoint is not thread-specific, this
5781 attribute is @code{None}. This attribute is writable.
5784 @defvar Breakpoint.task
5785 If the breakpoint is Ada task-specific, this attribute holds the Ada task
5786 id. If the breakpoint is not task-specific (or the underlying
5787 language is not Ada), this attribute is @code{None}. This attribute
5791 @defvar Breakpoint.ignore_count
5792 This attribute holds the ignore count for the breakpoint, an integer.
5793 This attribute is writable.
5796 @defvar Breakpoint.number
5797 This attribute holds the breakpoint's number --- the identifier used by
5798 the user to manipulate the breakpoint. This attribute is not writable.
5801 @defvar Breakpoint.type
5802 This attribute holds the breakpoint's type --- the identifier used to
5803 determine the actual breakpoint type or use-case. This attribute is not
5807 @defvar Breakpoint.visible
5808 This attribute tells whether the breakpoint is visible to the user
5809 when set, or when the @samp{info breakpoints} command is run. This
5810 attribute is not writable.
5813 @defvar Breakpoint.temporary
5814 This attribute indicates whether the breakpoint was created as a
5815 temporary breakpoint. Temporary breakpoints are automatically deleted
5816 after that breakpoint has been hit. Access to this attribute, and all
5817 other attributes and functions other than the @code{is_valid}
5818 function, will result in an error after the breakpoint has been hit
5819 (as it has been automatically deleted). This attribute is not
5823 @defvar Breakpoint.hit_count
5824 This attribute holds the hit count for the breakpoint, an integer.
5825 This attribute is writable, but currently it can only be set to zero.
5828 @defvar Breakpoint.location
5829 This attribute holds the location of the breakpoint, as specified by
5830 the user. It is a string. If the breakpoint does not have a location
5831 (that is, it is a watchpoint) the attribute's value is @code{None}. This
5832 attribute is not writable.
5835 @defvar Breakpoint.expression
5836 This attribute holds a breakpoint expression, as specified by
5837 the user. It is a string. If the breakpoint does not have an
5838 expression (the breakpoint is not a watchpoint) the attribute's value
5839 is @code{None}. This attribute is not writable.
5842 @defvar Breakpoint.condition
5843 This attribute holds the condition of the breakpoint, as specified by
5844 the user. It is a string. If there is no condition, this attribute's
5845 value is @code{None}. This attribute is writable.
5848 @defvar Breakpoint.commands
5849 This attribute holds the commands attached to the breakpoint. If
5850 there are commands, this attribute's value is a string holding all the
5851 commands, separated by newlines. If there are no commands, this
5852 attribute is @code{None}. This attribute is writable.
5855 @node Finish Breakpoints in Python
5856 @subsubsection Finish Breakpoints
5858 @cindex python finish breakpoints
5859 @tindex gdb.FinishBreakpoint
5861 A finish breakpoint is a temporary breakpoint set at the return address of
5862 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
5863 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
5864 and deleted when the execution will run out of the breakpoint scope (i.e.@:
5865 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
5866 Finish breakpoints are thread specific and must be create with the right
5869 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
5870 Create a finish breakpoint at the return address of the @code{gdb.Frame}
5871 object @var{frame}. If @var{frame} is not provided, this defaults to the
5872 newest frame. The optional @var{internal} argument allows the breakpoint to
5873 become invisible to the user. @xref{Breakpoints In Python}, for further
5874 details about this argument.
5877 @defun FinishBreakpoint.out_of_scope (self)
5878 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
5879 @code{return} command, @dots{}), a function may not properly terminate, and
5880 thus never hit the finish breakpoint. When @value{GDBN} notices such a
5881 situation, the @code{out_of_scope} callback will be triggered.
5883 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
5887 class MyFinishBreakpoint (gdb.FinishBreakpoint)
5889 print ("normal finish")
5892 def out_of_scope ():
5893 print ("abnormal finish")
5897 @defvar FinishBreakpoint.return_value
5898 When @value{GDBN} is stopped at a finish breakpoint and the frame
5899 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
5900 attribute will contain a @code{gdb.Value} object corresponding to the return
5901 value of the function. The value will be @code{None} if the function return
5902 type is @code{void} or if the return value was not computable. This attribute
5906 @node Lazy Strings In Python
5907 @subsubsection Python representation of lazy strings
5909 @cindex lazy strings in python
5910 @tindex gdb.LazyString
5912 A @dfn{lazy string} is a string whose contents is not retrieved or
5913 encoded until it is needed.
5915 A @code{gdb.LazyString} is represented in @value{GDBN} as an
5916 @code{address} that points to a region of memory, an @code{encoding}
5917 that will be used to encode that region of memory, and a @code{length}
5918 to delimit the region of memory that represents the string. The
5919 difference between a @code{gdb.LazyString} and a string wrapped within
5920 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
5921 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
5922 retrieved and encoded during printing, while a @code{gdb.Value}
5923 wrapping a string is immediately retrieved and encoded on creation.
5925 A @code{gdb.LazyString} object has the following functions:
5927 @defun LazyString.value ()
5928 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
5929 will point to the string in memory, but will lose all the delayed
5930 retrieval, encoding and handling that @value{GDBN} applies to a
5931 @code{gdb.LazyString}.
5934 @defvar LazyString.address
5935 This attribute holds the address of the string. This attribute is not
5939 @defvar LazyString.length
5940 This attribute holds the length of the string in characters. If the
5941 length is -1, then the string will be fetched and encoded up to the
5942 first null of appropriate width. This attribute is not writable.
5945 @defvar LazyString.encoding
5946 This attribute holds the encoding that will be applied to the string
5947 when the string is printed by @value{GDBN}. If the encoding is not
5948 set, or contains an empty string, then @value{GDBN} will select the
5949 most appropriate encoding when the string is printed. This attribute
5953 @defvar LazyString.type
5954 This attribute holds the type that is represented by the lazy string's
5955 type. For a lazy string this is a pointer or array type. To
5956 resolve this to the lazy string's character type, use the type's
5957 @code{target} method. @xref{Types In Python}. This attribute is not
5961 @node Architectures In Python
5962 @subsubsection Python representation of architectures
5963 @cindex Python architectures
5965 @value{GDBN} uses architecture specific parameters and artifacts in a
5966 number of its various computations. An architecture is represented
5967 by an instance of the @code{gdb.Architecture} class.
5969 A @code{gdb.Architecture} class has the following methods:
5971 @anchor{gdbpy_architecture_name}
5972 @defun Architecture.name ()
5973 Return the name (string value) of the architecture.
5976 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
5977 Return a list of disassembled instructions starting from the memory
5978 address @var{start_pc}. The optional arguments @var{end_pc} and
5979 @var{count} determine the number of instructions in the returned list.
5980 If both the optional arguments @var{end_pc} and @var{count} are
5981 specified, then a list of at most @var{count} disassembled instructions
5982 whose start address falls in the closed memory address interval from
5983 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
5984 specified, but @var{count} is specified, then @var{count} number of
5985 instructions starting from the address @var{start_pc} are returned. If
5986 @var{count} is not specified but @var{end_pc} is specified, then all
5987 instructions whose start address falls in the closed memory address
5988 interval from @var{start_pc} to @var{end_pc} are returned. If neither
5989 @var{end_pc} nor @var{count} are specified, then a single instruction at
5990 @var{start_pc} is returned. For all of these cases, each element of the
5991 returned list is a Python @code{dict} with the following string keys:
5996 The value corresponding to this key is a Python long integer capturing
5997 the memory address of the instruction.
6000 The value corresponding to this key is a string value which represents
6001 the instruction with assembly language mnemonics. The assembly
6002 language flavor used is the same as that specified by the current CLI
6003 variable @code{disassembly-flavor}. @xref{Machine Code}.
6006 The value corresponding to this key is the length (integer value) of the
6007 instruction in bytes.
6012 @findex Architecture.integer_type
6013 @defun Architecture.integer_type (size @r{[}, signed@r{]})
6014 This function looks up an integer type by its @var{size}, and
6015 optionally whether or not it is signed.
6017 @var{size} is the size, in bits, of the desired integer type. Only
6018 certain sizes are currently supported: 0, 8, 16, 24, 32, 64, and 128.
6020 If @var{signed} is not specified, it defaults to @code{True}. If
6021 @var{signed} is @code{False}, the returned type will be unsigned.
6023 If the indicated type cannot be found, this function will throw a
6024 @code{ValueError} exception.
6027 @anchor{gdbpy_architecture_registers}
6028 @defun Architecture.registers (@r{[} @var{reggroup} @r{]})
6029 Return a @code{gdb.RegisterDescriptorIterator} (@pxref{Registers In
6030 Python}) for all of the registers in @var{reggroup}, a string that is
6031 the name of a register group. If @var{reggroup} is omitted, or is the
6032 empty string, then the register group @samp{all} is assumed.
6035 @anchor{gdbpy_architecture_reggroups}
6036 @defun Architecture.register_groups ()
6037 Return a @code{gdb.RegisterGroupsIterator} (@pxref{Registers In
6038 Python}) for all of the register groups available for the
6039 @code{gdb.Architecture}.
6042 @node Registers In Python
6043 @subsubsection Registers In Python
6044 @cindex Registers In Python
6046 Python code can request from a @code{gdb.Architecture} information
6047 about the set of registers available
6048 (@pxref{gdbpy_architecture_registers,,@code{Architecture.registers}}).
6049 The register information is returned as a
6050 @code{gdb.RegisterDescriptorIterator}, which is an iterator that in
6051 turn returns @code{gdb.RegisterDescriptor} objects.
6053 A @code{gdb.RegisterDescriptor} does not provide the value of a
6054 register (@pxref{gdbpy_frame_read_register,,@code{Frame.read_register}}
6055 for reading a register's value), instead the @code{RegisterDescriptor}
6056 is a way to discover which registers are available for a particular
6059 A @code{gdb.RegisterDescriptor} has the following read-only properties:
6061 @defvar RegisterDescriptor.name
6062 The name of this register.
6065 It is also possible to lookup a register descriptor based on its name
6066 using the following @code{gdb.RegisterDescriptorIterator} function:
6068 @defun RegisterDescriptorIterator.find (@var{name})
6069 Takes @var{name} as an argument, which must be a string, and returns a
6070 @code{gdb.RegisterDescriptor} for the register with that name, or
6071 @code{None} if there is no register with that name.
6074 Python code can also request from a @code{gdb.Architecture}
6075 information about the set of register groups available on a given
6077 (@pxref{gdbpy_architecture_reggroups,,@code{Architecture.register_groups}}).
6079 Every register can be a member of zero or more register groups. Some
6080 register groups are used internally within @value{GDBN} to control
6081 things like which registers must be saved when calling into the
6082 program being debugged (@pxref{Calling,,Calling Program Functions}).
6083 Other register groups exist to allow users to easily see related sets
6084 of registers in commands like @code{info registers}
6085 (@pxref{info_registers_reggroup,,@code{info registers
6088 The register groups information is returned as a
6089 @code{gdb.RegisterGroupsIterator}, which is an iterator that in turn
6090 returns @code{gdb.RegisterGroup} objects.
6092 A @code{gdb.RegisterGroup} object has the following read-only
6095 @defvar RegisterGroup.name
6096 A string that is the name of this register group.
6099 @node Connections In Python
6100 @subsubsection Connections In Python
6101 @cindex connections in python
6102 @value{GDBN} lets you run and debug multiple programs in a single
6103 session. Each program being debugged has a connection, the connection
6104 describes how @value{GDBN} controls the program being debugged.
6105 Examples of different connection types are @samp{native} and
6106 @samp{remote}. @xref{Inferiors Connections and Programs}.
6108 Connections in @value{GDBN} are represented as instances of
6109 @code{gdb.TargetConnection}, or as one of its sub-classes. To get a
6110 list of all connections use @code{gdb.connections}
6111 (@pxref{gdbpy_connections,,gdb.connections}).
6113 To get the connection for a single @code{gdb.Inferior} read its
6114 @code{gdb.Inferior.connection} attribute
6115 (@pxref{gdbpy_inferior_connection,,gdb.Inferior.connection}).
6117 Currently there is only a single sub-class of
6118 @code{gdb.TargetConnection}, @code{gdb.RemoteTargetConnection},
6119 however, additional sub-classes may be added in future releases of
6120 @value{GDBN}. As a result you should avoid writing code like:
6123 conn = gdb.selected_inferior().connection
6124 if type(conn) is gdb.RemoteTargetConnection:
6125 print("This is a remote target connection")
6129 as this may fail when more connection types are added. Instead, you
6133 conn = gdb.selected_inferior().connection
6134 if isinstance(conn, gdb.RemoteTargetConnection):
6135 print("This is a remote target connection")
6138 A @code{gdb.TargetConnection} has the following method:
6140 @defun TargetConnection.is_valid ()
6141 Return @code{True} if the @code{gdb.TargetConnection} object is valid,
6142 @code{False} if not. A @code{gdb.TargetConnection} will become
6143 invalid if the connection no longer exists within @value{GDBN}, this
6144 might happen when no inferiors are using the connection, but could be
6145 delayed until the user replaces the current target.
6147 Reading any of the @code{gdb.TargetConnection} properties will throw
6148 an exception if the connection is invalid.
6151 A @code{gdb.TargetConnection} has the following read-only properties:
6153 @defvar TargetConnection.num
6154 An integer assigned by @value{GDBN} to uniquely identify this
6155 connection. This is the same value as displayed in the @samp{Num}
6156 column of the @code{info connections} command output (@pxref{Inferiors
6157 Connections and Programs,,info connections}).
6160 @defvar TargetConnection.type
6161 A string that describes what type of connection this is. This string
6162 will be one of the valid names that can be passed to the @code{target}
6163 command (@pxref{Target Commands,,target command}).
6166 @defvar TargetConnection.description
6167 A string that gives a short description of this target type. This is
6168 the same string that is displayed in the @samp{Description} column of
6169 the @code{info connection} command output (@pxref{Inferiors
6170 Connections and Programs,,info connections}).
6173 @defvar TargetConnection.details
6174 An optional string that gives additional information about this
6175 connection. This attribute can be @code{None} if there are no
6176 additional details for this connection.
6178 An example of a connection type that might have additional details is
6179 the @samp{remote} connection, in this case the details string can
6180 contain the @samp{@var{hostname}:@var{port}} that was used to connect
6181 to the remote target.
6184 The @code{gdb.RemoteTargetConnection} class is a sub-class of
6185 @code{gdb.TargetConnection}, and is used to represent @samp{remote}
6186 and @samp{extended-remote} connections. In addition to the attributes
6187 and methods available from the @code{gdb.TargetConnection} base class,
6188 a @code{gdb.RemoteTargetConnection} has the following method:
6190 @kindex maint packet
6191 @defun RemoteTargetConnection.send_packet (@var{packet})
6192 This method sends @var{packet} to the remote target and returns the
6193 response. The @var{packet} should either be a @code{bytes} object, or
6194 a @code{Unicode} string.
6196 If @var{packet} is a @code{Unicode} string, then the string is encoded
6197 to a @code{bytes} object using the @sc{ascii} codec. If the string
6198 can't be encoded then an @code{UnicodeError} is raised.
6200 If @var{packet} is not a @code{bytes} object, or a @code{Unicode}
6201 string, then a @code{TypeError} is raised. If @var{packet} is empty
6202 then a @code{ValueError} is raised.
6204 The response is returned as a @code{bytes} object. For Python 3 if it
6205 is known that the response can be represented as a string then this
6206 can be decoded from the buffer. For example, if it is known that the
6207 response is an @sc{ascii} string:
6210 remote_connection.send_packet("some_packet").decode("ascii")
6213 In Python 2 @code{bytes} and @code{str} are aliases, so the result is
6214 already a string, if the response includes non-printable characters,
6215 or null characters, then these will be present in the result, care
6216 should be taken when processing the result to handle this case.
6218 The prefix, suffix, and checksum (as required by the remote serial
6219 protocol) are automatically added to the outgoing packet, and removed
6220 from the incoming packet before the contents of the reply are
6223 This is equivalent to the @code{maintenance packet} command
6224 (@pxref{maint packet}).
6227 @node TUI Windows In Python
6228 @subsubsection Implementing new TUI windows
6229 @cindex Python TUI Windows
6231 New TUI (@pxref{TUI}) windows can be implemented in Python.
6233 @findex gdb.register_window_type
6234 @defun gdb.register_window_type (@var{name}, @var{factory})
6235 Because TUI windows are created and destroyed depending on the layout
6236 the user chooses, new window types are implemented by registering a
6237 factory function with @value{GDBN}.
6239 @var{name} is the name of the new window. It's an error to try to
6240 replace one of the built-in windows, but other window types can be
6243 @var{function} is a factory function that is called to create the TUI
6244 window. This is called with a single argument of type
6245 @code{gdb.TuiWindow}, described below. It should return an object
6246 that implements the TUI window protocol, also described below.
6249 As mentioned above, when a factory function is called, it is passed
6250 an object of type @code{gdb.TuiWindow}. This object has these
6251 methods and attributes:
6253 @defun TuiWindow.is_valid ()
6254 This method returns @code{True} when this window is valid. When the
6255 user changes the TUI layout, windows no longer visible in the new
6256 layout will be destroyed. At this point, the @code{gdb.TuiWindow}
6257 will no longer be valid, and methods (and attributes) other than
6258 @code{is_valid} will throw an exception.
6260 When the TUI is disabled using @code{tui disable} (@pxref{TUI
6261 Commands,,tui disable}) the window is hidden rather than destroyed,
6262 but @code{is_valid} will still return @code{False} and other methods
6263 (and attributes) will still throw an exception.
6266 @defvar TuiWindow.width
6267 This attribute holds the width of the window. It is not writable.
6270 @defvar TuiWindow.height
6271 This attribute holds the height of the window. It is not writable.
6274 @defvar TuiWindow.title
6275 This attribute holds the window's title, a string. This is normally
6276 displayed above the window. This attribute can be modified.
6279 @defun TuiWindow.erase ()
6280 Remove all the contents of the window.
6283 @defun TuiWindow.write (@var{string} @r{[}, @var{full_window}@r{]})
6284 Write @var{string} to the window. @var{string} can contain ANSI
6285 terminal escape styling sequences; @value{GDBN} will translate these
6286 as appropriate for the terminal.
6288 If the @var{full_window} parameter is @code{True}, then @var{string}
6289 contains the full contents of the window. This is similar to calling
6290 @code{erase} before @code{write}, but avoids the flickering.
6293 The factory function that you supply should return an object
6294 conforming to the TUI window protocol. These are the method that can
6295 be called on this object, which is referred to below as the ``window
6296 object''. The methods documented below are optional; if the object
6297 does not implement one of these methods, @value{GDBN} will not attempt
6298 to call it. Additional new methods may be added to the window
6299 protocol in the future. @value{GDBN} guarantees that they will begin
6300 with a lower-case letter, so you can start implementation methods with
6301 upper-case letters or underscore to avoid any future conflicts.
6303 @defun Window.close ()
6304 When the TUI window is closed, the @code{gdb.TuiWindow} object will be
6305 put into an invalid state. At this time, @value{GDBN} will call
6306 @code{close} method on the window object.
6308 After this method is called, @value{GDBN} will discard any references
6309 it holds on this window object, and will no longer call methods on
6313 @defun Window.render ()
6314 In some situations, a TUI window can change size. For example, this
6315 can happen if the user resizes the terminal, or changes the layout.
6316 When this happens, @value{GDBN} will call the @code{render} method on
6319 If your window is intended to update in response to changes in the
6320 inferior, you will probably also want to register event listeners and
6321 send output to the @code{gdb.TuiWindow}.
6324 @defun Window.hscroll (@var{num})
6325 This is a request to scroll the window horizontally. @var{num} is the
6326 amount by which to scroll, with negative numbers meaning to scroll
6327 right. In the TUI model, it is the viewport that moves, not the
6328 contents. A positive argument should cause the viewport to move
6329 right, and so the content should appear to move to the left.
6332 @defun Window.vscroll (@var{num})
6333 This is a request to scroll the window vertically. @var{num} is the
6334 amount by which to scroll, with negative numbers meaning to scroll
6335 backward. In the TUI model, it is the viewport that moves, not the
6336 contents. A positive argument should cause the viewport to move down,
6337 and so the content should appear to move up.
6340 @defun Window.click (@var{x}, @var{y}, @var{button})
6341 This is called on a mouse click in this window. @var{x} and @var{y} are
6342 the mouse coordinates inside the window (0-based, from the top left
6343 corner), and @var{button} specifies which mouse button was used, whose
6344 values can be 1 (left), 2 (middle), or 3 (right).
6347 @node Python Auto-loading
6348 @subsection Python Auto-loading
6349 @cindex Python auto-loading
6351 When a new object file is read (for example, due to the @code{file}
6352 command, or because the inferior has loaded a shared library),
6353 @value{GDBN} will look for Python support scripts in several ways:
6354 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
6355 @xref{Auto-loading extensions}.
6357 The auto-loading feature is useful for supplying application-specific
6358 debugging commands and scripts.
6360 Auto-loading can be enabled or disabled,
6361 and the list of auto-loaded scripts can be printed.
6364 @anchor{set auto-load python-scripts}
6365 @kindex set auto-load python-scripts
6366 @item set auto-load python-scripts [on|off]
6367 Enable or disable the auto-loading of Python scripts.
6369 @anchor{show auto-load python-scripts}
6370 @kindex show auto-load python-scripts
6371 @item show auto-load python-scripts
6372 Show whether auto-loading of Python scripts is enabled or disabled.
6374 @anchor{info auto-load python-scripts}
6375 @kindex info auto-load python-scripts
6376 @cindex print list of auto-loaded Python scripts
6377 @item info auto-load python-scripts [@var{regexp}]
6378 Print the list of all Python scripts that @value{GDBN} auto-loaded.
6380 Also printed is the list of Python scripts that were mentioned in
6381 the @code{.debug_gdb_scripts} section and were either not found
6382 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
6383 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
6384 This is useful because their names are not printed when @value{GDBN}
6385 tries to load them and fails. There may be many of them, and printing
6386 an error message for each one is problematic.
6388 If @var{regexp} is supplied only Python scripts with matching names are printed.
6393 (gdb) info auto-load python-scripts
6395 Yes py-section-script.py
6396 full name: /tmp/py-section-script.py
6397 No my-foo-pretty-printers.py
6401 When reading an auto-loaded file or script, @value{GDBN} sets the
6402 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
6403 function (@pxref{Objfiles In Python}). This can be useful for
6404 registering objfile-specific pretty-printers and frame-filters.
6406 @node Python modules
6407 @subsection Python modules
6408 @cindex python modules
6410 @value{GDBN} comes with several modules to assist writing Python code.
6413 * gdb.printing:: Building and registering pretty-printers.
6414 * gdb.types:: Utilities for working with types.
6415 * gdb.prompt:: Utilities for prompt value substitution.
6419 @subsubsection gdb.printing
6420 @cindex gdb.printing
6422 This module provides a collection of utilities for working with
6426 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
6427 This class specifies the API that makes @samp{info pretty-printer},
6428 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
6429 Pretty-printers should generally inherit from this class.
6431 @item SubPrettyPrinter (@var{name})
6432 For printers that handle multiple types, this class specifies the
6433 corresponding API for the subprinters.
6435 @item RegexpCollectionPrettyPrinter (@var{name})
6436 Utility class for handling multiple printers, all recognized via
6437 regular expressions.
6438 @xref{Writing a Pretty-Printer}, for an example.
6440 @item FlagEnumerationPrinter (@var{name})
6441 A pretty-printer which handles printing of @code{enum} values. Unlike
6442 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
6443 work properly when there is some overlap between the enumeration
6444 constants. The argument @var{name} is the name of the printer and
6445 also the name of the @code{enum} type to look up.
6447 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
6448 Register @var{printer} with the pretty-printer list of @var{obj}.
6449 If @var{replace} is @code{True} then any existing copy of the printer
6450 is replaced. Otherwise a @code{RuntimeError} exception is raised
6451 if a printer with the same name already exists.
6455 @subsubsection gdb.types
6458 This module provides a collection of utilities for working with
6459 @code{gdb.Type} objects.
6462 @item get_basic_type (@var{type})
6463 Return @var{type} with const and volatile qualifiers stripped,
6464 and with typedefs and C@t{++} references converted to the underlying type.
6469 typedef const int const_int;
6471 const_int& foo_ref (foo);
6472 int main () @{ return 0; @}
6479 (gdb) python import gdb.types
6480 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
6481 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
6485 @item has_field (@var{type}, @var{field})
6486 Return @code{True} if @var{type}, assumed to be a type with fields
6487 (e.g., a structure or union), has field @var{field}.
6489 @item make_enum_dict (@var{enum_type})
6490 Return a Python @code{dictionary} type produced from @var{enum_type}.
6492 @item deep_items (@var{type})
6493 Returns a Python iterator similar to the standard
6494 @code{gdb.Type.iteritems} method, except that the iterator returned
6495 by @code{deep_items} will recursively traverse anonymous struct or
6496 union fields. For example:
6510 Then in @value{GDBN}:
6512 (@value{GDBP}) python import gdb.types
6513 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
6514 (@value{GDBP}) python print struct_a.keys ()
6516 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
6517 @{['a', 'b0', 'b1']@}
6520 @item get_type_recognizers ()
6521 Return a list of the enabled type recognizers for the current context.
6522 This is called by @value{GDBN} during the type-printing process
6523 (@pxref{Type Printing API}).
6525 @item apply_type_recognizers (recognizers, type_obj)
6526 Apply the type recognizers, @var{recognizers}, to the type object
6527 @var{type_obj}. If any recognizer returns a string, return that
6528 string. Otherwise, return @code{None}. This is called by
6529 @value{GDBN} during the type-printing process (@pxref{Type Printing
6532 @item register_type_printer (locus, printer)
6533 This is a convenience function to register a type printer
6534 @var{printer}. The printer must implement the type printer protocol.
6535 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
6536 the printer is registered with that objfile; a @code{gdb.Progspace},
6537 in which case the printer is registered with that progspace; or
6538 @code{None}, in which case the printer is registered globally.
6541 This is a base class that implements the type printer protocol. Type
6542 printers are encouraged, but not required, to derive from this class.
6543 It defines a constructor:
6545 @defmethod TypePrinter __init__ (self, name)
6546 Initialize the type printer with the given name. The new printer
6547 starts in the enabled state.
6553 @subsubsection gdb.prompt
6556 This module provides a method for prompt value-substitution.
6559 @item substitute_prompt (@var{string})
6560 Return @var{string} with escape sequences substituted by values. Some
6561 escape sequences take arguments. You can specify arguments inside
6562 ``@{@}'' immediately following the escape sequence.
6564 The escape sequences you can pass to this function are:
6568 Substitute a backslash.
6570 Substitute an ESC character.
6572 Substitute the selected frame; an argument names a frame parameter.
6574 Substitute a newline.
6576 Substitute a parameter's value; the argument names the parameter.
6578 Substitute a carriage return.
6580 Substitute the selected thread; an argument names a thread parameter.
6582 Substitute the version of GDB.
6584 Substitute the current working directory.
6586 Begin a sequence of non-printing characters. These sequences are
6587 typically used with the ESC character, and are not counted in the string
6588 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
6589 blue-colored ``(gdb)'' prompt where the length is five.
6591 End a sequence of non-printing characters.
6597 substitute_prompt ("frame: \f, args: \p@{print frame-arguments@}")
6600 @exdent will return the string:
6603 "frame: main, args: scalars"