1 @c Copyright (C) 2008--2023 Free Software Foundation, Inc.
2 @c Permission is granted to copy, distribute and/or modify this document
3 @c under the terms of the GNU Free Documentation License, Version 1.3 or
4 @c any later version published by the Free Software Foundation; with the
5 @c Invariant Sections being ``Free Software'' and ``Free Software Needs
6 @c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
7 @c and with the Back-Cover Texts as in (a) below.
9 @c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
10 @c this GNU Manual. Buying copies from GNU Press supports the FSF in
11 @c developing GNU and promoting software freedom.''
14 @section Extending @value{GDBN} using Python
15 @cindex python scripting
16 @cindex scripting with python
18 You can extend @value{GDBN} using the @uref{http://www.python.org/,
19 Python programming language}. This feature is available only if
20 @value{GDBN} was configured using @option{--with-python}.
22 @cindex python directory
23 Python scripts used by @value{GDBN} should be installed in
24 @file{@var{data-directory}/python}, where @var{data-directory} is
25 the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
26 This directory, known as the @dfn{python directory},
27 is automatically added to the Python Search Path in order to allow
28 the Python interpreter to locate all scripts installed at this location.
30 Additionally, @value{GDBN} commands and convenience functions which
31 are written in Python and are located in the
32 @file{@var{data-directory}/python/gdb/command} or
33 @file{@var{data-directory}/python/gdb/function} directories are
34 automatically imported when @value{GDBN} starts.
37 * Python Commands:: Accessing Python from @value{GDBN}.
38 * Python API:: Accessing @value{GDBN} from Python.
39 * Python Auto-loading:: Automatically loading Python code.
40 * Python modules:: Python modules provided by @value{GDBN}.
44 @subsection Python Commands
45 @cindex python commands
46 @cindex commands to access python
48 @value{GDBN} provides two commands for accessing the Python interpreter,
49 and one related setting:
52 @kindex python-interactive
54 @item python-interactive @r{[}@var{command}@r{]}
55 @itemx pi @r{[}@var{command}@r{]}
56 Without an argument, the @code{python-interactive} command can be used
57 to start an interactive Python prompt. To return to @value{GDBN},
58 type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
60 Alternatively, a single-line Python command can be given as an
61 argument and evaluated. If the command is an expression, the result
62 will be printed; otherwise, nothing will be printed. For example:
65 (@value{GDBP}) python-interactive 2 + 3
71 @item python @r{[}@var{command}@r{]}
72 @itemx py @r{[}@var{command}@r{]}
73 The @code{python} command can be used to evaluate Python code.
75 If given an argument, the @code{python} command will evaluate the
76 argument as a Python command. For example:
79 (@value{GDBP}) python print 23
83 If you do not provide an argument to @code{python}, it will act as a
84 multi-line command, like @code{define}. In this case, the Python
85 script is made up of subsequent command lines, given after the
86 @code{python} command. This command list is terminated using a line
87 containing @code{end}. For example:
96 @anchor{set_python_print_stack}
97 @kindex set python print-stack
98 @item set python print-stack
99 By default, @value{GDBN} will print only the message component of a
100 Python exception when an error occurs in a Python script. This can be
101 controlled using @code{set python print-stack}: if @code{full}, then
102 full Python stack printing is enabled; if @code{none}, then Python stack
103 and message printing is disabled; if @code{message}, the default, only
104 the message component of the error is printed.
106 @kindex set python ignore-environment
107 @item set python ignore-environment @r{[}on@r{|}off@r{]}
108 By default this option is @samp{off}, and, when @value{GDBN}
109 initializes its internal Python interpreter, the Python interpreter
110 will check the environment for variables that will effect how it
111 behaves, for example @env{PYTHONHOME}, and
112 @env{PYTHONPATH}@footnote{See the ENVIRONMENT VARIABLES section of
113 @command{man 1 python} for a comprehensive list.}.
115 If this option is set to @samp{on} before Python is initialized then
116 Python will ignore all such environment variables. As Python is
117 initialized early during @value{GDBN}'s startup process, then this
118 option must be placed into the early initialization file
119 (@pxref{Initialization Files}) to have the desired effect.
121 This option is equivalent to passing @option{-E} to the real
122 @command{python} executable.
124 @kindex set python dont-write-bytecode
125 @item set python dont-write-bytecode @r{[}auto@r{|}on@r{|}off@r{]}
126 When this option is @samp{off}, then, once @value{GDBN} has
127 initialized the Python interpreter, the interpreter will byte-compile
128 any Python modules that it imports and write the byte code to disk in
131 If this option is set to @samp{on} before Python is initialized then
132 Python will no longer write the byte code to disk. As Python is
133 initialized early during @value{GDBN}'s startup process, then this
134 option must be placed into the early initialization file
135 (@pxref{Initialization Files}) to have the desired effect.
137 By default this option is set to @samp{auto}. In this mode, provided
138 the @code{python ignore-environment} setting is @samp{off}, the
139 environment variable @env{PYTHONDONTWRITEBYTECODE} is examined to see
140 if it should write out byte-code or not.
141 @env{PYTHONDONTWRITEBYTECODE} is considered to be off/disabled either
142 when set to the empty string or when the environment variable doesn't
143 exist. All other settings, including those which don't seem to make
144 sense, indicate that it's on/enabled.
146 This option is equivalent to passing @option{-B} to the real
147 @command{python} executable.
150 It is also possible to execute a Python script from the @value{GDBN}
154 @item source @file{script-name}
155 The script name must end with @samp{.py} and @value{GDBN} must be configured
156 to recognize the script language based on filename extension using
157 the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
160 The following commands are intended to help debug @value{GDBN} itself:
163 @kindex set debug py-breakpoint
164 @kindex show debug py-breakpoint
165 @item set debug py-breakpoint on@r{|}off
166 @itemx show debug py-breakpoint
167 When @samp{on}, @value{GDBN} prints debug messages related to the
168 Python breakpoint API. This is @samp{off} by default.
170 @kindex set debug py-unwind
171 @kindex show debug py-unwind
172 @item set debug py-unwind on@r{|}off
173 @itemx show debug py-unwind
174 When @samp{on}, @value{GDBN} prints debug messages related to the
175 Python unwinder API. This is @samp{off} by default.
179 @subsection Python API
181 @cindex programming in python
183 You can get quick online help for @value{GDBN}'s Python API by issuing
184 the command @w{@kbd{python help (gdb)}}.
186 Functions and methods which have two or more optional arguments allow
187 them to be specified using keyword syntax. This allows passing some
188 optional arguments while skipping others. Example:
189 @w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
192 * Basic Python:: Basic Python Functions.
193 * Exception Handling:: How Python exceptions are translated.
194 * Values From Inferior:: Python representation of values.
195 * Types In Python:: Python representation of types.
196 * Pretty Printing API:: Pretty-printing values.
197 * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
198 * Writing a Pretty-Printer:: Writing a Pretty-Printer.
199 * Type Printing API:: Pretty-printing types.
200 * Frame Filter API:: Filtering Frames.
201 * Frame Decorator API:: Decorating Frames.
202 * Writing a Frame Filter:: Writing a Frame Filter.
203 * Unwinding Frames in Python:: Writing frame unwinder.
204 * Xmethods In Python:: Adding and replacing methods of C++ classes.
205 * Xmethod API:: Xmethod types.
206 * Writing an Xmethod:: Writing an xmethod.
207 * Inferiors In Python:: Python representation of inferiors (processes)
208 * Events In Python:: Listening for events from @value{GDBN}.
209 * Threads In Python:: Accessing inferior threads from Python.
210 * Recordings In Python:: Accessing recordings from Python.
211 * CLI Commands In Python:: Implementing new CLI commands in Python.
212 * GDB/MI Commands In Python:: Implementing new @sc{GDB/MI} commands in Python.
213 * Parameters In Python:: Adding new @value{GDBN} parameters.
214 * Functions In Python:: Writing new convenience functions.
215 * Progspaces In Python:: Program spaces.
216 * Objfiles In Python:: Object files.
217 * Frames In Python:: Accessing inferior stack frames from Python.
218 * Blocks In Python:: Accessing blocks from Python.
219 * Symbols In Python:: Python representation of symbols.
220 * Symbol Tables In Python:: Python representation of symbol tables.
221 * Line Tables In Python:: Python representation of line tables.
222 * Breakpoints In Python:: Manipulating breakpoints using Python.
223 * Finish Breakpoints in Python:: Setting Breakpoints on function return
225 * Lazy Strings In Python:: Python representation of lazy strings.
226 * Architectures In Python:: Python representation of architectures.
227 * Registers In Python:: Python representation of registers.
228 * Connections In Python:: Python representation of connections.
229 * TUI Windows In Python:: Implementing new TUI windows.
230 * Disassembly In Python:: Instruction Disassembly In Python
234 @subsubsection Basic Python
236 @cindex python stdout
237 @cindex python pagination
238 At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
239 @code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
240 A Python program which outputs to one of these streams may have its
241 output interrupted by the user (@pxref{Screen Size}). In this
242 situation, a Python @code{KeyboardInterrupt} exception is thrown.
244 Some care must be taken when writing Python code to run in
245 @value{GDBN}. Two things worth noting in particular:
249 @value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
250 Python code must not override these, or even change the options using
251 @code{sigaction}. If your program changes the handling of these
252 signals, @value{GDBN} will most likely stop working correctly. Note
253 that it is unfortunately common for GUI toolkits to install a
254 @code{SIGCHLD} handler.
257 @value{GDBN} takes care to mark its internal file descriptors as
258 close-on-exec. However, this cannot be done in a thread-safe way on
259 all platforms. Your Python programs should be aware of this and
260 should both create new file descriptors with the close-on-exec flag
261 set and arrange to close unneeded file descriptors before starting a
265 @cindex python functions
266 @cindex python module
268 @value{GDBN} introduces a new Python module, named @code{gdb}. All
269 methods and classes added by @value{GDBN} are placed in this module.
270 @value{GDBN} automatically @code{import}s the @code{gdb} module for
271 use in all scripts evaluated by the @code{python} command.
273 Some types of the @code{gdb} module come with a textual representation
274 (accessible through the @code{repr} or @code{str} functions). These are
275 offered for debugging purposes only, expect them to change over time.
277 @findex gdb.PYTHONDIR
278 @defvar gdb.PYTHONDIR
279 A string containing the python directory (@pxref{Python}).
283 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
284 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
285 If a GDB exception happens while @var{command} runs, it is
286 translated as described in @ref{Exception Handling,,Exception Handling}.
288 The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
289 command as having originated from the user invoking it interactively.
290 It must be a boolean value. If omitted, it defaults to @code{False}.
292 By default, any output produced by @var{command} is sent to
293 @value{GDBN}'s standard output (and to the log output if logging is
294 turned on). If the @var{to_string} parameter is
295 @code{True}, then output will be collected by @code{gdb.execute} and
296 returned as a string. The default is @code{False}, in which case the
297 return value is @code{None}. If @var{to_string} is @code{True}, the
298 @value{GDBN} virtual terminal will be temporarily set to unlimited width
299 and height, and its pagination will be disabled; @pxref{Screen Size}.
302 @findex gdb.breakpoints
303 @defun gdb.breakpoints ()
304 Return a sequence holding all of @value{GDBN}'s breakpoints.
305 @xref{Breakpoints In Python}, for more information. In @value{GDBN}
306 version 7.11 and earlier, this function returned @code{None} if there
307 were no breakpoints. This peculiarity was subsequently fixed, and now
308 @code{gdb.breakpoints} returns an empty sequence in this case.
311 @defun gdb.rbreak (regex @r{[}, minsyms @r{[}, throttle, @r{[}, symtabs @r{]]]})
312 Return a Python list holding a collection of newly set
313 @code{gdb.Breakpoint} objects matching function names defined by the
314 @var{regex} pattern. If the @var{minsyms} keyword is @code{True}, all
315 system functions (those not explicitly defined in the inferior) will
316 also be included in the match. The @var{throttle} keyword takes an
317 integer that defines the maximum number of pattern matches for
318 functions matched by the @var{regex} pattern. If the number of
319 matches exceeds the integer value of @var{throttle}, a
320 @code{RuntimeError} will be raised and no breakpoints will be created.
321 If @var{throttle} is not defined then there is no imposed limit on the
322 maximum number of matches and breakpoints to be created. The
323 @var{symtabs} keyword takes a Python iterable that yields a collection
324 of @code{gdb.Symtab} objects and will restrict the search to those
325 functions only contained within the @code{gdb.Symtab} objects.
328 @findex gdb.parameter
329 @defun gdb.parameter (parameter)
330 Return the value of a @value{GDBN} @var{parameter} given by its name,
331 a string; the parameter name string may contain spaces if the parameter has a
332 multi-part name. For example, @samp{print object} is a valid
335 If the named parameter does not exist, this function throws a
336 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
337 parameter's value is converted to a Python value of the appropriate
341 @findex gdb.set_parameter
342 @defun gdb.set_parameter (name, value)
343 Sets the gdb parameter @var{name} to @var{value}. As with
344 @code{gdb.parameter}, the parameter name string may contain spaces if
345 the parameter has a multi-part name.
348 @findex gdb.with_parameter
349 @defun gdb.with_parameter (name, value)
350 Create a Python context manager (for use with the Python
351 @command{with} statement) that temporarily sets the gdb parameter
352 @var{name} to @var{value}. On exit from the context, the previous
353 value will be restored.
355 This uses @code{gdb.parameter} in its implementation, so it can throw
356 the same exceptions as that function.
358 For example, it's sometimes useful to evaluate some Python code with a
359 particular gdb language:
362 with gdb.with_parameter('language', 'pascal'):
363 ... language-specific operations
368 @defun gdb.history (number)
369 Return a value from @value{GDBN}'s value history (@pxref{Value
370 History}). The @var{number} argument indicates which history element to return.
371 If @var{number} is negative, then @value{GDBN} will take its absolute value
372 and count backward from the last element (i.e., the most recent element) to
373 find the value to return. If @var{number} is zero, then @value{GDBN} will
374 return the most recent element. If the element specified by @var{number}
375 doesn't exist in the value history, a @code{gdb.error} exception will be
378 If no exception is raised, the return value is always an instance of
379 @code{gdb.Value} (@pxref{Values From Inferior}).
382 @defun gdb.add_history (value)
383 Takes @var{value}, an instance of @code{gdb.Value} (@pxref{Values From
384 Inferior}), and appends the value this object represents to
385 @value{GDBN}'s value history (@pxref{Value History}), and return an
386 integer, its history number. If @var{value} is not a
387 @code{gdb.Value}, it is is converted using the @code{gdb.Value}
388 constructor. If @var{value} can't be converted to a @code{gdb.Value}
389 then a @code{TypeError} is raised.
391 When a command implemented in Python prints a single @code{gdb.Value}
392 as its result, then placing the value into the history will allow the
393 user convenient access to those values via CLI history facilities.
396 @defun gdb.history_count ()
397 Return an integer indicating the number of values in @value{GDBN}'s
398 value history (@pxref{Value History}).
401 @findex gdb.convenience_variable
402 @defun gdb.convenience_variable (name)
403 Return the value of the convenience variable (@pxref{Convenience
404 Vars}) named @var{name}. @var{name} must be a string. The name
405 should not include the @samp{$} that is used to mark a convenience
406 variable in an expression. If the convenience variable does not
407 exist, then @code{None} is returned.
410 @findex gdb.set_convenience_variable
411 @defun gdb.set_convenience_variable (name, value)
412 Set the value of the convenience variable (@pxref{Convenience Vars})
413 named @var{name}. @var{name} must be a string. The name should not
414 include the @samp{$} that is used to mark a convenience variable in an
415 expression. If @var{value} is @code{None}, then the convenience
416 variable is removed. Otherwise, if @var{value} is not a
417 @code{gdb.Value} (@pxref{Values From Inferior}), it is is converted
418 using the @code{gdb.Value} constructor.
421 @findex gdb.parse_and_eval
422 @defun gdb.parse_and_eval (expression)
423 Parse @var{expression}, which must be a string, as an expression in
424 the current language, evaluate it, and return the result as a
427 This function can be useful when implementing a new command
428 (@pxref{CLI Commands In Python}, @pxref{GDB/MI Commands In Python}),
429 as it provides a way to parse the
430 command's argument as an expression. It is also useful simply to
434 @findex gdb.find_pc_line
435 @defun gdb.find_pc_line (pc)
436 Return the @code{gdb.Symtab_and_line} object corresponding to the
437 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
438 value of @var{pc} is passed as an argument, then the @code{symtab} and
439 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
440 will be @code{None} and 0 respectively. This is identical to
441 @code{gdb.current_progspace().find_pc_line(pc)} and is included for
442 historical compatibility.
445 @findex gdb.post_event
446 @defun gdb.post_event (event)
447 Put @var{event}, a callable object taking no arguments, into
448 @value{GDBN}'s internal event queue. This callable will be invoked at
449 some later point, during @value{GDBN}'s event processing. Events
450 posted using @code{post_event} will be run in the order in which they
451 were posted; however, there is no way to know when they will be
452 processed relative to other events inside @value{GDBN}.
454 @value{GDBN} is not thread-safe. If your Python program uses multiple
455 threads, you must be careful to only call @value{GDBN}-specific
456 functions in the @value{GDBN} thread. @code{post_event} ensures
460 (@value{GDBP}) python
464 > def __init__(self, message):
465 > self.message = message;
466 > def __call__(self):
467 > gdb.write(self.message)
469 >class MyThread1 (threading.Thread):
471 > gdb.post_event(Writer("Hello "))
473 >class MyThread2 (threading.Thread):
475 > gdb.post_event(Writer("World\n"))
480 (@value{GDBP}) Hello World
485 @defun gdb.write (string @r{[}, stream@r{]})
486 Print a string to @value{GDBN}'s paginated output stream. The
487 optional @var{stream} determines the stream to print to. The default
488 stream is @value{GDBN}'s standard output stream. Possible stream
495 @value{GDBN}'s standard output stream.
500 @value{GDBN}'s standard error stream.
505 @value{GDBN}'s log stream (@pxref{Logging Output}).
508 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
509 call this function and will automatically direct the output to the
514 @defun gdb.flush (@r{[}, stream@r{]})
515 Flush the buffer of a @value{GDBN} paginated stream so that the
516 contents are displayed immediately. @value{GDBN} will flush the
517 contents of a stream automatically when it encounters a newline in the
518 buffer. The optional @var{stream} determines the stream to flush. The
519 default stream is @value{GDBN}'s standard output stream. Possible
526 @value{GDBN}'s standard output stream.
531 @value{GDBN}'s standard error stream.
536 @value{GDBN}'s log stream (@pxref{Logging Output}).
540 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
541 call this function for the relevant stream.
544 @findex gdb.target_charset
545 @defun gdb.target_charset ()
546 Return the name of the current target character set (@pxref{Character
547 Sets}). This differs from @code{gdb.parameter('target-charset')} in
548 that @samp{auto} is never returned.
551 @findex gdb.target_wide_charset
552 @defun gdb.target_wide_charset ()
553 Return the name of the current target wide character set
554 (@pxref{Character Sets}). This differs from
555 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
559 @findex gdb.host_charset
560 @defun gdb.host_charset ()
561 Return a string, the name of the current host character set
562 (@pxref{Character Sets}). This differs from
563 @code{gdb.parameter('host-charset')} in that @samp{auto} is never
567 @findex gdb.solib_name
568 @defun gdb.solib_name (address)
569 Return the name of the shared library holding the given @var{address}
570 as a string, or @code{None}. This is identical to
571 @code{gdb.current_progspace().solib_name(address)} and is included for
572 historical compatibility.
575 @findex gdb.decode_line
576 @defun gdb.decode_line (@r{[}expression@r{]})
577 Return locations of the line specified by @var{expression}, or of the
578 current line if no argument was given. This function returns a Python
579 tuple containing two elements. The first element contains a string
580 holding any unparsed section of @var{expression} (or @code{None} if
581 the expression has been fully parsed). The second element contains
582 either @code{None} or another tuple that contains all the locations
583 that match the expression represented as @code{gdb.Symtab_and_line}
584 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
585 provided, it is decoded the way that @value{GDBN}'s inbuilt
586 @code{break} or @code{edit} commands do (@pxref{Location
590 @defun gdb.prompt_hook (current_prompt)
593 If @var{prompt_hook} is callable, @value{GDBN} will call the method
594 assigned to this operation before a prompt is displayed by
597 The parameter @code{current_prompt} contains the current @value{GDBN}
598 prompt. This method must return a Python string, or @code{None}. If
599 a string is returned, the @value{GDBN} prompt will be set to that
600 string. If @code{None} is returned, @value{GDBN} will continue to use
603 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
604 such as those used by readline for command input, and annotation
605 related prompts are prohibited from being changed.
608 @anchor{gdb_architecture_names}
609 @defun gdb.architecture_names ()
610 Return a list containing all of the architecture names that the
611 current build of @value{GDBN} supports. Each architecture name is a
612 string. The names returned in this list are the same names as are
613 returned from @code{gdb.Architecture.name}
614 (@pxref{gdbpy_architecture_name,,Architecture.name}).
617 @anchor{gdbpy_connections}
618 @defun gdb.connections
619 Return a list of @code{gdb.TargetConnection} objects, one for each
620 currently active connection (@pxref{Connections In Python}). The
621 connection objects are in no particular order in the returned list.
624 @defun gdb.format_address (@var{address} @r{[}, @var{progspace}, @var{architecture}@r{]})
625 Return a string in the format @samp{@var{addr}
626 <@var{symbol}+@var{offset}>}, where @var{addr} is @var{address}
627 formatted in hexadecimal, @var{symbol} is the symbol whose address is
628 the nearest to @var{address} and below it in memory, and @var{offset}
629 is the offset from @var{symbol} to @var{address} in decimal.
631 If no suitable @var{symbol} was found, then the
632 <@var{symbol}+@var{offset}> part is not included in the returned
633 string, instead the returned string will just contain the
634 @var{address} formatted as hexadecimal. How far @value{GDBN} looks
635 back for a suitable symbol can be controlled with @kbd{set print
636 max-symbolic-offset} (@pxref{Print Settings}).
638 Additionally, the returned string can include file name and line
639 number information when @kbd{set print symbol-filename on}
640 (@pxref{Print Settings}), in this case the format of the returned
641 string is @samp{@var{addr} <@var{symbol}+@var{offset}> at
642 @var{filename}:@var{line-number}}.
645 The @var{progspace} is the gdb.Progspace in which @var{symbol} is
646 looked up, and @var{architecture} is used when formatting @var{addr},
647 e.g.@: in order to determine the size of an address in bytes.
649 If neither @var{progspace} or @var{architecture} are passed, then by
650 default @value{GDBN} will use the program space and architecture of
651 the currently selected inferior, thus, the following two calls are
655 gdb.format_address(address)
656 gdb.format_address(address,
657 gdb.selected_inferior().progspace,
658 gdb.selected_inferior().architecture())
661 It is not valid to only pass one of @var{progspace} or
662 @var{architecture}, either they must both be provided, or neither must
663 be provided (and the defaults will be used).
665 This method uses the same mechanism for formatting address, symbol,
666 and offset information as core @value{GDBN} does in commands such as
669 Here are some examples of the possible string formats:
673 0x00001042 <symbol+16>
674 0x00001042 <symbol+16 at file.c:123>
678 @defun gdb.current_language ()
679 Return the name of the current language as a string. Unlike
680 @code{gdb.parameter('language')}, this function will never return
681 @samp{auto}. If a @code{gdb.Frame} object is available (@pxref{Frames
682 In Python}), the @code{language} method might be preferable in some
683 cases, as that is not affected by the user's language setting.
686 @node Exception Handling
687 @subsubsection Exception Handling
688 @cindex python exceptions
689 @cindex exceptions, python
691 When executing the @code{python} command, Python exceptions
692 uncaught within the Python code are translated to calls to
693 @value{GDBN} error-reporting mechanism. If the command that called
694 @code{python} does not handle the error, @value{GDBN} will
695 terminate it and print an error message containing the Python
696 exception name, the associated value, and the Python call stack
697 backtrace at the point where the exception was raised. Example:
700 (@value{GDBP}) python print foo
701 Traceback (most recent call last):
702 File "<string>", line 1, in <module>
703 NameError: name 'foo' is not defined
706 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
707 Python code are converted to Python exceptions. The type of the
708 Python exception depends on the error.
712 This is the base class for most exceptions generated by @value{GDBN}.
713 It is derived from @code{RuntimeError}, for compatibility with earlier
714 versions of @value{GDBN}.
716 If an error occurring in @value{GDBN} does not fit into some more
717 specific category, then the generated exception will have this type.
719 @item gdb.MemoryError
720 This is a subclass of @code{gdb.error} which is thrown when an
721 operation tried to access invalid memory in the inferior.
723 @item KeyboardInterrupt
724 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
725 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
728 In all cases, your exception handler will see the @value{GDBN} error
729 message as its value and the Python call stack backtrace at the Python
730 statement closest to where the @value{GDBN} error occured as the
734 When implementing @value{GDBN} commands in Python via
735 @code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
736 to be able to throw an exception that doesn't cause a traceback to be
737 printed. For example, the user may have invoked the command
738 incorrectly. @value{GDBN} provides a special exception class that can
739 be used for this purpose.
743 When thrown from a command or function, this exception will cause the
744 command or function to fail, but the Python stack will not be
745 displayed. @value{GDBN} does not throw this exception itself, but
746 rather recognizes it when thrown from user Python code. Example:
750 >class HelloWorld (gdb.Command):
751 > """Greet the whole world."""
752 > def __init__ (self):
753 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
754 > def invoke (self, args, from_tty):
755 > argv = gdb.string_to_argv (args)
756 > if len (argv) != 0:
757 > raise gdb.GdbError ("hello-world takes no arguments")
758 > print ("Hello, World!")
762 hello-world takes no arguments
766 @node Values From Inferior
767 @subsubsection Values From Inferior
768 @cindex values from inferior, with Python
769 @cindex python, working with values from inferior
771 @cindex @code{gdb.Value}
772 @value{GDBN} provides values it obtains from the inferior program in
773 an object of type @code{gdb.Value}. @value{GDBN} uses this object
774 for its internal bookkeeping of the inferior's values, and for
775 fetching values when necessary.
777 Inferior values that are simple scalars can be used directly in
778 Python expressions that are valid for the value's data type. Here's
779 an example for an integer or floating-point value @code{some_val}:
786 As result of this, @code{bar} will also be a @code{gdb.Value} object
787 whose values are of the same type as those of @code{some_val}. Valid
788 Python operations can also be performed on @code{gdb.Value} objects
789 representing a @code{struct} or @code{class} object. For such cases,
790 the overloaded operator (if present), is used to perform the operation.
791 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
792 representing instances of a @code{class} which overloads the @code{+}
793 operator, then one can use the @code{+} operator in their Python script
801 The result of the operation @code{val3} is also a @code{gdb.Value}
802 object corresponding to the value returned by the overloaded @code{+}
803 operator. In general, overloaded operators are invoked for the
804 following operations: @code{+} (binary addition), @code{-} (binary
805 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
806 @code{>>}, @code{|}, @code{&}, @code{^}.
808 Inferior values that are structures or instances of some class can
809 be accessed using the Python @dfn{dictionary syntax}. For example, if
810 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
811 can access its @code{foo} element with:
814 bar = some_val['foo']
817 @cindex getting structure elements using gdb.Field objects as subscripts
818 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
819 elements can also be accessed by using @code{gdb.Field} objects as
820 subscripts (@pxref{Types In Python}, for more information on
821 @code{gdb.Field} objects). For example, if @code{foo_field} is a
822 @code{gdb.Field} object corresponding to element @code{foo} of the above
823 structure, then @code{bar} can also be accessed as follows:
826 bar = some_val[foo_field]
829 A @code{gdb.Value} that represents a function can be executed via
830 inferior function call. Any arguments provided to the call must match
831 the function's prototype, and must be provided in the order specified
834 For example, @code{some_val} is a @code{gdb.Value} instance
835 representing a function that takes two integers as arguments. To
836 execute this function, call it like so:
839 result = some_val (10,20)
842 Any values returned from a function call will be stored as a
845 The following attributes are provided:
847 @defvar Value.address
848 If this object is addressable, this read-only attribute holds a
849 @code{gdb.Value} object representing the address. Otherwise,
850 this attribute holds @code{None}.
853 @cindex optimized out value in Python
854 @defvar Value.is_optimized_out
855 This read-only boolean attribute is true if the compiler optimized out
856 this value, thus it is not available for fetching from the inferior.
860 The type of this @code{gdb.Value}. The value of this attribute is a
861 @code{gdb.Type} object (@pxref{Types In Python}).
864 @defvar Value.dynamic_type
865 The dynamic type of this @code{gdb.Value}. This uses the object's
866 virtual table and the C@t{++} run-time type information
867 (@acronym{RTTI}) to determine the dynamic type of the value. If this
868 value is of class type, it will return the class in which the value is
869 embedded, if any. If this value is of pointer or reference to a class
870 type, it will compute the dynamic type of the referenced object, and
871 return a pointer or reference to that type, respectively. In all
872 other cases, it will return the value's static type.
874 Note that this feature will only work when debugging a C@t{++} program
875 that includes @acronym{RTTI} for the object in question. Otherwise,
876 it will just return the static type of the value as in @kbd{ptype foo}
877 (@pxref{Symbols, ptype}).
880 @defvar Value.is_lazy
881 The value of this read-only boolean attribute is @code{True} if this
882 @code{gdb.Value} has not yet been fetched from the inferior.
883 @value{GDBN} does not fetch values until necessary, for efficiency.
887 myval = gdb.parse_and_eval ('somevar')
890 The value of @code{somevar} is not fetched at this time. It will be
891 fetched when the value is needed, or when the @code{fetch_lazy}
895 The following methods are provided:
897 @defun Value.__init__ (@var{val})
898 Many Python values can be converted directly to a @code{gdb.Value} via
899 this object initializer. Specifically:
903 A Python boolean is converted to the boolean type from the current
907 A Python integer is converted to the C @code{long} type for the
908 current architecture.
911 A Python long is converted to the C @code{long long} type for the
912 current architecture.
915 A Python float is converted to the C @code{double} type for the
916 current architecture.
919 A Python string is converted to a target string in the current target
920 language using the current target encoding.
921 If a character cannot be represented in the current target encoding,
922 then an exception is thrown.
924 @item @code{gdb.Value}
925 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
927 @item @code{gdb.LazyString}
928 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
929 Python}), then the lazy string's @code{value} method is called, and
934 @defun Value.__init__ (@var{val}, @var{type})
935 This second form of the @code{gdb.Value} constructor returns a
936 @code{gdb.Value} of type @var{type} where the value contents are taken
937 from the Python buffer object specified by @var{val}. The number of
938 bytes in the Python buffer object must be greater than or equal to the
941 If @var{type} is @code{None} then this version of @code{__init__}
942 behaves as though @var{type} was not passed at all.
945 @defun Value.cast (type)
946 Return a new instance of @code{gdb.Value} that is the result of
947 casting this instance to the type described by @var{type}, which must
948 be a @code{gdb.Type} object. If the cast cannot be performed for some
949 reason, this method throws an exception.
952 @defun Value.dereference ()
953 For pointer data types, this method returns a new @code{gdb.Value} object
954 whose contents is the object pointed to by the pointer. For example, if
955 @code{foo} is a C pointer to an @code{int}, declared in your C program as
962 then you can use the corresponding @code{gdb.Value} to access what
963 @code{foo} points to like this:
966 bar = foo.dereference ()
969 The result @code{bar} will be a @code{gdb.Value} object holding the
970 value pointed to by @code{foo}.
972 A similar function @code{Value.referenced_value} exists which also
973 returns @code{gdb.Value} objects corresponding to the values pointed to
974 by pointer values (and additionally, values referenced by reference
975 values). However, the behavior of @code{Value.dereference}
976 differs from @code{Value.referenced_value} by the fact that the
977 behavior of @code{Value.dereference} is identical to applying the C
978 unary operator @code{*} on a given value. For example, consider a
979 reference to a pointer @code{ptrref}, declared in your C@t{++} program
987 intptr &ptrref = ptr;
990 Though @code{ptrref} is a reference value, one can apply the method
991 @code{Value.dereference} to the @code{gdb.Value} object corresponding
992 to it and obtain a @code{gdb.Value} which is identical to that
993 corresponding to @code{val}. However, if you apply the method
994 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
995 object identical to that corresponding to @code{ptr}.
998 py_ptrref = gdb.parse_and_eval ("ptrref")
999 py_val = py_ptrref.dereference ()
1000 py_ptr = py_ptrref.referenced_value ()
1003 The @code{gdb.Value} object @code{py_val} is identical to that
1004 corresponding to @code{val}, and @code{py_ptr} is identical to that
1005 corresponding to @code{ptr}. In general, @code{Value.dereference} can
1006 be applied whenever the C unary operator @code{*} can be applied
1007 to the corresponding C value. For those cases where applying both
1008 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
1009 the results obtained need not be identical (as we have seen in the above
1010 example). The results are however identical when applied on
1011 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
1012 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
1015 @defun Value.referenced_value ()
1016 For pointer or reference data types, this method returns a new
1017 @code{gdb.Value} object corresponding to the value referenced by the
1018 pointer/reference value. For pointer data types,
1019 @code{Value.dereference} and @code{Value.referenced_value} produce
1020 identical results. The difference between these methods is that
1021 @code{Value.dereference} cannot get the values referenced by reference
1022 values. For example, consider a reference to an @code{int}, declared
1023 in your C@t{++} program as
1031 then applying @code{Value.dereference} to the @code{gdb.Value} object
1032 corresponding to @code{ref} will result in an error, while applying
1033 @code{Value.referenced_value} will result in a @code{gdb.Value} object
1034 identical to that corresponding to @code{val}.
1037 py_ref = gdb.parse_and_eval ("ref")
1038 er_ref = py_ref.dereference () # Results in error
1039 py_val = py_ref.referenced_value () # Returns the referenced value
1042 The @code{gdb.Value} object @code{py_val} is identical to that
1043 corresponding to @code{val}.
1046 @defun Value.reference_value ()
1047 Return a @code{gdb.Value} object which is a reference to the value
1048 encapsulated by this instance.
1051 @defun Value.const_value ()
1052 Return a @code{gdb.Value} object which is a @code{const} version of the
1053 value encapsulated by this instance.
1056 @defun Value.dynamic_cast (type)
1057 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
1058 operator were used. Consult a C@t{++} reference for details.
1061 @defun Value.reinterpret_cast (type)
1062 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
1063 operator were used. Consult a C@t{++} reference for details.
1066 @defun Value.format_string (...)
1067 Convert a @code{gdb.Value} to a string, similarly to what the @code{print}
1068 command does. Invoked with no arguments, this is equivalent to calling
1069 the @code{str} function on the @code{gdb.Value}. The representation of
1070 the same value may change across different versions of @value{GDBN}, so
1071 you shouldn't, for instance, parse the strings returned by this method.
1073 All the arguments are keyword only. If an argument is not specified, the
1074 current global default setting is used.
1078 @code{True} if pretty-printers (@pxref{Pretty Printing}) should not be
1079 used to format the value. @code{False} if enabled pretty-printers
1080 matching the type represented by the @code{gdb.Value} should be used to
1084 @code{True} if arrays should be pretty printed to be more convenient to
1085 read, @code{False} if they shouldn't (see @code{set print array} in
1086 @ref{Print Settings}).
1088 @item pretty_structs
1089 @code{True} if structs should be pretty printed to be more convenient to
1090 read, @code{False} if they shouldn't (see @code{set print pretty} in
1091 @ref{Print Settings}).
1094 @code{True} if array indexes should be included in the string
1095 representation of arrays, @code{False} if they shouldn't (see @code{set
1096 print array-indexes} in @ref{Print Settings}).
1099 @code{True} if the string representation of a pointer should include the
1100 corresponding symbol name (if one exists), @code{False} if it shouldn't
1101 (see @code{set print symbol} in @ref{Print Settings}).
1104 @code{True} if unions which are contained in other structures or unions
1105 should be expanded, @code{False} if they shouldn't (see @code{set print
1106 union} in @ref{Print Settings}).
1109 @code{True} if the string representation of a pointer should include the
1110 address, @code{False} if it shouldn't (see @code{set print address} in
1111 @ref{Print Settings}).
1114 @code{True} if binary values should be displayed in groups of four bits,
1115 known as nibbles. @code{False} if it shouldn't (@pxref{Print Settings,
1116 set print nibbles}).
1119 @code{True} if C@t{++} references should be resolved to the value they
1120 refer to, @code{False} (the default) if they shouldn't. Note that, unlike
1121 for the @code{print} command, references are not automatically expanded
1122 when using the @code{format_string} method or the @code{str}
1123 function. There is no global @code{print} setting to change the default
1126 @item actual_objects
1127 @code{True} if the representation of a pointer to an object should
1128 identify the @emph{actual} (derived) type of the object rather than the
1129 @emph{declared} type, using the virtual function table. @code{False} if
1130 the @emph{declared} type should be used. (See @code{set print object} in
1131 @ref{Print Settings}).
1133 @item static_members
1134 @code{True} if static members should be included in the string
1135 representation of a C@t{++} object, @code{False} if they shouldn't (see
1136 @code{set print static-members} in @ref{Print Settings}).
1138 @item max_characters
1139 Number of string characters to print, @code{0} to follow
1140 @code{max_elements}, or @code{UINT_MAX} to print an unlimited number
1141 of characters (see @code{set print characters} in @ref{Print Settings}).
1144 Number of array elements to print, or @code{0} to print an unlimited
1145 number of elements (see @code{set print elements} in @ref{Print
1149 The maximum depth to print for nested structs and unions, or @code{-1}
1150 to print an unlimited number of elements (see @code{set print
1151 max-depth} in @ref{Print Settings}).
1153 @item repeat_threshold
1154 Set the threshold for suppressing display of repeated array elements, or
1155 @code{0} to represent all elements, even if repeated. (See @code{set
1156 print repeats} in @ref{Print Settings}).
1159 A string containing a single character representing the format to use for
1160 the returned string. For instance, @code{'x'} is equivalent to using the
1161 @value{GDBN} command @code{print} with the @code{/x} option and formats
1162 the value as a hexadecimal number.
1165 @code{True} if @value{GDBN} should apply styling to the returned
1166 string. When styling is applied, the returned string might contain
1167 ANSI terminal escape sequences. Escape sequences will only be
1168 included if styling is turned on, see @ref{Output Styling}.
1169 Additionally, @value{GDBN} only styles some value contents, so not
1170 every output string will contain escape sequences.
1172 When @code{False}, which is the default, no output styling is applied.
1175 @code{True} when just a summary should be printed. In this mode,
1176 scalar values are printed in their entirety, but aggregates such as
1177 structures or unions are omitted. This mode is used by @code{set
1178 print frame-arguments scalars} (@pxref{Print Settings}).
1182 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
1183 If this @code{gdb.Value} represents a string, then this method
1184 converts the contents to a Python string. Otherwise, this method will
1187 Values are interpreted as strings according to the rules of the
1188 current language. If the optional length argument is given, the
1189 string will be converted to that length, and will include any embedded
1190 zeroes that the string may contain. Otherwise, for languages
1191 where the string is zero-terminated, the entire string will be
1194 For example, in C-like languages, a value is a string if it is a pointer
1195 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
1198 If the optional @var{encoding} argument is given, it must be a string
1199 naming the encoding of the string in the @code{gdb.Value}, such as
1200 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
1201 the same encodings as the corresponding argument to Python's
1202 @code{string.decode} method, and the Python codec machinery will be used
1203 to convert the string. If @var{encoding} is not given, or if
1204 @var{encoding} is the empty string, then either the @code{target-charset}
1205 (@pxref{Character Sets}) will be used, or a language-specific encoding
1206 will be used, if the current language is able to supply one.
1208 The optional @var{errors} argument is the same as the corresponding
1209 argument to Python's @code{string.decode} method.
1211 If the optional @var{length} argument is given, the string will be
1212 fetched and converted to the given length.
1215 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
1216 If this @code{gdb.Value} represents a string, then this method
1217 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
1218 In Python}). Otherwise, this method will throw an exception.
1220 If the optional @var{encoding} argument is given, it must be a string
1221 naming the encoding of the @code{gdb.LazyString}. Some examples are:
1222 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
1223 @var{encoding} argument is an encoding that @value{GDBN} does
1224 recognize, @value{GDBN} will raise an error.
1226 When a lazy string is printed, the @value{GDBN} encoding machinery is
1227 used to convert the string during printing. If the optional
1228 @var{encoding} argument is not provided, or is an empty string,
1229 @value{GDBN} will automatically select the encoding most suitable for
1230 the string type. For further information on encoding in @value{GDBN}
1231 please see @ref{Character Sets}.
1233 If the optional @var{length} argument is given, the string will be
1234 fetched and encoded to the length of characters specified. If
1235 the @var{length} argument is not provided, the string will be fetched
1236 and encoded until a null of appropriate width is found.
1239 @defun Value.fetch_lazy ()
1240 If the @code{gdb.Value} object is currently a lazy value
1241 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
1242 fetched from the inferior. Any errors that occur in the process
1243 will produce a Python exception.
1245 If the @code{gdb.Value} object is not a lazy value, this method
1248 This method does not return a value.
1252 @node Types In Python
1253 @subsubsection Types In Python
1254 @cindex types in Python
1255 @cindex Python, working with types
1258 @value{GDBN} represents types from the inferior using the class
1261 The following type-related functions are available in the @code{gdb}
1264 @findex gdb.lookup_type
1265 @defun gdb.lookup_type (name @r{[}, block@r{]})
1266 This function looks up a type by its @var{name}, which must be a string.
1268 If @var{block} is given, then @var{name} is looked up in that scope.
1269 Otherwise, it is searched for globally.
1271 Ordinarily, this function will return an instance of @code{gdb.Type}.
1272 If the named type cannot be found, it will throw an exception.
1275 Integer types can be found without looking them up by name.
1276 @xref{Architectures In Python}, for the @code{integer_type} method.
1278 If the type is a structure or class type, or an enum type, the fields
1279 of that type can be accessed using the Python @dfn{dictionary syntax}.
1280 For example, if @code{some_type} is a @code{gdb.Type} instance holding
1281 a structure type, you can access its @code{foo} field with:
1284 bar = some_type['foo']
1287 @code{bar} will be a @code{gdb.Field} object; see below under the
1288 description of the @code{Type.fields} method for a description of the
1289 @code{gdb.Field} class.
1291 An instance of @code{Type} has the following attributes:
1293 @defvar Type.alignof
1294 The alignment of this type, in bytes. Type alignment comes from the
1295 debugging information; if it was not specified, then @value{GDBN} will
1296 use the relevant ABI to try to determine the alignment. In some
1297 cases, even this is not possible, and zero will be returned.
1301 The type code for this type. The type code will be one of the
1302 @code{TYPE_CODE_} constants defined below.
1305 @defvar Type.dynamic
1306 A boolean indicating whether this type is dynamic. In some
1307 situations, such as Rust @code{enum} types or Ada variant records, the
1308 concrete type of a value may vary depending on its contents. That is,
1309 the declared type of a variable, or the type returned by
1310 @code{gdb.lookup_type} may be dynamic; while the type of the
1311 variable's value will be a concrete instance of that dynamic type.
1313 For example, consider this code:
1319 Here, at least conceptually (whether your compiler actually does this
1320 is a separate issue), examining @w{@code{gdb.lookup_symbol("array", ...).type}}
1321 could yield a @code{gdb.Type} which reports a size of @code{None}.
1322 This is the dynamic type.
1324 However, examining @code{gdb.parse_and_eval("array").type} would yield
1325 a concrete type, whose length would be known.
1329 The name of this type. If this type has no name, then @code{None}
1334 The size of this type, in target @code{char} units. Usually, a
1335 target's @code{char} type will be an 8-bit byte. However, on some
1336 unusual platforms, this type may have a different size. A dynamic
1337 type may not have a fixed size; in this case, this attribute's value
1338 will be @code{None}.
1342 The tag name for this type. The tag name is the name after
1343 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1344 languages have this concept. If this type has no tag name, then
1345 @code{None} is returned.
1348 @defvar Type.objfile
1349 The @code{gdb.Objfile} that this type was defined in, or @code{None} if
1350 there is no associated objfile.
1353 @defvar Type.is_scalar
1354 This property is @code{True} if the type is a scalar type, otherwise,
1355 this property is @code{False}. Examples of non-scalar types include
1356 structures, unions, and classes.
1359 @defvar Type.is_signed
1360 For scalar types (those for which @code{Type.is_scalar} is
1361 @code{True}), this property is @code{True} if the type is signed,
1362 otherwise this property is @code{False}.
1364 Attempting to read this property for a non-scalar type (a type for
1365 which @code{Type.is_scalar} is @code{False}), will raise a
1369 The following methods are provided:
1371 @defun Type.fields ()
1373 Return the fields of this type. The behavior depends on the type code:
1378 For structure and union types, this method returns the fields.
1381 Range types have two fields, the minimum and maximum values.
1384 Enum types have one field per enum constant.
1387 Function and method types have one field per parameter. The base types of
1388 C@t{++} classes are also represented as fields.
1391 Array types have one field representing the array's range.
1394 If the type does not fit into one of these categories, a @code{TypeError}
1399 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
1402 This attribute is not available for @code{enum} or @code{static}
1403 (as in C@t{++}) fields. The value is the position, counting
1404 in bits, from the start of the containing type. Note that, in a
1405 dynamic type, the position of a field may not be constant. In this
1406 case, the value will be @code{None}. Also, a dynamic type may have
1407 fields that do not appear in a corresponding concrete type.
1410 This attribute is only available for @code{enum} fields, and its value
1411 is the enumeration member's integer representation.
1414 The name of the field, or @code{None} for anonymous fields.
1417 This is @code{True} if the field is artificial, usually meaning that
1418 it was provided by the compiler and not the user. This attribute is
1419 always provided, and is @code{False} if the field is not artificial.
1422 This is @code{True} if the field represents a base class of a C@t{++}
1423 structure. This attribute is always provided, and is @code{False}
1424 if the field is not a base class of the type that is the argument of
1425 @code{fields}, or if that type was not a C@t{++} class.
1428 If the field is packed, or is a bitfield, then this will have a
1429 non-zero value, which is the size of the field in bits. Otherwise,
1430 this will be zero; in this case the field's size is given by its type.
1433 The type of the field. This is usually an instance of @code{Type},
1434 but it can be @code{None} in some situations.
1437 The type which contains this field. This is an instance of
1442 @defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
1443 Return a new @code{gdb.Type} object which represents an array of this
1444 type. If one argument is given, it is the inclusive upper bound of
1445 the array; in this case the lower bound is zero. If two arguments are
1446 given, the first argument is the lower bound of the array, and the
1447 second argument is the upper bound of the array. An array's length
1448 must not be negative, but the bounds can be.
1451 @defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
1452 Return a new @code{gdb.Type} object which represents a vector of this
1453 type. If one argument is given, it is the inclusive upper bound of
1454 the vector; in this case the lower bound is zero. If two arguments are
1455 given, the first argument is the lower bound of the vector, and the
1456 second argument is the upper bound of the vector. A vector's length
1457 must not be negative, but the bounds can be.
1459 The difference between an @code{array} and a @code{vector} is that
1460 arrays behave like in C: when used in expressions they decay to a pointer
1461 to the first element whereas vectors are treated as first class values.
1464 @defun Type.const ()
1465 Return a new @code{gdb.Type} object which represents a
1466 @code{const}-qualified variant of this type.
1469 @defun Type.volatile ()
1470 Return a new @code{gdb.Type} object which represents a
1471 @code{volatile}-qualified variant of this type.
1474 @defun Type.unqualified ()
1475 Return a new @code{gdb.Type} object which represents an unqualified
1476 variant of this type. That is, the result is neither @code{const} nor
1480 @defun Type.range ()
1481 Return a Python @code{Tuple} object that contains two elements: the
1482 low bound of the argument type and the high bound of that type. If
1483 the type does not have a range, @value{GDBN} will raise a
1484 @code{gdb.error} exception (@pxref{Exception Handling}).
1487 @defun Type.reference ()
1488 Return a new @code{gdb.Type} object which represents a reference to this
1492 @defun Type.pointer ()
1493 Return a new @code{gdb.Type} object which represents a pointer to this
1497 @defun Type.strip_typedefs ()
1498 Return a new @code{gdb.Type} that represents the real type,
1499 after removing all layers of typedefs.
1502 @defun Type.target ()
1503 Return a new @code{gdb.Type} object which represents the target type
1506 For a pointer type, the target type is the type of the pointed-to
1507 object. For an array type (meaning C-like arrays), the target type is
1508 the type of the elements of the array. For a function or method type,
1509 the target type is the type of the return value. For a complex type,
1510 the target type is the type of the elements. For a typedef, the
1511 target type is the aliased type.
1513 If the type does not have a target, this method will throw an
1517 @defun Type.template_argument (n @r{[}, block@r{]})
1518 If this @code{gdb.Type} is an instantiation of a template, this will
1519 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1520 value of the @var{n}th template argument (indexed starting at 0).
1522 If this @code{gdb.Type} is not a template type, or if the type has fewer
1523 than @var{n} template arguments, this will throw an exception.
1524 Ordinarily, only C@t{++} code will have template types.
1526 If @var{block} is given, then @var{name} is looked up in that scope.
1527 Otherwise, it is searched for globally.
1530 @defun Type.optimized_out ()
1531 Return @code{gdb.Value} instance of this type whose value is optimized
1532 out. This allows a frame decorator to indicate that the value of an
1533 argument or a local variable is not known.
1536 Each type has a code, which indicates what category this type falls
1537 into. The available type categories are represented by constants
1538 defined in the @code{gdb} module:
1541 @vindex TYPE_CODE_PTR
1542 @item gdb.TYPE_CODE_PTR
1543 The type is a pointer.
1545 @vindex TYPE_CODE_ARRAY
1546 @item gdb.TYPE_CODE_ARRAY
1547 The type is an array.
1549 @vindex TYPE_CODE_STRUCT
1550 @item gdb.TYPE_CODE_STRUCT
1551 The type is a structure.
1553 @vindex TYPE_CODE_UNION
1554 @item gdb.TYPE_CODE_UNION
1555 The type is a union.
1557 @vindex TYPE_CODE_ENUM
1558 @item gdb.TYPE_CODE_ENUM
1559 The type is an enum.
1561 @vindex TYPE_CODE_FLAGS
1562 @item gdb.TYPE_CODE_FLAGS
1563 A bit flags type, used for things such as status registers.
1565 @vindex TYPE_CODE_FUNC
1566 @item gdb.TYPE_CODE_FUNC
1567 The type is a function.
1569 @vindex TYPE_CODE_INT
1570 @item gdb.TYPE_CODE_INT
1571 The type is an integer type.
1573 @vindex TYPE_CODE_FLT
1574 @item gdb.TYPE_CODE_FLT
1575 A floating point type.
1577 @vindex TYPE_CODE_VOID
1578 @item gdb.TYPE_CODE_VOID
1579 The special type @code{void}.
1581 @vindex TYPE_CODE_SET
1582 @item gdb.TYPE_CODE_SET
1585 @vindex TYPE_CODE_RANGE
1586 @item gdb.TYPE_CODE_RANGE
1587 A range type, that is, an integer type with bounds.
1589 @vindex TYPE_CODE_STRING
1590 @item gdb.TYPE_CODE_STRING
1591 A string type. Note that this is only used for certain languages with
1592 language-defined string types; C strings are not represented this way.
1594 @vindex TYPE_CODE_BITSTRING
1595 @item gdb.TYPE_CODE_BITSTRING
1596 A string of bits. It is deprecated.
1598 @vindex TYPE_CODE_ERROR
1599 @item gdb.TYPE_CODE_ERROR
1600 An unknown or erroneous type.
1602 @vindex TYPE_CODE_METHOD
1603 @item gdb.TYPE_CODE_METHOD
1604 A method type, as found in C@t{++}.
1606 @vindex TYPE_CODE_METHODPTR
1607 @item gdb.TYPE_CODE_METHODPTR
1608 A pointer-to-member-function.
1610 @vindex TYPE_CODE_MEMBERPTR
1611 @item gdb.TYPE_CODE_MEMBERPTR
1612 A pointer-to-member.
1614 @vindex TYPE_CODE_REF
1615 @item gdb.TYPE_CODE_REF
1618 @vindex TYPE_CODE_RVALUE_REF
1619 @item gdb.TYPE_CODE_RVALUE_REF
1620 A C@t{++}11 rvalue reference type.
1622 @vindex TYPE_CODE_CHAR
1623 @item gdb.TYPE_CODE_CHAR
1626 @vindex TYPE_CODE_BOOL
1627 @item gdb.TYPE_CODE_BOOL
1630 @vindex TYPE_CODE_COMPLEX
1631 @item gdb.TYPE_CODE_COMPLEX
1632 A complex float type.
1634 @vindex TYPE_CODE_TYPEDEF
1635 @item gdb.TYPE_CODE_TYPEDEF
1636 A typedef to some other type.
1638 @vindex TYPE_CODE_NAMESPACE
1639 @item gdb.TYPE_CODE_NAMESPACE
1640 A C@t{++} namespace.
1642 @vindex TYPE_CODE_DECFLOAT
1643 @item gdb.TYPE_CODE_DECFLOAT
1644 A decimal floating point type.
1646 @vindex TYPE_CODE_INTERNAL_FUNCTION
1647 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1648 A function internal to @value{GDBN}. This is the type used to represent
1649 convenience functions.
1651 @vindex TYPE_CODE_XMETHOD
1652 @item gdb.TYPE_CODE_XMETHOD
1653 A method internal to @value{GDBN}. This is the type used to represent
1654 xmethods (@pxref{Writing an Xmethod}).
1656 @vindex TYPE_CODE_FIXED_POINT
1657 @item gdb.TYPE_CODE_FIXED_POINT
1658 A fixed-point number.
1660 @vindex TYPE_CODE_NAMESPACE
1661 @item gdb.TYPE_CODE_NAMESPACE
1665 Further support for types is provided in the @code{gdb.types}
1666 Python module (@pxref{gdb.types}).
1668 @node Pretty Printing API
1669 @subsubsection Pretty Printing API
1670 @cindex python pretty printing api
1672 A pretty-printer is just an object that holds a value and implements a
1673 specific interface, defined here. An example output is provided
1674 (@pxref{Pretty Printing}).
1676 @defun pretty_printer.children (self)
1677 @value{GDBN} will call this method on a pretty-printer to compute the
1678 children of the pretty-printer's value.
1680 This method must return an object conforming to the Python iterator
1681 protocol. Each item returned by the iterator must be a tuple holding
1682 two elements. The first element is the ``name'' of the child; the
1683 second element is the child's value. The value can be any Python
1684 object which is convertible to a @value{GDBN} value.
1686 This method is optional. If it does not exist, @value{GDBN} will act
1687 as though the value has no children.
1689 For efficiency, the @code{children} method should lazily compute its
1690 results. This will let @value{GDBN} read as few elements as
1691 necessary, for example when various print settings (@pxref{Print
1692 Settings}) or @code{-var-list-children} (@pxref{GDB/MI Variable
1693 Objects}) limit the number of elements to be displayed.
1695 Children may be hidden from display based on the value of @samp{set
1696 print max-depth} (@pxref{Print Settings}).
1699 @defun pretty_printer.display_hint (self)
1700 The CLI may call this method and use its result to change the
1701 formatting of a value. The result will also be supplied to an MI
1702 consumer as a @samp{displayhint} attribute of the variable being
1705 This method is optional. If it does exist, this method must return a
1706 string or the special value @code{None}.
1708 Some display hints are predefined by @value{GDBN}:
1712 Indicate that the object being printed is ``array-like''. The CLI
1713 uses this to respect parameters such as @code{set print elements} and
1714 @code{set print array}.
1717 Indicate that the object being printed is ``map-like'', and that the
1718 children of this value can be assumed to alternate between keys and
1722 Indicate that the object being printed is ``string-like''. If the
1723 printer's @code{to_string} method returns a Python string of some
1724 kind, then @value{GDBN} will call its internal language-specific
1725 string-printing function to format the string. For the CLI this means
1726 adding quotation marks, possibly escaping some characters, respecting
1727 @code{set print elements}, and the like.
1730 The special value @code{None} causes @value{GDBN} to apply the default
1734 @defun pretty_printer.to_string (self)
1735 @value{GDBN} will call this method to display the string
1736 representation of the value passed to the object's constructor.
1738 When printing from the CLI, if the @code{to_string} method exists,
1739 then @value{GDBN} will prepend its result to the values returned by
1740 @code{children}. Exactly how this formatting is done is dependent on
1741 the display hint, and may change as more hints are added. Also,
1742 depending on the print settings (@pxref{Print Settings}), the CLI may
1743 print just the result of @code{to_string} in a stack trace, omitting
1744 the result of @code{children}.
1746 If this method returns a string, it is printed verbatim.
1748 Otherwise, if this method returns an instance of @code{gdb.Value},
1749 then @value{GDBN} prints this value. This may result in a call to
1750 another pretty-printer.
1752 If instead the method returns a Python value which is convertible to a
1753 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1754 the resulting value. Again, this may result in a call to another
1755 pretty-printer. Python scalars (integers, floats, and booleans) and
1756 strings are convertible to @code{gdb.Value}; other types are not.
1758 Finally, if this method returns @code{None} then no further operations
1759 are peformed in this method and nothing is printed.
1761 If the result is not one of these types, an exception is raised.
1764 @value{GDBN} provides a function which can be used to look up the
1765 default pretty-printer for a @code{gdb.Value}:
1767 @findex gdb.default_visualizer
1768 @defun gdb.default_visualizer (value)
1769 This function takes a @code{gdb.Value} object as an argument. If a
1770 pretty-printer for this value exists, then it is returned. If no such
1771 printer exists, then this returns @code{None}.
1774 Normally, a pretty-printer can respect the user's print settings
1775 (including temporarily applied settings, such as @samp{/x}) simply by
1776 calling @code{Value.format_string} (@pxref{Values From Inferior}).
1777 However, these settings can also be queried directly:
1779 @findex gdb.print_options
1780 @defun gdb.print_options ()
1781 Return a dictionary whose keys are the valid keywords that can be
1782 given to @code{Value.format_string}, and whose values are the user's
1783 settings. During a @code{print} or other operation, the values will
1784 reflect any flags that are temporarily in effect.
1787 (gdb) python print (gdb.print_options ()['max_elements'])
1792 @node Selecting Pretty-Printers
1793 @subsubsection Selecting Pretty-Printers
1794 @cindex selecting python pretty-printers
1796 @value{GDBN} provides several ways to register a pretty-printer:
1797 globally, per program space, and per objfile. When choosing how to
1798 register your pretty-printer, a good rule is to register it with the
1799 smallest scope possible: that is prefer a specific objfile first, then
1800 a program space, and only register a printer globally as a last
1803 @findex gdb.pretty_printers
1804 @defvar gdb.pretty_printers
1805 The Python list @code{gdb.pretty_printers} contains an array of
1806 functions or callable objects that have been registered via addition
1807 as a pretty-printer. Printers in this list are called @code{global}
1808 printers, they're available when debugging all inferiors.
1811 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1812 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1815 Each function on these lists is passed a single @code{gdb.Value}
1816 argument and should return a pretty-printer object conforming to the
1817 interface definition above (@pxref{Pretty Printing API}). If a function
1818 cannot create a pretty-printer for the value, it should return
1821 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1822 @code{gdb.Objfile} in the current program space and iteratively calls
1823 each enabled lookup routine in the list for that @code{gdb.Objfile}
1824 until it receives a pretty-printer object.
1825 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1826 searches the pretty-printer list of the current program space,
1827 calling each enabled function until an object is returned.
1828 After these lists have been exhausted, it tries the global
1829 @code{gdb.pretty_printers} list, again calling each enabled function until an
1832 The order in which the objfiles are searched is not specified. For a
1833 given list, functions are always invoked from the head of the list,
1834 and iterated over sequentially until the end of the list, or a printer
1837 For various reasons a pretty-printer may not work.
1838 For example, the underlying data structure may have changed and
1839 the pretty-printer is out of date.
1841 The consequences of a broken pretty-printer are severe enough that
1842 @value{GDBN} provides support for enabling and disabling individual
1843 printers. For example, if @code{print frame-arguments} is on,
1844 a backtrace can become highly illegible if any argument is printed
1845 with a broken printer.
1847 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1848 attribute to the registered function or callable object. If this attribute
1849 is present and its value is @code{False}, the printer is disabled, otherwise
1850 the printer is enabled.
1852 @node Writing a Pretty-Printer
1853 @subsubsection Writing a Pretty-Printer
1854 @cindex writing a pretty-printer
1856 A pretty-printer consists of two parts: a lookup function to detect
1857 if the type is supported, and the printer itself.
1859 Here is an example showing how a @code{std::string} printer might be
1860 written. @xref{Pretty Printing API}, for details on the API this class
1864 class StdStringPrinter(object):
1865 "Print a std::string"
1867 def __init__(self, val):
1870 def to_string(self):
1871 return self.val['_M_dataplus']['_M_p']
1873 def display_hint(self):
1877 And here is an example showing how a lookup function for the printer
1878 example above might be written.
1881 def str_lookup_function(val):
1882 lookup_tag = val.type.tag
1883 if lookup_tag is None:
1885 regex = re.compile("^std::basic_string<char,.*>$")
1886 if regex.match(lookup_tag):
1887 return StdStringPrinter(val)
1891 The example lookup function extracts the value's type, and attempts to
1892 match it to a type that it can pretty-print. If it is a type the
1893 printer can pretty-print, it will return a printer object. If not, it
1894 returns @code{None}.
1896 We recommend that you put your core pretty-printers into a Python
1897 package. If your pretty-printers are for use with a library, we
1898 further recommend embedding a version number into the package name.
1899 This practice will enable @value{GDBN} to load multiple versions of
1900 your pretty-printers at the same time, because they will have
1903 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
1904 can be evaluated multiple times without changing its meaning. An
1905 ideal auto-load file will consist solely of @code{import}s of your
1906 printer modules, followed by a call to a register pretty-printers with
1907 the current objfile.
1909 Taken as a whole, this approach will scale nicely to multiple
1910 inferiors, each potentially using a different library version.
1911 Embedding a version number in the Python package name will ensure that
1912 @value{GDBN} is able to load both sets of printers simultaneously.
1913 Then, because the search for pretty-printers is done by objfile, and
1914 because your auto-loaded code took care to register your library's
1915 printers with a specific objfile, @value{GDBN} will find the correct
1916 printers for the specific version of the library used by each
1919 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
1920 this code might appear in @code{gdb.libstdcxx.v6}:
1923 def register_printers(objfile):
1924 objfile.pretty_printers.append(str_lookup_function)
1928 And then the corresponding contents of the auto-load file would be:
1931 import gdb.libstdcxx.v6
1932 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
1935 The previous example illustrates a basic pretty-printer.
1936 There are a few things that can be improved on.
1937 The printer doesn't have a name, making it hard to identify in a
1938 list of installed printers. The lookup function has a name, but
1939 lookup functions can have arbitrary, even identical, names.
1941 Second, the printer only handles one type, whereas a library typically has
1942 several types. One could install a lookup function for each desired type
1943 in the library, but one could also have a single lookup function recognize
1944 several types. The latter is the conventional way this is handled.
1945 If a pretty-printer can handle multiple data types, then its
1946 @dfn{subprinters} are the printers for the individual data types.
1948 The @code{gdb.printing} module provides a formal way of solving these
1949 problems (@pxref{gdb.printing}).
1950 Here is another example that handles multiple types.
1952 These are the types we are going to pretty-print:
1955 struct foo @{ int a, b; @};
1956 struct bar @{ struct foo x, y; @};
1959 Here are the printers:
1963 """Print a foo object."""
1965 def __init__(self, val):
1968 def to_string(self):
1969 return ("a=<" + str(self.val["a"]) +
1970 "> b=<" + str(self.val["b"]) + ">")
1973 """Print a bar object."""
1975 def __init__(self, val):
1978 def to_string(self):
1979 return ("x=<" + str(self.val["x"]) +
1980 "> y=<" + str(self.val["y"]) + ">")
1983 This example doesn't need a lookup function, that is handled by the
1984 @code{gdb.printing} module. Instead a function is provided to build up
1985 the object that handles the lookup.
1990 def build_pretty_printer():
1991 pp = gdb.printing.RegexpCollectionPrettyPrinter(
1993 pp.add_printer('foo', '^foo$', fooPrinter)
1994 pp.add_printer('bar', '^bar$', barPrinter)
1998 And here is the autoload support:
2003 gdb.printing.register_pretty_printer(
2004 gdb.current_objfile(),
2005 my_library.build_pretty_printer())
2008 Finally, when this printer is loaded into @value{GDBN}, here is the
2009 corresponding output of @samp{info pretty-printer}:
2012 (gdb) info pretty-printer
2019 @node Type Printing API
2020 @subsubsection Type Printing API
2021 @cindex type printing API for Python
2023 @value{GDBN} provides a way for Python code to customize type display.
2024 This is mainly useful for substituting canonical typedef names for
2027 @cindex type printer
2028 A @dfn{type printer} is just a Python object conforming to a certain
2029 protocol. A simple base class implementing the protocol is provided;
2030 see @ref{gdb.types}. A type printer must supply at least:
2032 @defivar type_printer enabled
2033 A boolean which is True if the printer is enabled, and False
2034 otherwise. This is manipulated by the @code{enable type-printer}
2035 and @code{disable type-printer} commands.
2038 @defivar type_printer name
2039 The name of the type printer. This must be a string. This is used by
2040 the @code{enable type-printer} and @code{disable type-printer}
2044 @defmethod type_printer instantiate (self)
2045 This is called by @value{GDBN} at the start of type-printing. It is
2046 only called if the type printer is enabled. This method must return a
2047 new object that supplies a @code{recognize} method, as described below.
2051 When displaying a type, say via the @code{ptype} command, @value{GDBN}
2052 will compute a list of type recognizers. This is done by iterating
2053 first over the per-objfile type printers (@pxref{Objfiles In Python}),
2054 followed by the per-progspace type printers (@pxref{Progspaces In
2055 Python}), and finally the global type printers.
2057 @value{GDBN} will call the @code{instantiate} method of each enabled
2058 type printer. If this method returns @code{None}, then the result is
2059 ignored; otherwise, it is appended to the list of recognizers.
2061 Then, when @value{GDBN} is going to display a type name, it iterates
2062 over the list of recognizers. For each one, it calls the recognition
2063 function, stopping if the function returns a non-@code{None} value.
2064 The recognition function is defined as:
2066 @defmethod type_recognizer recognize (self, type)
2067 If @var{type} is not recognized, return @code{None}. Otherwise,
2068 return a string which is to be printed as the name of @var{type}.
2069 The @var{type} argument will be an instance of @code{gdb.Type}
2070 (@pxref{Types In Python}).
2073 @value{GDBN} uses this two-pass approach so that type printers can
2074 efficiently cache information without holding on to it too long. For
2075 example, it can be convenient to look up type information in a type
2076 printer and hold it for a recognizer's lifetime; if a single pass were
2077 done then type printers would have to make use of the event system in
2078 order to avoid holding information that could become stale as the
2081 @node Frame Filter API
2082 @subsubsection Filtering Frames
2083 @cindex frame filters api
2085 Frame filters are Python objects that manipulate the visibility of a
2086 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
2089 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
2090 commands (@pxref{GDB/MI}), those that return a collection of frames
2091 are affected. The commands that work with frame filters are:
2093 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
2094 @code{-stack-list-frames}
2095 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
2096 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
2097 -stack-list-variables command}), @code{-stack-list-arguments}
2098 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
2099 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
2100 -stack-list-locals command}).
2102 A frame filter works by taking an iterator as an argument, applying
2103 actions to the contents of that iterator, and returning another
2104 iterator (or, possibly, the same iterator it was provided in the case
2105 where the filter does not perform any operations). Typically, frame
2106 filters utilize tools such as the Python's @code{itertools} module to
2107 work with and create new iterators from the source iterator.
2108 Regardless of how a filter chooses to apply actions, it must not alter
2109 the underlying @value{GDBN} frame or frames, or attempt to alter the
2110 call-stack within @value{GDBN}. This preserves data integrity within
2111 @value{GDBN}. Frame filters are executed on a priority basis and care
2112 should be taken that some frame filters may have been executed before,
2113 and that some frame filters will be executed after.
2115 An important consideration when designing frame filters, and well
2116 worth reflecting upon, is that frame filters should avoid unwinding
2117 the call stack if possible. Some stacks can run very deep, into the
2118 tens of thousands in some cases. To search every frame when a frame
2119 filter executes may be too expensive at that step. The frame filter
2120 cannot know how many frames it has to iterate over, and it may have to
2121 iterate through them all. This ends up duplicating effort as
2122 @value{GDBN} performs this iteration when it prints the frames. If
2123 the filter can defer unwinding frames until frame decorators are
2124 executed, after the last filter has executed, it should. @xref{Frame
2125 Decorator API}, for more information on decorators. Also, there are
2126 examples for both frame decorators and filters in later chapters.
2127 @xref{Writing a Frame Filter}, for more information.
2129 The Python dictionary @code{gdb.frame_filters} contains key/object
2130 pairings that comprise a frame filter. Frame filters in this
2131 dictionary are called @code{global} frame filters, and they are
2132 available when debugging all inferiors. These frame filters must
2133 register with the dictionary directly. In addition to the
2134 @code{global} dictionary, there are other dictionaries that are loaded
2135 with different inferiors via auto-loading (@pxref{Python
2136 Auto-loading}). The two other areas where frame filter dictionaries
2137 can be found are: @code{gdb.Progspace} which contains a
2138 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
2139 object which also contains a @code{frame_filters} dictionary
2142 When a command is executed from @value{GDBN} that is compatible with
2143 frame filters, @value{GDBN} combines the @code{global},
2144 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
2145 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
2146 several frames, and thus several object files, might be in use.
2147 @value{GDBN} then prunes any frame filter whose @code{enabled}
2148 attribute is @code{False}. This pruned list is then sorted according
2149 to the @code{priority} attribute in each filter.
2151 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
2152 creates an iterator which wraps each frame in the call stack in a
2153 @code{FrameDecorator} object, and calls each filter in order. The
2154 output from the previous filter will always be the input to the next
2157 Frame filters have a mandatory interface which each frame filter must
2158 implement, defined here:
2160 @defun FrameFilter.filter (iterator)
2161 @value{GDBN} will call this method on a frame filter when it has
2162 reached the order in the priority list for that filter.
2164 For example, if there are four frame filters:
2175 The order that the frame filters will be called is:
2178 Filter3 -> Filter2 -> Filter1 -> Filter4
2181 Note that the output from @code{Filter3} is passed to the input of
2182 @code{Filter2}, and so on.
2184 This @code{filter} method is passed a Python iterator. This iterator
2185 contains a sequence of frame decorators that wrap each
2186 @code{gdb.Frame}, or a frame decorator that wraps another frame
2187 decorator. The first filter that is executed in the sequence of frame
2188 filters will receive an iterator entirely comprised of default
2189 @code{FrameDecorator} objects. However, after each frame filter is
2190 executed, the previous frame filter may have wrapped some or all of
2191 the frame decorators with their own frame decorator. As frame
2192 decorators must also conform to a mandatory interface, these
2193 decorators can be assumed to act in a uniform manner (@pxref{Frame
2196 This method must return an object conforming to the Python iterator
2197 protocol. Each item in the iterator must be an object conforming to
2198 the frame decorator interface. If a frame filter does not wish to
2199 perform any operations on this iterator, it should return that
2202 This method is not optional. If it does not exist, @value{GDBN} will
2203 raise and print an error.
2206 @defvar FrameFilter.name
2207 The @code{name} attribute must be Python string which contains the
2208 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
2209 Management}). This attribute may contain any combination of letters
2210 or numbers. Care should be taken to ensure that it is unique. This
2211 attribute is mandatory.
2214 @defvar FrameFilter.enabled
2215 The @code{enabled} attribute must be Python boolean. This attribute
2216 indicates to @value{GDBN} whether the frame filter is enabled, and
2217 should be considered when frame filters are executed. If
2218 @code{enabled} is @code{True}, then the frame filter will be executed
2219 when any of the backtrace commands detailed earlier in this chapter
2220 are executed. If @code{enabled} is @code{False}, then the frame
2221 filter will not be executed. This attribute is mandatory.
2224 @defvar FrameFilter.priority
2225 The @code{priority} attribute must be Python integer. This attribute
2226 controls the order of execution in relation to other frame filters.
2227 There are no imposed limits on the range of @code{priority} other than
2228 it must be a valid integer. The higher the @code{priority} attribute,
2229 the sooner the frame filter will be executed in relation to other
2230 frame filters. Although @code{priority} can be negative, it is
2231 recommended practice to assume zero is the lowest priority that a
2232 frame filter can be assigned. Frame filters that have the same
2233 priority are executed in unsorted order in that priority slot. This
2234 attribute is mandatory. 100 is a good default priority.
2237 @node Frame Decorator API
2238 @subsubsection Decorating Frames
2239 @cindex frame decorator api
2241 Frame decorators are sister objects to frame filters (@pxref{Frame
2242 Filter API}). Frame decorators are applied by a frame filter and can
2243 only be used in conjunction with frame filters.
2245 The purpose of a frame decorator is to customize the printed content
2246 of each @code{gdb.Frame} in commands where frame filters are executed.
2247 This concept is called decorating a frame. Frame decorators decorate
2248 a @code{gdb.Frame} with Python code contained within each API call.
2249 This separates the actual data contained in a @code{gdb.Frame} from
2250 the decorated data produced by a frame decorator. This abstraction is
2251 necessary to maintain integrity of the data contained in each
2254 Frame decorators have a mandatory interface, defined below.
2256 @value{GDBN} already contains a frame decorator called
2257 @code{FrameDecorator}. This contains substantial amounts of
2258 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
2259 recommended that other frame decorators inherit and extend this
2260 object, and only to override the methods needed.
2262 @tindex gdb.FrameDecorator
2263 @code{FrameDecorator} is defined in the Python module
2264 @code{gdb.FrameDecorator}, so your code can import it like:
2266 from gdb.FrameDecorator import FrameDecorator
2269 @defun FrameDecorator.elided (self)
2271 The @code{elided} method groups frames together in a hierarchical
2272 system. An example would be an interpreter, where multiple low-level
2273 frames make up a single call in the interpreted language. In this
2274 example, the frame filter would elide the low-level frames and present
2275 a single high-level frame, representing the call in the interpreted
2276 language, to the user.
2278 The @code{elided} function must return an iterable and this iterable
2279 must contain the frames that are being elided wrapped in a suitable
2280 frame decorator. If no frames are being elided this function may
2281 return an empty iterable, or @code{None}. Elided frames are indented
2282 from normal frames in a @code{CLI} backtrace, or in the case of
2283 @sc{GDB/MI}, are placed in the @code{children} field of the eliding
2286 It is the frame filter's task to also filter out the elided frames from
2287 the source iterator. This will avoid printing the frame twice.
2290 @defun FrameDecorator.function (self)
2292 This method returns the name of the function in the frame that is to
2295 This method must return a Python string describing the function, or
2298 If this function returns @code{None}, @value{GDBN} will not print any
2299 data for this field.
2302 @defun FrameDecorator.address (self)
2304 This method returns the address of the frame that is to be printed.
2306 This method must return a Python numeric integer type of sufficient
2307 size to describe the address of the frame, or @code{None}.
2309 If this function returns a @code{None}, @value{GDBN} will not print
2310 any data for this field.
2313 @defun FrameDecorator.filename (self)
2315 This method returns the filename and path associated with this frame.
2317 This method must return a Python string containing the filename and
2318 the path to the object file backing the frame, or @code{None}.
2320 If this function returns a @code{None}, @value{GDBN} will not print
2321 any data for this field.
2324 @defun FrameDecorator.line (self):
2326 This method returns the line number associated with the current
2327 position within the function addressed by this frame.
2329 This method must return a Python integer type, or @code{None}.
2331 If this function returns a @code{None}, @value{GDBN} will not print
2332 any data for this field.
2335 @defun FrameDecorator.frame_args (self)
2338 This method must return an iterable, or @code{None}. Returning an
2339 empty iterable, or @code{None} means frame arguments will not be
2340 printed for this frame. This iterable must contain objects that
2341 implement two methods, described here.
2343 This object must implement a @code{symbol} method which takes a
2344 single @code{self} parameter and must return a @code{gdb.Symbol}
2345 (@pxref{Symbols In Python}), or a Python string. The object must also
2346 implement a @code{value} method which takes a single @code{self}
2347 parameter and must return a @code{gdb.Value} (@pxref{Values From
2348 Inferior}), a Python value, or @code{None}. If the @code{value}
2349 method returns @code{None}, and the @code{argument} method returns a
2350 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
2351 the @code{gdb.Symbol} automatically.
2356 class SymValueWrapper():
2358 def __init__(self, symbol, value):
2368 class SomeFrameDecorator()
2371 def frame_args(self):
2374 block = self.inferior_frame.block()
2378 # Iterate over all symbols in a block. Only add
2379 # symbols that are arguments.
2381 if not sym.is_argument:
2383 args.append(SymValueWrapper(sym,None))
2385 # Add example synthetic argument.
2386 args.append(SymValueWrapper(``foo'', 42))
2392 @defun FrameDecorator.frame_locals (self)
2394 This method must return an iterable or @code{None}. Returning an
2395 empty iterable, or @code{None} means frame local arguments will not be
2396 printed for this frame.
2398 The object interface, the description of the various strategies for
2399 reading frame locals, and the example are largely similar to those
2400 described in the @code{frame_args} function, (@pxref{frame_args,,The
2401 frame filter frame_args function}). Below is a modified example:
2404 class SomeFrameDecorator()
2407 def frame_locals(self):
2410 block = self.inferior_frame.block()
2414 # Iterate over all symbols in a block. Add all
2415 # symbols, except arguments.
2419 vars.append(SymValueWrapper(sym,None))
2421 # Add an example of a synthetic local variable.
2422 vars.append(SymValueWrapper(``bar'', 99))
2428 @defun FrameDecorator.inferior_frame (self):
2430 This method must return the underlying @code{gdb.Frame} that this
2431 frame decorator is decorating. @value{GDBN} requires the underlying
2432 frame for internal frame information to determine how to print certain
2433 values when printing a frame.
2436 @node Writing a Frame Filter
2437 @subsubsection Writing a Frame Filter
2438 @cindex writing a frame filter
2440 There are three basic elements that a frame filter must implement: it
2441 must correctly implement the documented interface (@pxref{Frame Filter
2442 API}), it must register itself with @value{GDBN}, and finally, it must
2443 decide if it is to work on the data provided by @value{GDBN}. In all
2444 cases, whether it works on the iterator or not, each frame filter must
2445 return an iterator. A bare-bones frame filter follows the pattern in
2446 the following example.
2451 class FrameFilter():
2454 # Frame filter attribute creation.
2456 # 'name' is the name of the filter that GDB will display.
2458 # 'priority' is the priority of the filter relative to other
2461 # 'enabled' is a boolean that indicates whether this filter is
2462 # enabled and should be executed.
2468 # Register this frame filter with the global frame_filters
2470 gdb.frame_filters[self.name] = self
2472 def filter(self, frame_iter):
2473 # Just return the iterator.
2477 The frame filter in the example above implements the three
2478 requirements for all frame filters. It implements the API, self
2479 registers, and makes a decision on the iterator (in this case, it just
2480 returns the iterator untouched).
2482 The first step is attribute creation and assignment, and as shown in
2483 the comments the filter assigns the following attributes: @code{name},
2484 @code{priority} and whether the filter should be enabled with the
2485 @code{enabled} attribute.
2487 The second step is registering the frame filter with the dictionary or
2488 dictionaries that the frame filter has interest in. As shown in the
2489 comments, this filter just registers itself with the global dictionary
2490 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
2491 is a dictionary that is initialized in the @code{gdb} module when
2492 @value{GDBN} starts. What dictionary a filter registers with is an
2493 important consideration. Generally, if a filter is specific to a set
2494 of code, it should be registered either in the @code{objfile} or
2495 @code{progspace} dictionaries as they are specific to the program
2496 currently loaded in @value{GDBN}. The global dictionary is always
2497 present in @value{GDBN} and is never unloaded. Any filters registered
2498 with the global dictionary will exist until @value{GDBN} exits. To
2499 avoid filters that may conflict, it is generally better to register
2500 frame filters against the dictionaries that more closely align with
2501 the usage of the filter currently in question. @xref{Python
2502 Auto-loading}, for further information on auto-loading Python scripts.
2504 @value{GDBN} takes a hands-off approach to frame filter registration,
2505 therefore it is the frame filter's responsibility to ensure
2506 registration has occurred, and that any exceptions are handled
2507 appropriately. In particular, you may wish to handle exceptions
2508 relating to Python dictionary key uniqueness. It is mandatory that
2509 the dictionary key is the same as frame filter's @code{name}
2510 attribute. When a user manages frame filters (@pxref{Frame Filter
2511 Management}), the names @value{GDBN} will display are those contained
2512 in the @code{name} attribute.
2514 The final step of this example is the implementation of the
2515 @code{filter} method. As shown in the example comments, we define the
2516 @code{filter} method and note that the method must take an iterator,
2517 and also must return an iterator. In this bare-bones example, the
2518 frame filter is not very useful as it just returns the iterator
2519 untouched. However this is a valid operation for frame filters that
2520 have the @code{enabled} attribute set, but decide not to operate on
2523 In the next example, the frame filter operates on all frames and
2524 utilizes a frame decorator to perform some work on the frames.
2525 @xref{Frame Decorator API}, for further information on the frame
2526 decorator interface.
2528 This example works on inlined frames. It highlights frames which are
2529 inlined by tagging them with an ``[inlined]'' tag. By applying a
2530 frame decorator to all frames with the Python @code{itertools imap}
2531 method, the example defers actions to the frame decorator. Frame
2532 decorators are only processed when @value{GDBN} prints the backtrace.
2534 This introduces a new decision making topic: whether to perform
2535 decision making operations at the filtering step, or at the printing
2536 step. In this example's approach, it does not perform any filtering
2537 decisions at the filtering step beyond mapping a frame decorator to
2538 each frame. This allows the actual decision making to be performed
2539 when each frame is printed. This is an important consideration, and
2540 well worth reflecting upon when designing a frame filter. An issue
2541 that frame filters should avoid is unwinding the stack if possible.
2542 Some stacks can run very deep, into the tens of thousands in some
2543 cases. To search every frame to determine if it is inlined ahead of
2544 time may be too expensive at the filtering step. The frame filter
2545 cannot know how many frames it has to iterate over, and it would have
2546 to iterate through them all. This ends up duplicating effort as
2547 @value{GDBN} performs this iteration when it prints the frames.
2549 In this example decision making can be deferred to the printing step.
2550 As each frame is printed, the frame decorator can examine each frame
2551 in turn when @value{GDBN} iterates. From a performance viewpoint,
2552 this is the most appropriate decision to make as it avoids duplicating
2553 the effort that the printing step would undertake anyway. Also, if
2554 there are many frame filters unwinding the stack during filtering, it
2555 can substantially delay the printing of the backtrace which will
2556 result in large memory usage, and a poor user experience.
2559 class InlineFilter():
2562 self.name = "InlinedFrameFilter"
2565 gdb.frame_filters[self.name] = self
2567 def filter(self, frame_iter):
2568 frame_iter = itertools.imap(InlinedFrameDecorator,
2573 This frame filter is somewhat similar to the earlier example, except
2574 that the @code{filter} method applies a frame decorator object called
2575 @code{InlinedFrameDecorator} to each element in the iterator. The
2576 @code{imap} Python method is light-weight. It does not proactively
2577 iterate over the iterator, but rather creates a new iterator which
2578 wraps the existing one.
2580 Below is the frame decorator for this example.
2583 class InlinedFrameDecorator(FrameDecorator):
2585 def __init__(self, fobj):
2586 super(InlinedFrameDecorator, self).__init__(fobj)
2589 frame = self.inferior_frame()
2590 name = str(frame.name())
2592 if frame.type() == gdb.INLINE_FRAME:
2593 name = name + " [inlined]"
2598 This frame decorator only defines and overrides the @code{function}
2599 method. It lets the supplied @code{FrameDecorator}, which is shipped
2600 with @value{GDBN}, perform the other work associated with printing
2603 The combination of these two objects create this output from a
2607 #0 0x004004e0 in bar () at inline.c:11
2608 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2609 #2 0x00400566 in main () at inline.c:31
2612 So in the case of this example, a frame decorator is applied to all
2613 frames, regardless of whether they may be inlined or not. As
2614 @value{GDBN} iterates over the iterator produced by the frame filters,
2615 @value{GDBN} executes each frame decorator which then makes a decision
2616 on what to print in the @code{function} callback. Using a strategy
2617 like this is a way to defer decisions on the frame content to printing
2620 @subheading Eliding Frames
2622 It might be that the above example is not desirable for representing
2623 inlined frames, and a hierarchical approach may be preferred. If we
2624 want to hierarchically represent frames, the @code{elided} frame
2625 decorator interface might be preferable.
2627 This example approaches the issue with the @code{elided} method. This
2628 example is quite long, but very simplistic. It is out-of-scope for
2629 this section to write a complete example that comprehensively covers
2630 all approaches of finding and printing inlined frames. However, this
2631 example illustrates the approach an author might use.
2633 This example comprises of three sections.
2636 class InlineFrameFilter():
2639 self.name = "InlinedFrameFilter"
2642 gdb.frame_filters[self.name] = self
2644 def filter(self, frame_iter):
2645 return ElidingInlineIterator(frame_iter)
2648 This frame filter is very similar to the other examples. The only
2649 difference is this frame filter is wrapping the iterator provided to
2650 it (@code{frame_iter}) with a custom iterator called
2651 @code{ElidingInlineIterator}. This again defers actions to when
2652 @value{GDBN} prints the backtrace, as the iterator is not traversed
2655 The iterator for this example is as follows. It is in this section of
2656 the example where decisions are made on the content of the backtrace.
2659 class ElidingInlineIterator:
2660 def __init__(self, ii):
2661 self.input_iterator = ii
2667 frame = next(self.input_iterator)
2669 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2673 eliding_frame = next(self.input_iterator)
2674 except StopIteration:
2676 return ElidingFrameDecorator(eliding_frame, [frame])
2679 This iterator implements the Python iterator protocol. When the
2680 @code{next} function is called (when @value{GDBN} prints each frame),
2681 the iterator checks if this frame decorator, @code{frame}, is wrapping
2682 an inlined frame. If it is not, it returns the existing frame decorator
2683 untouched. If it is wrapping an inlined frame, it assumes that the
2684 inlined frame was contained within the next oldest frame,
2685 @code{eliding_frame}, which it fetches. It then creates and returns a
2686 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2687 elided frame, and the eliding frame.
2690 class ElidingInlineDecorator(FrameDecorator):
2692 def __init__(self, frame, elided_frames):
2693 super(ElidingInlineDecorator, self).__init__(frame)
2695 self.elided_frames = elided_frames
2698 return iter(self.elided_frames)
2701 This frame decorator overrides one function and returns the inlined
2702 frame in the @code{elided} method. As before it lets
2703 @code{FrameDecorator} do the rest of the work involved in printing
2704 this frame. This produces the following output.
2707 #0 0x004004e0 in bar () at inline.c:11
2708 #2 0x00400529 in main () at inline.c:25
2709 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2712 In that output, @code{max} which has been inlined into @code{main} is
2713 printed hierarchically. Another approach would be to combine the
2714 @code{function} method, and the @code{elided} method to both print a
2715 marker in the inlined frame, and also show the hierarchical
2718 @node Unwinding Frames in Python
2719 @subsubsection Unwinding Frames in Python
2720 @cindex unwinding frames in Python
2722 In @value{GDBN} terminology ``unwinding'' is the process of finding
2723 the previous frame (that is, caller's) from the current one. An
2724 unwinder has three methods. The first one checks if it can handle
2725 given frame (``sniff'' it). For the frames it can sniff an unwinder
2726 provides two additional methods: it can return frame's ID, and it can
2727 fetch registers from the previous frame. A running @value{GDBN}
2728 mantains a list of the unwinders and calls each unwinder's sniffer in
2729 turn until it finds the one that recognizes the current frame. There
2730 is an API to register an unwinder.
2732 The unwinders that come with @value{GDBN} handle standard frames.
2733 However, mixed language applications (for example, an application
2734 running Java Virtual Machine) sometimes use frame layouts that cannot
2735 be handled by the @value{GDBN} unwinders. You can write Python code
2736 that can handle such custom frames.
2738 You implement a frame unwinder in Python as a class with which has two
2739 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2740 a single method @code{__call__}, which examines a given frame and
2741 returns an object (an instance of @code{gdb.UnwindInfo class)}
2742 describing it. If an unwinder does not recognize a frame, it should
2743 return @code{None}. The code in @value{GDBN} that enables writing
2744 unwinders in Python uses this object to return frame's ID and previous
2745 frame registers when @value{GDBN} core asks for them.
2747 An unwinder should do as little work as possible. Some otherwise
2748 innocuous operations can cause problems (even crashes, as this code is
2749 not not well-hardened yet). For example, making an inferior call from
2750 an unwinder is unadvisable, as an inferior call will reset
2751 @value{GDBN}'s stack unwinding process, potentially causing re-entrant
2754 @subheading Unwinder Input
2756 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2757 provides a method to read frame's registers:
2759 @defun PendingFrame.read_register (reg)
2760 This method returns the contents of the register @var{reg} in the
2761 frame as a @code{gdb.Value} object. For a description of the
2762 acceptable values of @var{reg} see
2763 @ref{gdbpy_frame_read_register,,Frame.read_register}. If @var{reg}
2764 does not name a register for the current architecture, this method
2765 will throw an exception.
2767 Note that this method will always return a @code{gdb.Value} for a
2768 valid register name. This does not mean that the value will be valid.
2769 For example, you may request a register that an earlier unwinder could
2770 not unwind---the value will be unavailable. Instead, the
2771 @code{gdb.Value} returned from this method will be lazy; that is, its
2772 underlying bits will not be fetched until it is first used. So,
2773 attempting to use such a value will cause an exception at the point of
2776 The type of the returned @code{gdb.Value} depends on the register and
2777 the architecture. It is common for registers to have a scalar type,
2778 like @code{long long}; but many other types are possible, such as
2779 pointer, pointer-to-function, floating point or vector types.
2782 It also provides a factory method to create a @code{gdb.UnwindInfo}
2783 instance to be returned to @value{GDBN}:
2785 @defun PendingFrame.create_unwind_info (frame_id)
2786 Returns a new @code{gdb.UnwindInfo} instance identified by given
2787 @var{frame_id}. The argument is used to build @value{GDBN}'s frame ID
2788 using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
2789 determine which function will be used, as follows:
2793 The frame is identified by the given stack address and PC. The stack
2794 address must be chosen so that it is constant throughout the lifetime
2795 of the frame, so a typical choice is the value of the stack pointer at
2796 the start of the function---in the DWARF standard, this would be the
2797 ``Call Frame Address''.
2799 This is the most common case by far. The other cases are documented
2800 for completeness but are only useful in specialized situations.
2802 @item sp, pc, special
2803 The frame is identified by the stack address, the PC, and a
2804 ``special'' address. The special address is used on architectures
2805 that can have frames that do not change the stack, but which are still
2806 distinct, for example the IA-64, which has a second stack for
2807 registers. Both @var{sp} and @var{special} must be constant
2808 throughout the lifetime of the frame.
2811 The frame is identified by the stack address only. Any other stack
2812 frame with a matching @var{sp} will be considered to match this frame.
2813 Inside gdb, this is called a ``wild frame''. You will never need
2817 Each attribute value should be an instance of @code{gdb.Value}.
2821 @defun PendingFrame.architecture ()
2822 Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
2823 for this @code{gdb.PendingFrame}. This represents the architecture of
2824 the particular frame being unwound.
2827 @defun PendingFrame.level ()
2828 Return an integer, the stack frame level for this frame.
2829 @xref{Frames, ,Stack Frames}.
2832 @subheading Unwinder Output: UnwindInfo
2834 Use @code{PendingFrame.create_unwind_info} method described above to
2835 create a @code{gdb.UnwindInfo} instance. Use the following method to
2836 specify caller registers that have been saved in this frame:
2838 @defun gdb.UnwindInfo.add_saved_register (reg, value)
2839 @var{reg} identifies the register, for a description of the acceptable
2840 values see @ref{gdbpy_frame_read_register,,Frame.read_register}.
2841 @var{value} is a register value (a @code{gdb.Value} object).
2844 @subheading Unwinder Skeleton Code
2846 @value{GDBN} comes with the module containing the base @code{Unwinder}
2847 class. Derive your unwinder class from it and structure the code as
2851 from gdb.unwinders import Unwinder
2853 class FrameId(object):
2854 def __init__(self, sp, pc):
2859 class MyUnwinder(Unwinder):
2861 super(MyUnwinder, self).__init___(<expects unwinder name argument>)
2863 def __call__(pending_frame):
2864 if not <we recognize frame>:
2866 # Create UnwindInfo. Usually the frame is identified by the stack
2867 # pointer and the program counter.
2868 sp = pending_frame.read_register(<SP number>)
2869 pc = pending_frame.read_register(<PC number>)
2870 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
2872 # Find the values of the registers in the caller's frame and
2873 # save them in the result:
2874 unwind_info.add_saved_register(<register>, <value>)
2877 # Return the result:
2882 @subheading Registering an Unwinder
2884 Object files and program spaces can have unwinders registered with
2885 them. In addition, you can also register unwinders globally.
2887 The @code{gdb.unwinders} module provides the function to register an
2890 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
2891 @var{locus} specifies to which unwinder list to prepend the
2892 @var{unwinder}. It can be either an object file, a program space, or
2893 @code{None}, in which case the unwinder is registered globally. The
2894 newly added @var{unwinder} will be called before any other unwinder from the
2895 same locus. Two unwinders in the same locus cannot have the same
2896 name. An attempt to add an unwinder with an already existing name raises
2897 an exception unless @var{replace} is @code{True}, in which case the
2898 old unwinder is deleted.
2901 @subheading Unwinder Precedence
2903 @value{GDBN} first calls the unwinders from all the object files in no
2904 particular order, then the unwinders from the current program space,
2905 and finally the unwinders from @value{GDBN}.
2907 @node Xmethods In Python
2908 @subsubsection Xmethods In Python
2909 @cindex xmethods in Python
2911 @dfn{Xmethods} are additional methods or replacements for existing
2912 methods of a C@t{++} class. This feature is useful for those cases
2913 where a method defined in C@t{++} source code could be inlined or
2914 optimized out by the compiler, making it unavailable to @value{GDBN}.
2915 For such cases, one can define an xmethod to serve as a replacement
2916 for the method defined in the C@t{++} source code. @value{GDBN} will
2917 then invoke the xmethod, instead of the C@t{++} method, to
2918 evaluate expressions. One can also use xmethods when debugging
2919 with core files. Moreover, when debugging live programs, invoking an
2920 xmethod need not involve running the inferior (which can potentially
2921 perturb its state). Hence, even if the C@t{++} method is available, it
2922 is better to use its replacement xmethod if one is defined.
2924 The xmethods feature in Python is available via the concepts of an
2925 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
2926 implement an xmethod, one has to implement a matcher and a
2927 corresponding worker for it (more than one worker can be
2928 implemented, each catering to a different overloaded instance of the
2929 method). Internally, @value{GDBN} invokes the @code{match} method of a
2930 matcher to match the class type and method name. On a match, the
2931 @code{match} method returns a list of matching @emph{worker} objects.
2932 Each worker object typically corresponds to an overloaded instance of
2933 the xmethod. They implement a @code{get_arg_types} method which
2934 returns a sequence of types corresponding to the arguments the xmethod
2935 requires. @value{GDBN} uses this sequence of types to perform
2936 overload resolution and picks a winning xmethod worker. A winner
2937 is also selected from among the methods @value{GDBN} finds in the
2938 C@t{++} source code. Next, the winning xmethod worker and the
2939 winning C@t{++} method are compared to select an overall winner. In
2940 case of a tie between a xmethod worker and a C@t{++} method, the
2941 xmethod worker is selected as the winner. That is, if a winning
2942 xmethod worker is found to be equivalent to the winning C@t{++}
2943 method, then the xmethod worker is treated as a replacement for
2944 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
2945 method. If the winning xmethod worker is the overall winner, then
2946 the corresponding xmethod is invoked via the @code{__call__} method
2947 of the worker object.
2949 If one wants to implement an xmethod as a replacement for an
2950 existing C@t{++} method, then they have to implement an equivalent
2951 xmethod which has exactly the same name and takes arguments of
2952 exactly the same type as the C@t{++} method. If the user wants to
2953 invoke the C@t{++} method even though a replacement xmethod is
2954 available for that method, then they can disable the xmethod.
2956 @xref{Xmethod API}, for API to implement xmethods in Python.
2957 @xref{Writing an Xmethod}, for implementing xmethods in Python.
2960 @subsubsection Xmethod API
2963 The @value{GDBN} Python API provides classes, interfaces and functions
2964 to implement, register and manipulate xmethods.
2965 @xref{Xmethods In Python}.
2967 An xmethod matcher should be an instance of a class derived from
2968 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
2969 object with similar interface and attributes. An instance of
2970 @code{XMethodMatcher} has the following attributes:
2973 The name of the matcher.
2977 A boolean value indicating whether the matcher is enabled or disabled.
2981 A list of named methods managed by the matcher. Each object in the list
2982 is an instance of the class @code{XMethod} defined in the module
2983 @code{gdb.xmethod}, or any object with the following attributes:
2988 Name of the xmethod which should be unique for each xmethod
2989 managed by the matcher.
2992 A boolean value indicating whether the xmethod is enabled or
2997 The class @code{XMethod} is a convenience class with same
2998 attributes as above along with the following constructor:
3000 @defun XMethod.__init__ (self, name)
3001 Constructs an enabled xmethod with name @var{name}.
3006 The @code{XMethodMatcher} class has the following methods:
3008 @defun XMethodMatcher.__init__ (self, name)
3009 Constructs an enabled xmethod matcher with name @var{name}. The
3010 @code{methods} attribute is initialized to @code{None}.
3013 @defun XMethodMatcher.match (self, class_type, method_name)
3014 Derived classes should override this method. It should return a
3015 xmethod worker object (or a sequence of xmethod worker
3016 objects) matching the @var{class_type} and @var{method_name}.
3017 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
3018 is a string value. If the matcher manages named methods as listed in
3019 its @code{methods} attribute, then only those worker objects whose
3020 corresponding entries in the @code{methods} list are enabled should be
3024 An xmethod worker should be an instance of a class derived from
3025 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
3026 or support the following interface:
3028 @defun XMethodWorker.get_arg_types (self)
3029 This method returns a sequence of @code{gdb.Type} objects corresponding
3030 to the arguments that the xmethod takes. It can return an empty
3031 sequence or @code{None} if the xmethod does not take any arguments.
3032 If the xmethod takes a single argument, then a single
3033 @code{gdb.Type} object corresponding to it can be returned.
3036 @defun XMethodWorker.get_result_type (self, *args)
3037 This method returns a @code{gdb.Type} object representing the type
3038 of the result of invoking this xmethod.
3039 The @var{args} argument is the same tuple of arguments that would be
3040 passed to the @code{__call__} method of this worker.
3043 @defun XMethodWorker.__call__ (self, *args)
3044 This is the method which does the @emph{work} of the xmethod. The
3045 @var{args} arguments is the tuple of arguments to the xmethod. Each
3046 element in this tuple is a gdb.Value object. The first element is
3047 always the @code{this} pointer value.
3050 For @value{GDBN} to lookup xmethods, the xmethod matchers
3051 should be registered using the following function defined in the module
3054 @defun register_xmethod_matcher (locus, matcher, replace=False)
3055 The @code{matcher} is registered with @code{locus}, replacing an
3056 existing matcher with the same name as @code{matcher} if
3057 @code{replace} is @code{True}. @code{locus} can be a
3058 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
3059 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
3060 @code{None}. If it is @code{None}, then @code{matcher} is registered
3064 @node Writing an Xmethod
3065 @subsubsection Writing an Xmethod
3066 @cindex writing xmethods in Python
3068 Implementing xmethods in Python will require implementing xmethod
3069 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
3070 the following C@t{++} class:
3076 MyClass (int a) : a_(a) @{ @}
3078 int geta (void) @{ return a_; @}
3079 int operator+ (int b);
3086 MyClass::operator+ (int b)
3093 Let us define two xmethods for the class @code{MyClass}, one
3094 replacing the method @code{geta}, and another adding an overloaded
3095 flavor of @code{operator+} which takes a @code{MyClass} argument (the
3096 C@t{++} code above already has an overloaded @code{operator+}
3097 which takes an @code{int} argument). The xmethod matcher can be
3101 class MyClass_geta(gdb.xmethod.XMethod):
3103 gdb.xmethod.XMethod.__init__(self, 'geta')
3105 def get_worker(self, method_name):
3106 if method_name == 'geta':
3107 return MyClassWorker_geta()
3110 class MyClass_sum(gdb.xmethod.XMethod):
3112 gdb.xmethod.XMethod.__init__(self, 'sum')
3114 def get_worker(self, method_name):
3115 if method_name == 'operator+':
3116 return MyClassWorker_plus()
3119 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
3121 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
3122 # List of methods 'managed' by this matcher
3123 self.methods = [MyClass_geta(), MyClass_sum()]
3125 def match(self, class_type, method_name):
3126 if class_type.tag != 'MyClass':
3129 for method in self.methods:
3131 worker = method.get_worker(method_name)
3133 workers.append(worker)
3139 Notice that the @code{match} method of @code{MyClassMatcher} returns
3140 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
3141 method, and a worker object of type @code{MyClassWorker_plus} for the
3142 @code{operator+} method. This is done indirectly via helper classes
3143 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
3144 @code{methods} attribute in a matcher as it is optional. However, if a
3145 matcher manages more than one xmethod, it is a good practice to list the
3146 xmethods in the @code{methods} attribute of the matcher. This will then
3147 facilitate enabling and disabling individual xmethods via the
3148 @code{enable/disable} commands. Notice also that a worker object is
3149 returned only if the corresponding entry in the @code{methods} attribute
3150 of the matcher is enabled.
3152 The implementation of the worker classes returned by the matcher setup
3153 above is as follows:
3156 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
3157 def get_arg_types(self):
3160 def get_result_type(self, obj):
3161 return gdb.lookup_type('int')
3163 def __call__(self, obj):
3167 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
3168 def get_arg_types(self):
3169 return gdb.lookup_type('MyClass')
3171 def get_result_type(self, obj):
3172 return gdb.lookup_type('int')
3174 def __call__(self, obj, other):
3175 return obj['a_'] + other['a_']
3178 For @value{GDBN} to actually lookup a xmethod, it has to be
3179 registered with it. The matcher defined above is registered with
3180 @value{GDBN} globally as follows:
3183 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
3186 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
3194 then, after loading the Python script defining the xmethod matchers
3195 and workers into @value{GDBN}, invoking the method @code{geta} or using
3196 the operator @code{+} on @code{obj} will invoke the xmethods
3207 Consider another example with a C++ template class:
3214 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
3215 ~MyTemplate () @{ delete [] data_; @}
3217 int footprint (void)
3219 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
3228 Let us implement an xmethod for the above class which serves as a
3229 replacement for the @code{footprint} method. The full code listing
3230 of the xmethod workers and xmethod matchers is as follows:
3233 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
3234 def __init__(self, class_type):
3235 self.class_type = class_type
3237 def get_arg_types(self):
3240 def get_result_type(self):
3241 return gdb.lookup_type('int')
3243 def __call__(self, obj):
3244 return (self.class_type.sizeof +
3246 self.class_type.template_argument(0).sizeof)
3249 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
3251 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
3253 def match(self, class_type, method_name):
3254 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
3256 method_name == 'footprint'):
3257 return MyTemplateWorker_footprint(class_type)
3260 Notice that, in this example, we have not used the @code{methods}
3261 attribute of the matcher as the matcher manages only one xmethod. The
3262 user can enable/disable this xmethod by enabling/disabling the matcher
3265 @node Inferiors In Python
3266 @subsubsection Inferiors In Python
3267 @cindex inferiors in Python
3269 @findex gdb.Inferior
3270 Programs which are being run under @value{GDBN} are called inferiors
3271 (@pxref{Inferiors Connections and Programs}). Python scripts can access
3272 information about and manipulate inferiors controlled by @value{GDBN}
3273 via objects of the @code{gdb.Inferior} class.
3275 The following inferior-related functions are available in the @code{gdb}
3278 @defun gdb.inferiors ()
3279 Return a tuple containing all inferior objects.
3282 @defun gdb.selected_inferior ()
3283 Return an object representing the current inferior.
3286 A @code{gdb.Inferior} object has the following attributes:
3288 @defvar Inferior.num
3289 ID of inferior, as assigned by GDB.
3292 @anchor{gdbpy_inferior_connection}
3293 @defvar Inferior.connection
3294 The @code{gdb.TargetConnection} for this inferior (@pxref{Connections
3295 In Python}), or @code{None} if this inferior has no connection.
3298 @defvar Inferior.connection_num
3299 ID of inferior's connection as assigned by @value{GDBN}, or None if
3300 the inferior is not connected to a target. @xref{Inferiors Connections
3301 and Programs}. This is equivalent to
3302 @code{gdb.Inferior.connection.num} in the case where
3303 @code{gdb.Inferior.connection} is not @code{None}.
3306 @defvar Inferior.pid
3307 Process ID of the inferior, as assigned by the underlying operating
3311 @defvar Inferior.was_attached
3312 Boolean signaling whether the inferior was created using `attach', or
3313 started by @value{GDBN} itself.
3316 @defvar Inferior.progspace
3317 The inferior's program space. @xref{Progspaces In Python}.
3320 A @code{gdb.Inferior} object has the following methods:
3322 @defun Inferior.is_valid ()
3323 Returns @code{True} if the @code{gdb.Inferior} object is valid,
3324 @code{False} if not. A @code{gdb.Inferior} object will become invalid
3325 if the inferior no longer exists within @value{GDBN}. All other
3326 @code{gdb.Inferior} methods will throw an exception if it is invalid
3327 at the time the method is called.
3330 @defun Inferior.threads ()
3331 This method returns a tuple holding all the threads which are valid
3332 when it is called. If there are no valid threads, the method will
3333 return an empty tuple.
3336 @defun Inferior.architecture ()
3337 Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
3338 for this inferior. This represents the architecture of the inferior
3339 as a whole. Some platforms can have multiple architectures in a
3340 single address space, so this may not match the architecture of a
3341 particular frame (@pxref{Frames In Python}).
3344 @anchor{gdbpy_inferior_read_memory}
3345 @findex Inferior.read_memory
3346 @defun Inferior.read_memory (address, length)
3347 Read @var{length} addressable memory units from the inferior, starting at
3348 @var{address}. Returns a buffer object, which behaves much like an array
3349 or a string. It can be modified and given to the
3350 @code{Inferior.write_memory} function. In Python 3, the return
3351 value is a @code{memoryview} object.
3354 @findex Inferior.write_memory
3355 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
3356 Write the contents of @var{buffer} to the inferior, starting at
3357 @var{address}. The @var{buffer} parameter must be a Python object
3358 which supports the buffer protocol, i.e., a string, an array or the
3359 object returned from @code{Inferior.read_memory}. If given, @var{length}
3360 determines the number of addressable memory units from @var{buffer} to be
3364 @findex gdb.search_memory
3365 @defun Inferior.search_memory (address, length, pattern)
3366 Search a region of the inferior memory starting at @var{address} with
3367 the given @var{length} using the search pattern supplied in
3368 @var{pattern}. The @var{pattern} parameter must be a Python object
3369 which supports the buffer protocol, i.e., a string, an array or the
3370 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
3371 containing the address where the pattern was found, or @code{None} if
3372 the pattern could not be found.
3375 @findex Inferior.thread_from_handle
3376 @findex Inferior.thread_from_thread_handle
3377 @defun Inferior.thread_from_handle (handle)
3378 Return the thread object corresponding to @var{handle}, a thread
3379 library specific data structure such as @code{pthread_t} for pthreads
3380 library implementations.
3382 The function @code{Inferior.thread_from_thread_handle} provides
3383 the same functionality, but use of @code{Inferior.thread_from_thread_handle}
3387 @node Events In Python
3388 @subsubsection Events In Python
3389 @cindex inferior events in Python
3391 @value{GDBN} provides a general event facility so that Python code can be
3392 notified of various state changes, particularly changes that occur in
3395 An @dfn{event} is just an object that describes some state change. The
3396 type of the object and its attributes will vary depending on the details
3397 of the change. All the existing events are described below.
3399 In order to be notified of an event, you must register an event handler
3400 with an @dfn{event registry}. An event registry is an object in the
3401 @code{gdb.events} module which dispatches particular events. A registry
3402 provides methods to register and unregister event handlers:
3404 @defun EventRegistry.connect (object)
3405 Add the given callable @var{object} to the registry. This object will be
3406 called when an event corresponding to this registry occurs.
3409 @defun EventRegistry.disconnect (object)
3410 Remove the given @var{object} from the registry. Once removed, the object
3411 will no longer receive notifications of events.
3417 def exit_handler (event):
3418 print ("event type: exit")
3419 if hasattr (event, 'exit_code'):
3420 print ("exit code: %d" % (event.exit_code))
3422 print ("exit code not available")
3424 gdb.events.exited.connect (exit_handler)
3427 In the above example we connect our handler @code{exit_handler} to the
3428 registry @code{events.exited}. Once connected, @code{exit_handler} gets
3429 called when the inferior exits. The argument @dfn{event} in this example is
3430 of type @code{gdb.ExitedEvent}. As you can see in the example the
3431 @code{ExitedEvent} object has an attribute which indicates the exit code of
3434 Some events can be thread specific when @value{GDBN} is running in
3435 non-stop mode. When represented in Python, these events all extend
3436 @code{gdb.ThreadEvent}. This event is a base class and is never
3437 emitted directly; instead, events which are emitted by this or other
3438 modules might extend this event. Examples of these events are
3439 @code{gdb.BreakpointEvent} and @code{gdb.ContinueEvent}.
3440 @code{gdb.ThreadEvent} holds the following attributes:
3442 @defvar ThreadEvent.inferior_thread
3443 In non-stop mode this attribute will be set to the specific thread which was
3444 involved in the emitted event. Otherwise, it will be set to @code{None}.
3447 The following is a listing of the event registries that are available and
3448 details of the events they emit:
3453 Emits @code{gdb.ContinueEvent}, which extends @code{gdb.ThreadEvent}.
3454 This event indicates that the inferior has been continued after a
3455 stop. For inherited attribute refer to @code{gdb.ThreadEvent} above.
3458 Emits @code{events.ExitedEvent}, which indicates that the inferior has
3459 exited. @code{events.ExitedEvent} has two attributes:
3461 @defvar ExitedEvent.exit_code
3462 An integer representing the exit code, if available, which the inferior
3463 has returned. (The exit code could be unavailable if, for example,
3464 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
3465 the attribute does not exist.
3468 @defvar ExitedEvent.inferior
3469 A reference to the inferior which triggered the @code{exited} event.
3473 Emits @code{gdb.StopEvent}, which extends @code{gdb.ThreadEvent}.
3475 Indicates that the inferior has stopped. All events emitted by this
3476 registry extend @code{gdb.StopEvent}. As a child of
3477 @code{gdb.ThreadEvent}, @code{gdb.StopEvent} will indicate the stopped
3478 thread when @value{GDBN} is running in non-stop mode. Refer to
3479 @code{gdb.ThreadEvent} above for more details.
3481 Emits @code{gdb.SignalEvent}, which extends @code{gdb.StopEvent}.
3483 This event indicates that the inferior or one of its threads has
3484 received a signal. @code{gdb.SignalEvent} has the following
3487 @defvar SignalEvent.stop_signal
3488 A string representing the signal received by the inferior. A list of possible
3489 signal values can be obtained by running the command @code{info signals} in
3490 the @value{GDBN} command prompt.
3493 Also emits @code{gdb.BreakpointEvent}, which extends
3494 @code{gdb.StopEvent}.
3496 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
3497 been hit, and has the following attributes:
3499 @defvar BreakpointEvent.breakpoints
3500 A sequence containing references to all the breakpoints (type
3501 @code{gdb.Breakpoint}) that were hit.
3502 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
3505 @defvar BreakpointEvent.breakpoint
3506 A reference to the first breakpoint that was hit. This attribute is
3507 maintained for backward compatibility and is now deprecated in favor
3508 of the @code{gdb.BreakpointEvent.breakpoints} attribute.
3511 @item events.new_objfile
3512 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
3513 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
3515 @defvar NewObjFileEvent.new_objfile
3516 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
3517 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
3520 @item events.free_objfile
3521 Emits @code{gdb.FreeObjFileEvent} which indicates that an object file
3522 is about to be removed from @value{GDBN}. One reason this can happen
3523 is when the inferior calls @code{dlclose}.
3524 @code{gdb.FreeObjFileEvent} has one attribute:
3526 @defvar NewObjFileEvent.objfile
3527 A reference to the object file (@code{gdb.Objfile}) which will be unloaded.
3528 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
3531 @item events.clear_objfiles
3532 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
3533 files for a program space has been reset.
3534 @code{gdb.ClearObjFilesEvent} has one attribute:
3536 @defvar ClearObjFilesEvent.progspace
3537 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
3538 been cleared. @xref{Progspaces In Python}.
3541 @item events.inferior_call
3542 Emits events just before and after a function in the inferior is
3543 called by @value{GDBN}. Before an inferior call, this emits an event
3544 of type @code{gdb.InferiorCallPreEvent}, and after an inferior call,
3545 this emits an event of type @code{gdb.InferiorCallPostEvent}.
3548 @tindex gdb.InferiorCallPreEvent
3549 @item @code{gdb.InferiorCallPreEvent}
3550 Indicates that a function in the inferior is about to be called.
3552 @defvar InferiorCallPreEvent.ptid
3553 The thread in which the call will be run.
3556 @defvar InferiorCallPreEvent.address
3557 The location of the function to be called.
3560 @tindex gdb.InferiorCallPostEvent
3561 @item @code{gdb.InferiorCallPostEvent}
3562 Indicates that a function in the inferior has just been called.
3564 @defvar InferiorCallPostEvent.ptid
3565 The thread in which the call was run.
3568 @defvar InferiorCallPostEvent.address
3569 The location of the function that was called.
3573 @item events.memory_changed
3574 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
3575 inferior has been modified by the @value{GDBN} user, for instance via a
3576 command like @w{@code{set *addr = value}}. The event has the following
3579 @defvar MemoryChangedEvent.address
3580 The start address of the changed region.
3583 @defvar MemoryChangedEvent.length
3584 Length in bytes of the changed region.
3587 @item events.register_changed
3588 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
3589 inferior has been modified by the @value{GDBN} user.
3591 @defvar RegisterChangedEvent.frame
3592 A gdb.Frame object representing the frame in which the register was modified.
3594 @defvar RegisterChangedEvent.regnum
3595 Denotes which register was modified.
3598 @item events.breakpoint_created
3599 This is emitted when a new breakpoint has been created. The argument
3600 that is passed is the new @code{gdb.Breakpoint} object.
3602 @item events.breakpoint_modified
3603 This is emitted when a breakpoint has been modified in some way. The
3604 argument that is passed is the new @code{gdb.Breakpoint} object.
3606 @item events.breakpoint_deleted
3607 This is emitted when a breakpoint has been deleted. The argument that
3608 is passed is the @code{gdb.Breakpoint} object. When this event is
3609 emitted, the @code{gdb.Breakpoint} object will already be in its
3610 invalid state; that is, the @code{is_valid} method will return
3613 @item events.before_prompt
3614 This event carries no payload. It is emitted each time @value{GDBN}
3615 presents a prompt to the user.
3617 @item events.new_inferior
3618 This is emitted when a new inferior is created. Note that the
3619 inferior is not necessarily running; in fact, it may not even have an
3620 associated executable.
3622 The event is of type @code{gdb.NewInferiorEvent}. This has a single
3625 @defvar NewInferiorEvent.inferior
3626 The new inferior, a @code{gdb.Inferior} object.
3629 @item events.inferior_deleted
3630 This is emitted when an inferior has been deleted. Note that this is
3631 not the same as process exit; it is notified when the inferior itself
3632 is removed, say via @code{remove-inferiors}.
3634 The event is of type @code{gdb.InferiorDeletedEvent}. This has a single
3637 @defvar InferiorDeletedEvent.inferior
3638 The inferior that is being removed, a @code{gdb.Inferior} object.
3641 @item events.new_thread
3642 This is emitted when @value{GDBN} notices a new thread. The event is of
3643 type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}.
3644 This has a single attribute:
3646 @defvar NewThreadEvent.inferior_thread
3650 @item events.gdb_exiting
3651 This is emitted when @value{GDBN} exits. This event is not emitted if
3652 @value{GDBN} exits as a result of an internal error, or after an
3653 unexpected signal. The event is of type @code{gdb.GdbExitingEvent},
3654 which has a single attribute:
3656 @defvar GdbExitingEvent.exit_code
3657 An integer, the value of the exit code @value{GDBN} will return.
3660 @item events.connection_removed
3661 This is emitted when @value{GDBN} removes a connection
3662 (@pxref{Connections In Python}). The event is of type
3663 @code{gdb.ConnectionEvent}. This has a single read-only attribute:
3665 @defvar ConnectionEvent.connection
3666 The @code{gdb.TargetConnection} that is being removed.
3671 @node Threads In Python
3672 @subsubsection Threads In Python
3673 @cindex threads in python
3675 @findex gdb.InferiorThread
3676 Python scripts can access information about, and manipulate inferior threads
3677 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
3679 The following thread-related functions are available in the @code{gdb}
3682 @findex gdb.selected_thread
3683 @defun gdb.selected_thread ()
3684 This function returns the thread object for the selected thread. If there
3685 is no selected thread, this will return @code{None}.
3688 To get the list of threads for an inferior, use the @code{Inferior.threads()}
3689 method. @xref{Inferiors In Python}.
3691 A @code{gdb.InferiorThread} object has the following attributes:
3693 @defvar InferiorThread.name
3694 The name of the thread. If the user specified a name using
3695 @code{thread name}, then this returns that name. Otherwise, if an
3696 OS-supplied name is available, then it is returned. Otherwise, this
3697 returns @code{None}.
3699 This attribute can be assigned to. The new value must be a string
3700 object, which sets the new name, or @code{None}, which removes any
3701 user-specified thread name.
3704 @defvar InferiorThread.num
3705 The per-inferior number of the thread, as assigned by GDB.
3708 @defvar InferiorThread.global_num
3709 The global ID of the thread, as assigned by GDB. You can use this to
3710 make Python breakpoints thread-specific, for example
3711 (@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
3714 @defvar InferiorThread.ptid
3715 ID of the thread, as assigned by the operating system. This attribute is a
3716 tuple containing three integers. The first is the Process ID (PID); the second
3717 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
3718 Either the LWPID or TID may be 0, which indicates that the operating system
3719 does not use that identifier.
3722 @defvar InferiorThread.inferior
3723 The inferior this thread belongs to. This attribute is represented as
3724 a @code{gdb.Inferior} object. This attribute is not writable.
3727 @defvar InferiorThread.details
3728 A string containing target specific thread state information. The
3729 format of this string varies by target. If there is no additional
3730 state information for this thread, then this attribute contains
3733 For example, on a @sc{gnu}/Linux system, a thread that is in the
3734 process of exiting will return the string @samp{Exiting}. For remote
3735 targets the @code{details} string will be obtained with the
3736 @samp{qThreadExtraInfo} remote packet, if the target supports it
3737 (@pxref{qThreadExtraInfo,,@samp{qThreadExtraInfo}}).
3739 @value{GDBN} displays the @code{details} string as part of the
3740 @samp{Target Id} column, in the @code{info threads} output
3741 (@pxref{info_threads,,@samp{info threads}}).
3744 A @code{gdb.InferiorThread} object has the following methods:
3746 @defun InferiorThread.is_valid ()
3747 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
3748 @code{False} if not. A @code{gdb.InferiorThread} object will become
3749 invalid if the thread exits, or the inferior that the thread belongs
3750 is deleted. All other @code{gdb.InferiorThread} methods will throw an
3751 exception if it is invalid at the time the method is called.
3754 @defun InferiorThread.switch ()
3755 This changes @value{GDBN}'s currently selected thread to the one represented
3759 @defun InferiorThread.is_stopped ()
3760 Return a Boolean indicating whether the thread is stopped.
3763 @defun InferiorThread.is_running ()
3764 Return a Boolean indicating whether the thread is running.
3767 @defun InferiorThread.is_exited ()
3768 Return a Boolean indicating whether the thread is exited.
3771 @defun InferiorThread.handle ()
3772 Return the thread object's handle, represented as a Python @code{bytes}
3773 object. A @code{gdb.Value} representation of the handle may be
3774 constructed via @code{gdb.Value(bufobj, type)} where @var{bufobj} is
3775 the Python @code{bytes} representation of the handle and @var{type} is
3776 a @code{gdb.Type} for the handle type.
3779 @node Recordings In Python
3780 @subsubsection Recordings In Python
3781 @cindex recordings in python
3783 The following recordings-related functions
3784 (@pxref{Process Record and Replay}) are available in the @code{gdb}
3787 @defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
3788 Start a recording using the given @var{method} and @var{format}. If
3789 no @var{format} is given, the default format for the recording method
3790 is used. If no @var{method} is given, the default method will be used.
3791 Returns a @code{gdb.Record} object on success. Throw an exception on
3794 The following strings can be passed as @var{method}:
3800 @code{"btrace"}: Possible values for @var{format}: @code{"pt"},
3801 @code{"bts"} or leave out for default format.
3805 @defun gdb.current_recording ()
3806 Access a currently running recording. Return a @code{gdb.Record}
3807 object on success. Return @code{None} if no recording is currently
3811 @defun gdb.stop_recording ()
3812 Stop the current recording. Throw an exception if no recording is
3813 currently active. All record objects become invalid after this call.
3816 A @code{gdb.Record} object has the following attributes:
3818 @defvar Record.method
3819 A string with the current recording method, e.g.@: @code{full} or
3823 @defvar Record.format
3824 A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
3828 @defvar Record.begin
3829 A method specific instruction object representing the first instruction
3834 A method specific instruction object representing the current
3835 instruction, that is not actually part of the recording.
3838 @defvar Record.replay_position
3839 The instruction representing the current replay position. If there is
3840 no replay active, this will be @code{None}.
3843 @defvar Record.instruction_history
3844 A list with all recorded instructions.
3847 @defvar Record.function_call_history
3848 A list with all recorded function call segments.
3851 A @code{gdb.Record} object has the following methods:
3853 @defun Record.goto (instruction)
3854 Move the replay position to the given @var{instruction}.
3857 The common @code{gdb.Instruction} class that recording method specific
3858 instruction objects inherit from, has the following attributes:
3860 @defvar Instruction.pc
3861 An integer representing this instruction's address.
3864 @defvar Instruction.data
3865 A buffer with the raw instruction data. In Python 3, the return value is a
3866 @code{memoryview} object.
3869 @defvar Instruction.decoded
3870 A human readable string with the disassembled instruction.
3873 @defvar Instruction.size
3874 The size of the instruction in bytes.
3877 Additionally @code{gdb.RecordInstruction} has the following attributes:
3879 @defvar RecordInstruction.number
3880 An integer identifying this instruction. @code{number} corresponds to
3881 the numbers seen in @code{record instruction-history}
3882 (@pxref{Process Record and Replay}).
3885 @defvar RecordInstruction.sal
3886 A @code{gdb.Symtab_and_line} object representing the associated symtab
3887 and line of this instruction. May be @code{None} if no debug information is
3891 @defvar RecordInstruction.is_speculative
3892 A boolean indicating whether the instruction was executed speculatively.
3895 If an error occured during recording or decoding a recording, this error is
3896 represented by a @code{gdb.RecordGap} object in the instruction list. It has
3897 the following attributes:
3899 @defvar RecordGap.number
3900 An integer identifying this gap. @code{number} corresponds to the numbers seen
3901 in @code{record instruction-history} (@pxref{Process Record and Replay}).
3904 @defvar RecordGap.error_code
3905 A numerical representation of the reason for the gap. The value is specific to
3906 the current recording method.
3909 @defvar RecordGap.error_string
3910 A human readable string with the reason for the gap.
3913 A @code{gdb.RecordFunctionSegment} object has the following attributes:
3915 @defvar RecordFunctionSegment.number
3916 An integer identifying this function segment. @code{number} corresponds to
3917 the numbers seen in @code{record function-call-history}
3918 (@pxref{Process Record and Replay}).
3921 @defvar RecordFunctionSegment.symbol
3922 A @code{gdb.Symbol} object representing the associated symbol. May be
3923 @code{None} if no debug information is available.
3926 @defvar RecordFunctionSegment.level
3927 An integer representing the function call's stack level. May be
3928 @code{None} if the function call is a gap.
3931 @defvar RecordFunctionSegment.instructions
3932 A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
3933 associated with this function call.
3936 @defvar RecordFunctionSegment.up
3937 A @code{gdb.RecordFunctionSegment} object representing the caller's
3938 function segment. If the call has not been recorded, this will be the
3939 function segment to which control returns. If neither the call nor the
3940 return have been recorded, this will be @code{None}.
3943 @defvar RecordFunctionSegment.prev
3944 A @code{gdb.RecordFunctionSegment} object representing the previous
3945 segment of this function call. May be @code{None}.
3948 @defvar RecordFunctionSegment.next
3949 A @code{gdb.RecordFunctionSegment} object representing the next segment of
3950 this function call. May be @code{None}.
3953 The following example demonstrates the usage of these objects and
3954 functions to create a function that will rewind a record to the last
3955 time a function in a different file was executed. This would typically
3956 be used to track the execution of user provided callback functions in a
3957 library which typically are not visible in a back trace.
3961 rec = gdb.current_recording ()
3965 insn = rec.instruction_history
3970 position = insn.index (rec.replay_position)
3974 filename = insn[position].sal.symtab.fullname ()
3978 for i in reversed (insn[:position]):
3980 current = i.sal.symtab.fullname ()
3984 if filename == current:
3991 Another possible application is to write a function that counts the
3992 number of code executions in a given line range. This line range can
3993 contain parts of functions or span across several functions and is not
3994 limited to be contiguous.
3997 def countrange (filename, linerange):
4000 def filter_only (file_name):
4001 for call in gdb.current_recording ().function_call_history:
4003 if file_name in call.symbol.symtab.fullname ():
4008 for c in filter_only (filename):
4009 for i in c.instructions:
4011 if i.sal.line in linerange:
4020 @node CLI Commands In Python
4021 @subsubsection CLI Commands In Python
4023 @cindex CLI commands in python
4024 @cindex commands in python, CLI
4025 @cindex python commands, CLI
4026 You can implement new @value{GDBN} CLI commands in Python. A CLI
4027 command is implemented using an instance of the @code{gdb.Command}
4028 class, most commonly using a subclass.
4030 @defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
4031 The object initializer for @code{Command} registers the new command
4032 with @value{GDBN}. This initializer is normally invoked from the
4033 subclass' own @code{__init__} method.
4035 @var{name} is the name of the command. If @var{name} consists of
4036 multiple words, then the initial words are looked for as prefix
4037 commands. In this case, if one of the prefix commands does not exist,
4038 an exception is raised.
4040 There is no support for multi-line commands.
4042 @var{command_class} should be one of the @samp{COMMAND_} constants
4043 defined below. This argument tells @value{GDBN} how to categorize the
4044 new command in the help system.
4046 @var{completer_class} is an optional argument. If given, it should be
4047 one of the @samp{COMPLETE_} constants defined below. This argument
4048 tells @value{GDBN} how to perform completion for this command. If not
4049 given, @value{GDBN} will attempt to complete using the object's
4050 @code{complete} method (see below); if no such method is found, an
4051 error will occur when completion is attempted.
4053 @var{prefix} is an optional argument. If @code{True}, then the new
4054 command is a prefix command; sub-commands of this command may be
4057 The help text for the new command is taken from the Python
4058 documentation string for the command's class, if there is one. If no
4059 documentation string is provided, the default value ``This command is
4060 not documented.'' is used.
4063 @cindex don't repeat Python command
4064 @defun Command.dont_repeat ()
4065 By default, a @value{GDBN} command is repeated when the user enters a
4066 blank line at the command prompt. A command can suppress this
4067 behavior by invoking the @code{dont_repeat} method at some point in
4068 its @code{invoke} method (normally this is done early in case of
4069 exception). This is similar to the user command @code{dont-repeat},
4070 see @ref{Define, dont-repeat}.
4073 @defun Command.invoke (argument, from_tty)
4074 This method is called by @value{GDBN} when this command is invoked.
4076 @var{argument} is a string. It is the argument to the command, after
4077 leading and trailing whitespace has been stripped.
4079 @var{from_tty} is a boolean argument. When true, this means that the
4080 command was entered by the user at the terminal; when false it means
4081 that the command came from elsewhere.
4083 If this method throws an exception, it is turned into a @value{GDBN}
4084 @code{error} call. Otherwise, the return value is ignored.
4086 @findex gdb.string_to_argv
4087 To break @var{argument} up into an argv-like string use
4088 @code{gdb.string_to_argv}. This function behaves identically to
4089 @value{GDBN}'s internal argument lexer @code{buildargv}.
4090 It is recommended to use this for consistency.
4091 Arguments are separated by spaces and may be quoted.
4095 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
4096 ['1', '2 "3', '4 "5', "6 '7"]
4101 @cindex completion of Python commands
4102 @defun Command.complete (text, word)
4103 This method is called by @value{GDBN} when the user attempts
4104 completion on this command. All forms of completion are handled by
4105 this method, that is, the @key{TAB} and @key{M-?} key bindings
4106 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
4109 The arguments @var{text} and @var{word} are both strings; @var{text}
4110 holds the complete command line up to the cursor's location, while
4111 @var{word} holds the last word of the command line; this is computed
4112 using a word-breaking heuristic.
4114 The @code{complete} method can return several values:
4117 If the return value is a sequence, the contents of the sequence are
4118 used as the completions. It is up to @code{complete} to ensure that the
4119 contents actually do complete the word. A zero-length sequence is
4120 allowed, it means that there were no completions available. Only
4121 string elements of the sequence are used; other elements in the
4122 sequence are ignored.
4125 If the return value is one of the @samp{COMPLETE_} constants defined
4126 below, then the corresponding @value{GDBN}-internal completion
4127 function is invoked, and its result is used.
4130 All other results are treated as though there were no available
4135 When a new command is registered, it must be declared as a member of
4136 some general class of commands. This is used to classify top-level
4137 commands in the on-line help system; note that prefix commands are not
4138 listed under their own category but rather that of their top-level
4139 command. The available classifications are represented by constants
4140 defined in the @code{gdb} module:
4143 @findex COMMAND_NONE
4144 @findex gdb.COMMAND_NONE
4145 @item gdb.COMMAND_NONE
4146 The command does not belong to any particular class. A command in
4147 this category will not be displayed in any of the help categories.
4149 @findex COMMAND_RUNNING
4150 @findex gdb.COMMAND_RUNNING
4151 @item gdb.COMMAND_RUNNING
4152 The command is related to running the inferior. For example,
4153 @code{start}, @code{step}, and @code{continue} are in this category.
4154 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
4155 commands in this category.
4157 @findex COMMAND_DATA
4158 @findex gdb.COMMAND_DATA
4159 @item gdb.COMMAND_DATA
4160 The command is related to data or variables. For example,
4161 @code{call}, @code{find}, and @code{print} are in this category. Type
4162 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
4165 @findex COMMAND_STACK
4166 @findex gdb.COMMAND_STACK
4167 @item gdb.COMMAND_STACK
4168 The command has to do with manipulation of the stack. For example,
4169 @code{backtrace}, @code{frame}, and @code{return} are in this
4170 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
4171 list of commands in this category.
4173 @findex COMMAND_FILES
4174 @findex gdb.COMMAND_FILES
4175 @item gdb.COMMAND_FILES
4176 This class is used for file-related commands. For example,
4177 @code{file}, @code{list} and @code{section} are in this category.
4178 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
4179 commands in this category.
4181 @findex COMMAND_SUPPORT
4182 @findex gdb.COMMAND_SUPPORT
4183 @item gdb.COMMAND_SUPPORT
4184 This should be used for ``support facilities'', generally meaning
4185 things that are useful to the user when interacting with @value{GDBN},
4186 but not related to the state of the inferior. For example,
4187 @code{help}, @code{make}, and @code{shell} are in this category. Type
4188 @kbd{help support} at the @value{GDBN} prompt to see a list of
4189 commands in this category.
4191 @findex COMMAND_STATUS
4192 @findex gdb.COMMAND_STATUS
4193 @item gdb.COMMAND_STATUS
4194 The command is an @samp{info}-related command, that is, related to the
4195 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
4196 and @code{show} are in this category. Type @kbd{help status} at the
4197 @value{GDBN} prompt to see a list of commands in this category.
4199 @findex COMMAND_BREAKPOINTS
4200 @findex gdb.COMMAND_BREAKPOINTS
4201 @item gdb.COMMAND_BREAKPOINTS
4202 The command has to do with breakpoints. For example, @code{break},
4203 @code{clear}, and @code{delete} are in this category. Type @kbd{help
4204 breakpoints} at the @value{GDBN} prompt to see a list of commands in
4207 @findex COMMAND_TRACEPOINTS
4208 @findex gdb.COMMAND_TRACEPOINTS
4209 @item gdb.COMMAND_TRACEPOINTS
4210 The command has to do with tracepoints. For example, @code{trace},
4211 @code{actions}, and @code{tfind} are in this category. Type
4212 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
4213 commands in this category.
4216 @findex gdb.COMMAND_TUI
4217 @item gdb.COMMAND_TUI
4218 The command has to do with the text user interface (@pxref{TUI}).
4219 Type @kbd{help tui} at the @value{GDBN} prompt to see a list of
4220 commands in this category.
4222 @findex COMMAND_USER
4223 @findex gdb.COMMAND_USER
4224 @item gdb.COMMAND_USER
4225 The command is a general purpose command for the user, and typically
4226 does not fit in one of the other categories.
4227 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
4228 a list of commands in this category, as well as the list of gdb macros
4229 (@pxref{Sequences}).
4231 @findex COMMAND_OBSCURE
4232 @findex gdb.COMMAND_OBSCURE
4233 @item gdb.COMMAND_OBSCURE
4234 The command is only used in unusual circumstances, or is not of
4235 general interest to users. For example, @code{checkpoint},
4236 @code{fork}, and @code{stop} are in this category. Type @kbd{help
4237 obscure} at the @value{GDBN} prompt to see a list of commands in this
4240 @findex COMMAND_MAINTENANCE
4241 @findex gdb.COMMAND_MAINTENANCE
4242 @item gdb.COMMAND_MAINTENANCE
4243 The command is only useful to @value{GDBN} maintainers. The
4244 @code{maintenance} and @code{flushregs} commands are in this category.
4245 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
4246 commands in this category.
4249 A new command can use a predefined completion function, either by
4250 specifying it via an argument at initialization, or by returning it
4251 from the @code{complete} method. These predefined completion
4252 constants are all defined in the @code{gdb} module:
4255 @vindex COMPLETE_NONE
4256 @item gdb.COMPLETE_NONE
4257 This constant means that no completion should be done.
4259 @vindex COMPLETE_FILENAME
4260 @item gdb.COMPLETE_FILENAME
4261 This constant means that filename completion should be performed.
4263 @vindex COMPLETE_LOCATION
4264 @item gdb.COMPLETE_LOCATION
4265 This constant means that location completion should be done.
4266 @xref{Location Specifications}.
4268 @vindex COMPLETE_COMMAND
4269 @item gdb.COMPLETE_COMMAND
4270 This constant means that completion should examine @value{GDBN}
4273 @vindex COMPLETE_SYMBOL
4274 @item gdb.COMPLETE_SYMBOL
4275 This constant means that completion should be done using symbol names
4278 @vindex COMPLETE_EXPRESSION
4279 @item gdb.COMPLETE_EXPRESSION
4280 This constant means that completion should be done on expressions.
4281 Often this means completing on symbol names, but some language
4282 parsers also have support for completing on field names.
4285 The following code snippet shows how a trivial CLI command can be
4286 implemented in Python:
4289 class HelloWorld (gdb.Command):
4290 """Greet the whole world."""
4292 def __init__ (self):
4293 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
4295 def invoke (self, arg, from_tty):
4296 print ("Hello, World!")
4301 The last line instantiates the class, and is necessary to trigger the
4302 registration of the command with @value{GDBN}. Depending on how the
4303 Python code is read into @value{GDBN}, you may need to import the
4304 @code{gdb} module explicitly.
4306 @node GDB/MI Commands In Python
4307 @subsubsection @sc{GDB/MI} Commands In Python
4309 @cindex MI commands in python
4310 @cindex commands in python, GDB/MI
4311 @cindex python commands, GDB/MI
4312 It is possible to add @sc{GDB/MI} (@pxref{GDB/MI}) commands
4313 implemented in Python. A @sc{GDB/MI} command is implemented using an
4314 instance of the @code{gdb.MICommand} class, most commonly using a
4317 @defun MICommand.__init__ (name)
4318 The object initializer for @code{MICommand} registers the new command
4319 with @value{GDBN}. This initializer is normally invoked from the
4320 subclass' own @code{__init__} method.
4322 @var{name} is the name of the command. It must be a valid name of a
4323 @sc{GDB/MI} command, and in particular must start with a hyphen
4324 (@code{-}). Reusing the name of a built-in @sc{GDB/MI} is not
4325 allowed, and a @code{RuntimeError} will be raised. Using the name
4326 of an @sc{GDB/MI} command previously defined in Python is allowed, the
4327 previous command will be replaced with the new command.
4330 @defun MICommand.invoke (arguments)
4331 This method is called by @value{GDBN} when the new MI command is
4334 @var{arguments} is a list of strings. Note, that @code{--thread}
4335 and @code{--frame} arguments are handled by @value{GDBN} itself therefore
4336 they do not show up in @code{arguments}.
4338 If this method raises an exception, then it is turned into a
4339 @sc{GDB/MI} @code{^error} response. Only @code{gdb.GdbError}
4340 exceptions (or its sub-classes) should be used for reporting errors to
4341 users, any other exception type is treated as a failure of the
4342 @code{invoke} method, and the exception will be printed to the error
4343 stream according to the @kbd{set python print-stack} setting
4344 (@pxref{set_python_print_stack,,@kbd{set python print-stack}}).
4346 If this method returns @code{None}, then the @sc{GDB/MI} command will
4347 return a @code{^done} response with no additional values.
4349 Otherwise, the return value must be a dictionary, which is converted
4350 to a @sc{GDB/MI} @var{result-record} (@pxref{GDB/MI Output Syntax}).
4351 The keys of this dictionary must be strings, and are used as
4352 @var{variable} names in the @var{result-record}, these strings must
4353 comply with the naming rules detailed below. The values of this
4354 dictionary are recursively handled as follows:
4358 If the value is Python sequence or iterator, it is converted to
4359 @sc{GDB/MI} @var{list} with elements converted recursively.
4362 If the value is Python dictionary, it is converted to
4363 @sc{GDB/MI} @var{tuple}. Keys in that dictionary must be strings,
4364 which comply with the @var{variable} naming rules detailed below.
4365 Values are converted recursively.
4368 Otherwise, value is first converted to a Python string using
4369 @code{str ()} and then converted to @sc{GDB/MI} @var{const}.
4372 The strings used for @var{variable} names in the @sc{GDB/MI} output
4373 must follow the following rules; the string must be at least one
4374 character long, the first character must be in the set
4375 @code{[a-zA-Z]}, while every subsequent character must be in the set
4376 @code{[-_a-zA-Z0-9]}.
4379 An instance of @code{MICommand} has the following attributes:
4381 @defvar MICommand.name
4382 A string, the name of this @sc{GDB/MI} command, as was passed to the
4383 @code{__init__} method. This attribute is read-only.
4386 @defvar MICommand.installed
4387 A boolean value indicating if this command is installed ready for a
4388 user to call from the command line. Commands are automatically
4389 installed when they are instantiated, after which this attribute will
4392 If later, a new command is created with the same name, then the
4393 original command will become uninstalled, and this attribute will be
4396 This attribute is read-write, setting this attribute to @code{False}
4397 will uninstall the command, removing it from the set of available
4398 commands. Setting this attribute to @code{True} will install the
4399 command for use. If there is already a Python command with this name
4400 installed, the currently installed command will be uninstalled, and
4401 this command installed in its place.
4404 The following code snippet shows how a two trivial MI command can be
4405 implemented in Python:
4408 class MIEcho(gdb.MICommand):
4409 """Echo arguments passed to the command."""
4411 def __init__(self, name, mode):
4413 super(MIEcho, self).__init__(name)
4415 def invoke(self, argv):
4416 if self._mode == 'dict':
4417 return @{ 'dict': @{ 'argv' : argv @} @}
4418 elif self._mode == 'list':
4419 return @{ 'list': argv @}
4421 return @{ 'string': ", ".join(argv) @}
4424 MIEcho("-echo-dict", "dict")
4425 MIEcho("-echo-list", "list")
4426 MIEcho("-echo-string", "string")
4429 The last three lines instantiate the class three times, creating three
4430 new @sc{GDB/MI} commands @code{-echo-dict}, @code{-echo-list}, and
4431 @code{-echo-string}. Each time a subclass of @code{gdb.MICommand} is
4432 instantiated, the new command is automatically registered with
4435 Depending on how the Python code is read into @value{GDBN}, you may
4436 need to import the @code{gdb} module explicitly.
4438 The following example shows a @value{GDBN} session in which the above
4439 commands have been added:
4443 -echo-dict abc def ghi
4444 ^done,dict=@{argv=["abc","def","ghi"]@}
4446 -echo-list abc def ghi
4447 ^done,list=["abc","def","ghi"]
4449 -echo-string abc def ghi
4450 ^done,string="abc, def, ghi"
4454 @node Parameters In Python
4455 @subsubsection Parameters In Python
4457 @cindex parameters in python
4458 @cindex python parameters
4459 @tindex gdb.Parameter
4461 You can implement new @value{GDBN} parameters using Python. A new
4462 parameter is implemented as an instance of the @code{gdb.Parameter}
4465 Parameters are exposed to the user via the @code{set} and
4466 @code{show} commands. @xref{Help}.
4468 There are many parameters that already exist and can be set in
4469 @value{GDBN}. Two examples are: @code{set follow fork} and
4470 @code{set charset}. Setting these parameters influences certain
4471 behavior in @value{GDBN}. Similarly, you can define parameters that
4472 can be used to influence behavior in custom Python scripts and commands.
4474 @defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
4475 The object initializer for @code{Parameter} registers the new
4476 parameter with @value{GDBN}. This initializer is normally invoked
4477 from the subclass' own @code{__init__} method.
4479 @var{name} is the name of the new parameter. If @var{name} consists
4480 of multiple words, then the initial words are looked for as prefix
4481 parameters. An example of this can be illustrated with the
4482 @code{set print} set of parameters. If @var{name} is
4483 @code{print foo}, then @code{print} will be searched as the prefix
4484 parameter. In this case the parameter can subsequently be accessed in
4485 @value{GDBN} as @code{set print foo}.
4487 If @var{name} consists of multiple words, and no prefix parameter group
4488 can be found, an exception is raised.
4490 @var{command-class} should be one of the @samp{COMMAND_} constants
4491 (@pxref{CLI Commands In Python}). This argument tells @value{GDBN} how to
4492 categorize the new parameter in the help system.
4494 @var{parameter-class} should be one of the @samp{PARAM_} constants
4495 defined below. This argument tells @value{GDBN} the type of the new
4496 parameter; this information is used for input validation and
4499 If @var{parameter-class} is @code{PARAM_ENUM}, then
4500 @var{enum-sequence} must be a sequence of strings. These strings
4501 represent the possible values for the parameter.
4503 If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
4504 of a fourth argument will cause an exception to be thrown.
4506 The help text for the new parameter includes the Python documentation
4507 string from the parameter's class, if there is one. If there is no
4508 documentation string, a default value is used. The documentation
4509 string is included in the output of the parameters @code{help set} and
4510 @code{help show} commands, and should be written taking this into
4514 @defvar Parameter.set_doc
4515 If this attribute exists, and is a string, then its value is used as
4516 the first part of the help text for this parameter's @code{set}
4517 command. The second part of the help text is taken from the
4518 documentation string for the parameter's class, if there is one.
4520 The value of @code{set_doc} should give a brief summary specific to
4521 the set action, this text is only displayed when the user runs the
4522 @code{help set} command for this parameter. The class documentation
4523 should be used to give a fuller description of what the parameter
4524 does, this text is displayed for both the @code{help set} and
4525 @code{help show} commands.
4527 The @code{set_doc} value is examined when @code{Parameter.__init__} is
4528 invoked; subsequent changes have no effect.
4531 @defvar Parameter.show_doc
4532 If this attribute exists, and is a string, then its value is used as
4533 the first part of the help text for this parameter's @code{show}
4534 command. The second part of the help text is taken from the
4535 documentation string for the parameter's class, if there is one.
4537 The value of @code{show_doc} should give a brief summary specific to
4538 the show action, this text is only displayed when the user runs the
4539 @code{help show} command for this parameter. The class documentation
4540 should be used to give a fuller description of what the parameter
4541 does, this text is displayed for both the @code{help set} and
4542 @code{help show} commands.
4544 The @code{show_doc} value is examined when @code{Parameter.__init__}
4545 is invoked; subsequent changes have no effect.
4548 @defvar Parameter.value
4549 The @code{value} attribute holds the underlying value of the
4550 parameter. It can be read and assigned to just as any other
4551 attribute. @value{GDBN} does validation when assignments are made.
4554 There are two methods that may be implemented in any @code{Parameter}
4557 @defun Parameter.get_set_string (self)
4558 If this method exists, @value{GDBN} will call it when a
4559 @var{parameter}'s value has been changed via the @code{set} API (for
4560 example, @kbd{set foo off}). The @code{value} attribute has already
4561 been populated with the new value and may be used in output. This
4562 method must return a string. If the returned string is not empty,
4563 @value{GDBN} will present it to the user.
4565 If this method raises the @code{gdb.GdbError} exception
4566 (@pxref{Exception Handling}), then @value{GDBN} will print the
4567 exception's string and the @code{set} command will fail. Note,
4568 however, that the @code{value} attribute will not be reset in this
4569 case. So, if your parameter must validate values, it should store the
4570 old value internally and reset the exposed value, like so:
4573 class ExampleParam (gdb.Parameter):
4574 def __init__ (self, name):
4575 super (ExampleParam, self).__init__ (name,
4579 self.saved_value = True
4582 def get_set_string (self):
4583 if not self.validate():
4584 self.value = self.saved_value
4585 raise gdb.GdbError('Failed to validate')
4586 self.saved_value = self.value
4591 @defun Parameter.get_show_string (self, svalue)
4592 @value{GDBN} will call this method when a @var{parameter}'s
4593 @code{show} API has been invoked (for example, @kbd{show foo}). The
4594 argument @code{svalue} receives the string representation of the
4595 current value. This method must return a string.
4598 When a new parameter is defined, its type must be specified. The
4599 available types are represented by constants defined in the @code{gdb}
4603 @findex PARAM_BOOLEAN
4604 @findex gdb.PARAM_BOOLEAN
4605 @item gdb.PARAM_BOOLEAN
4606 The value is a plain boolean. The Python boolean values, @code{True}
4607 and @code{False} are the only valid values.
4609 @findex PARAM_AUTO_BOOLEAN
4610 @findex gdb.PARAM_AUTO_BOOLEAN
4611 @item gdb.PARAM_AUTO_BOOLEAN
4612 The value has three possible states: true, false, and @samp{auto}. In
4613 Python, true and false are represented using boolean constants, and
4614 @samp{auto} is represented using @code{None}.
4616 @findex PARAM_UINTEGER
4617 @findex gdb.PARAM_UINTEGER
4618 @item gdb.PARAM_UINTEGER
4619 The value is an unsigned integer. The value of @code{None} should be
4620 interpreted to mean ``unlimited'' (literal @code{'unlimited'} can also
4621 be used to set that value), and the value of 0 is reserved and should
4624 @findex PARAM_INTEGER
4625 @findex gdb.PARAM_INTEGER
4626 @item gdb.PARAM_INTEGER
4627 The value is a signed integer. The value of @code{None} should be
4628 interpreted to mean ``unlimited'' (literal @code{'unlimited'} can also
4629 be used to set that value), and the value of 0 is reserved and should
4632 @findex PARAM_STRING
4633 @findex gdb.PARAM_STRING
4634 @item gdb.PARAM_STRING
4635 The value is a string. When the user modifies the string, any escape
4636 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
4637 translated into corresponding characters and encoded into the current
4640 @findex PARAM_STRING_NOESCAPE
4641 @findex gdb.PARAM_STRING_NOESCAPE
4642 @item gdb.PARAM_STRING_NOESCAPE
4643 The value is a string. When the user modifies the string, escapes are
4644 passed through untranslated.
4646 @findex PARAM_OPTIONAL_FILENAME
4647 @findex gdb.PARAM_OPTIONAL_FILENAME
4648 @item gdb.PARAM_OPTIONAL_FILENAME
4649 The value is a either a filename (a string), or @code{None}.
4651 @findex PARAM_FILENAME
4652 @findex gdb.PARAM_FILENAME
4653 @item gdb.PARAM_FILENAME
4654 The value is a filename. This is just like
4655 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
4657 @findex PARAM_ZINTEGER
4658 @findex gdb.PARAM_ZINTEGER
4659 @item gdb.PARAM_ZINTEGER
4660 The value is a signed integer. This is like @code{PARAM_INTEGER},
4661 except that 0 is allowed and the value of @code{None} is not supported.
4663 @findex PARAM_ZUINTEGER
4664 @findex gdb.PARAM_ZUINTEGER
4665 @item gdb.PARAM_ZUINTEGER
4666 The value is an unsigned integer. This is like @code{PARAM_UINTEGER},
4667 except that 0 is allowed and the value of @code{None} is not supported.
4669 @findex PARAM_ZUINTEGER_UNLIMITED
4670 @findex gdb.PARAM_ZUINTEGER_UNLIMITED
4671 @item gdb.PARAM_ZUINTEGER_UNLIMITED
4672 The value is a signed integer. This is like @code{PARAM_INTEGER}
4673 including that the value of @code{None} should be interpreted to mean
4674 ``unlimited'' (literal @code{'unlimited'} can also be used to set that
4675 value), except that 0 is allowed, and the value cannot be negative,
4676 except the special value -1 is returned for the setting of ``unlimited''.
4679 @findex gdb.PARAM_ENUM
4680 @item gdb.PARAM_ENUM
4681 The value is a string, which must be one of a collection string
4682 constants provided when the parameter is created.
4685 @node Functions In Python
4686 @subsubsection Writing new convenience functions
4688 @cindex writing convenience functions
4689 @cindex convenience functions in python
4690 @cindex python convenience functions
4691 @tindex gdb.Function
4693 You can implement new convenience functions (@pxref{Convenience Vars})
4694 in Python. A convenience function is an instance of a subclass of the
4695 class @code{gdb.Function}.
4697 @defun Function.__init__ (name)
4698 The initializer for @code{Function} registers the new function with
4699 @value{GDBN}. The argument @var{name} is the name of the function,
4700 a string. The function will be visible to the user as a convenience
4701 variable of type @code{internal function}, whose name is the same as
4702 the given @var{name}.
4704 The documentation for the new function is taken from the documentation
4705 string for the new class.
4708 @defun Function.invoke (@var{*args})
4709 When a convenience function is evaluated, its arguments are converted
4710 to instances of @code{gdb.Value}, and then the function's
4711 @code{invoke} method is called. Note that @value{GDBN} does not
4712 predetermine the arity of convenience functions. Instead, all
4713 available arguments are passed to @code{invoke}, following the
4714 standard Python calling convention. In particular, a convenience
4715 function can have default values for parameters without ill effect.
4717 The return value of this method is used as its value in the enclosing
4718 expression. If an ordinary Python value is returned, it is converted
4719 to a @code{gdb.Value} following the usual rules.
4722 The following code snippet shows how a trivial convenience function can
4723 be implemented in Python:
4726 class Greet (gdb.Function):
4727 """Return string to greet someone.
4728 Takes a name as argument."""
4730 def __init__ (self):
4731 super (Greet, self).__init__ ("greet")
4733 def invoke (self, name):
4734 return "Hello, %s!" % name.string ()
4739 The last line instantiates the class, and is necessary to trigger the
4740 registration of the function with @value{GDBN}. Depending on how the
4741 Python code is read into @value{GDBN}, you may need to import the
4742 @code{gdb} module explicitly.
4744 Now you can use the function in an expression:
4747 (gdb) print $greet("Bob")
4751 @node Progspaces In Python
4752 @subsubsection Program Spaces In Python
4754 @cindex progspaces in python
4755 @tindex gdb.Progspace
4757 A program space, or @dfn{progspace}, represents a symbolic view
4758 of an address space.
4759 It consists of all of the objfiles of the program.
4760 @xref{Objfiles In Python}.
4761 @xref{Inferiors Connections and Programs, program spaces}, for more details
4762 about program spaces.
4764 The following progspace-related functions are available in the
4767 @findex gdb.current_progspace
4768 @defun gdb.current_progspace ()
4769 This function returns the program space of the currently selected inferior.
4770 @xref{Inferiors Connections and Programs}. This is identical to
4771 @code{gdb.selected_inferior().progspace} (@pxref{Inferiors In Python}) and is
4772 included for historical compatibility.
4775 @findex gdb.progspaces
4776 @defun gdb.progspaces ()
4777 Return a sequence of all the progspaces currently known to @value{GDBN}.
4780 Each progspace is represented by an instance of the @code{gdb.Progspace}
4783 @defvar Progspace.filename
4784 The file name of the progspace as a string.
4787 @defvar Progspace.pretty_printers
4788 The @code{pretty_printers} attribute is a list of functions. It is
4789 used to look up pretty-printers. A @code{Value} is passed to each
4790 function in order; if the function returns @code{None}, then the
4791 search continues. Otherwise, the return value should be an object
4792 which is used to format the value. @xref{Pretty Printing API}, for more
4796 @defvar Progspace.type_printers
4797 The @code{type_printers} attribute is a list of type printer objects.
4798 @xref{Type Printing API}, for more information.
4801 @defvar Progspace.frame_filters
4802 The @code{frame_filters} attribute is a dictionary of frame filter
4803 objects. @xref{Frame Filter API}, for more information.
4806 A program space has the following methods:
4808 @findex Progspace.block_for_pc
4809 @defun Progspace.block_for_pc (pc)
4810 Return the innermost @code{gdb.Block} containing the given @var{pc}
4811 value. If the block cannot be found for the @var{pc} value specified,
4812 the function will return @code{None}.
4815 @findex Progspace.find_pc_line
4816 @defun Progspace.find_pc_line (pc)
4817 Return the @code{gdb.Symtab_and_line} object corresponding to the
4818 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid value
4819 of @var{pc} is passed as an argument, then the @code{symtab} and
4820 @code{line} attributes of the returned @code{gdb.Symtab_and_line}
4821 object will be @code{None} and 0 respectively.
4824 @findex Progspace.is_valid
4825 @defun Progspace.is_valid ()
4826 Returns @code{True} if the @code{gdb.Progspace} object is valid,
4827 @code{False} if not. A @code{gdb.Progspace} object can become invalid
4828 if the program space file it refers to is not referenced by any
4829 inferior. All other @code{gdb.Progspace} methods will throw an
4830 exception if it is invalid at the time the method is called.
4833 @findex Progspace.objfiles
4834 @defun Progspace.objfiles ()
4835 Return a sequence of all the objfiles referenced by this program
4836 space. @xref{Objfiles In Python}.
4839 @findex Progspace.solib_name
4840 @defun Progspace.solib_name (address)
4841 Return the name of the shared library holding the given @var{address}
4842 as a string, or @code{None}.
4845 One may add arbitrary attributes to @code{gdb.Progspace} objects
4846 in the usual Python way.
4847 This is useful if, for example, one needs to do some extra record keeping
4848 associated with the program space.
4850 In this contrived example, we want to perform some processing when
4851 an objfile with a certain symbol is loaded, but we only want to do
4852 this once because it is expensive. To achieve this we record the results
4853 with the program space because we can't predict when the desired objfile
4858 def clear_objfiles_handler(event):
4859 event.progspace.expensive_computation = None
4860 def expensive(symbol):
4861 """A mock routine to perform an "expensive" computation on symbol."""
4862 print ("Computing the answer to the ultimate question ...")
4864 def new_objfile_handler(event):
4865 objfile = event.new_objfile
4866 progspace = objfile.progspace
4867 if not hasattr(progspace, 'expensive_computation') or \
4868 progspace.expensive_computation is None:
4869 # We use 'main' for the symbol to keep the example simple.
4870 # Note: There's no current way to constrain the lookup
4872 symbol = gdb.lookup_global_symbol('main')
4873 if symbol is not None:
4874 progspace.expensive_computation = expensive(symbol)
4875 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
4876 gdb.events.new_objfile.connect(new_objfile_handler)
4878 (gdb) file /tmp/hello
4879 Reading symbols from /tmp/hello...
4880 Computing the answer to the ultimate question ...
4881 (gdb) python print gdb.current_progspace().expensive_computation
4884 Starting program: /tmp/hello
4886 [Inferior 1 (process 4242) exited normally]
4889 @node Objfiles In Python
4890 @subsubsection Objfiles In Python
4892 @cindex objfiles in python
4895 @value{GDBN} loads symbols for an inferior from various
4896 symbol-containing files (@pxref{Files}). These include the primary
4897 executable file, any shared libraries used by the inferior, and any
4898 separate debug info files (@pxref{Separate Debug Files}).
4899 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
4901 The following objfile-related functions are available in the
4904 @findex gdb.current_objfile
4905 @defun gdb.current_objfile ()
4906 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
4907 sets the ``current objfile'' to the corresponding objfile. This
4908 function returns the current objfile. If there is no current objfile,
4909 this function returns @code{None}.
4912 @findex gdb.objfiles
4913 @defun gdb.objfiles ()
4914 Return a sequence of objfiles referenced by the current program space.
4915 @xref{Objfiles In Python}, and @ref{Progspaces In Python}. This is identical
4916 to @code{gdb.selected_inferior().progspace.objfiles()} and is included for
4917 historical compatibility.
4920 @findex gdb.lookup_objfile
4921 @defun gdb.lookup_objfile (name @r{[}, by_build_id@r{]})
4922 Look up @var{name}, a file name or build ID, in the list of objfiles
4923 for the current program space (@pxref{Progspaces In Python}).
4924 If the objfile is not found throw the Python @code{ValueError} exception.
4926 If @var{name} is a relative file name, then it will match any
4927 source file name with the same trailing components. For example, if
4928 @var{name} is @samp{gcc/expr.c}, then it will match source file
4929 name of @file{/build/trunk/gcc/expr.c}, but not
4930 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
4932 If @var{by_build_id} is provided and is @code{True} then @var{name}
4933 is the build ID of the objfile. Otherwise, @var{name} is a file name.
4934 This is supported only on some operating systems, notably those which use
4935 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4936 about this feature, see the description of the @option{--build-id}
4937 command-line option in @ref{Options, , Command Line Options, ld,
4941 Each objfile is represented by an instance of the @code{gdb.Objfile}
4944 @defvar Objfile.filename
4945 The file name of the objfile as a string, with symbolic links resolved.
4947 The value is @code{None} if the objfile is no longer valid.
4948 See the @code{gdb.Objfile.is_valid} method, described below.
4951 @defvar Objfile.username
4952 The file name of the objfile as specified by the user as a string.
4954 The value is @code{None} if the objfile is no longer valid.
4955 See the @code{gdb.Objfile.is_valid} method, described below.
4958 @defvar Objfile.is_file
4959 An objfile often comes from an ordinary file, but in some cases it may
4960 be constructed from the contents of memory. This attribute is
4961 @code{True} for file-backed objfiles, and @code{False} for other
4965 @defvar Objfile.owner
4966 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
4967 object that debug info is being provided for.
4968 Otherwise this is @code{None}.
4969 Separate debug info objfiles are added with the
4970 @code{gdb.Objfile.add_separate_debug_file} method, described below.
4973 @defvar Objfile.build_id
4974 The build ID of the objfile as a string.
4975 If the objfile does not have a build ID then the value is @code{None}.
4977 This is supported only on some operating systems, notably those which use
4978 the ELF format for binary files and the @sc{gnu} Binutils. For more details
4979 about this feature, see the description of the @option{--build-id}
4980 command-line option in @ref{Options, , Command Line Options, ld,
4984 @defvar Objfile.progspace
4985 The containing program space of the objfile as a @code{gdb.Progspace}
4986 object. @xref{Progspaces In Python}.
4989 @defvar Objfile.pretty_printers
4990 The @code{pretty_printers} attribute is a list of functions. It is
4991 used to look up pretty-printers. A @code{Value} is passed to each
4992 function in order; if the function returns @code{None}, then the
4993 search continues. Otherwise, the return value should be an object
4994 which is used to format the value. @xref{Pretty Printing API}, for more
4998 @defvar Objfile.type_printers
4999 The @code{type_printers} attribute is a list of type printer objects.
5000 @xref{Type Printing API}, for more information.
5003 @defvar Objfile.frame_filters
5004 The @code{frame_filters} attribute is a dictionary of frame filter
5005 objects. @xref{Frame Filter API}, for more information.
5008 One may add arbitrary attributes to @code{gdb.Objfile} objects
5009 in the usual Python way.
5010 This is useful if, for example, one needs to do some extra record keeping
5011 associated with the objfile.
5013 In this contrived example we record the time when @value{GDBN}
5019 def new_objfile_handler(event):
5020 # Set the time_loaded attribute of the new objfile.
5021 event.new_objfile.time_loaded = datetime.datetime.today()
5022 gdb.events.new_objfile.connect(new_objfile_handler)
5025 Reading symbols from ./hello...
5026 (gdb) python print gdb.objfiles()[0].time_loaded
5027 2014-10-09 11:41:36.770345
5030 A @code{gdb.Objfile} object has the following methods:
5032 @defun Objfile.is_valid ()
5033 Returns @code{True} if the @code{gdb.Objfile} object is valid,
5034 @code{False} if not. A @code{gdb.Objfile} object can become invalid
5035 if the object file it refers to is not loaded in @value{GDBN} any
5036 longer. All other @code{gdb.Objfile} methods will throw an exception
5037 if it is invalid at the time the method is called.
5040 @defun Objfile.add_separate_debug_file (file)
5041 Add @var{file} to the list of files that @value{GDBN} will search for
5042 debug information for the objfile.
5043 This is useful when the debug info has been removed from the program
5044 and stored in a separate file. @value{GDBN} has built-in support for
5045 finding separate debug info files (@pxref{Separate Debug Files}), but if
5046 the file doesn't live in one of the standard places that @value{GDBN}
5047 searches then this function can be used to add a debug info file
5048 from a different place.
5051 @defun Objfile.lookup_global_symbol (name @r{[}, domain@r{]})
5052 Search for a global symbol named @var{name} in this objfile. Optionally, the
5053 search scope can be restricted with the @var{domain} argument.
5054 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5055 module and described in @ref{Symbols In Python}. This function is similar to
5056 @code{gdb.lookup_global_symbol}, except that the search is limited to this
5059 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
5063 @defun Objfile.lookup_static_symbol (name @r{[}, domain@r{]})
5064 Like @code{Objfile.lookup_global_symbol}, but searches for a global
5065 symbol with static linkage named @var{name} in this objfile.
5068 @node Frames In Python
5069 @subsubsection Accessing inferior stack frames from Python
5071 @cindex frames in python
5072 When the debugged program stops, @value{GDBN} is able to analyze its call
5073 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
5074 represents a frame in the stack. A @code{gdb.Frame} object is only valid
5075 while its corresponding frame exists in the inferior's stack. If you try
5076 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
5077 exception (@pxref{Exception Handling}).
5079 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
5083 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
5087 The following frame-related functions are available in the @code{gdb} module:
5089 @findex gdb.selected_frame
5090 @defun gdb.selected_frame ()
5091 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
5094 @findex gdb.newest_frame
5095 @defun gdb.newest_frame ()
5096 Return the newest frame object for the selected thread.
5099 @defun gdb.frame_stop_reason_string (reason)
5100 Return a string explaining the reason why @value{GDBN} stopped unwinding
5101 frames, as expressed by the given @var{reason} code (an integer, see the
5102 @code{unwind_stop_reason} method further down in this section).
5105 @findex gdb.invalidate_cached_frames
5106 @defun gdb.invalidate_cached_frames
5107 @value{GDBN} internally keeps a cache of the frames that have been
5108 unwound. This function invalidates this cache.
5110 This function should not generally be called by ordinary Python code.
5111 It is documented for the sake of completeness.
5114 A @code{gdb.Frame} object has the following methods:
5116 @defun Frame.is_valid ()
5117 Returns true if the @code{gdb.Frame} object is valid, false if not.
5118 A frame object can become invalid if the frame it refers to doesn't
5119 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
5120 an exception if it is invalid at the time the method is called.
5123 @defun Frame.name ()
5124 Returns the function name of the frame, or @code{None} if it can't be
5128 @defun Frame.architecture ()
5129 Returns the @code{gdb.Architecture} object corresponding to the frame's
5130 architecture. @xref{Architectures In Python}.
5133 @defun Frame.type ()
5134 Returns the type of the frame. The value can be one of:
5136 @item gdb.NORMAL_FRAME
5137 An ordinary stack frame.
5139 @item gdb.DUMMY_FRAME
5140 A fake stack frame that was created by @value{GDBN} when performing an
5141 inferior function call.
5143 @item gdb.INLINE_FRAME
5144 A frame representing an inlined function. The function was inlined
5145 into a @code{gdb.NORMAL_FRAME} that is older than this one.
5147 @item gdb.TAILCALL_FRAME
5148 A frame representing a tail call. @xref{Tail Call Frames}.
5150 @item gdb.SIGTRAMP_FRAME
5151 A signal trampoline frame. This is the frame created by the OS when
5152 it calls into a signal handler.
5154 @item gdb.ARCH_FRAME
5155 A fake stack frame representing a cross-architecture call.
5157 @item gdb.SENTINEL_FRAME
5158 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
5163 @defun Frame.unwind_stop_reason ()
5164 Return an integer representing the reason why it's not possible to find
5165 more frames toward the outermost frame. Use
5166 @code{gdb.frame_stop_reason_string} to convert the value returned by this
5167 function to a string. The value can be one of:
5170 @item gdb.FRAME_UNWIND_NO_REASON
5171 No particular reason (older frames should be available).
5173 @item gdb.FRAME_UNWIND_NULL_ID
5174 The previous frame's analyzer returns an invalid result. This is no
5175 longer used by @value{GDBN}, and is kept only for backward
5178 @item gdb.FRAME_UNWIND_OUTERMOST
5179 This frame is the outermost.
5181 @item gdb.FRAME_UNWIND_UNAVAILABLE
5182 Cannot unwind further, because that would require knowing the
5183 values of registers or memory that have not been collected.
5185 @item gdb.FRAME_UNWIND_INNER_ID
5186 This frame ID looks like it ought to belong to a NEXT frame,
5187 but we got it for a PREV frame. Normally, this is a sign of
5188 unwinder failure. It could also indicate stack corruption.
5190 @item gdb.FRAME_UNWIND_SAME_ID
5191 This frame has the same ID as the previous one. That means
5192 that unwinding further would almost certainly give us another
5193 frame with exactly the same ID, so break the chain. Normally,
5194 this is a sign of unwinder failure. It could also indicate
5197 @item gdb.FRAME_UNWIND_NO_SAVED_PC
5198 The frame unwinder did not find any saved PC, but we needed
5199 one to unwind further.
5201 @item gdb.FRAME_UNWIND_MEMORY_ERROR
5202 The frame unwinder caused an error while trying to access memory.
5204 @item gdb.FRAME_UNWIND_FIRST_ERROR
5205 Any stop reason greater or equal to this value indicates some kind
5206 of error. This special value facilitates writing code that tests
5207 for errors in unwinding in a way that will work correctly even if
5208 the list of the other values is modified in future @value{GDBN}
5209 versions. Using it, you could write:
5211 reason = gdb.selected_frame().unwind_stop_reason ()
5212 reason_str = gdb.frame_stop_reason_string (reason)
5213 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
5214 print ("An error occured: %s" % reason_str)
5221 Returns the frame's resume address.
5224 @defun Frame.block ()
5225 Return the frame's code block. @xref{Blocks In Python}. If the frame
5226 does not have a block -- for example, if there is no debugging
5227 information for the code in question -- then this will throw an
5231 @defun Frame.function ()
5232 Return the symbol for the function corresponding to this frame.
5233 @xref{Symbols In Python}.
5236 @defun Frame.older ()
5237 Return the frame that called this frame.
5240 @defun Frame.newer ()
5241 Return the frame called by this frame.
5244 @defun Frame.find_sal ()
5245 Return the frame's symtab and line object.
5246 @xref{Symbol Tables In Python}.
5249 @anchor{gdbpy_frame_read_register}
5250 @defun Frame.read_register (register)
5251 Return the value of @var{register} in this frame. Returns a
5252 @code{Gdb.Value} object. Throws an exception if @var{register} does
5253 not exist. The @var{register} argument must be one of the following:
5256 A string that is the name of a valid register (e.g., @code{'sp'} or
5259 A @code{gdb.RegisterDescriptor} object (@pxref{Registers In Python}).
5261 A @value{GDBN} internal, platform specific number. Using these
5262 numbers is supported for historic reasons, but is not recommended as
5263 future changes to @value{GDBN} could change the mapping between
5264 numbers and the registers they represent, breaking any Python code
5265 that uses the platform-specific numbers. The numbers are usually
5266 found in the corresponding @file{@var{platform}-tdep.h} file in the
5267 @value{GDBN} source tree.
5269 Using a string to access registers will be slightly slower than the
5270 other two methods as @value{GDBN} must look up the mapping between
5271 name and internal register number. If performance is critical
5272 consider looking up and caching a @code{gdb.RegisterDescriptor}
5276 @defun Frame.read_var (variable @r{[}, block@r{]})
5277 Return the value of @var{variable} in this frame. If the optional
5278 argument @var{block} is provided, search for the variable from that
5279 block; otherwise start at the frame's current block (which is
5280 determined by the frame's current program counter). The @var{variable}
5281 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
5282 @code{gdb.Block} object.
5285 @defun Frame.select ()
5286 Set this frame to be the selected frame. @xref{Stack, ,Examining the
5290 @defun Frame.level ()
5291 Return an integer, the stack frame level for this frame. @xref{Frames, ,Stack Frames}.
5294 @defun Frame.language ()
5295 Return a string, the source language for this frame.
5298 @node Blocks In Python
5299 @subsubsection Accessing blocks from Python
5301 @cindex blocks in python
5304 In @value{GDBN}, symbols are stored in blocks. A block corresponds
5305 roughly to a scope in the source code. Blocks are organized
5306 hierarchically, and are represented individually in Python as a
5307 @code{gdb.Block}. Blocks rely on debugging information being
5310 A frame has a block. Please see @ref{Frames In Python}, for a more
5311 in-depth discussion of frames.
5313 The outermost block is known as the @dfn{global block}. The global
5314 block typically holds public global variables and functions.
5316 The block nested just inside the global block is the @dfn{static
5317 block}. The static block typically holds file-scoped variables and
5320 @value{GDBN} provides a method to get a block's superblock, but there
5321 is currently no way to examine the sub-blocks of a block, or to
5322 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
5325 Here is a short example that should help explain blocks:
5328 /* This is in the global block. */
5331 /* This is in the static block. */
5332 static int file_scope;
5334 /* 'function' is in the global block, and 'argument' is
5335 in a block nested inside of 'function'. */
5336 int function (int argument)
5338 /* 'local' is in a block inside 'function'. It may or may
5339 not be in the same block as 'argument'. */
5343 /* 'inner' is in a block whose superblock is the one holding
5347 /* If this call is expanded by the compiler, you may see
5348 a nested block here whose function is 'inline_function'
5349 and whose superblock is the one holding 'inner'. */
5355 A @code{gdb.Block} is iterable. The iterator returns the symbols
5356 (@pxref{Symbols In Python}) local to the block. Python programs
5357 should not assume that a specific block object will always contain a
5358 given symbol, since changes in @value{GDBN} features and
5359 infrastructure may cause symbols move across blocks in a symbol
5360 table. You can also use Python's @dfn{dictionary syntax} to access
5361 variables in this block, e.g.:
5364 symbol = some_block['variable'] # symbol is of type gdb.Symbol
5367 The following block-related functions are available in the @code{gdb}
5370 @findex gdb.block_for_pc
5371 @defun gdb.block_for_pc (pc)
5372 Return the innermost @code{gdb.Block} containing the given @var{pc}
5373 value. If the block cannot be found for the @var{pc} value specified,
5374 the function will return @code{None}. This is identical to
5375 @code{gdb.current_progspace().block_for_pc(pc)} and is included for
5376 historical compatibility.
5379 A @code{gdb.Block} object has the following methods:
5381 @defun Block.is_valid ()
5382 Returns @code{True} if the @code{gdb.Block} object is valid,
5383 @code{False} if not. A block object can become invalid if the block it
5384 refers to doesn't exist anymore in the inferior. All other
5385 @code{gdb.Block} methods will throw an exception if it is invalid at
5386 the time the method is called. The block's validity is also checked
5387 during iteration over symbols of the block.
5390 A @code{gdb.Block} object has the following attributes:
5393 The start address of the block. This attribute is not writable.
5397 One past the last address that appears in the block. This attribute
5401 @defvar Block.function
5402 The name of the block represented as a @code{gdb.Symbol}. If the
5403 block is not named, then this attribute holds @code{None}. This
5404 attribute is not writable.
5406 For ordinary function blocks, the superblock is the static block.
5407 However, you should note that it is possible for a function block to
5408 have a superblock that is not the static block -- for instance this
5409 happens for an inlined function.
5412 @defvar Block.superblock
5413 The block containing this block. If this parent block does not exist,
5414 this attribute holds @code{None}. This attribute is not writable.
5417 @defvar Block.global_block
5418 The global block associated with this block. This attribute is not
5422 @defvar Block.static_block
5423 The static block associated with this block. This attribute is not
5427 @defvar Block.is_global
5428 @code{True} if the @code{gdb.Block} object is a global block,
5429 @code{False} if not. This attribute is not
5433 @defvar Block.is_static
5434 @code{True} if the @code{gdb.Block} object is a static block,
5435 @code{False} if not. This attribute is not writable.
5438 @node Symbols In Python
5439 @subsubsection Python representation of Symbols
5441 @cindex symbols in python
5444 @value{GDBN} represents every variable, function and type as an
5445 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
5446 Similarly, Python represents these symbols in @value{GDBN} with the
5447 @code{gdb.Symbol} object.
5449 The following symbol-related functions are available in the @code{gdb}
5452 @findex gdb.lookup_symbol
5453 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
5454 This function searches for a symbol by name. The search scope can be
5455 restricted to the parameters defined in the optional domain and block
5458 @var{name} is the name of the symbol. It must be a string. The
5459 optional @var{block} argument restricts the search to symbols visible
5460 in that @var{block}. The @var{block} argument must be a
5461 @code{gdb.Block} object. If omitted, the block for the current frame
5462 is used. The optional @var{domain} argument restricts
5463 the search to the domain type. The @var{domain} argument must be a
5464 domain constant defined in the @code{gdb} module and described later
5467 The result is a tuple of two elements.
5468 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
5470 If the symbol is found, the second element is @code{True} if the symbol
5471 is a field of a method's object (e.g., @code{this} in C@t{++}),
5472 otherwise it is @code{False}.
5473 If the symbol is not found, the second element is @code{False}.
5476 @findex gdb.lookup_global_symbol
5477 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
5478 This function searches for a global symbol by name.
5479 The search scope can be restricted to by the domain argument.
5481 @var{name} is the name of the symbol. It must be a string.
5482 The optional @var{domain} argument restricts the search to the domain type.
5483 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5484 module and described later in this chapter.
5486 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
5490 @findex gdb.lookup_static_symbol
5491 @defun gdb.lookup_static_symbol (name @r{[}, domain@r{]})
5492 This function searches for a global symbol with static linkage by name.
5493 The search scope can be restricted to by the domain argument.
5495 @var{name} is the name of the symbol. It must be a string.
5496 The optional @var{domain} argument restricts the search to the domain type.
5497 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5498 module and described later in this chapter.
5500 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
5503 Note that this function will not find function-scoped static variables. To look
5504 up such variables, iterate over the variables of the function's
5505 @code{gdb.Block} and check that @code{block.addr_class} is
5506 @code{gdb.SYMBOL_LOC_STATIC}.
5508 There can be multiple global symbols with static linkage with the same
5509 name. This function will only return the first matching symbol that
5510 it finds. Which symbol is found depends on where @value{GDBN} is
5511 currently stopped, as @value{GDBN} will first search for matching
5512 symbols in the current object file, and then search all other object
5513 files. If the application is not yet running then @value{GDBN} will
5514 search all object files in the order they appear in the debug
5518 @findex gdb.lookup_static_symbols
5519 @defun gdb.lookup_static_symbols (name @r{[}, domain@r{]})
5520 Similar to @code{gdb.lookup_static_symbol}, this function searches for
5521 global symbols with static linkage by name, and optionally restricted
5522 by the domain argument. However, this function returns a list of all
5523 matching symbols found, not just the first one.
5525 @var{name} is the name of the symbol. It must be a string.
5526 The optional @var{domain} argument restricts the search to the domain type.
5527 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5528 module and described later in this chapter.
5530 The result is a list of @code{gdb.Symbol} objects which could be empty
5531 if no matching symbols were found.
5533 Note that this function will not find function-scoped static variables. To look
5534 up such variables, iterate over the variables of the function's
5535 @code{gdb.Block} and check that @code{block.addr_class} is
5536 @code{gdb.SYMBOL_LOC_STATIC}.
5539 A @code{gdb.Symbol} object has the following attributes:
5542 The type of the symbol or @code{None} if no type is recorded.
5543 This attribute is represented as a @code{gdb.Type} object.
5544 @xref{Types In Python}. This attribute is not writable.
5547 @defvar Symbol.symtab
5548 The symbol table in which the symbol appears. This attribute is
5549 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
5550 Python}. This attribute is not writable.
5554 The line number in the source code at which the symbol was defined.
5559 The name of the symbol as a string. This attribute is not writable.
5562 @defvar Symbol.linkage_name
5563 The name of the symbol, as used by the linker (i.e., may be mangled).
5564 This attribute is not writable.
5567 @defvar Symbol.print_name
5568 The name of the symbol in a form suitable for output. This is either
5569 @code{name} or @code{linkage_name}, depending on whether the user
5570 asked @value{GDBN} to display demangled or mangled names.
5573 @defvar Symbol.addr_class
5574 The address class of the symbol. This classifies how to find the value
5575 of a symbol. Each address class is a constant defined in the
5576 @code{gdb} module and described later in this chapter.
5579 @defvar Symbol.needs_frame
5580 This is @code{True} if evaluating this symbol's value requires a frame
5581 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
5582 local variables will require a frame, but other symbols will not.
5585 @defvar Symbol.is_argument
5586 @code{True} if the symbol is an argument of a function.
5589 @defvar Symbol.is_constant
5590 @code{True} if the symbol is a constant.
5593 @defvar Symbol.is_function
5594 @code{True} if the symbol is a function or a method.
5597 @defvar Symbol.is_variable
5598 @code{True} if the symbol is a variable.
5601 A @code{gdb.Symbol} object has the following methods:
5603 @defun Symbol.is_valid ()
5604 Returns @code{True} if the @code{gdb.Symbol} object is valid,
5605 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
5606 the symbol it refers to does not exist in @value{GDBN} any longer.
5607 All other @code{gdb.Symbol} methods will throw an exception if it is
5608 invalid at the time the method is called.
5611 @defun Symbol.value (@r{[}frame@r{]})
5612 Compute the value of the symbol, as a @code{gdb.Value}. For
5613 functions, this computes the address of the function, cast to the
5614 appropriate type. If the symbol requires a frame in order to compute
5615 its value, then @var{frame} must be given. If @var{frame} is not
5616 given, or if @var{frame} is invalid, then this method will throw an
5620 The available domain categories in @code{gdb.Symbol} are represented
5621 as constants in the @code{gdb} module:
5624 @vindex SYMBOL_UNDEF_DOMAIN
5625 @item gdb.SYMBOL_UNDEF_DOMAIN
5626 This is used when a domain has not been discovered or none of the
5627 following domains apply. This usually indicates an error either
5628 in the symbol information or in @value{GDBN}'s handling of symbols.
5630 @vindex SYMBOL_VAR_DOMAIN
5631 @item gdb.SYMBOL_VAR_DOMAIN
5632 This domain contains variables, function names, typedef names and enum
5635 @vindex SYMBOL_STRUCT_DOMAIN
5636 @item gdb.SYMBOL_STRUCT_DOMAIN
5637 This domain holds struct, union and enum type names.
5639 @vindex SYMBOL_LABEL_DOMAIN
5640 @item gdb.SYMBOL_LABEL_DOMAIN
5641 This domain contains names of labels (for gotos).
5643 @vindex SYMBOL_MODULE_DOMAIN
5644 @item gdb.SYMBOL_MODULE_DOMAIN
5645 This domain contains names of Fortran module types.
5647 @vindex SYMBOL_COMMON_BLOCK_DOMAIN
5648 @item gdb.SYMBOL_COMMON_BLOCK_DOMAIN
5649 This domain contains names of Fortran common blocks.
5652 The available address class categories in @code{gdb.Symbol} are represented
5653 as constants in the @code{gdb} module:
5656 @vindex SYMBOL_LOC_UNDEF
5657 @item gdb.SYMBOL_LOC_UNDEF
5658 If this is returned by address class, it indicates an error either in
5659 the symbol information or in @value{GDBN}'s handling of symbols.
5661 @vindex SYMBOL_LOC_CONST
5662 @item gdb.SYMBOL_LOC_CONST
5663 Value is constant int.
5665 @vindex SYMBOL_LOC_STATIC
5666 @item gdb.SYMBOL_LOC_STATIC
5667 Value is at a fixed address.
5669 @vindex SYMBOL_LOC_REGISTER
5670 @item gdb.SYMBOL_LOC_REGISTER
5671 Value is in a register.
5673 @vindex SYMBOL_LOC_ARG
5674 @item gdb.SYMBOL_LOC_ARG
5675 Value is an argument. This value is at the offset stored within the
5676 symbol inside the frame's argument list.
5678 @vindex SYMBOL_LOC_REF_ARG
5679 @item gdb.SYMBOL_LOC_REF_ARG
5680 Value address is stored in the frame's argument list. Just like
5681 @code{LOC_ARG} except that the value's address is stored at the
5682 offset, not the value itself.
5684 @vindex SYMBOL_LOC_REGPARM_ADDR
5685 @item gdb.SYMBOL_LOC_REGPARM_ADDR
5686 Value is a specified register. Just like @code{LOC_REGISTER} except
5687 the register holds the address of the argument instead of the argument
5690 @vindex SYMBOL_LOC_LOCAL
5691 @item gdb.SYMBOL_LOC_LOCAL
5692 Value is a local variable.
5694 @vindex SYMBOL_LOC_TYPEDEF
5695 @item gdb.SYMBOL_LOC_TYPEDEF
5696 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
5699 @vindex SYMBOL_LOC_LABEL
5700 @item gdb.SYMBOL_LOC_LABEL
5703 @vindex SYMBOL_LOC_BLOCK
5704 @item gdb.SYMBOL_LOC_BLOCK
5707 @vindex SYMBOL_LOC_CONST_BYTES
5708 @item gdb.SYMBOL_LOC_CONST_BYTES
5709 Value is a byte-sequence.
5711 @vindex SYMBOL_LOC_UNRESOLVED
5712 @item gdb.SYMBOL_LOC_UNRESOLVED
5713 Value is at a fixed address, but the address of the variable has to be
5714 determined from the minimal symbol table whenever the variable is
5717 @vindex SYMBOL_LOC_OPTIMIZED_OUT
5718 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
5719 The value does not actually exist in the program.
5721 @vindex SYMBOL_LOC_COMPUTED
5722 @item gdb.SYMBOL_LOC_COMPUTED
5723 The value's address is a computed location.
5725 @vindex SYMBOL_LOC_COMMON_BLOCK
5726 @item gdb.SYMBOL_LOC_COMMON_BLOCK
5727 The value's address is a symbol. This is only used for Fortran common
5731 @node Symbol Tables In Python
5732 @subsubsection Symbol table representation in Python
5734 @cindex symbol tables in python
5736 @tindex gdb.Symtab_and_line
5738 Access to symbol table data maintained by @value{GDBN} on the inferior
5739 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
5740 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
5741 from the @code{find_sal} method in @code{gdb.Frame} object.
5742 @xref{Frames In Python}.
5744 For more information on @value{GDBN}'s symbol table management, see
5745 @ref{Symbols, ,Examining the Symbol Table}, for more information.
5747 A @code{gdb.Symtab_and_line} object has the following attributes:
5749 @defvar Symtab_and_line.symtab
5750 The symbol table object (@code{gdb.Symtab}) for this frame.
5751 This attribute is not writable.
5754 @defvar Symtab_and_line.pc
5755 Indicates the start of the address range occupied by code for the
5756 current source line. This attribute is not writable.
5759 @defvar Symtab_and_line.last
5760 Indicates the end of the address range occupied by code for the current
5761 source line. This attribute is not writable.
5764 @defvar Symtab_and_line.line
5765 Indicates the current line number for this object. This
5766 attribute is not writable.
5769 A @code{gdb.Symtab_and_line} object has the following methods:
5771 @defun Symtab_and_line.is_valid ()
5772 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
5773 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
5774 invalid if the Symbol table and line object it refers to does not
5775 exist in @value{GDBN} any longer. All other
5776 @code{gdb.Symtab_and_line} methods will throw an exception if it is
5777 invalid at the time the method is called.
5780 A @code{gdb.Symtab} object has the following attributes:
5782 @defvar Symtab.filename
5783 The symbol table's source filename. This attribute is not writable.
5786 @defvar Symtab.objfile
5787 The symbol table's backing object file. @xref{Objfiles In Python}.
5788 This attribute is not writable.
5791 @defvar Symtab.producer
5792 The name and possibly version number of the program that
5793 compiled the code in the symbol table.
5794 The contents of this string is up to the compiler.
5795 If no producer information is available then @code{None} is returned.
5796 This attribute is not writable.
5799 A @code{gdb.Symtab} object has the following methods:
5801 @defun Symtab.is_valid ()
5802 Returns @code{True} if the @code{gdb.Symtab} object is valid,
5803 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
5804 the symbol table it refers to does not exist in @value{GDBN} any
5805 longer. All other @code{gdb.Symtab} methods will throw an exception
5806 if it is invalid at the time the method is called.
5809 @defun Symtab.fullname ()
5810 Return the symbol table's source absolute file name.
5813 @defun Symtab.global_block ()
5814 Return the global block of the underlying symbol table.
5815 @xref{Blocks In Python}.
5818 @defun Symtab.static_block ()
5819 Return the static block of the underlying symbol table.
5820 @xref{Blocks In Python}.
5823 @defun Symtab.linetable ()
5824 Return the line table associated with the symbol table.
5825 @xref{Line Tables In Python}.
5828 @node Line Tables In Python
5829 @subsubsection Manipulating line tables using Python
5831 @cindex line tables in python
5832 @tindex gdb.LineTable
5834 Python code can request and inspect line table information from a
5835 symbol table that is loaded in @value{GDBN}. A line table is a
5836 mapping of source lines to their executable locations in memory. To
5837 acquire the line table information for a particular symbol table, use
5838 the @code{linetable} function (@pxref{Symbol Tables In Python}).
5840 A @code{gdb.LineTable} is iterable. The iterator returns
5841 @code{LineTableEntry} objects that correspond to the source line and
5842 address for each line table entry. @code{LineTableEntry} objects have
5843 the following attributes:
5845 @defvar LineTableEntry.line
5846 The source line number for this line table entry. This number
5847 corresponds to the actual line of source. This attribute is not
5851 @defvar LineTableEntry.pc
5852 The address that is associated with the line table entry where the
5853 executable code for that source line resides in memory. This
5854 attribute is not writable.
5857 As there can be multiple addresses for a single source line, you may
5858 receive multiple @code{LineTableEntry} objects with matching
5859 @code{line} attributes, but with different @code{pc} attributes. The
5860 iterator is sorted in ascending @code{pc} order. Here is a small
5861 example illustrating iterating over a line table.
5864 symtab = gdb.selected_frame().find_sal().symtab
5865 linetable = symtab.linetable()
5866 for line in linetable:
5867 print ("Line: "+str(line.line)+" Address: "+hex(line.pc))
5870 This will have the following output:
5873 Line: 33 Address: 0x4005c8L
5874 Line: 37 Address: 0x4005caL
5875 Line: 39 Address: 0x4005d2L
5876 Line: 40 Address: 0x4005f8L
5877 Line: 42 Address: 0x4005ffL
5878 Line: 44 Address: 0x400608L
5879 Line: 42 Address: 0x40060cL
5880 Line: 45 Address: 0x400615L
5883 In addition to being able to iterate over a @code{LineTable}, it also
5884 has the following direct access methods:
5886 @defun LineTable.line (line)
5887 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
5888 entries in the line table for the given @var{line}, which specifies
5889 the source code line. If there are no entries for that source code
5890 @var{line}, the Python @code{None} is returned.
5893 @defun LineTable.has_line (line)
5894 Return a Python @code{Boolean} indicating whether there is an entry in
5895 the line table for this source line. Return @code{True} if an entry
5896 is found, or @code{False} if not.
5899 @defun LineTable.source_lines ()
5900 Return a Python @code{List} of the source line numbers in the symbol
5901 table. Only lines with executable code locations are returned. The
5902 contents of the @code{List} will just be the source line entries
5903 represented as Python @code{Long} values.
5906 @node Breakpoints In Python
5907 @subsubsection Manipulating breakpoints using Python
5909 @cindex breakpoints in python
5910 @tindex gdb.Breakpoint
5912 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
5915 A breakpoint can be created using one of the two forms of the
5916 @code{gdb.Breakpoint} constructor. The first one accepts a string
5917 like one would pass to the @code{break}
5918 (@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
5919 (@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
5920 create both breakpoints and watchpoints. The second accepts separate Python
5921 arguments similar to @ref{Explicit Locations}, and can only be used to create
5924 @defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]})
5925 Create a new breakpoint according to @var{spec}, which is a string naming the
5926 location of a breakpoint, or an expression that defines a watchpoint. The
5927 string should describe a location in a format recognized by the @code{break}
5928 command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
5929 watchpoint, by the @code{watch} command
5930 (@pxref{Set Watchpoints, , Setting Watchpoints}).
5932 The optional @var{type} argument specifies the type of the breakpoint to create,
5935 The optional @var{wp_class} argument defines the class of watchpoint to create,
5936 if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
5937 defaults to @code{gdb.WP_WRITE}.
5939 The optional @var{internal} argument allows the breakpoint to become invisible
5940 to the user. The breakpoint will neither be reported when created, nor will it
5941 be listed in the output from @code{info breakpoints} (but will be listed with
5942 the @code{maint info breakpoints} command).
5944 The optional @var{temporary} argument makes the breakpoint a temporary
5945 breakpoint. Temporary breakpoints are deleted after they have been hit. Any
5946 further access to the Python breakpoint after it has been hit will result in a
5947 runtime error (as that breakpoint has now been automatically deleted).
5949 The optional @var{qualified} argument is a boolean that allows interpreting
5950 the function passed in @code{spec} as a fully-qualified name. It is equivalent
5951 to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
5952 @ref{Explicit Locations}).
5956 @defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]})
5957 This second form of creating a new breakpoint specifies the explicit
5958 location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
5959 be created in the specified source file @var{source}, at the specified
5960 @var{function}, @var{label} and @var{line}.
5962 @var{internal}, @var{temporary} and @var{qualified} have the same usage as
5963 explained previously.
5966 The available types are represented by constants defined in the @code{gdb}
5970 @vindex BP_BREAKPOINT
5971 @item gdb.BP_BREAKPOINT
5972 Normal code breakpoint.
5974 @vindex BP_HARDWARE_BREAKPOINT
5975 @item gdb.BP_HARDWARE_BREAKPOINT
5976 Hardware assisted code breakpoint.
5978 @vindex BP_WATCHPOINT
5979 @item gdb.BP_WATCHPOINT
5980 Watchpoint breakpoint.
5982 @vindex BP_HARDWARE_WATCHPOINT
5983 @item gdb.BP_HARDWARE_WATCHPOINT
5984 Hardware assisted watchpoint.
5986 @vindex BP_READ_WATCHPOINT
5987 @item gdb.BP_READ_WATCHPOINT
5988 Hardware assisted read watchpoint.
5990 @vindex BP_ACCESS_WATCHPOINT
5991 @item gdb.BP_ACCESS_WATCHPOINT
5992 Hardware assisted access watchpoint.
5994 @vindex BP_CATCHPOINT
5995 @item gdb.BP_CATCHPOINT
5996 Catchpoint. Currently, this type can't be used when creating
5997 @code{gdb.Breakpoint} objects, but will be present in
5998 @code{gdb.Breakpoint} objects reported from
5999 @code{gdb.BreakpointEvent}s (@pxref{Events In Python}).
6002 The available watchpoint types are represented by constants defined in the
6008 Read only watchpoint.
6012 Write only watchpoint.
6016 Read/Write watchpoint.
6019 @defun Breakpoint.stop (self)
6020 The @code{gdb.Breakpoint} class can be sub-classed and, in
6021 particular, you may choose to implement the @code{stop} method.
6022 If this method is defined in a sub-class of @code{gdb.Breakpoint},
6023 it will be called when the inferior reaches any location of a
6024 breakpoint which instantiates that sub-class. If the method returns
6025 @code{True}, the inferior will be stopped at the location of the
6026 breakpoint, otherwise the inferior will continue.
6028 If there are multiple breakpoints at the same location with a
6029 @code{stop} method, each one will be called regardless of the
6030 return status of the previous. This ensures that all @code{stop}
6031 methods have a chance to execute at that location. In this scenario
6032 if one of the methods returns @code{True} but the others return
6033 @code{False}, the inferior will still be stopped.
6035 You should not alter the execution state of the inferior (i.e.@:, step,
6036 next, etc.), alter the current frame context (i.e.@:, change the current
6037 active frame), or alter, add or delete any breakpoint. As a general
6038 rule, you should not alter any data within @value{GDBN} or the inferior
6041 Example @code{stop} implementation:
6044 class MyBreakpoint (gdb.Breakpoint):
6046 inf_val = gdb.parse_and_eval("foo")
6053 @defun Breakpoint.is_valid ()
6054 Return @code{True} if this @code{Breakpoint} object is valid,
6055 @code{False} otherwise. A @code{Breakpoint} object can become invalid
6056 if the user deletes the breakpoint. In this case, the object still
6057 exists, but the underlying breakpoint does not. In the cases of
6058 watchpoint scope, the watchpoint remains valid even if execution of the
6059 inferior leaves the scope of that watchpoint.
6062 @defun Breakpoint.delete ()
6063 Permanently deletes the @value{GDBN} breakpoint. This also
6064 invalidates the Python @code{Breakpoint} object. Any further access
6065 to this object's attributes or methods will raise an error.
6068 @defvar Breakpoint.enabled
6069 This attribute is @code{True} if the breakpoint is enabled, and
6070 @code{False} otherwise. This attribute is writable. You can use it to enable
6071 or disable the breakpoint.
6074 @defvar Breakpoint.silent
6075 This attribute is @code{True} if the breakpoint is silent, and
6076 @code{False} otherwise. This attribute is writable.
6078 Note that a breakpoint can also be silent if it has commands and the
6079 first command is @code{silent}. This is not reported by the
6080 @code{silent} attribute.
6083 @defvar Breakpoint.pending
6084 This attribute is @code{True} if the breakpoint is pending, and
6085 @code{False} otherwise. @xref{Set Breaks}. This attribute is
6089 @anchor{python_breakpoint_thread}
6090 @defvar Breakpoint.thread
6091 If the breakpoint is thread-specific, this attribute holds the
6092 thread's global id. If the breakpoint is not thread-specific, this
6093 attribute is @code{None}. This attribute is writable.
6096 @defvar Breakpoint.task
6097 If the breakpoint is Ada task-specific, this attribute holds the Ada task
6098 id. If the breakpoint is not task-specific (or the underlying
6099 language is not Ada), this attribute is @code{None}. This attribute
6103 @defvar Breakpoint.ignore_count
6104 This attribute holds the ignore count for the breakpoint, an integer.
6105 This attribute is writable.
6108 @defvar Breakpoint.number
6109 This attribute holds the breakpoint's number --- the identifier used by
6110 the user to manipulate the breakpoint. This attribute is not writable.
6113 @defvar Breakpoint.type
6114 This attribute holds the breakpoint's type --- the identifier used to
6115 determine the actual breakpoint type or use-case. This attribute is not
6119 @defvar Breakpoint.visible
6120 This attribute tells whether the breakpoint is visible to the user
6121 when set, or when the @samp{info breakpoints} command is run. This
6122 attribute is not writable.
6125 @defvar Breakpoint.temporary
6126 This attribute indicates whether the breakpoint was created as a
6127 temporary breakpoint. Temporary breakpoints are automatically deleted
6128 after that breakpoint has been hit. Access to this attribute, and all
6129 other attributes and functions other than the @code{is_valid}
6130 function, will result in an error after the breakpoint has been hit
6131 (as it has been automatically deleted). This attribute is not
6135 @defvar Breakpoint.hit_count
6136 This attribute holds the hit count for the breakpoint, an integer.
6137 This attribute is writable, but currently it can only be set to zero.
6140 @defvar Breakpoint.location
6141 This attribute holds the location of the breakpoint, as specified by
6142 the user. It is a string. If the breakpoint does not have a location
6143 (that is, it is a watchpoint) the attribute's value is @code{None}. This
6144 attribute is not writable.
6147 @defvar Breakpoint.locations
6148 Get the most current list of breakpoint locations that are inserted for this
6149 breakpoint, with elements of type @code{gdb.BreakpointLocation}
6150 (described below). This functionality matches that of the
6151 @code{info breakpoint} command (@pxref{Set Breaks}), in that it only retrieves
6152 the most current list of locations, thus the list itself when returned is
6153 not updated behind the scenes. This attribute is not writable.
6156 @defvar Breakpoint.expression
6157 This attribute holds a breakpoint expression, as specified by
6158 the user. It is a string. If the breakpoint does not have an
6159 expression (the breakpoint is not a watchpoint) the attribute's value
6160 is @code{None}. This attribute is not writable.
6163 @defvar Breakpoint.condition
6164 This attribute holds the condition of the breakpoint, as specified by
6165 the user. It is a string. If there is no condition, this attribute's
6166 value is @code{None}. This attribute is writable.
6169 @defvar Breakpoint.commands
6170 This attribute holds the commands attached to the breakpoint. If
6171 there are commands, this attribute's value is a string holding all the
6172 commands, separated by newlines. If there are no commands, this
6173 attribute is @code{None}. This attribute is writable.
6176 @subheading Breakpoint Locations
6178 A breakpoint location is one of the actual places where a breakpoint has been
6179 set, represented in the Python API by the @code{gdb.BreakpointLocation}
6180 type. This type is never instantiated by the user directly, but is retrieved
6181 from @code{Breakpoint.locations} which returns a list of breakpoint
6182 locations where it is currently set. Breakpoint locations can become
6183 invalid if new symbol files are loaded or dynamically loaded libraries are
6184 closed. Accessing the attributes of an invalidated breakpoint location will
6185 throw a @code{RuntimeError} exception. Access the @code{Breakpoint.locations}
6186 attribute again to retrieve the new and valid breakpoints location list.
6188 @defvar BreakpointLocation.source
6189 This attribute returns the source file path and line number where this location
6190 was set. The type of the attribute is a tuple of @var{string} and
6191 @var{long}. If the breakpoint location doesn't have a source location,
6192 it returns None, which is the case for watchpoints and catchpoints.
6193 This will throw a @code{RuntimeError} exception if the location
6194 has been invalidated. This attribute is not writable.
6197 @defvar BreakpointLocation.address
6198 This attribute returns the address where this location was set.
6199 This attribute is of type long. This will throw a @code{RuntimeError}
6200 exception if the location has been invalidated. This attribute is
6204 @defvar BreakpointLocation.enabled
6205 This attribute holds the value for whether or not this location is enabled.
6206 This attribute is writable (boolean). This will throw a @code{RuntimeError}
6207 exception if the location has been invalidated.
6210 @defvar BreakpointLocation.owner
6211 This attribute holds a reference to the @code{gdb.Breakpoint} owner object,
6212 from which this @code{gdb.BreakpointLocation} was retrieved from.
6213 This will throw a @code{RuntimeError} exception if the location has been
6214 invalidated. This attribute is not writable.
6217 @defvar BreakpointLocation.function
6218 This attribute gets the name of the function where this location was set.
6219 If no function could be found this attribute returns @code{None}.
6220 This will throw a @code{RuntimeError} exception if the location has
6221 been invalidated. This attribute is not writable.
6224 @defvar BreakpointLocation.fullname
6225 This attribute gets the full name of where this location was set. If no
6226 full name could be found, this attribute returns @code{None}.
6227 This will throw a @code{RuntimeError} exception if the location has
6228 been invalidated. This attribute is not writable.
6231 @defvar BreakpointLocation.thread_groups
6232 This attribute gets the thread groups it was set in. It returns a @code{List}
6233 of the thread group ID's. This will throw a @code{RuntimeError}
6234 exception if the location has been invalidated. This attribute
6238 @node Finish Breakpoints in Python
6239 @subsubsection Finish Breakpoints
6241 @cindex python finish breakpoints
6242 @tindex gdb.FinishBreakpoint
6244 A finish breakpoint is a temporary breakpoint set at the return address of
6245 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
6246 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
6247 and deleted when the execution will run out of the breakpoint scope (i.e.@:
6248 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
6249 Finish breakpoints are thread specific and must be create with the right
6252 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
6253 Create a finish breakpoint at the return address of the @code{gdb.Frame}
6254 object @var{frame}. If @var{frame} is not provided, this defaults to the
6255 newest frame. The optional @var{internal} argument allows the breakpoint to
6256 become invisible to the user. @xref{Breakpoints In Python}, for further
6257 details about this argument.
6260 @defun FinishBreakpoint.out_of_scope (self)
6261 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
6262 @code{return} command, @dots{}), a function may not properly terminate, and
6263 thus never hit the finish breakpoint. When @value{GDBN} notices such a
6264 situation, the @code{out_of_scope} callback will be triggered.
6266 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
6270 class MyFinishBreakpoint (gdb.FinishBreakpoint)
6272 print ("normal finish")
6275 def out_of_scope ():
6276 print ("abnormal finish")
6280 @defvar FinishBreakpoint.return_value
6281 When @value{GDBN} is stopped at a finish breakpoint and the frame
6282 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
6283 attribute will contain a @code{gdb.Value} object corresponding to the return
6284 value of the function. The value will be @code{None} if the function return
6285 type is @code{void} or if the return value was not computable. This attribute
6289 @node Lazy Strings In Python
6290 @subsubsection Python representation of lazy strings
6292 @cindex lazy strings in python
6293 @tindex gdb.LazyString
6295 A @dfn{lazy string} is a string whose contents is not retrieved or
6296 encoded until it is needed.
6298 A @code{gdb.LazyString} is represented in @value{GDBN} as an
6299 @code{address} that points to a region of memory, an @code{encoding}
6300 that will be used to encode that region of memory, and a @code{length}
6301 to delimit the region of memory that represents the string. The
6302 difference between a @code{gdb.LazyString} and a string wrapped within
6303 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
6304 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
6305 retrieved and encoded during printing, while a @code{gdb.Value}
6306 wrapping a string is immediately retrieved and encoded on creation.
6308 A @code{gdb.LazyString} object has the following functions:
6310 @defun LazyString.value ()
6311 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
6312 will point to the string in memory, but will lose all the delayed
6313 retrieval, encoding and handling that @value{GDBN} applies to a
6314 @code{gdb.LazyString}.
6317 @defvar LazyString.address
6318 This attribute holds the address of the string. This attribute is not
6322 @defvar LazyString.length
6323 This attribute holds the length of the string in characters. If the
6324 length is -1, then the string will be fetched and encoded up to the
6325 first null of appropriate width. This attribute is not writable.
6328 @defvar LazyString.encoding
6329 This attribute holds the encoding that will be applied to the string
6330 when the string is printed by @value{GDBN}. If the encoding is not
6331 set, or contains an empty string, then @value{GDBN} will select the
6332 most appropriate encoding when the string is printed. This attribute
6336 @defvar LazyString.type
6337 This attribute holds the type that is represented by the lazy string's
6338 type. For a lazy string this is a pointer or array type. To
6339 resolve this to the lazy string's character type, use the type's
6340 @code{target} method. @xref{Types In Python}. This attribute is not
6344 @node Architectures In Python
6345 @subsubsection Python representation of architectures
6346 @cindex Python architectures
6348 @value{GDBN} uses architecture specific parameters and artifacts in a
6349 number of its various computations. An architecture is represented
6350 by an instance of the @code{gdb.Architecture} class.
6352 A @code{gdb.Architecture} class has the following methods:
6354 @anchor{gdbpy_architecture_name}
6355 @defun Architecture.name ()
6356 Return the name (string value) of the architecture.
6359 @defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
6360 Return a list of disassembled instructions starting from the memory
6361 address @var{start_pc}. The optional arguments @var{end_pc} and
6362 @var{count} determine the number of instructions in the returned list.
6363 If both the optional arguments @var{end_pc} and @var{count} are
6364 specified, then a list of at most @var{count} disassembled instructions
6365 whose start address falls in the closed memory address interval from
6366 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
6367 specified, but @var{count} is specified, then @var{count} number of
6368 instructions starting from the address @var{start_pc} are returned. If
6369 @var{count} is not specified but @var{end_pc} is specified, then all
6370 instructions whose start address falls in the closed memory address
6371 interval from @var{start_pc} to @var{end_pc} are returned. If neither
6372 @var{end_pc} nor @var{count} are specified, then a single instruction at
6373 @var{start_pc} is returned. For all of these cases, each element of the
6374 returned list is a Python @code{dict} with the following string keys:
6379 The value corresponding to this key is a Python long integer capturing
6380 the memory address of the instruction.
6383 The value corresponding to this key is a string value which represents
6384 the instruction with assembly language mnemonics. The assembly
6385 language flavor used is the same as that specified by the current CLI
6386 variable @code{disassembly-flavor}. @xref{Machine Code}.
6389 The value corresponding to this key is the length (integer value) of the
6390 instruction in bytes.
6395 @findex Architecture.integer_type
6396 @defun Architecture.integer_type (size @r{[}, signed@r{]})
6397 This function looks up an integer type by its @var{size}, and
6398 optionally whether or not it is signed.
6400 @var{size} is the size, in bits, of the desired integer type. Only
6401 certain sizes are currently supported: 0, 8, 16, 24, 32, 64, and 128.
6403 If @var{signed} is not specified, it defaults to @code{True}. If
6404 @var{signed} is @code{False}, the returned type will be unsigned.
6406 If the indicated type cannot be found, this function will throw a
6407 @code{ValueError} exception.
6410 @anchor{gdbpy_architecture_registers}
6411 @defun Architecture.registers (@r{[} @var{reggroup} @r{]})
6412 Return a @code{gdb.RegisterDescriptorIterator} (@pxref{Registers In
6413 Python}) for all of the registers in @var{reggroup}, a string that is
6414 the name of a register group. If @var{reggroup} is omitted, or is the
6415 empty string, then the register group @samp{all} is assumed.
6418 @anchor{gdbpy_architecture_reggroups}
6419 @defun Architecture.register_groups ()
6420 Return a @code{gdb.RegisterGroupsIterator} (@pxref{Registers In
6421 Python}) for all of the register groups available for the
6422 @code{gdb.Architecture}.
6425 @node Registers In Python
6426 @subsubsection Registers In Python
6427 @cindex Registers In Python
6429 Python code can request from a @code{gdb.Architecture} information
6430 about the set of registers available
6431 (@pxref{gdbpy_architecture_registers,,@code{Architecture.registers}}).
6432 The register information is returned as a
6433 @code{gdb.RegisterDescriptorIterator}, which is an iterator that in
6434 turn returns @code{gdb.RegisterDescriptor} objects.
6436 A @code{gdb.RegisterDescriptor} does not provide the value of a
6437 register (@pxref{gdbpy_frame_read_register,,@code{Frame.read_register}}
6438 for reading a register's value), instead the @code{RegisterDescriptor}
6439 is a way to discover which registers are available for a particular
6442 A @code{gdb.RegisterDescriptor} has the following read-only properties:
6444 @defvar RegisterDescriptor.name
6445 The name of this register.
6448 It is also possible to lookup a register descriptor based on its name
6449 using the following @code{gdb.RegisterDescriptorIterator} function:
6451 @defun RegisterDescriptorIterator.find (@var{name})
6452 Takes @var{name} as an argument, which must be a string, and returns a
6453 @code{gdb.RegisterDescriptor} for the register with that name, or
6454 @code{None} if there is no register with that name.
6457 Python code can also request from a @code{gdb.Architecture}
6458 information about the set of register groups available on a given
6460 (@pxref{gdbpy_architecture_reggroups,,@code{Architecture.register_groups}}).
6462 Every register can be a member of zero or more register groups. Some
6463 register groups are used internally within @value{GDBN} to control
6464 things like which registers must be saved when calling into the
6465 program being debugged (@pxref{Calling,,Calling Program Functions}).
6466 Other register groups exist to allow users to easily see related sets
6467 of registers in commands like @code{info registers}
6468 (@pxref{info_registers_reggroup,,@code{info registers
6471 The register groups information is returned as a
6472 @code{gdb.RegisterGroupsIterator}, which is an iterator that in turn
6473 returns @code{gdb.RegisterGroup} objects.
6475 A @code{gdb.RegisterGroup} object has the following read-only
6478 @defvar RegisterGroup.name
6479 A string that is the name of this register group.
6482 @node Connections In Python
6483 @subsubsection Connections In Python
6484 @cindex connections in python
6485 @value{GDBN} lets you run and debug multiple programs in a single
6486 session. Each program being debugged has a connection, the connection
6487 describes how @value{GDBN} controls the program being debugged.
6488 Examples of different connection types are @samp{native} and
6489 @samp{remote}. @xref{Inferiors Connections and Programs}.
6491 Connections in @value{GDBN} are represented as instances of
6492 @code{gdb.TargetConnection}, or as one of its sub-classes. To get a
6493 list of all connections use @code{gdb.connections}
6494 (@pxref{gdbpy_connections,,gdb.connections}).
6496 To get the connection for a single @code{gdb.Inferior} read its
6497 @code{gdb.Inferior.connection} attribute
6498 (@pxref{gdbpy_inferior_connection,,gdb.Inferior.connection}).
6500 Currently there is only a single sub-class of
6501 @code{gdb.TargetConnection}, @code{gdb.RemoteTargetConnection},
6502 however, additional sub-classes may be added in future releases of
6503 @value{GDBN}. As a result you should avoid writing code like:
6506 conn = gdb.selected_inferior().connection
6507 if type(conn) is gdb.RemoteTargetConnection:
6508 print("This is a remote target connection")
6512 as this may fail when more connection types are added. Instead, you
6516 conn = gdb.selected_inferior().connection
6517 if isinstance(conn, gdb.RemoteTargetConnection):
6518 print("This is a remote target connection")
6521 A @code{gdb.TargetConnection} has the following method:
6523 @defun TargetConnection.is_valid ()
6524 Return @code{True} if the @code{gdb.TargetConnection} object is valid,
6525 @code{False} if not. A @code{gdb.TargetConnection} will become
6526 invalid if the connection no longer exists within @value{GDBN}, this
6527 might happen when no inferiors are using the connection, but could be
6528 delayed until the user replaces the current target.
6530 Reading any of the @code{gdb.TargetConnection} properties will throw
6531 an exception if the connection is invalid.
6534 A @code{gdb.TargetConnection} has the following read-only properties:
6536 @defvar TargetConnection.num
6537 An integer assigned by @value{GDBN} to uniquely identify this
6538 connection. This is the same value as displayed in the @samp{Num}
6539 column of the @code{info connections} command output (@pxref{Inferiors
6540 Connections and Programs,,info connections}).
6543 @defvar TargetConnection.type
6544 A string that describes what type of connection this is. This string
6545 will be one of the valid names that can be passed to the @code{target}
6546 command (@pxref{Target Commands,,target command}).
6549 @defvar TargetConnection.description
6550 A string that gives a short description of this target type. This is
6551 the same string that is displayed in the @samp{Description} column of
6552 the @code{info connection} command output (@pxref{Inferiors
6553 Connections and Programs,,info connections}).
6556 @defvar TargetConnection.details
6557 An optional string that gives additional information about this
6558 connection. This attribute can be @code{None} if there are no
6559 additional details for this connection.
6561 An example of a connection type that might have additional details is
6562 the @samp{remote} connection, in this case the details string can
6563 contain the @samp{@var{hostname}:@var{port}} that was used to connect
6564 to the remote target.
6567 The @code{gdb.RemoteTargetConnection} class is a sub-class of
6568 @code{gdb.TargetConnection}, and is used to represent @samp{remote}
6569 and @samp{extended-remote} connections. In addition to the attributes
6570 and methods available from the @code{gdb.TargetConnection} base class,
6571 a @code{gdb.RemoteTargetConnection} has the following method:
6573 @kindex maint packet
6574 @defun RemoteTargetConnection.send_packet (@var{packet})
6575 This method sends @var{packet} to the remote target and returns the
6576 response. The @var{packet} should either be a @code{bytes} object, or
6577 a @code{Unicode} string.
6579 If @var{packet} is a @code{Unicode} string, then the string is encoded
6580 to a @code{bytes} object using the @sc{ascii} codec. If the string
6581 can't be encoded then an @code{UnicodeError} is raised.
6583 If @var{packet} is not a @code{bytes} object, or a @code{Unicode}
6584 string, then a @code{TypeError} is raised. If @var{packet} is empty
6585 then a @code{ValueError} is raised.
6587 The response is returned as a @code{bytes} object. For Python 3 if it
6588 is known that the response can be represented as a string then this
6589 can be decoded from the buffer. For example, if it is known that the
6590 response is an @sc{ascii} string:
6593 remote_connection.send_packet("some_packet").decode("ascii")
6596 In Python 2 @code{bytes} and @code{str} are aliases, so the result is
6597 already a string, if the response includes non-printable characters,
6598 or null characters, then these will be present in the result, care
6599 should be taken when processing the result to handle this case.
6601 The prefix, suffix, and checksum (as required by the remote serial
6602 protocol) are automatically added to the outgoing packet, and removed
6603 from the incoming packet before the contents of the reply are
6606 This is equivalent to the @code{maintenance packet} command
6607 (@pxref{maint packet}).
6610 @node TUI Windows In Python
6611 @subsubsection Implementing new TUI windows
6612 @cindex Python TUI Windows
6614 New TUI (@pxref{TUI}) windows can be implemented in Python.
6616 @findex gdb.register_window_type
6617 @defun gdb.register_window_type (@var{name}, @var{factory})
6618 Because TUI windows are created and destroyed depending on the layout
6619 the user chooses, new window types are implemented by registering a
6620 factory function with @value{GDBN}.
6622 @var{name} is the name of the new window. It's an error to try to
6623 replace one of the built-in windows, but other window types can be
6624 replaced. The @var{name} should match the regular expression
6625 @code{[a-zA-Z][-_.a-zA-Z0-9]*}, it is an error to try and create a
6626 window with an invalid name.
6628 @var{function} is a factory function that is called to create the TUI
6629 window. This is called with a single argument of type
6630 @code{gdb.TuiWindow}, described below. It should return an object
6631 that implements the TUI window protocol, also described below.
6634 As mentioned above, when a factory function is called, it is passed
6635 an object of type @code{gdb.TuiWindow}. This object has these
6636 methods and attributes:
6638 @defun TuiWindow.is_valid ()
6639 This method returns @code{True} when this window is valid. When the
6640 user changes the TUI layout, windows no longer visible in the new
6641 layout will be destroyed. At this point, the @code{gdb.TuiWindow}
6642 will no longer be valid, and methods (and attributes) other than
6643 @code{is_valid} will throw an exception.
6645 When the TUI is disabled using @code{tui disable} (@pxref{TUI
6646 Commands,,tui disable}) the window is hidden rather than destroyed,
6647 but @code{is_valid} will still return @code{False} and other methods
6648 (and attributes) will still throw an exception.
6651 @defvar TuiWindow.width
6652 This attribute holds the width of the window. It is not writable.
6655 @defvar TuiWindow.height
6656 This attribute holds the height of the window. It is not writable.
6659 @defvar TuiWindow.title
6660 This attribute holds the window's title, a string. This is normally
6661 displayed above the window. This attribute can be modified.
6664 @defun TuiWindow.erase ()
6665 Remove all the contents of the window.
6668 @defun TuiWindow.write (@var{string} @r{[}, @var{full_window}@r{]})
6669 Write @var{string} to the window. @var{string} can contain ANSI
6670 terminal escape styling sequences; @value{GDBN} will translate these
6671 as appropriate for the terminal.
6673 If the @var{full_window} parameter is @code{True}, then @var{string}
6674 contains the full contents of the window. This is similar to calling
6675 @code{erase} before @code{write}, but avoids the flickering.
6678 The factory function that you supply should return an object
6679 conforming to the TUI window protocol. These are the method that can
6680 be called on this object, which is referred to below as the ``window
6681 object''. The methods documented below are optional; if the object
6682 does not implement one of these methods, @value{GDBN} will not attempt
6683 to call it. Additional new methods may be added to the window
6684 protocol in the future. @value{GDBN} guarantees that they will begin
6685 with a lower-case letter, so you can start implementation methods with
6686 upper-case letters or underscore to avoid any future conflicts.
6688 @defun Window.close ()
6689 When the TUI window is closed, the @code{gdb.TuiWindow} object will be
6690 put into an invalid state. At this time, @value{GDBN} will call
6691 @code{close} method on the window object.
6693 After this method is called, @value{GDBN} will discard any references
6694 it holds on this window object, and will no longer call methods on
6698 @defun Window.render ()
6699 In some situations, a TUI window can change size. For example, this
6700 can happen if the user resizes the terminal, or changes the layout.
6701 When this happens, @value{GDBN} will call the @code{render} method on
6704 If your window is intended to update in response to changes in the
6705 inferior, you will probably also want to register event listeners and
6706 send output to the @code{gdb.TuiWindow}.
6709 @defun Window.hscroll (@var{num})
6710 This is a request to scroll the window horizontally. @var{num} is the
6711 amount by which to scroll, with negative numbers meaning to scroll
6712 right. In the TUI model, it is the viewport that moves, not the
6713 contents. A positive argument should cause the viewport to move
6714 right, and so the content should appear to move to the left.
6717 @defun Window.vscroll (@var{num})
6718 This is a request to scroll the window vertically. @var{num} is the
6719 amount by which to scroll, with negative numbers meaning to scroll
6720 backward. In the TUI model, it is the viewport that moves, not the
6721 contents. A positive argument should cause the viewport to move down,
6722 and so the content should appear to move up.
6725 @defun Window.click (@var{x}, @var{y}, @var{button})
6726 This is called on a mouse click in this window. @var{x} and @var{y} are
6727 the mouse coordinates inside the window (0-based, from the top left
6728 corner), and @var{button} specifies which mouse button was used, whose
6729 values can be 1 (left), 2 (middle), or 3 (right).
6732 @node Disassembly In Python
6733 @subsubsection Instruction Disassembly In Python
6734 @cindex python instruction disassembly
6736 @value{GDBN}'s builtin disassembler can be extended, or even replaced,
6737 using the Python API. The disassembler related features are contained
6738 within the @code{gdb.disassembler} module:
6740 @deftp {class} gdb.disassembler.DisassembleInfo
6741 Disassembly is driven by instances of this class. Each time
6742 @value{GDBN} needs to disassemble an instruction, an instance of this
6743 class is created and passed to a registered disassembler. The
6744 disassembler is then responsible for disassembling an instruction and
6747 Instances of this type are usually created within @value{GDBN},
6748 however, it is possible to create a copy of an instance of this type,
6749 see the description of @code{__init__} for more details.
6751 This class has the following properties and methods:
6753 @defvar DisassembleInfo.address
6754 A read-only integer containing the address at which @value{GDBN}
6755 wishes to disassemble a single instruction.
6758 @defvar DisassembleInfo.architecture
6759 The @code{gdb.Architecture} (@pxref{Architectures In Python}) for
6760 which @value{GDBN} is currently disassembling, this property is
6764 @defvar DisassembleInfo.progspace
6765 The @code{gdb.Progspace} (@pxref{Progspaces In Python,,Program Spaces
6766 In Python}) for which @value{GDBN} is currently disassembling, this
6767 property is read-only.
6770 @defun DisassembleInfo.is_valid ()
6771 Returns @code{True} if the @code{DisassembleInfo} object is valid,
6772 @code{False} if not. A @code{DisassembleInfo} object will become
6773 invalid once the disassembly call for which the @code{DisassembleInfo}
6774 was created, has returned. Calling other @code{DisassembleInfo}
6775 methods, or accessing @code{DisassembleInfo} properties, will raise a
6776 @code{RuntimeError} exception if it is invalid.
6779 @defun DisassembleInfo.__init__ (info)
6780 This can be used to create a new @code{DisassembleInfo} object that is
6781 a copy of @var{info}. The copy will have the same @code{address},
6782 @code{architecture}, and @code{progspace} values as @var{info}, and
6783 will become invalid at the same time as @var{info}.
6785 This method exists so that sub-classes of @code{DisassembleInfo} can
6786 be created, these sub-classes must be initialized as copies of an
6787 existing @code{DisassembleInfo} object, but sub-classes might choose
6788 to override the @code{read_memory} method, and so control what
6789 @value{GDBN} sees when reading from memory
6790 (@pxref{builtin_disassemble}).
6793 @defun DisassembleInfo.read_memory (length, offset)
6794 This method allows the disassembler to read the bytes of the
6795 instruction to be disassembled. The method reads @var{length} bytes,
6796 starting at @var{offset} from
6797 @code{DisassembleInfo.address}.
6799 It is important that the disassembler read the instruction bytes using
6800 this method, rather than reading inferior memory directly, as in some
6801 cases @value{GDBN} disassembles from an internal buffer rather than
6802 directly from inferior memory, calling this method handles this
6805 Returns a buffer object, which behaves much like an array or a string,
6806 just as @code{Inferior.read_memory} does
6807 (@pxref{gdbpy_inferior_read_memory,,Inferior.read_memory}). The
6808 length of the returned buffer will always be exactly @var{length}.
6810 If @value{GDBN} is unable to read the required memory then a
6811 @code{gdb.MemoryError} exception is raised (@pxref{Exception
6814 This method can be overridden by a sub-class in order to control what
6815 @value{GDBN} sees when reading from memory
6816 (@pxref{builtin_disassemble}). When overriding this method it is
6817 important to understand how @code{builtin_disassemble} makes use of
6820 While disassembling a single instruction there could be multiple calls
6821 to this method, and the same bytes might be read multiple times. Any
6822 single call might only read a subset of the total instruction bytes.
6824 If an implementation of @code{read_memory} is unable to read the
6825 requested memory contents, for example, if there's a request to read
6826 from an invalid memory address, then a @code{gdb.MemoryError} should
6829 Raising a @code{MemoryError} inside @code{read_memory} does not
6830 automatically mean a @code{MemoryError} will be raised by
6831 @code{builtin_disassemble}. It is possible the @value{GDBN}'s builtin
6832 disassembler is probing to see how many bytes are available. When
6833 @code{read_memory} raises the @code{MemoryError} the builtin
6834 disassembler might be able to perform a complete disassembly with the
6835 bytes it has available, in this case @code{builtin_disassemble} will
6836 not itself raise a @code{MemoryError}.
6838 Any other exception type raised in @code{read_memory} will propagate
6839 back and be re-raised by @code{builtin_disassemble}.
6843 @deftp {class} Disassembler
6844 This is a base class from which all user implemented disassemblers
6847 @defun Disassembler.__init__ (name)
6848 The constructor takes @var{name}, a string, which should be a short
6849 name for this disassembler.
6852 @defun Disassembler.__call__ (info)
6853 The @code{__call__} method must be overridden by sub-classes to
6854 perform disassembly. Calling @code{__call__} on this base class will
6855 raise a @code{NotImplementedError} exception.
6857 The @var{info} argument is an instance of @code{DisassembleInfo}, and
6858 describes the instruction that @value{GDBN} wants disassembling.
6860 If this function returns @code{None}, this indicates to @value{GDBN}
6861 that this sub-class doesn't wish to disassemble the requested
6862 instruction. @value{GDBN} will then use its builtin disassembler to
6863 perform the disassembly.
6865 Alternatively, this function can return a @code{DisassemblerResult}
6866 that represents the disassembled instruction, this type is described
6867 in more detail below.
6869 The @code{__call__} method can raise a @code{gdb.MemoryError}
6870 exception (@pxref{Exception Handling}) to indicate to @value{GDBN}
6871 that there was a problem accessing the required memory, this will then
6872 be displayed by @value{GDBN} within the disassembler output.
6874 Ideally, the only three outcomes from invoking @code{__call__} would
6875 be a return of @code{None}, a successful disassembly returned in a
6876 @code{DisassemblerResult}, or a @code{MemoryError} indicating that
6877 there was a problem reading memory.
6879 However, as an implementation of @code{__call__} could fail due to
6880 other reasons, e.g.@: some external resource required to perform
6881 disassembly is temporarily unavailable, then, if @code{__call__}
6882 raises a @code{GdbError}, the exception will be converted to a string
6883 and printed at the end of the disassembly output, the disassembly
6884 request will then stop.
6886 Any other exception type raised by the @code{__call__} method is
6887 considered an error in the user code, the exception will be printed to
6888 the error stream according to the @kbd{set python print-stack} setting
6889 (@pxref{set_python_print_stack,,@kbd{set python print-stack}}).
6893 @deftp {class} DisassemblerResult
6894 This class is used to hold the result of calling
6895 @w{@code{Disassembler.__call__}}, and represents a single disassembled
6896 instruction. This class has the following properties and methods:
6898 @defun DisassemblerResult.__init__ (@var{length}, @var{string})
6899 Initialize an instance of this class, @var{length} is the length of
6900 the disassembled instruction in bytes, which must be greater than
6901 zero, and @var{string} is a non-empty string that represents the
6902 disassembled instruction.
6905 @defvar DisassemblerResult.length
6906 A read-only property containing the length of the disassembled
6907 instruction in bytes, this will always be greater than zero.
6910 @defvar DisassemblerResult.string
6911 A read-only property containing a non-empty string representing the
6912 disassembled instruction.
6916 The following functions are also contained in the
6917 @code{gdb.disassembler} module:
6919 @defun register_disassembler (disassembler, architecture)
6920 The @var{disassembler} must be a sub-class of
6921 @code{gdb.disassembler.Disassembler} or @code{None}.
6923 The optional @var{architecture} is either a string, or the value
6924 @code{None}. If it is a string, then it should be the name of an
6925 architecture known to @value{GDBN}, as returned either from
6926 @code{gdb.Architecture.name}
6927 (@pxref{gdbpy_architecture_name,,gdb.Architecture.name}), or from
6928 @code{gdb.architecture_names}
6929 (@pxref{gdb_architecture_names,,gdb.architecture_names}).
6931 The @var{disassembler} will be installed for the architecture named by
6932 @var{architecture}, or if @var{architecture} is @code{None}, then
6933 @var{disassembler} will be installed as a global disassembler for use
6934 by all architectures.
6936 @cindex disassembler in Python, global vs.@: specific
6937 @cindex search order for disassembler in Python
6938 @cindex look up of disassembler in Python
6939 @value{GDBN} only records a single disassembler for each architecture,
6940 and a single global disassembler. Calling
6941 @code{register_disassembler} for an architecture, or for the global
6942 disassembler, will replace any existing disassembler registered for
6943 that @var{architecture} value. The previous disassembler is returned.
6945 If @var{disassembler} is @code{None} then any disassembler currently
6946 registered for @var{architecture} is deregistered and returned.
6948 When @value{GDBN} is looking for a disassembler to use, @value{GDBN}
6949 first looks for an architecture specific disassembler. If none has
6950 been registered then @value{GDBN} looks for a global disassembler (one
6951 registered with @var{architecture} set to @code{None}). Only one
6952 disassembler is called to perform disassembly, so, if there is both an
6953 architecture specific disassembler, and a global disassembler
6954 registered, it is the architecture specific disassembler that will be
6957 @value{GDBN} tracks the architecture specific, and global
6958 disassemblers separately, so it doesn't matter in which order
6959 disassemblers are created or registered; an architecture specific
6960 disassembler, if present, will always be used in preference to a
6961 global disassembler.
6963 You can use the @kbd{maint info python-disassemblers} command
6964 (@pxref{maint info python-disassemblers}) to see which disassemblers
6965 have been registered.
6968 @anchor{builtin_disassemble}
6969 @defun builtin_disassemble (info)
6970 This function calls back into @value{GDBN}'s builtin disassembler to
6971 disassemble the instruction identified by @var{info}, an instance, or
6972 sub-class, of @code{DisassembleInfo}.
6974 When the builtin disassembler needs to read memory the
6975 @code{read_memory} method on @var{info} will be called. By
6976 sub-classing @code{DisassembleInfo} and overriding the
6977 @code{read_memory} method, it is possible to intercept calls to
6978 @code{read_memory} from the builtin disassembler, and to modify the
6981 It is important to understand that, even when
6982 @code{DisassembleInfo.read_memory} raises a @code{gdb.MemoryError}, it
6983 is the internal disassembler itself that reports the memory error to
6984 @value{GDBN}. The reason for this is that the disassembler might
6985 probe memory to see if a byte is readable or not; if the byte can't be
6986 read then the disassembler may choose not to report an error, but
6987 instead to disassemble the bytes that it does have available.
6989 If the builtin disassembler is successful then an instance of
6990 @code{DisassemblerResult} is returned from @code{builtin_disassemble},
6991 alternatively, if something goes wrong, an exception will be raised.
6993 A @code{MemoryError} will be raised if @code{builtin_disassemble} is
6994 unable to read some memory that is required in order to perform
6995 disassembly correctly.
6997 Any exception that is not a @code{MemoryError}, that is raised in a
6998 call to @code{read_memory}, will pass through
6999 @code{builtin_disassemble}, and be visible to the caller.
7001 Finally, there are a few cases where @value{GDBN}'s builtin
7002 disassembler can fail for reasons that are not covered by
7003 @code{MemoryError}. In these cases, a @code{GdbError} will be raised.
7004 The contents of the exception will be a string describing the problem
7005 the disassembler encountered.
7008 Here is an example that registers a global disassembler. The new
7009 disassembler invokes the builtin disassembler, and then adds a
7010 comment, @code{## Comment}, to each line of disassembly output:
7013 class ExampleDisassembler(gdb.disassembler.Disassembler):
7015 super().__init__("ExampleDisassembler")
7017 def __call__(self, info):
7018 result = gdb.disassembler.builtin_disassemble(info)
7019 length = result.length
7020 text = result.string + "\t## Comment"
7021 return gdb.disassembler.DisassemblerResult(length, text)
7023 gdb.disassembler.register_disassembler(ExampleDisassembler())
7026 The following example creates a sub-class of @code{DisassembleInfo} in
7027 order to intercept the @code{read_memory} calls, within
7028 @code{read_memory} any bytes read from memory have the two 4-bit
7029 nibbles swapped around. This isn't a very useful adjustment, but
7030 serves as an example.
7033 class MyInfo(gdb.disassembler.DisassembleInfo):
7034 def __init__(self, info):
7035 super().__init__(info)
7037 def read_memory(self, length, offset):
7038 buffer = super().read_memory(length, offset)
7039 result = bytearray()
7041 v = int.from_bytes(b, 'little')
7042 v = (v << 4) & 0xf0 | (v >> 4)
7044 return memoryview(result)
7046 class NibbleSwapDisassembler(gdb.disassembler.Disassembler):
7048 super().__init__("NibbleSwapDisassembler")
7050 def __call__(self, info):
7052 return gdb.disassembler.builtin_disassemble(info)
7054 gdb.disassembler.register_disassembler(NibbleSwapDisassembler())
7057 @node Python Auto-loading
7058 @subsection Python Auto-loading
7059 @cindex Python auto-loading
7061 When a new object file is read (for example, due to the @code{file}
7062 command, or because the inferior has loaded a shared library),
7063 @value{GDBN} will look for Python support scripts in several ways:
7064 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
7065 @xref{Auto-loading extensions}.
7067 The auto-loading feature is useful for supplying application-specific
7068 debugging commands and scripts.
7070 Auto-loading can be enabled or disabled,
7071 and the list of auto-loaded scripts can be printed.
7074 @anchor{set auto-load python-scripts}
7075 @kindex set auto-load python-scripts
7076 @item set auto-load python-scripts [on|off]
7077 Enable or disable the auto-loading of Python scripts.
7079 @anchor{show auto-load python-scripts}
7080 @kindex show auto-load python-scripts
7081 @item show auto-load python-scripts
7082 Show whether auto-loading of Python scripts is enabled or disabled.
7084 @anchor{info auto-load python-scripts}
7085 @kindex info auto-load python-scripts
7086 @cindex print list of auto-loaded Python scripts
7087 @item info auto-load python-scripts [@var{regexp}]
7088 Print the list of all Python scripts that @value{GDBN} auto-loaded.
7090 Also printed is the list of Python scripts that were mentioned in
7091 the @code{.debug_gdb_scripts} section and were either not found
7092 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
7093 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
7094 This is useful because their names are not printed when @value{GDBN}
7095 tries to load them and fails. There may be many of them, and printing
7096 an error message for each one is problematic.
7098 If @var{regexp} is supplied only Python scripts with matching names are printed.
7103 (gdb) info auto-load python-scripts
7105 Yes py-section-script.py
7106 full name: /tmp/py-section-script.py
7107 No my-foo-pretty-printers.py
7111 When reading an auto-loaded file or script, @value{GDBN} sets the
7112 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
7113 function (@pxref{Objfiles In Python}). This can be useful for
7114 registering objfile-specific pretty-printers and frame-filters.
7116 @node Python modules
7117 @subsection Python modules
7118 @cindex python modules
7120 @value{GDBN} comes with several modules to assist writing Python code.
7123 * gdb.printing:: Building and registering pretty-printers.
7124 * gdb.types:: Utilities for working with types.
7125 * gdb.prompt:: Utilities for prompt value substitution.
7129 @subsubsection gdb.printing
7130 @cindex gdb.printing
7132 This module provides a collection of utilities for working with
7136 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
7137 This class specifies the API that makes @samp{info pretty-printer},
7138 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
7139 Pretty-printers should generally inherit from this class.
7141 @item SubPrettyPrinter (@var{name})
7142 For printers that handle multiple types, this class specifies the
7143 corresponding API for the subprinters.
7145 @item RegexpCollectionPrettyPrinter (@var{name})
7146 Utility class for handling multiple printers, all recognized via
7147 regular expressions.
7148 @xref{Writing a Pretty-Printer}, for an example.
7150 @item FlagEnumerationPrinter (@var{name})
7151 A pretty-printer which handles printing of @code{enum} values. Unlike
7152 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
7153 work properly when there is some overlap between the enumeration
7154 constants. The argument @var{name} is the name of the printer and
7155 also the name of the @code{enum} type to look up.
7157 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
7158 Register @var{printer} with the pretty-printer list of @var{obj}.
7159 If @var{replace} is @code{True} then any existing copy of the printer
7160 is replaced. Otherwise a @code{RuntimeError} exception is raised
7161 if a printer with the same name already exists.
7165 @subsubsection gdb.types
7168 This module provides a collection of utilities for working with
7169 @code{gdb.Type} objects.
7172 @item get_basic_type (@var{type})
7173 Return @var{type} with const and volatile qualifiers stripped,
7174 and with typedefs and C@t{++} references converted to the underlying type.
7179 typedef const int const_int;
7181 const_int& foo_ref (foo);
7182 int main () @{ return 0; @}
7189 (gdb) python import gdb.types
7190 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
7191 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
7195 @item has_field (@var{type}, @var{field})
7196 Return @code{True} if @var{type}, assumed to be a type with fields
7197 (e.g., a structure or union), has field @var{field}.
7199 @item make_enum_dict (@var{enum_type})
7200 Return a Python @code{dictionary} type produced from @var{enum_type}.
7202 @item deep_items (@var{type})
7203 Returns a Python iterator similar to the standard
7204 @code{gdb.Type.iteritems} method, except that the iterator returned
7205 by @code{deep_items} will recursively traverse anonymous struct or
7206 union fields. For example:
7220 Then in @value{GDBN}:
7222 (@value{GDBP}) python import gdb.types
7223 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
7224 (@value{GDBP}) python print struct_a.keys ()
7226 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
7227 @{['a', 'b0', 'b1']@}
7230 @item get_type_recognizers ()
7231 Return a list of the enabled type recognizers for the current context.
7232 This is called by @value{GDBN} during the type-printing process
7233 (@pxref{Type Printing API}).
7235 @item apply_type_recognizers (recognizers, type_obj)
7236 Apply the type recognizers, @var{recognizers}, to the type object
7237 @var{type_obj}. If any recognizer returns a string, return that
7238 string. Otherwise, return @code{None}. This is called by
7239 @value{GDBN} during the type-printing process (@pxref{Type Printing
7242 @item register_type_printer (locus, printer)
7243 This is a convenience function to register a type printer
7244 @var{printer}. The printer must implement the type printer protocol.
7245 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
7246 the printer is registered with that objfile; a @code{gdb.Progspace},
7247 in which case the printer is registered with that progspace; or
7248 @code{None}, in which case the printer is registered globally.
7251 This is a base class that implements the type printer protocol. Type
7252 printers are encouraged, but not required, to derive from this class.
7253 It defines a constructor:
7255 @defmethod TypePrinter __init__ (self, name)
7256 Initialize the type printer with the given name. The new printer
7257 starts in the enabled state.
7263 @subsubsection gdb.prompt
7266 This module provides a method for prompt value-substitution.
7269 @item substitute_prompt (@var{string})
7270 Return @var{string} with escape sequences substituted by values. Some
7271 escape sequences take arguments. You can specify arguments inside
7272 ``@{@}'' immediately following the escape sequence.
7274 The escape sequences you can pass to this function are:
7278 Substitute a backslash.
7280 Substitute an ESC character.
7282 Substitute the selected frame; an argument names a frame parameter.
7284 Substitute a newline.
7286 Substitute a parameter's value; the argument names the parameter.
7288 Substitute a carriage return.
7290 Substitute the selected thread; an argument names a thread parameter.
7292 Substitute the version of GDB.
7294 Substitute the current working directory.
7296 Begin a sequence of non-printing characters. These sequences are
7297 typically used with the ESC character, and are not counted in the string
7298 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
7299 blue-colored ``(gdb)'' prompt where the length is five.
7301 End a sequence of non-printing characters.
7307 substitute_prompt ("frame: \f, args: \p@{print frame-arguments@}")
7310 @exdent will return the string:
7313 "frame: main, args: scalars"